SmartSnippets DA1459x SDK
Files | Data Structures | Functions
Monitor & Control I/F

Files

file  mcif.h
 Monitor and Control I/F API.
 

Data Structures

struct  mcif_ascii_parse_element_s
 MCIF-ASCII command description structure. More...
 

Functions

void mcif_setup_queues (int cli_id, OS_QUEUE txq, OS_QUEUE rxq)
 Setup the MCIF queues. More...
 
OS_BASE_TYPE mcif_queue_send (int cli_id, const void *item, OS_TICK_TIME wait_ticks)
 Send a message to MCIF. More...
 
void mcif_init (void)
 Initialize MCIF framework. More...
 

CONFIGURATION

Configuration of MCIF

#define MCIF_CLIENTS_NR   1
 Maximum number of MCIF clients. More...
 
#define MCIF_USE_TASK_NOTIFICATIONS   0
 Use task notifications to indicate a new frame. More...
 
#define MCIF_MAX_ARGS   2
 Maximum number of arguments to use. More...
 
#define MCIF_UART   HW_UART1
 MCIF UART. More...
 
#define MCIF_GPIO_PORT_UART_RX   HW_GPIO_PORT_1
 MCIF UART RX GPIO PORT. More...
 
#define MCIF_GPIO_PIN_UART_RX   HW_GPIO_PIN_5
 MCIF UART RX GPIO PIN. More...
 
#define MCIF_GPIO_PORT_UART_TX   HW_GPIO_PORT_1
 MCIF UART TX GPIO PORT. More...
 
#define MCIF_GPIO_PIN_UART_TX   HW_GPIO_PIN_0
 MCIF UART TX GPIO PIN. More...
 
#define MCIF_UART_BAUDRATE   HW_UART_BAUDRATE_115200
 MCIF UART baudrate. More...
 
#define MCIF_UART_DATABITS   HW_UART_DATABITS_8
 MCIF UART databits. More...
 
#define MCIF_UART_STOPBITS   HW_UART_STOPBITS_1
 MCIF UART stopbits. More...
 
#define MCIF_UART_PARITY   HW_UART_PARITY_NONE
 MCIF UART parity. More...
 
#define MCIF_LOG_TAG   30
 MCIF LOG TAG. More...
 
#define MCIF_ASCII_MAX_LINE   80
 MCIF ASCII max line. More...
 
#define MCIF_UART_DMA_BUFFER   MCIF_ASCII_MAX_LINE
 MCIF MAX DMA Buffer. More...
 
#define MCIF_ASCII_PROMPT   "\r\nEnter command (or ?/help for help) > "
 MCIF ASCII prompt. More...
 

MCIF ASCII Specific Definitions

The following definitions are specific to the MCIF ASCII backend. The MCIF ASCII backend can be used to provide a simple terminal-like interface to the application through the UART.

typedef void(* cmd_cb_t) (xQueueHandle txq, void *arg1, void *arg2)
 ASCII command-set argument X not-applicable flag. More...
 
void mcif_ascii_parse_message (const struct mcif_ascii_parse_element_s *parse_table, xQueueHandle txq, struct mcif_message_s *msg)
 Parse the received message. More...
 
void mcif_ascii_print_prompt (const struct mcif_ascii_parse_element_s *parse_table, xQueueHandle txq, struct mcif_message_s *msg) __WEAK
 Print a prompt. More...
 
void mcif_ascii_print_unknown (const struct mcif_ascii_parse_element_s *parse_table, xQueueHandle txq, struct mcif_message_s *msg) __WEAK
 Print the unknown command message. More...
 
void mcif_ascii_send_response (const struct mcif_ascii_parse_element_s *parse_table, xQueueHandle txq, struct mcif_message_s *msg, bool show_prompt)
 Send a response to the terminal. More...
 
#define MCIF_ASCII_FLAGS_MASK   0x3
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG1_NA   0x0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG2_NA   0x0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG3_NA   0x0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG4_NA   0x0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG5_NA   0x0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG6_NA   0x0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG1_INT   0x1
 ASCII command-set integer argument X. More...
 
#define MCIF_ASCII_FLAGS_ARG2_INT   0x4
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG3_INT   0x10
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG4_INT   0x40
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG5_INT   0x100
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG6_INT   0x400
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG1_STR   0x2
 ASCII command-set string argument X. More...
 
