Class for sending AT commands and parsing AT responses. More...

#include <ATHandler.h>

Public Member Functions
	ATHandler (FileHandle fh, events::EventQueue &queue, uint32_t timeout, const char output_delimiter, uint16_t send_delay=0)
	Constructor.
FileHandle *	get_file_handle ()
	Return used file handle.
nsapi_error_t	close ()
	Close and delete the current ATHandler instance, if the reference count to it is 0.
void	lock ()
	Locks the mutex for file handle if AT_HANDLER_MUTEX is defined.
void	unlock ()
	Unlocks the mutex for file handle if AT_HANDLER_MUTEX is defined.
nsapi_error_t	unlock_return_error ()
	Locks the mutex for file handle if AT_HANDLER_MUTEX is defined and returns the last error.
void	set_urc_handler (const char *prefix, Callback< void()> callback)
	Set callback function for URC.
nsapi_error_t	get_last_error () const
	returns the last error while parsing AT responses.
device_err_t	get_last_device_error () const
	returns the last device error while parsing AT responses.
void	inc_ref_count ()
	Increase reference count.
void	dec_ref_count ()
	Decrease reference count.
int	get_ref_count ()
	Get the current reference count.
void	set_at_timeout (uint32_t timeout_milliseconds, bool default_timeout=false)
	Set timeout in milliseconds for AT commands.
void	restore_at_timeout ()
	Restore timeout to previous timeout.
void	clear_error ()
	Clear pending error flag.
void	flush ()
	Flushes the underlying stream.
void	process_oob ()
	Tries to find oob's from the AT response.
void	set_file_handle (FileHandle *fh)
	Set file handle, which is used for reading AT responses and writing AT commands.
void	set_is_filehandle_usable (bool usable)
	Set is file handle usable.
bool	sync (int timeout_ms)
	Synchronize AT command and response handling to modem.
void	set_send_delay (uint16_t send_delay)
	Sets the delay to be applied before sending any AT command.
void	set_baud (int baud_rate)
	Sets UARTSerial filehandle to given baud rate.
virtual void	cmd_start (const char *cmd)
	Starts the command writing by clearing the last error and writing the given command.
void	cmd_start_stop (const char cmd, const char cmd_chr, const char *format="",...)
	cmd_start_stop Starts an AT command, writes given variadic arguments and stops the command.
nsapi_error_t	at_cmd_str (const char cmd, const char cmd_chr, char resp_buf, size_t resp_buf_size, const char format="",...)
	at_cmd_str Send an AT command and read a single string response.
nsapi_error_t	at_cmd_int (const char cmd, const char cmd_chr, int &resp, const char *format="",...)
	at_cmd_int Send an AT command and read a single integer response.
nsapi_error_t	at_cmd_discard (const char cmd, const char cmd_chr, const char *format="",...)
	at_cmd_discard Send an AT command and read and discard a response.
void	write_int (int32_t param)
	Writes integer type AT command subparameter.
void	write_string (const char *param, bool useQuotations=true)
	Writes string type AT command subparamater.
void	cmd_stop ()
	Stops the AT command by writing command-line terminator CR to mark command as finished.
void	cmd_stop_read_resp ()
	Stops the AT command by writing command-line terminator CR to mark command as finished and reads the OK/ERROR response.
size_t	write_bytes (const uint8_t *data, size_t len)
	Write bytes without any subparameter delimiters, such as comma.
void	set_stop_tag (const char *stop_tag_seq)
	Sets the stop tag for the current scope (response/information response/element) Parameter's reading routines will stop the reading when such tag is found and will set the found flag.
void	set_delimiter (char delimiter)
	Sets the delimiter between parameters or between elements of the information response.
void	set_default_delimiter ()
	Sets the delimiter to default value defined by DEFAULT_DELIMITER.
void	use_delimiter (bool use_delimiter)
	Defines behaviour for using or ignoring the delimiter within an AT command.
void	skip_param (uint32_t count=1)
	Consumes the reading buffer up to the delimiter or stop_tag.
void	skip_param (ssize_t len, uint32_t count)
	Consumes the given length from the reading buffer.
ssize_t	read_bytes (uint8_t *buf, size_t len)
	Reads given number of bytes from receiving buffer without checking any subparameter delimiters, such as comma.
ssize_t	read_string (char *str, size_t size, bool read_even_stop_tag=false)
	Reads chars from reading buffer.
ssize_t	read_hex_string (char *str, size_t size)
	Reads chars representing hex ascii values and converts them to the corresponding chars.
