API for the AT Command Line Interface extension. More...

Collaboration diagram for AT Command Line Interface:

Data Structures
struct	qATCLI_Handler_t
	The command argument with all the regarding information of the incoming AT command. More...

struct	qATCLI_t
	An AT Command Line Interface (CLI) object. More...

struct	qATCLI_Command_t
	An AT-Command object. More...

Macros
#define	qATCLI_ERROR_CODE(ecode)
	Used to indicate an error code as return value inside a command-callback. This code is defined by the application writer and should be a value between `1` and `32766`.

Typedefs
typedef qATCLI_Response_t(*	qATCLI_CommandCallback_t) (qATCLI_Handler_t arg1)
	Pointer to function : An AT-Command callback.

typedef qUINT16_t	qATCLI_Options_t
	A typedef that holds the options for an AT-Command object.

Enumerations
enum	qATCLI_Response_t { qATCLI_ERROR , qATCLI_NOTALLOWED , qATCLI_NORESPONSE , qATCLI_OK , qATCLI_DEVID , qATCLI_NOTFOUND , qATCLI_OUTPUT }
	an enumeration to define the possible values that can be returned from the callback of a command. More...

enum	qATCLI_CommandType_t { qATCLI_CMDTYPE_UNDEF , qATCLI_CMDTYPE_PARA , qATCLI_CMDTYPE_TEST , qATCLI_CMDTYPE_READ , qATCLI_CMDTYPE_ACT }
	An enum to describe the available AT command types. More...

enum	qATCLI_BuiltInString_t { QATCLI_BUILTIN_STR_IDENTIFIER , QATCLI_BUILTIN_STR_OK_RESPONSE , QATCLI_BUILTIN_STR_ERROR_RESPONSE , QATCLI_BUILTIN_STR_NOTFOUND_RESPONSE , QATCLI_BUILTIN_STR_TERM_EOL }
	Possible values for built-in string identifiers. More...

Functions
qBool_t	qATCLI_SetBuiltInString (qATCLI_t const cli, qATCLI_BuiltInString_t which, const char str)
	Set a CLI built-in string to a custom one.

qBool_t	qATCLI_Setup (qATCLI_t const cli, const qPutChar_t outFcn, char pInput, const size_t sizeInput, char *pOutput, const size_t sizeOutput)
	Setup an instance of the AT Command Line Interface.

qBool_t	qATCLI_CmdSubscribe (qATCLI_t const cli, qATCLI_Command_t const cmd, char textCommand, const qATCLI_CommandCallback_t cFcn, qATCLI_Options_t cmdOpt, void param)
	This function subscribes the CLI instance to a specific command with an associated Callback function, so that next time the required command is sent to the CLI input, the callback function will be executed. The CLI parser only analyze commands that follows the extended AT-Commands syntax (the + char can be ignored).

qATCLI_Command_t *	qATCLI_CmdIterate (const qATCLI_t *const cli, const qBool_t reload)
	Iterate between the commands available inside the AT-CLI instance.

qBool_t	qATCLI_ISRHandler (qATCLI_t *const cli, const char c)
	Feed the CLI input with a single character. This call is mandatory from an interrupt context. Put it inside the desired peripheral's ISR. If your ISR get a block of data, use instead qATCLI_ISRHandlerBlock()

qBool_t	qATCLI_ISRHandlerBlock (qATCLI_t const cli, char pData, const size_t n)
	Feed the CLI input with a string. This call is mandatory from an interrupt context. Put it inside the desired peripheral's ISR. If your ISR only get a single char, use instead qATCLI_ISRHandler()

qBool_t	qATCLI_Raise (qATCLI_t const cli, const char cmd)
	Sends a command to the specified AT Command Line Interface instance.

qATCLI_Response_t	qATCLI_Exec (qATCLI_t const cli, char cmd)
	Try to execute the requested command.

qBool_t	qATCLI_Input_Flush (qATCLI_t *const cli)
	Flush the CLI input buffer.

qBool_t	qATCLI_Run (qATCLI_t *const cli)
	Run the AT Command Line Interface when the input is ready.

Detailed Description

API for the AT Command Line Interface extension.

Macro Definition Documentation

◆ qATCLI_ERROR_CODE

#define qATCLI_ERROR_CODE ( ecode )

Used to indicate an error code as return value inside a command-callback. This code is defined by the application writer and should be a value between 1 and 32766.

For example, a return value of qATCLI_ERROR_CODE(15), will print out the string ERROR:15.

Typedef Documentation

◆ qATCLI_CommandCallback_t

typedef qATCLI_Response_t(* qATCLI_CommandCallback_t) (qATCLI_Handler_t arg1)