#define MCIF_ASCII_FLAGS_ARG2_STR   0x8
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG3_STR   0x20
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG4_STR   0x80
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG5_STR   0x200
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG6_STR   0x800
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG1_STR_NO_WHITE   0x3
 ASCII command-set string with no whitespace argument X. More...
 
#define MCIF_ASCII_FLAGS_ARG2_STR_NO_WHITE   0xc
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG3_STR_NO_WHITE   0x30
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG4_STR_NO_WHITE   0xc0
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG5_STR_NO_WHITE   0x300
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_ARG6_STR_NO_WHITE   0xc00
 ASCII command-set argument X not-applicable flag. More...
 
#define MCIF_ASCII_FLAGS_AUTO_REPLY   0x80
 ASCII command-set auto-reply flag. More...
 

Detailed Description

Macro Definition Documentation

◆ MCIF_ASCII_FLAGS_ARG1_INT

#define MCIF_ASCII_FLAGS_ARG1_INT   0x1

ASCII command-set integer argument X.

When this flag is set on a command, argument X of the command is expected to be an integer, expressed either in decimal, or in hex, using the 0x prefix (e.g. 0xcafe).

◆ MCIF_ASCII_FLAGS_ARG1_NA

#define MCIF_ASCII_FLAGS_ARG1_NA   0x0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG1_STR

#define MCIF_ASCII_FLAGS_ARG1_STR   0x2

ASCII command-set string argument X.

When this flag is set on a command, argument X of the command is expected to be a string. Note that the string comprises the rest of the entered line, including any spaces. Therefore, if this is set, there can be no second argument to the command

◆ MCIF_ASCII_FLAGS_ARG1_STR_NO_WHITE

#define MCIF_ASCII_FLAGS_ARG1_STR_NO_WHITE   0x3

ASCII command-set string with no whitespace argument X.

When this flag is set on a command, argument X of the command is expected to be a string. This differs from ARGX_STR in that this string must have no whitespace, and therefore, additional arguments are allowed in the line

◆ MCIF_ASCII_FLAGS_ARG2_INT

#define MCIF_ASCII_FLAGS_ARG2_INT   0x4

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG2_NA

#define MCIF_ASCII_FLAGS_ARG2_NA   0x0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG2_STR

#define MCIF_ASCII_FLAGS_ARG2_STR   0x8

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG2_STR_NO_WHITE

#define MCIF_ASCII_FLAGS_ARG2_STR_NO_WHITE   0xc

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG3_INT

#define MCIF_ASCII_FLAGS_ARG3_INT   0x10

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG3_NA

#define MCIF_ASCII_FLAGS_ARG3_NA   0x0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG3_STR

#define MCIF_ASCII_FLAGS_ARG3_STR   0x20

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG3_STR_NO_WHITE

#define MCIF_ASCII_FLAGS_ARG3_STR_NO_WHITE   0x30

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG4_INT

#define MCIF_ASCII_FLAGS_ARG4_INT   0x40

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG4_NA

#define MCIF_ASCII_FLAGS_ARG4_NA   0x0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG4_STR

#define MCIF_ASCII_FLAGS_ARG4_STR   0x80

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG4_STR_NO_WHITE

#define MCIF_ASCII_FLAGS_ARG4_STR_NO_WHITE   0xc0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG5_INT

#define MCIF_ASCII_FLAGS_ARG5_INT   0x100

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG5_NA

#define MCIF_ASCII_FLAGS_ARG5_NA   0x0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG5_STR

#define MCIF_ASCII_FLAGS_ARG5_STR   0x200

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG5_STR_NO_WHITE

#define MCIF_ASCII_FLAGS_ARG5_STR_NO_WHITE   0x300

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG6_INT

#define MCIF_ASCII_FLAGS_ARG6_INT   0x400

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG6_NA

#define MCIF_ASCII_FLAGS_ARG6_NA   0x0

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG6_STR

#define MCIF_ASCII_FLAGS_ARG6_STR   0x800

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_ARG6_STR_NO_WHITE

#define MCIF_ASCII_FLAGS_ARG6_STR_NO_WHITE   0xc00

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_FLAGS_AUTO_REPLY

#define MCIF_ASCII_FLAGS_AUTO_REPLY   0x80

ASCII command-set auto-reply flag.

When this flag is set on a command, when the command returns, the MCIF-ASCII framework will automatically reply "OK" to the user. This is a convenience option, for commands that always succeed.