void	write_hex_string (char *str, size_t size)
	Converts contained chars to their hex ascii value and writes the resulting string to the file handle For example: "AV" to "4156".
int32_t	read_int ()
	Reads as string and converts result to integer.
void	resp_start (const char *prefix=NULL, bool stop=false)
	This looks for necessary matches: prefix, OK, ERROR, URCs and sets the correct scope.
void	resp_stop ()
	Ends all scopes starting from current scope.
bool	info_resp ()
	Looks for matching the prefix given to resp_start() call.
bool	info_elem (char start_tag)
	Looks for matching the start tag.
bool	consume_to_stop_tag ()
	Consumes the received content until current stop tag is found.
int	get_3gpp_error ()
	Return the last 3GPP error code.
void	set_debug (bool debug_on)
	AT debugging, when enabled will print all data read and written, non-printable chars are printed as "[%d]".
bool	get_debug () const
	Get degug state set by set_debug.
Static Public Member Functions
static ATHandler *	get_instance (FileHandle fileHandle, events::EventQueue &queue, uint32_t timeout, const char delimiter, uint16_t send_delay, bool debug_on)
	Get a new ATHandler instance, and update the linked list.
static void	set_at_timeout_list (uint32_t timeout_milliseconds, bool default_timeout=false)
	Set timeout in milliseconds for all ATHandlers in the _atHandlers list.
static void	set_debug_list (bool debug_on)
	Set debug_on for all ATHandlers in the _atHandlers list.

Detailed Description

Class for sending AT commands and parsing AT responses.

Definition at line 68 of file ATHandler.h.

Constructor & Destructor Documentation

ATHandler	(	FileHandle *	fh,
		events::EventQueue &	queue,
		uint32_t	timeout,
		const char *	output_delimiter,
		uint16_t	send_delay = `0`
	)

Constructor.

Parameters:

fh	file handle used for reading AT responses and writing AT commands
queue	Event queue used to transfer sigio events to this thread
timeout	Timeout when reading for AT response
output_delimiter	delimiter used when parsing at responses, "\r" should be used as output_delimiter
send_delay	the minimum delay in ms between the end of last response and the beginning of a new command

Definition at line 164 of file ATHandler.cpp.

Member Function Documentation

nsapi_error_t at_cmd_discard	(	const char *	cmd,
		const char *	cmd_chr,
		const char *	format = `""`,
			...
	)

at_cmd_discard Send an AT command and read and discard a response.

Locks and unlocks ATHandler for operation

Parameters:

cmd	AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chr	Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
format	Format string for variadic arguments to be added to AT command; No separator needed. Use d for integer, s for string and b for byte string (requires 2 arguments: string and length)

Returns:: last error that happened when parsing AT responses

Definition at line 1404 of file ATHandler.cpp.

nsapi_error_t at_cmd_int	(	const char *	cmd,
		const char *	cmd_chr,
		int &	resp,
		const char *	format = `""`,
			...
	)

at_cmd_int Send an AT command and read a single integer response.

Locks and unlocks ATHandler for operation

Parameters:

cmd	AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chr	Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
resp	Integer to hold response
format	Format string for variadic arguments to be added to AT command; No separator needed. Use d for integer, s for string and b for byte string (requires 2 arguments: string and length)

Returns:: last error that happened when parsing AT responses

Definition at line 1380 of file ATHandler.cpp.

nsapi_error_t at_cmd_str	(	const char *	cmd,
		const char *	cmd_chr,
		char *	resp_buf,
		size_t	resp_buf_size,
		const char *	format = `""`,
			...
	)

at_cmd_str Send an AT command and read a single string response.

Locks and unlocks ATHandler for operation

Parameters:

cmd	AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chr	Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
resp_buf	Response buffer
resp_buf_size	Response buffer size
format	Format string for variadic arguments to be added to AT command; No separator needed. Use d for integer, s for string and b for byte string (requires 2 arguments: string and length)

Returns:: last error that happened when parsing AT responses

Definition at line 1351 of file ATHandler.cpp.

void clear_error ( )

Clear pending error flag.

By default, error is cleared only in lock().

Definition at line 914 of file ATHandler.cpp.

nsapi_error_t close ( )

Close and delete the current ATHandler instance, if the reference count to it is 0.

Close() can be only called, if the ATHandler was opened with get_instance()

Returns:: NSAPI_ERROR_OK on success, NSAPI_ERROR_PARAMETER on failure

Definition at line 98 of file ATHandler.cpp.

void cmd_start ( const char * cmd ) [virtual]

Starts the command writing by clearing the last error and writing the given command.

In case of failure when writing, the last error is set to NSAPI_ERROR_DEVICE_ERROR.

