cui.h

Go to the documentation of this file.

/******************************************************************************

 @file CUI.h

 @brief This file contains the interface of the Common User Interface. (CUI)

 Group: LPRF SW RND
 $Target Device: DEVICES $

 ******************************************************************************
 $License: BSD3 2016 $
 ******************************************************************************
 $Release Name: PACKAGE NAME $
 $Release Date: PACKAGE RELEASE DATE $
 *****************************************************************************/

#ifndef CUI_H
#define CUI_H

#include <stdlib.h>
#include <stdint.h>
#include <ti/drivers/apps/Button.h>
#include <ti/drivers/apps/LED.h>

#ifdef __cplusplus
extern "C"
{
#endif

/*********************************************************************
 * MACROS
 */
/*
 * CUI Module configurable defines. These can be used by the user allow for
 * things such as more clients to be opened or changing the maximum length of a
 * menu line.
 *
 * !!!!
 * !!!! Do not modify these values directly. Either use an .opt file or Project
 * !!!!     level defines
 * !!!!
 *
 * By increasing these values the cui module will need to use more memory.
 * You can therefore reduce the amount of memory this module will require by
 * decreasing these values.
 *
 * RAM Usage per client         = ~56 bytes
 * RAM Usage per menus          = ~20 bytes
 * RAM Usage per status lines   = ~76 bytes
 *
 * Reducing MAX_*_LEN defines will reduce the RAM usage, but the reduced memory
 * value will not scale to the number of clients/menus/status lines. In most
 * situations changing MAX_*_LEN defines will not produce any appreciable memory
 * savings.
 */

/*
 * Client Configurable Defines
 */
#ifndef MAX_CLIENTS
#define MAX_CLIENTS                 2
#endif
#ifndef MAX_CLIENT_NAME_LEN
#define MAX_CLIENT_NAME_LEN         64
#endif

/*
 * Menu Configurable Defines
 */
#ifndef MAX_REGISTERED_MENUS
#define MAX_REGISTERED_MENUS        4
#endif
#ifndef MAX_MENU_LINE_LEN
#define MAX_MENU_LINE_LEN           128
#endif

/*
 * Status Line Configurable Defines
 */
#ifndef MAX_STATUS_LINE_LABEL_LEN
#define MAX_STATUS_LINE_LABEL_LEN   32
#endif
#ifndef MAX_STATUS_LINE_VALUE_LEN
#define MAX_STATUS_LINE_VALUE_LEN   128
#endif

/*
 * Creates a main menu. A main menu must have a non NULL uart update function.
 * This will be verified when registering the menu. numItems is incremented by
 * one to allow for a common default "Back" or "Help" menu item between menus.
 */
#define CUI_MAIN_MENU(_menuSymbol, _pMenuTitle, _numItems, _pMenuUpdateFn) \
        CUI_menu_t _menuSymbol = { \
        .uartUpdateFn=_pMenuUpdateFn, \
        .pTitle=_pMenuTitle, \
        .numItems=_numItems + 1, \
        .pUpper=NULL, \
            .menuItems = {
/*
 * Creates a sub menu. This will be verified when registering the menu. numItems
 *  is incremented by one to allow for a common default "Back" or "Help" menu
 *  item between menus.
 */
#define CUI_SUB_MENU(_menuSymbol, _pMenuTitle, _numItems, _pUpperMenu) \
        extern CUI_menu_t _pUpperMenu; \
        CUI_menu_t _menuSymbol = { \
        .uartUpdateFn=NULL, \
        .pTitle=_pMenuTitle, \
        .numItems=_numItems + 1, \
        .pUpper=&_pUpperMenu, \
            .menuItems = {

/*
 * Inserts _pSubMenu into the .menuItems[] of a parent menu.
 */
#define CUI_MENU_ITEM_SUBMENU(_pSubMenu) {.pDesc=NULL, .item.pSubMenu=(&_pSubMenu)},

/*
 * Inserts an action into the .menuItems[] of a parent menu.
 */
#define CUI_MENU_ITEM_ACTION(_pItemDesc, _pFnAction) {.pDesc=(_pItemDesc), .interceptable=false, .interceptActive=false, .item.pFnAction=(_pFnAction)},

/*
 * Inserts an interceptable action into the .menuItems[] of a parent menu.
 */
#define CUI_MENU_ITEM_INT_ACTION(_pItemDesc, _pFnIntercept) {.pDesc=(_pItemDesc), .interceptable=true, .interceptActive=false, .item.pFnIntercept=(_pFnIntercept)},

/*
 * Helper macros to add generic Help and Back screens to all menus
 * The CUI will use these for you. Do not use these in an application.
 */
#define CUI_MENU_ITEM_HELP CUI_MENU_ITEM_INT_ACTION(CUI_MENU_ACTION_HELP_DESC, (CUI_pFnIntercept_t) CUI_menuActionHelp)
#define CUI_MENU_ITEM_BACK CUI_MENU_ITEM_ACTION(CUI_MENU_ACTION_BACK_DESC, (CUI_pFnAction_t) CUI_menuActionBack)
#define CUI_MAIN_MENU_END CUI_MENU_ITEM_HELP }};
#define CUI_SUB_MENU_END CUI_MENU_ITEM_BACK }};
#define CUI_MENU_ACTION_BACK_DESC  "<      BACK      >"
#define CUI_MENU_ACTION_HELP_DESC  "<      HELP      >"


#define CUI_IS_INPUT_NUM(_input)        ((_input >= '0') && (_input <= '9'))
#define CUI_IS_INPUT_ALPHA(_input)      ((_input >= 'a') && (_input <= 'z'))
#define CUI_IS_INPUT_ALPHA_NUM(_input)  ((CUI_IS_INPUT_ALPHA(_input)) && (CUI_IS_INPUT_NUM(_input)))
#define CUI_IS_INPUT_HEX(_input)        ((CUI_IS_INPUT_NUM(_input)) || ((_input >= 'a') && (_input <= 'f')))
#define CUI_IS_INPUT_BINARY(_input)     ((_input == '0') || (_input == '1'))



/* Indication of previewing an interceptable item */
#define CUI_ITEM_PREVIEW            0x00

/* Indication item is now intercepting the uart */
#define CUI_ITEM_INTERCEPT_START    0xFE

/* Indication item is done intercepting the uart */
#define CUI_ITEM_INTERCEPT_STOP     0xFF

/* Indication item intercept should be canceled */
#define CUI_ITEM_INTERCEPT_CANCEL   0xF9

#define CUI_INPUT_UP                0xFA // Up Arrow
#define CUI_INPUT_DOWN              0xFB // Down Arrow
#define CUI_INPUT_RIGHT             0xFC // Right Arrow
#define CUI_INPUT_LEFT              0xFD // Left Arrow
#define CUI_INPUT_BACK              0x7F // Backspace Key
#define CUI_INPUT_EXECUTE           0x0D // Enter Key
#define CUI_INPUT_ESC               0x1B // ESC (escape) Key

#define CUI_COLOR_RESET             "\033[0m"
#define CUI_COLOR_RED               "\033[31m"
#define CUI_COLOR_GREEN             "\033[32m"
#define CUI_COLOR_YELLOW            "\033[33m"
#define CUI_COLOR_BLUE              "\033[34m"
#define CUI_COLOR_MAGENTA           "\033[35m"
#define CUI_COLOR_CYAN              "\033[36m"
#define CUI_COLOR_WHITE             "\033[37m"

#define CUI_DEBUG_MSG_START         "\0337"
#define CUI_DEBUG_MSG_END           "\0338\033[k"

#define CUI_BLINK_CONTINUOUS        0xFFFF

/******************************************************************************
 * TYPEDEFS
 */

/*
 * [Return Types]
 */
typedef enum CUI_retVal
{
  CUI_SUCCESS,
  CUI_FAILURE,
  CUI_INVALID_CB,
  CUI_INVALID_PIN_ID,
  CUI_RESOURCE_ALREADY_ACQUIRED,
  CUI_RESOURCE_NOT_ACQUIRED,
  CUI_MODULE_UNINITIALIZED,
  CUI_INVALID_CLIENT_HANDLE,
  CUI_MAX_CLIENTS_REACHED,
  CUI_NO_ASYNC_LINES_RELEASED,
  CUI_INVALID_LINE_ID,
  CUI_UNKOWN_VALUE_TYPE,
  CUI_UART_FAILURE,
  CUI_INVALID_PARAM,
  CUI_MAX_MENUS_REACHED,
  CUI_PREV_WRITE_UNFINISHED,
  CUI_MISSING_UART_UPDATE_FN,
  CUI_WRONG_BTN_MODE,
  CUI_NOT_MANAGING_BTNS,
  CUI_NOT_MANAGING_LEDS,
  CUI_NOT_MANAGING_UART
} CUI_retVal_t;

/*
 * [General CUI Types]
 */
typedef uint32_t CUI_clientHandle_t;

typedef struct {
    bool manageBtns;
    bool manageLeds;
    bool manageUart;
} CUI_params_t;

typedef struct {
    char clientName[MAX_CLIENT_NAME_LEN];
    uint8_t maxStatusLines;
} CUI_clientParams_t;

/*
 * [Button Related Types]
 */
typedef void (*CUI_btnPressCB_t)(uint32_t _index, Button_EventMask _buttonEvents);

typedef struct {
    uint32_t index;
    CUI_btnPressCB_t appCB;
} CUI_btnRequest_t;

/*
 * [LED Related Types]
 */
typedef struct {
    uint32_t index;
} CUI_ledRequest_t;

/*
 * [Display Related Types]
 */
typedef struct {
    int32_t row;
    int32_t col;
} CUI_cursorInfo_t;

typedef void (*CUI_pFnClientMenuUpdate_t)(void);

/* Type definitions for action functions types */
typedef void (*CUI_pFnAction_t)(const int32_t _itemEntry);
typedef void (*CUI_pFnIntercept_t)(const char _input, char* _lines[3], CUI_cursorInfo_t * _curInfo);

typedef struct CUI_menu_s CUI_menu_t;

/* Type definition for a sub menu/action item entry */
typedef struct {
    char* pDesc;                      /* action description. NULL for sub menu */
    bool interceptable;               /* Is item interceptable */
    bool interceptActive;             /* Is item currently being intercepted */
    union {
        CUI_menu_t* pSubMenu;               /* Sub menu */
        CUI_pFnAction_t   pFnAction;        /* Function for action */
        CUI_pFnIntercept_t pFnIntercept;    /* Function for interceptable action */
    } item;
} CUI_menuItem_t;

/* Type definition for a menu object */
struct CUI_menu_s {
    CUI_pFnClientMenuUpdate_t uartUpdateFn;     /* Uart Update function */
    const char* pTitle;                         /* Title of this menu */
    int32_t numItems;                           /* # of item entries */
    CUI_menu_t*  pUpper;                        /* upper menu */
    CUI_menuItem_t menuItems[];                 /* item entries */
};

/******************************************************************************
 Function Prototypes
 *****************************************************************************/

/******************************************************************************
 * General CUI APIs
 *****************************************************************************/
/*********************************************************************
 * @fn          CUI_init
 *
 * @brief       Initialize the CUI module. This function must be called
 *                  before any other CUI functions.
 */
CUI_retVal_t CUI_init(CUI_params_t* _pParams);

/*********************************************************************
 * @fn          CUI_paramsInit
 *
 * @brief       Initialize a CUI_params_t struct to a known state.
 *                  The known state in this case setting each resource
 *                  management flag to true
 */
void CUI_paramsInit(CUI_params_t* _pParams);

/*********************************************************************
 * @fn          CUI_clientOpen
 *
 * @brief       Open a client with the CUI module. A client is required
 *                  to request/acquire resources
 */
CUI_clientHandle_t CUI_clientOpen(CUI_clientParams_t* _pParams);

/*********************************************************************
 * @fn          CUI_clientParamsInit
 *
 * @brief       Initialize a CUI_clientParams_t struct to a known state.
 */
void CUI_clientParamsInit(CUI_clientParams_t* _pClientParams);

/*********************************************************************
 * @fn          CUI_close
 *
 * @brief       Close the CUI module. Release all resources and memory.
 */
CUI_retVal_t CUI_close();

/******************************************************************************
 * Button CUI APIs
 *****************************************************************************/
/*********************************************************************
 * @fn          CUI_btnResourceRequest
 *
 * @brief       Request access to a button resource
 */
CUI_retVal_t CUI_btnResourceRequest(const CUI_clientHandle_t _clientHandle, const CUI_btnRequest_t* _pRequest);

/*********************************************************************
 * @fn          CUI_btnSetCb
 *
 * @brief       Set the CUI_btnPressCB of a button resource that is currently
 *                  acquired
 */
CUI_retVal_t CUI_btnSetCb(const CUI_clientHandle_t _clientHandle, const uint32_t _index, const CUI_btnPressCB_t _appCb);

/*********************************************************************
 * @fn          CUI_btnGetValue
 *
 * @brief       Set the CUI_btnPressCB of a button resource that is currently
 *                  acquired
 */
CUI_retVal_t CUI_btnGetValue(const CUI_clientHandle_t _clientHandle, const uint32_t _index, bool* _pBtnState);

/*********************************************************************
 * @fn          CUI_btnResourceRelease
 *
 * @brief       Release access to a button resource that is currently acquired
 */
CUI_retVal_t CUI_btnResourceRelease(const CUI_clientHandle_t _clientHandle, const uint32_t _index);

/******************************************************************************
 * LED CUI APIs
 *****************************************************************************/
/*********************************************************************
 * @fn          CUI_ledResourceRequest
 *
 * @brief       Request access to a led resource
 */
CUI_retVal_t CUI_ledResourceRequest(const CUI_clientHandle_t _clientHandle, const CUI_ledRequest_t* _pRequest);

/*********************************************************************
 * @fn          CUI_ledResourceRelease
 *
 * @brief       Release access to a led resource that is currently acquired
 */
CUI_retVal_t CUI_ledResourceRelease(const CUI_clientHandle_t _clientHandle, const uint32_t _index);

/*********************************************************************
 * @fn          CUI_ledOn
 *
 * @brief       Turn a led on
 */
CUI_retVal_t CUI_ledOn(const CUI_clientHandle_t _clientHandle, const uint32_t _index, const uint8_t _brightness);

/*********************************************************************
 * @fn          CUI_ledOff
 *
 * @brief       Turn a led off
 */
CUI_retVal_t CUI_ledOff(const CUI_clientHandle_t _clientHandle, const uint32_t _index);

/*********************************************************************
 * @fn          CUI_ledToggle
 *
 * @brief       Toggle the state of a led [on/off]
 */
CUI_retVal_t CUI_ledToggle(const CUI_clientHandle_t _clientHandle, const uint32_t _index);

/*********************************************************************
 * @fn          CUI_ledBlink
 *
 * @brief       Start blinking a led. Blinking will be at a rate of LED_BLINK_PERIOD ms
 */
CUI_retVal_t CUI_ledBlink(const CUI_clientHandle_t _clientHandle, const uint32_t _index, const uint16_t _numBlinks);

/******************************************************************************
 * Menu CUI APIs
 *****************************************************************************/
/*********************************************************************
 * @fn          CUI_registerMenu
 *
 * @brief       Register a menu with the CUI module
 */
CUI_retVal_t CUI_registerMenu(const CUI_clientHandle_t _clientHandle, CUI_menu_t* _pMenu);

/*********************************************************************
 * @fn          CUI_deRegisterMenu
 *
 * @brief       De-registers a menu with the CUI module
 */
CUI_retVal_t CUI_deRegisterMenu(const CUI_clientHandle_t _clientHandle, CUI_menu_t* _pMenu);

/*********************************************************************
 * @fn          CUI_updateMultiMenuTitle
 *
 * @brief       Changes the default multi menu title
 */
CUI_retVal_t CUI_updateMultiMenuTitle(const char* _pTitle);

/*********************************************************************
 * @fn          CUI_menuNav
 *
 * @brief       Navigate to a specific entry of a menu that has already been
 *              registered
 */
CUI_retVal_t CUI_menuNav(const CUI_clientHandle_t _clientHandle, CUI_menu_t* _pMenu, const uint32_t _itemIndex);

/*********************************************************************
 * @fn          CUI_processMenuUpdate
 *
 * @brief       This function should be called whenever there is UART input
 *                  to be processed.
 */
CUI_retVal_t CUI_processMenuUpdate(void);

/******************************************************************************
 * Status Line CUI APIs
 *****************************************************************************/
/*********************************************************************
 * @fn          CUI_statusLineResourceRequest
 *
 * @brief       Request access to a new status line
 */
CUI_retVal_t CUI_statusLineResourceRequest(const CUI_clientHandle_t _clientHandle, const char _pLabel[MAX_STATUS_LINE_LABEL_LEN], uint32_t* _pLineId);

/*********************************************************************
 * @fn          CUI_statusLinePrintf
 *
 * @brief        Update an acquired status line
 */
CUI_retVal_t CUI_statusLinePrintf(const CUI_clientHandle_t _clientHandle, const uint32_t _lineId, const char *format, ...);


/*********************************************************************
 * Assert Debug API
 ********************************************************************/
/*********************************************************************
 *  @fn         CUI_assert
 *
 *  @brief      Without requiring a cuiHandle_t you may print an assert
 *                string and optionally spinLock while flashing the leds.
 *
 *              Note: If you choose to spinLock, this function will close
 *                all existing clients that have been opened and then
 *                enter an infinite loop that flashes the leds.
 */
void CUI_assert(const char* _assertMsg, const bool _spinLock);

void CUI_menuActionBack(const int32_t _itemEntry);
void CUI_menuActionHelp(const char _input, char* _pLines[3], CUI_cursorInfo_t* _pCurInfo);
#ifdef __cplusplus
}
#endif

#endif /* CUI_H */