◆ MCIF_ASCII_FLAGS_MASK

#define MCIF_ASCII_FLAGS_MASK   0x3

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

◆ MCIF_ASCII_MAX_LINE

#define MCIF_ASCII_MAX_LINE   80

MCIF ASCII max line.

Define the maximum line length for input

◆ MCIF_ASCII_PROMPT

#define MCIF_ASCII_PROMPT   "\r\nEnter command (or ?/help for help) > "

MCIF ASCII prompt.

This is the prompt shown on the terminal. Can be changed, if needed.

◆ MCIF_CLIENTS_NR

#define MCIF_CLIENTS_NR   1

Maximum number of MCIF clients.

The maximum number of MCIF clients. Currently must be set to 1 (only MCIF_ASCII is implemented, that supports a single client)

◆ MCIF_GPIO_PIN_UART_RX

#define MCIF_GPIO_PIN_UART_RX   HW_GPIO_PIN_5

MCIF UART RX GPIO PIN.

Define the GPIO pin to use for the RX pin

◆ MCIF_GPIO_PIN_UART_TX

#define MCIF_GPIO_PIN_UART_TX   HW_GPIO_PIN_0

MCIF UART TX GPIO PIN.

Define the GPIO pin to use for the TX pin

◆ MCIF_GPIO_PORT_UART_RX

#define MCIF_GPIO_PORT_UART_RX   HW_GPIO_PORT_1

MCIF UART RX GPIO PORT.

Define the GPIO port to use for the RX pin

◆ MCIF_GPIO_PORT_UART_TX

#define MCIF_GPIO_PORT_UART_TX   HW_GPIO_PORT_1

MCIF UART TX GPIO PORT.

Define the GPIO port to use for the TX pin

◆ MCIF_LOG_TAG

#define MCIF_LOG_TAG   30

MCIF LOG TAG.

Define the LOG TAG (the tag used when logging using the logging library)

◆ MCIF_MAX_ARGS

#define MCIF_MAX_ARGS   2

Maximum number of arguments to use.

Range: [2, 6]

◆ MCIF_UART

#define MCIF_UART   HW_UART1

MCIF UART.

Define the UART to use for MCIF

◆ MCIF_UART_BAUDRATE

#define MCIF_UART_BAUDRATE   HW_UART_BAUDRATE_115200

MCIF UART baudrate.

Define the UART baudrate to use

◆ MCIF_UART_DATABITS

#define MCIF_UART_DATABITS   HW_UART_DATABITS_8

MCIF UART databits.

Define the UART databits to use

◆ MCIF_UART_DMA_BUFFER

#define MCIF_UART_DMA_BUFFER   MCIF_ASCII_MAX_LINE

MCIF MAX DMA Buffer.

Define the maximum DMA buffer to be used for UART input

◆ MCIF_UART_PARITY

#define MCIF_UART_PARITY   HW_UART_PARITY_NONE

MCIF UART parity.

Define the UART parity to use

◆ MCIF_UART_STOPBITS

#define MCIF_UART_STOPBITS   HW_UART_STOPBITS_1

MCIF UART stopbits.

Define the UART stopbits to use

◆ MCIF_USE_TASK_NOTIFICATIONS

#define MCIF_USE_TASK_NOTIFICATIONS   0

Use task notifications to indicate a new frame.

If set to 1, task notifications will be used to notify the application task that a new frame is in the queue

Typedef Documentation

◆ cmd_cb_t

typedef void(* cmd_cb_t) (xQueueHandle txq, void *arg1, void *arg2)

ASCII command-set argument X not-applicable flag.

When this flag is set on a command, argument X (and subsequently, arguments > X as well) is not applicable. i.e. this command does not accept an argument

Function Documentation

◆ mcif_ascii_parse_message()

void mcif_ascii_parse_message ( const struct mcif_ascii_parse_element_s parse_table,
xQueueHandle  txq,
struct mcif_message_s *  msg 
)

Parse the received message.

This function is the main entry point of the MCIF-ASCII framework in the task application. After receiving the message from the MCIF-ASCII RX queue, the application can call this function to parse the message and call the appropriate user callback.

Parameters
[in]parse_table- a pointer to an array of struct mcif_ascii_parse_element_s elements, that each define a user command. The array must be NULL terminated (i.e. the last item on the array must be a NULL).
[in]txq- the MCIF-ASCII transmit queue. Can be used to send responses back to the terminal
[in]msg- a pointer to the message received that is to be parsed.