Parameters:

cmd	AT command to be written to modem

Definition at line 1278 of file ATHandler.cpp.

void cmd_start_stop	(	const char *	cmd,
		const char *	cmd_chr,
		const char *	format = `""`,
			...
	)

cmd_start_stop Starts an AT command, writes given variadic arguments and stops the command.

Use this command when you need multiple response parameters to be handled. NOTE: Does not lock ATHandler for process!

Parameters:

cmd	AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chr	Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
format	Format string for variadic arguments to be added to AT command; No separator needed. Use d for integer, s for string and b for byte string (requires 2 arguments: string and length)

Definition at line 1339 of file ATHandler.cpp.

void cmd_stop ( )

Stops the AT command by writing command-line terminator CR to mark command as finished.

Definition at line 1455 of file ATHandler.cpp.

void cmd_stop_read_resp ( )

Stops the AT command by writing command-line terminator CR to mark command as finished and reads the OK/ERROR response.

Definition at line 1464 of file ATHandler.cpp.

bool consume_to_stop_tag ( )

Consumes the received content until current stop tag is found.

Returns:: true if stop tag is found, false otherwise

Definition at line 1168 of file ATHandler.cpp.

void dec_ref_count ( )

Decrease reference count.

Used for counting references to this instance. Note that this should be used with care, if the ATHandler was taken into use with get_instance()

Definition at line 257 of file ATHandler.cpp.

void flush ( )

Flushes the underlying stream.

Definition at line 1544 of file ATHandler.cpp.

int get_3gpp_error ( )

Return the last 3GPP error code.

Returns:: last 3GPP error code

Definition at line 943 of file ATHandler.cpp.

bool get_debug ( ) const

Get degug state set by set_debug.

Returns:: current state of debug

Definition at line 219 of file ATHandler.cpp.

FileHandle * get_file_handle ( )

Return used file handle.

Returns:: used file handle

Definition at line 267 of file ATHandler.cpp.

ATHandler * get_instance	(	FileHandle *	fileHandle,
		events::EventQueue &	queue,
		uint32_t	timeout,
		const char *	delimiter,
		uint16_t	send_delay,
		bool	debug_on
	)		`[static]`

Get a new ATHandler instance, and update the linked list.

Once the use of the ATHandler has finished, call to close() has to be made

Parameters:

fileHandle	filehandle used for reading AT responses and writing AT commands. If there is already an ATHandler with the same fileHandle pointer, then a pointer to that ATHandler instance will be returned with that ATHandler's queue, timeout, delimiter, send_delay and debug_on values
queue	Event queue used to transfer sigio events to this thread
timeout	Timeout when reading for AT response
delimiter	delimiter used when parsing at responses, "\r" should be used as output_delimiter
send_delay	the minimum delay in ms between the end of last response and the beginning of a new command
debug_on	Set true to enable debug traces

Returns:: NULL, if fileHandle is not set, or a pointer to an existing ATHandler, if the fileHandle is already in use. Otherwise a pointer to a new ATHandler instance is returned

Definition at line 69 of file ATHandler.cpp.

device_err_t get_last_device_error ( ) const

returns the last device error while parsing AT responses.

Actually AT error (CME/CMS).

Returns:: last error struct device_err_t

Definition at line 927 of file ATHandler.cpp.

nsapi_error_t get_last_error ( ) const

returns the last error while parsing AT responses.

Returns:: last error

Definition at line 922 of file ATHandler.cpp.

int get_ref_count ( )

Get the current reference count.

Used for counting references to this instance.

Returns:: current reference count

Definition at line 262 of file ATHandler.cpp.

void inc_ref_count ( )

Increase reference count.

Used for counting references to this instance. Note that this should be used with care, if the ATHandler was taken into use with get_instance()

Definition at line 252 of file ATHandler.cpp.

bool info_elem ( char start_tag )

Looks for matching the start tag.

If needed, it ends the scope of a previous element. Sets the element scope if start tag is found and information response scope if start tag is not found.

Parameters:

start_tag tag to be matched to begin parsing an element of an information response

Returns:: true if new element is found, false otherwise

Definition at line 1099 of file ATHandler.cpp.

bool info_resp ( )

Looks for matching the prefix given to resp_start() call.

If needed, it ends the scope of a previous information response. Sets the information response scope if new prefix is found and response scope if prefix is not found.

Returns:: true if prefix defined for information response is not empty string and is found, false otherwise.

Definition at line 1069 of file ATHandler.cpp.

void lock ( void )

Locks the mutex for file handle if AT_HANDLER_MUTEX is defined.

