Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Public Member Functions | Static Public Member Functions
ATHandler Class Reference

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. More...
 
FileHandleget_file_handle ()
 Return used file handle. More...
 
nsapi_error_t close ()
 Close and delete the current ATHandler instance, if the reference count to it is 0. More...
 
void lock ()
 Locks the mutex for file handle if AT_HANDLER_MUTEX is defined. More...
 
void unlock ()
 Unlocks the mutex for file handle if AT_HANDLER_MUTEX is defined. More...
 
nsapi_error_t unlock_return_error ()
 Locks the mutex for file handle if AT_HANDLER_MUTEX is defined and returns the last error. More...
 
void set_urc_handler (const char *prefix, Callback< void()> callback)
 Set callback function for URC. More...
 
nsapi_error_t get_last_error () const
 returns the last error while parsing AT responses. More...
 
device_err_t get_last_device_error () const
 returns the last device error while parsing AT responses. More...
 
void inc_ref_count ()
 Increase reference count. More...
 
void dec_ref_count ()
 Decrease reference count. More...
 
int get_ref_count ()
 Get the current reference count. More...
 
void set_at_timeout (uint32_t timeout_milliseconds, bool default_timeout=false)
 Set timeout in milliseconds for AT commands. More...
 
void restore_at_timeout ()
 Restore timeout to previous timeout. More...
 
void clear_error ()
 Clear pending error flag. More...
 
void flush ()
 Flushes the underlying stream. More...
 
void process_oob ()
 Tries to find oob's from the AT response. More...
 
void set_file_handle (FileHandle *fh)
 Set file handle, which is used for reading AT responses and writing AT commands. More...
 
void set_is_filehandle_usable (bool usable)
 Set is file handle usable. More...
 
bool sync (int timeout_ms)
 Synchronize AT command and response handling to modem. More...
 
virtual void cmd_start (const char *cmd)
 Starts the command writing by clearing the last error and writing the given command. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void write_int (int32_t param)
 Writes integer type AT command subparameter. More...
 
void write_string (const char *param, bool useQuotations=true)
 Writes string type AT command subparamater. More...
 
void cmd_stop ()
 Stops the AT command by writing command-line terminator CR to mark command as finished. More...
 
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. More...
 
size_t write_bytes (const uint8_t *data, size_t len)
 Write bytes without any subparameter delimiters, such as comma. More...
 
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. More...
 
void set_delimiter (char delimiter)
 Sets the delimiter between parameters or between elements of the information response. More...
 
void set_default_delimiter ()
 Sets the delimiter to default value defined by DEFAULT_DELIMITER. More...
 
void use_delimiter (bool use_delimiter)
 Defines behaviour for using or ignoring the delimiter within an AT command. More...
 
void skip_param (uint32_t count=1)
 Consumes the reading buffer up to the delimiter or stop_tag. More...
 
void skip_param (ssize_t len, uint32_t count)
 Consumes the given length from the reading buffer. More...
 
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. More...
 
ssize_t read_string (char *str, size_t size, bool read_even_stop_tag=false)
 Reads chars from reading buffer. More...
 
ssize_t read_hex_string (char *str, size_t size)
 Reads chars representing hex ascii values and converts them to the corresponding chars. More...
 
int32_t read_int ()
 Reads as string and converts result to integer. More...
 
void resp_start (const char *prefix=NULL, bool stop=false)
 This looks for necessary matches: prefix, OK, ERROR, URCs and sets the correct scope. More...
 
void resp_stop ()
 Ends all scopes starting from current scope. More...
 
bool info_resp ()
 Looks for matching the prefix given to resp_start() call. More...
 
bool info_elem (char start_tag)
 Looks for matching the start tag. More...
 
bool consume_to_stop_tag ()
 Consumes the received content until current stop tag is found. More...
 
int get_3gpp_error ()
 Return the last 3GPP error code. More...
 
void set_debug (bool debug_on)
 AT debugging, when enabled will print all data read and written, non-printable chars are printed as "[%d]". More...
 
bool get_debug () const
 Get degug state set by set_debug. More...
 

Static Public Member Functions

static ATHandlerget_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. More...
 
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. More...
 
static void set_debug_list (bool debug_on)
 Set debug_on for all ATHandlers in the _atHandlers list. More...
 

Detailed Description

Class for sending AT commands and parsing AT responses.

Definition at line 63 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
fhfile handle used for reading AT responses and writing AT commands
queueEvent queue used to transfer sigio events to this thread
timeoutTimeout when reading for AT response
output_delimiterdelimiter used when parsing at responses, "\r" should be used as output_delimiter
send_delaythe minimum delay in ms between the end of last response and the beginning of a new command

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
cmdAT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chrChar to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
formatFormat 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
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
cmdAT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chrChar to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
respInteger to hold response
formatFormat 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
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
cmdAT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chrChar to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
resp_bufResponse buffer
resp_buf_sizeResponse buffer size
formatFormat 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
void clear_error ( )