◆ mcif_ascii_print_prompt()

void mcif_ascii_print_prompt ( const struct mcif_ascii_parse_element_s parse_table,
xQueueHandle  txq,
struct mcif_message_s *  msg 
)

Print a prompt.

This function can be used (usually from within a command user callback) to print a response to the terminal. This is usually done after completing the command processing so that the user can continue entering more commands. Additionally, this function is also called internally by the framework when a prompt needs to be displayed (e.g. when MCIF_ASCII_FLAGS_AUTO_REPLY is set for the command, or when the command entered in the terminal is invalid).

Parameters
[in]parse_table- a pointer to an array of struct mcif_ascii_parse_element_s elements, that each define a user command. The array must be NULL terminated (i.e. the last item on the array must be a NULL).
[in]txq- the MCIF-ASCII transmit queue. Can be used to send responses back to the terminal
[in]msg- a pointer to the message received (if needed for prompt). It must be freed sometime after the call to mcif_ascii_parse_message() by the user app.

◆ mcif_ascii_print_unknown()

void mcif_ascii_print_unknown ( const struct mcif_ascii_parse_element_s parse_table,
xQueueHandle  txq,
struct mcif_message_s *  msg 
)

Print the unknown command message.

This function is used by the framework to print an error message and a help screen, based on the available commands, when an unknown command is entered by the user. This function is defined as weak and can be therefore overridden if a different output is needed in this case.

Parameters
[in]parse_table- a pointer to an array of struct mcif_ascii_parse_element_s elements, that each define a user command. The array must be NULL terminated (i.e. the last item on the array must be a NULL).
[in]txq- the MCIF-ASCII transmit queue. Can be used to send responses back to the terminal
[in]msg- a pointer to the message received (if needed by an overriding function)

◆ mcif_ascii_send_response()

void mcif_ascii_send_response ( const struct mcif_ascii_parse_element_s parse_table,
xQueueHandle  txq,
struct mcif_message_s *  msg,
bool  show_prompt 
)

Send a response to the terminal.

This function is used to send a generic response to the terminal. The response

Parameters
[in]parse_table- a pointer to an array of struct mcif_ascii_parse_element_s elements, that each define a user command. The array must be NULL terminated (i.e. the last item on the array must be a NULL).
[in]txq- the MCIF-ASCII transmit queue. Can be used to send responses back to the terminal
[in]msg- a pointer to the message to be sent to the terminal. This buffer will be freed by MCIF-ASCII.
[in]show_prompt- If set to true, after displaying the msg to the terminal, MCIF-ASCII will also display a prompt.

◆ mcif_init()

void mcif_init ( void  )

Initialize MCIF framework.

Initialize the MCIF framework. This includes initializing the framing backend (currently, only MCIF-ASCII is available), setting up the UART (except from the GPIOs) and creating the MCIF OS task.

◆ mcif_queue_send()

OS_BASE_TYPE mcif_queue_send ( int  cli_id,
const void *  item,
OS_TICK_TIME  wait_ticks 
)

Send a message to MCIF.

This function is used to send a message to MCIF. This function is NOT needed for MCIF-ASCII, since mcif_ascii_send_response() etc functions call this one internally.

Parameters
[in]cli_id- The ID of the client to send a message to.
[in]item- A pointer to the pointer to the message buffer.
[in]wait_ticks- The number of OS ticks to wait for the queue to have available space.
Returns
Returns true if the message was sent, False if not (i.e. the queue was full and the timeout expired)

◆ mcif_setup_queues()

void mcif_setup_queues ( int  cli_id,
OS_QUEUE  txq,
OS_QUEUE  rxq 
)

Setup the MCIF queues.

This function is used by the application to setup the queues to be used by the MCIF framework for this application. The queues must be allocated and initialized by the application. The client id (cli_id) is an identifier for the specific MCIF client (the application). It must be less than MCIF_CLIENTS_NR. For the special case of MCIF-ASCII, cli_id must be set to zero, and, obviously, MCIF-ASCII can only have a single client.

NOTE: THIS FUNCTION MUST BE CALLED BEFORE mcif_init()

Parameters
[in]cli_id- The ID of the client to setup the queues for.
[out]txq- The queue to use to transmit messages to MCIF
[in]rxq- The queue to use to receive messages from MCIF