Pointer to function : An AT-Command callback.

Example :

qATCLI_Response_t commandCallback_example( qATCLI_Handler_t h ) {
      qATCLI_Response_t retValue = qATCLI_ERROR;
      switch ( h->Type ) {
          case qATCLI_CMDTYPE_ACT:
              h->puts( "Test message" );
              retValue = qATCLI_OK;
              break;
          default:
              break;
      }
      return retValue;
}

Parameters

arg1	A pointer to the public data of the CLI instance where the command its subscribed to.

Returns: none.

Enumeration Type Documentation

◆ qATCLI_BuiltInString_t

enum qATCLI_BuiltInString_t

Possible values for built-in string identifiers.

Enumerator
QATCLI_BUILTIN_STR_IDENTIFIER	To select the device identifier string. This string will be printed-out after a call to the `ATCLI_DEFAULT_ID_COMMAND` -> default `ATID`
QATCLI_BUILTIN_STR_OK_RESPONSE	To select the output message when a command callback returns qATCLI_OK.
QATCLI_BUILTIN_STR_ERROR_RESPONSE	To select the output message when a command callback returns qATCLI_ERROR or any qATCLI_ERROR_CODE(#)
QATCLI_BUILTIN_STR_NOTFOUND_RESPONSE	To select the output message when input does not match with any of the available commands
QATCLI_BUILTIN_STR_TERM_EOL	To select the End-Of-Line string printed out after any of the CLI messages

◆ qATCLI_CommandType_t

enum qATCLI_CommandType_t

An enum to describe the available AT command types.

Enumerator
qATCLI_CMDTYPE_UNDEF	Was not able to detected a correct input command
qATCLI_CMDTYPE_PARA	Command that receives parameters (comma separated arguments after the equal(=) symbol) : `"AT+cmd=x,y"`
qATCLI_CMDTYPE_TEST	Command in test mode (no arguments allowed): `"AT+cmd=?"`
qATCLI_CMDTYPE_READ	Command to query information(data allowed after the ? symbol) : `"AT+cmd?"`
qATCLI_CMDTYPE_ACT	Command to perform an action (no arguments allowed) : `AT+cmd`

◆ qATCLI_Response_t

enum qATCLI_Response_t

an enumeration to define the possible values that can be returned from the callback of a command.

Enumerator
qATCLI_ERROR	To indicate an error operation. The CLI will print the `ERROR_String` to the output.
qATCLI_NOTALLOWED	To indicate an successful operation. The CLI will print the `NOT_Allowed` string to the output.
qATCLI_NORESPONSE	To indicate that no response will be printed out.
qATCLI_OK	To indicate an successful operation. The CLI will print the `OK_String` to the output.
qATCLI_DEVID	To indicate that the device "Identifier" should be printed out.
qATCLI_NOTFOUND	To indicate that the command was not found. The CLI will print the `NOTFOUND_string` to the output
qATCLI_OUTPUT	To indicate that only the output buffer will be print out

Function Documentation

◆ qATCLI_CmdIterate()

qATCLI_Command_t * qATCLI_CmdIterate	(	const qATCLI_t *const	cli,
		const qBool_t	reload )

Iterate between the commands available inside the AT-CLI instance.

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	reload	If qTrue, the iterator will set their position at the beginning of the list of subscribed commands.

Returns: The current iterated command. NULL when no more commands are available.

◆ qATCLI_CmdSubscribe()

qBool_t qATCLI_CmdSubscribe	(	qATCLI_t *const	cli,
		qATCLI_Command_t *const	cmd,
		char *	textCommand,
		const qATCLI_CommandCallback_t	cFcn,
		qATCLI_Options_t	cmdOpt,
		void *	param )

This function subscribes the CLI instance to a specific command with an associated Callback function, so that next time the required command is sent to the CLI input, the callback function will be executed. The CLI parser only analyze commands that follows the extended AT-Commands syntax (the + char can be ignored).

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	cmd	A pointer to the AT command object.
[in]	textCommand	The string (name) of the command we want to subscribe to. Since this service only handles AT commands, this string has to begin by the "at" characters and should be in lower case.
[in]	cFcn	The handler of the callback function associated to the command. Prototype: qATCLI_Response_t xCallback( qATCLI_Handler_t )
[in]	cmdOpt	This flag combines with a bitwise OR the following information:

qATCLI_CMDTYPE_PARA : AT+cmd=x,y is allowed. The execution of the callback function also depends on whether the number of argument is valid or not. Information about number of arguments is combined with a bitwise 'OR' : qATCLI_CMDTYPE_PARA | 0xXY , where X which defines maximum argument number for incoming command and Y which defines minimum argument number for incoming command

qATCLI_CMDTYPE_TEST : "AT+cmd=?" is allowed.

qATCLI_CMDTYPE_READ : "AT+cmd?" is allowed.

qATCLI_CMDTYPE_ACT : AT+cmd is allowed.

Parameters

[in] param User storage pointer.

Returns: qTrue on success, otherwise return qFalse.

◆ qATCLI_Exec()

qATCLI_Response_t qATCLI_Exec	(	qATCLI_t *const	cli,
		char *	cmd )

Try to execute the requested command.

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	cmd	The command string, including arguments if required.

Returns: The response output for the requested command.

◆ qATCLI_Input_Flush()

qBool_t qATCLI_Input_Flush ( qATCLI_t *const cli )

Flush the CLI input buffer.

Parameters

[in] cli A pointer to the AT Command Line Interface instance

Returns: qTrue on success, otherwise return qFalse

◆ qATCLI_ISRHandler()

qBool_t qATCLI_ISRHandler	(	qATCLI_t *const	cli,
		const char	c )

Feed the CLI input with a single character. This call is mandatory from an interrupt context. Put it inside the desired peripheral's ISR. If your ISR get a block of data, use instead qATCLI_ISRHandlerBlock()

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	c	The incoming byte/char to the input.

Returns: qTrue when the CLI is ready to process the input, otherwise return qFalse

◆ qATCLI_ISRHandlerBlock()

qBool_t qATCLI_ISRHandlerBlock	(	qATCLI_t *const	cli,
		char *	pData,
		const size_t	n )

Feed the CLI input with a string. This call is mandatory from an interrupt context. Put it inside the desired peripheral's ISR. If your ISR only get a single char, use instead qATCLI_ISRHandler()

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	pData	The incoming string.
[in]	n	The length of the string.

Returns: qTrue when the CLI is ready to process the input, otherwise return qFalse

◆ qATCLI_Raise()

qBool_t qATCLI_Raise	(	qATCLI_t *const	cli,
		const char *	cmd )

Sends a command to the specified AT Command Line Interface instance.

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	cmd	The command string, including arguments if required.

Returns: qTrue when the CLI accepts the input. If busy, return qFalse

◆ qATCLI_Run()

qBool_t qATCLI_Run ( qATCLI_t *const cli )

Run the AT Command Line Interface when the input is ready.

See also: qOS_Add_ATCLITask()

Parameters

[in] cli A pointer to the AT Command Line Interface instance

Returns: qTrue on success, otherwise return qFalse

◆ qATCLI_SetBuiltInString()

qBool_t qATCLI_SetBuiltInString	(	qATCLI_t *const	cli,
		qATCLI_BuiltInString_t	which,
		const char *	str )

Set a CLI built-in string to a custom one.

Note: CLI Built-in strings will be written to their default values.

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	which	To select which built-in string will be changed.
[in]	str	The value of the selected string.

Returns: qTrue on success, otherwise return qFalse.

◆ qATCLI_Setup()

qBool_t qATCLI_Setup	(	qATCLI_t *const	cli,
		const qPutChar_t	outFcn,
		char *	pInput,
		const size_t	sizeInput,
		char *	pOutput,
		const size_t	sizeOutput )

Setup an instance of the AT Command Line Interface.

See also: qOS_Add_ATCLITask()

Note: CLI Built-in strings will be written to their default values.

Parameters

[in]	cli	A pointer to the AT Command Line Interface instance
[in]	outFcn	The basic output-char wrapper function. All the CLI responses will be printed-out through this function.
[in]	pInput	A memory location to store the cli input (Mandatory)
[in]	sizeInput	The size of the memory allocated in pInput
[in]	pOutput	A memory location to store the CLI output
[in]	sizeOutput	The size of the memory allocated in pOutput

Returns: qTrue on success, otherwise return qFalse.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ qATCLI_ERROR_CODE

Typedef Documentation

◆ qATCLI_CommandCallback_t

Enumeration Type Documentation

◆ qATCLI_BuiltInString_t

◆ qATCLI_CommandType_t

◆ qATCLI_Response_t

Function Documentation

◆ qATCLI_CmdIterate()

◆ qATCLI_CmdSubscribe()

◆ qATCLI_Exec()

◆ qATCLI_Input_Flush()

◆ qATCLI_ISRHandler()

◆ qATCLI_ISRHandlerBlock()

◆ qATCLI_Raise()

◆ qATCLI_Run()

◆ qATCLI_SetBuiltInString()

◆ qATCLI_Setup()