Clear pending error flag.

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

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
virtual 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
cmdAT command to be written to modem
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
cmdAT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
cmd_chrChar to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
formatFormat 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)
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.

bool consume_to_stop_tag ( )

Consumes the received content until current stop tag is found.

Returns
true if stop tag is found, false otherwise
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()

void flush ( )

Flushes the underlying stream.

int get_3gpp_error ( )

Return the last 3GPP error code.

Returns
last 3GPP error code
bool get_debug ( ) const

Get degug state set by set_debug.

Returns
current state of debug
FileHandle* get_file_handle ( )

Return used file handle.

Returns
used file handle
static 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
fileHandlefilehandle 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
queueEvent queue used to transfer sigio events to this thread
timeoutTimeout when reading for AT response
delimiterdelimiter used when parsing at responses, "\r" should be used as output_delimiter
send_delaythe minimum delay in ms between the end of last response and the beginning of a new command
debug_onSet 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
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
nsapi_error_t get_last_error ( ) const

returns the last error while parsing AT responses.

Returns
last error
int get_ref_count ( )

Get the current reference count.

Used for counting references to this instance.

Returns
current reference count
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()

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_tagtag to be matched to begin parsing an element of an information response
Returns
true if new element is found, false otherwise
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.
void lock ( )

Locks the mutex for file handle if AT_HANDLER_MUTEX is defined.

void process_oob ( )

Tries to find oob's from the AT response.

Call the urc callback if one is found.

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
bufoutput buffer for the read
lenmaximum number of bytes to read
Returns
number of successfully read bytes or -1 in case of error
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
stroutput buffer for the read
sizemaximum number of chars to output
Returns
length of output string or -1 in case of read timeout before delimiter or stop tag is found
int32_t read_int ( )

Reads as string and converts result to integer.

Supports only positive integers.

Returns
the positive integer or -1 in case of error.
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
stroutput buffer for the read
sizemaximum number of chars to output including NULL
read_even_stop_tagif 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
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
prefixstring to be matched from receiving buffer. If not NULL and match succeeds, then scope will be set as information response(info_type)
stopflag 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)
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

void restore_at_timeout ( )

Restore timeout to previous timeout.

Handy if there is a need to change timeout temporarily.

void set_at_timeout ( uint32_t  timeout_milliseconds,
bool  default_timeout = false 
)

Set timeout in milliseconds for AT commands.

Parameters
timeout_millisecondsTimeout in milliseconds
default_timeoutStore as default timeout
static 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_millisecondsTimeout in milliseconds
default_timeoutStore as default timeout
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_onEnable/disable debugging
static void set_debug_list ( bool  debug_on)
static

Set debug_on for all ATHandlers in the _atHandlers list.

Parameters
debug_onSet true to enable debug traces
void set_default_delimiter ( )

Sets the delimiter to default value defined by DEFAULT_DELIMITER.

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
delimiterchar to be set as _delimiter
void set_file_handle ( FileHandle fh)

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

Parameters
fhfile handle used for reading AT responses and writing AT commands
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
usabletrue for usable filehandle
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_seqstring to be set as stop tag
void set_urc_handler ( const char *  prefix,
Callback< void()>  callback 
)

Set callback function for URC.

Parameters
prefixURC text to look for, e.g. "+CMTI:". Maximum length is BUFF_SIZE.
callbackfunction to call on prefix, or 0 to remove callback
void skip_param ( uint32_t  count = 1)

Consumes the reading buffer up to the delimiter or stop_tag.

Parameters
countnumber of parameters to be skipped
void skip_param ( ssize_t  len,
uint32_t  count 
)

Consumes the given length from the reading buffer.

Parameters
lenlength to be consumed from reading buffer
countnumber of parameters to be skipped
bool sync ( int  timeout_ms)

Synchronize AT command and response handling to modem.

Parameters
timeout_msATHandler timeout when trying to sync. Will be restored when function returns.
Returns
true is synchronization was successful, false in case of failure
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.

Returns
last error that happened when parsing AT responses
void use_delimiter ( bool  use_delimiter)

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

Parameters
use_delimiterindicating if delimiter should be used or not
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
databytes to be written to modem
lenlength of data string
Returns
number of characters successfully written
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
paramint to be written to modem as AT command subparameter
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
paramstring to be written to modem as AT command subparameter
useQuotationsflag indicating whether the string should be included in quotation marks
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.