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

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

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

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

Clear pending error flag.

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

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

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

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)

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

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

Consumes the received content until current stop tag is found.

Returns

true if stop tag is found, false otherwise

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()

Flushes the underlying stream.

Return the last 3GPP error code.

Returns

last 3GPP error code

Get degug state set by set_debug.

Returns

current state of debug

Return used file handle.

Returns

used file handle

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

returns the last device error while parsing AT responses.

Actually AT error (CME/CMS).

Returns

last error struct device_err_t

returns the last error while parsing AT responses.

Returns

last error

Get the current reference count.

Used for counting references to this instance.

Returns

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

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

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.

Locks the mutex for file handle if AT_HANDLER_MUTEX is defined.

Tries to find oob's from the AT response.

Call the urc callback if one is found.

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

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

Reads as string and converts result to integer.

Supports only non-negative integers.

Returns

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

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

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)

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

Restore timeout to previous timeout.

Handy if there is a need to change timeout temporarily.

Set timeout in milliseconds for AT commands.

Parameters

timeout_milliseconds	Timeout in milliseconds
default_timeout	Store as default timeout

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

Parameters

timeout_milliseconds	Timeout in milliseconds
default_timeout	Store as default timeout

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

Set debug_on for all ATHandlers in the _atHandlers list.

Parameters

debug_on

Set true to enable debug traces

Sets the delimiter to default value defined by DEFAULT_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

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

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

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

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

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

Consumes the reading buffer up to the delimiter or stop_tag.

Parameters

count

number of parameters to be skipped

Consumes the given length from the reading buffer.

Parameters

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

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

Unlocks the mutex for file handle if AT_HANDLER_MUTEX is defined.

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

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

Parameters

use_delimiter

indicating if delimiter should be used or not

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

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

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

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