Definition at line 366 of file ATHandler.cpp.

void process_oob ( )

Tries to find oob's from the AT response.

Call the urc callback if one is found.

Definition at line 414 of file ATHandler.cpp.

ssize_t read_bytes	(	uint8_t *	buf,
		size_t	len
	)

Reads given number of bytes from receiving buffer without checking any subparameter delimiters, such as comma.

Parameters:

buf	output buffer for the read
len	maximum number of bytes to read

Returns:: number of successfully read bytes or -1 in case of error

Definition at line 581 of file ATHandler.cpp.

ssize_t read_hex_string	(	char *	str,
		size_t	size
	)

Reads chars representing hex ascii values and converts them to the corresponding chars.

For example: "4156" to "AV". Terminates with null. Skips the quotation marks. Stops on delimiter or stop tag.

Parameters:

str	output buffer for the read
size	maximum number of chars to output

Returns:: length of output string or -1 in case of read timeout before delimiter or stop tag is found

Definition at line 686 of file ATHandler.cpp.

int32_t read_int ( )

Reads as string and converts result to integer.

Supports only non-negative integers.

Returns:: the non-negative integer or -1 in case of error.

Definition at line 772 of file ATHandler.cpp.

ssize_t read_string	(	char *	str,
		size_t	size,
		bool	read_even_stop_tag = `false`
	)

Reads chars from reading buffer.

Terminates with null. Skips the quotation marks. Stops on delimiter or stop tag.

Parameters:

str	output buffer for the read
size	maximum number of chars to output including NULL
read_even_stop_tag	if true then try to read even if the stop tag was found previously

Returns:: length of output string or -1 in case of read timeout before delimiter or stop tag is found

Definition at line 617 of file ATHandler.cpp.

void resp_start	(	const char *	prefix = `NULL`,
		bool	stop = `false`
	)

This looks for necessary matches: prefix, OK, ERROR, URCs and sets the correct scope.

Parameters:

prefix	string to be matched from receiving buffer. If not NULL and match succeeds, then scope will be set as information response(info_type)
stop	flag to indicate if we go to information response scope or not. (needed when nothing is expected to be received anymore after the prefix match: sms case: "> ", bc95 reboot case)

Definition at line 1043 of file ATHandler.cpp.

void resp_stop ( )

Ends all scopes starting from current scope.

Consumes everything until the scope's stop tag is found, then goes to next scope until response scope is ending. URC match is checked during response scope ending, for every new line / CRLF.

Possible sequence: element scope -> information response scope -> response scope

Definition at line 1190 of file ATHandler.cpp.

void restore_at_timeout ( )

Restore timeout to previous timeout.

Handy if there is a need to change timeout temporarily.

Definition at line 405 of file ATHandler.cpp.

void set_at_timeout	(	uint32_t	timeout_milliseconds,
		bool	default_timeout = `false`
	)

Set timeout in milliseconds for AT commands.

Parameters:

timeout_milliseconds	Timeout in milliseconds
default_timeout	Store as default timeout

Definition at line 392 of file ATHandler.cpp.

void set_at_timeout_list	(	uint32_t	timeout_milliseconds,
		bool	default_timeout = `false`
	)		`[static]`

Set timeout in milliseconds for all ATHandlers in the _atHandlers list.

Parameters:

timeout_milliseconds	Timeout in milliseconds
default_timeout	Store as default timeout

Definition at line 129 of file ATHandler.cpp.

void set_baud ( int baud_rate )

Sets UARTSerial filehandle to given baud rate.

Parameters:

baud_rate

Definition at line 1657 of file ATHandler.cpp.

void set_debug ( bool debug_on )

AT debugging, when enabled will print all data read and written, non-printable chars are printed as "[%d]".

AT debug can be enabled at compile time using MBED_CONF_CELLULAR_DEBUG_AT flag or at runtime calling set_debug(). Note that MBED_CONF_MBED_TRACE_ENABLE must also be enabled.

Parameters:

debug_on Enable/disable debugging

Definition at line 214 of file ATHandler.cpp.

void set_debug_list ( bool debug_on ) [static]

Set debug_on for all ATHandlers in the _atHandlers list.

Parameters:

debug_on Set true to enable debug traces

Definition at line 140 of file ATHandler.cpp.

void set_default_delimiter ( )

Sets the delimiter to default value defined by DEFAULT_DELIMITER.

Definition at line 802 of file ATHandler.cpp.

void set_delimiter ( char delimiter )

Sets the delimiter between parameters or between elements of the information response.

Parameter's reading routines will stop when such char is read.

Parameters:

delimiter char to be set as _delimiter

Definition at line 797 of file ATHandler.cpp.

void set_file_handle ( FileHandle * fh )

Set file handle, which is used for reading AT responses and writing AT commands.

Parameters:

fh	file handle used for reading AT responses and writing AT commands

Definition at line 272 of file ATHandler.cpp.

void set_is_filehandle_usable ( bool usable )

Set is file handle usable.

Some situations like after going to data mode, file handle is not usable anymore. Any items in queue are not to be processed.

Parameters:

usable true for usable filehandle

Definition at line 284 of file ATHandler.cpp.

void set_send_delay ( uint16_t send_delay )

Sets the delay to be applied before sending any AT command.

Parameters:

send_delay the minimum delay in ms between the end of last response and the beginning of a new command

Definition at line 1635 of file ATHandler.cpp.

void set_stop_tag ( const char * stop_tag_seq )

Sets the stop tag for the current scope (response/information response/element) Parameter's reading routines will stop the reading when such tag is found and will set the found flag.

Consume routines will read everything until such tag is found.

Parameters:

stop_tag_seq string to be set as stop tag

Definition at line 825 of file ATHandler.cpp.

void set_urc_handler	(	const char *	prefix,
		Callback< void()>	callback
	)

Set callback function for URC.

Parameters:

prefix	URC text to look for, e.g. "+CMTI:". Maximum length is BUFF_SIZE.
callback	function to call on prefix, or 0 to remove callback

Definition at line 299 of file ATHandler.cpp.

void skip_param ( uint32_t count = 1 )

Consumes the reading buffer up to the delimiter or stop_tag.

Parameters:

count number of parameters to be skipped

Definition at line 529 of file ATHandler.cpp.

void skip_param	(	ssize_t	len,
		uint32_t	count
	)

Consumes the given length from the reading buffer.

Parameters:

len	length to be consumed from reading buffer
count	number of parameters to be skipped

Definition at line 561 of file ATHandler.cpp.

bool sync ( int timeout_ms )

Synchronize AT command and response handling to modem.

Parameters:

timeout_ms ATHandler timeout when trying to sync. Will be restored when function returns.

Returns:: true is synchronization was successful, false in case of failure

Definition at line 1600 of file ATHandler.cpp.

void unlock ( void )

Unlocks the mutex for file handle if AT_HANDLER_MUTEX is defined.

Definition at line 375 of file ATHandler.cpp.

nsapi_error_t unlock_return_error ( )

Locks the mutex for file handle if AT_HANDLER_MUTEX is defined and returns the last error.

Returns:: last error that happened when parsing AT responses

Definition at line 385 of file ATHandler.cpp.

void use_delimiter ( bool use_delimiter )

Defines behaviour for using or ignoring the delimiter within an AT command.

Parameters:

use_delimiter indicating if delimiter should be used or not

Definition at line 807 of file ATHandler.cpp.

size_t write_bytes	(	const uint8_t *	data,
		size_t	len
	)

Write bytes without any subparameter delimiters, such as comma.

In case of failure when writing, the last error is set to NSAPI_ERROR_DEVICE_ERROR.

Parameters:

data	bytes to be written to modem
len	length of data string

Returns:: number of characters successfully written

Definition at line 1471 of file ATHandler.cpp.

void write_hex_string	(	char *	str,
		size_t	size
	)

Converts contained chars to their hex ascii value and writes the resulting string to the file handle For example: "AV" to "4156".

Parameters:

str	input buffer to be converted to hex ascii
size	of the input param str

Definition at line 1640 of file ATHandler.cpp.

void write_int ( int32_t param )

Writes integer type AT command subparameter.

Starts with the delimiter if not the first param after cmd_start. In case of failure when writing, the last error is set to NSAPI_ERROR_DEVICE_ERROR.

Parameters:

param int to be written to modem as AT command subparameter

Definition at line 1419 of file ATHandler.cpp.

void write_string	(	const char *	param,
		bool	useQuotations = `true`
	)

Writes string type AT command subparamater.

Quotes are added to surround the given string. Starts with the delimiter if not the first param after cmd_start. In case of failure when writing, the last error is set to NSAPI_ERROR_DEVICE_ERROR.

Parameters:

param	string to be written to modem as AT command subparameter
useQuotations	flag indicating whether the string should be included in quotation marks

Definition at line 1435 of file ATHandler.cpp.

Type:	Library
Created:	17 Dec 2019
Imports:	79
Forks:	0
Commits:	2
Dependents:	2
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

ATHandler Class Reference

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

ATHandler Class Reference

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning