Nicolas Borla / Mbed OS BBR_1Ebene
Embed: (wiki syntax)

« Back to documentation index

ATHandler Class Reference

ATHandler Class Reference

Class ATHandler. More...

#include <ATHandler.h>

Public Member Functions

 ATHandler (FileHandle *fh, events::EventQueue &queue, int timeout, const char *output_delimiter, uint16_t send_delay=0)
 Constructor.
FileHandleget_file_handle ()
 Return used file handle.
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.
nsapi_error_t set_urc_handler (const char *prefix, mbed::Callback< void()> callback)
 Set the urc callback for urc.
void remove_urc_handler (const char *prefix, mbed::Callback< void()> callback)
 Remove urc handler from linked list of urc's.
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_filehandle_sigio ()
 Set sigio for the current file handle.
void set_file_handle (FileHandle *fh)
 Set file handle, which is used for reading AT responses and writing AT commands.
void cmd_start (const char *cmd)
 Starts the command writing by clearing the last error and writing the given command.
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.
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 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.
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.
void enable_debug (bool enable)
 Sets _debug_on flag.
int get_3gpp_error ()
 Return the last 3GPP error code.

Detailed Description

Class ATHandler.

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,
int  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

Definition at line 64 of file ATHandler.cpp.


Member Function Documentation

void clear_error (  )

Clear pending error flag.

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

Definition at line 671 of file ATHandler.cpp.

void cmd_start ( const char *  cmd )

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

Definition at line 1013 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 1075 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 927 of file ATHandler.cpp.

void dec_ref_count (  )

Decrease reference count.

Used for counting references to this instance.

Definition at line 136 of file ATHandler.cpp.

void enable_debug ( bool  enable )

Sets _debug_on flag.

Parameters:
enablevalue to be set for _debug_on flag

Definition at line 114 of file ATHandler.cpp.

void flush (  )

Flushes the underlying stream.

Definition at line 1139 of file ATHandler.cpp.

int get_3gpp_error (  )

Return the last 3GPP error code.

Returns:
last 3GPP error code

Definition at line 700 of file ATHandler.cpp.

FileHandle * get_file_handle (  )

Return used file handle.

Returns:
used file handle

Definition at line 146 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 684 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 679 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 141 of file ATHandler.cpp.

void inc_ref_count (  )

Increase reference count.

Used for counting references to this instance.

Definition at line 131 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_tagtag to be matched to begin parsing an element of an information response
Returns:
true if new element is found, false otherwise

Definition at line 864 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 new information response is found, false otherwise

Definition at line 833 of file ATHandler.cpp.

void lock ( void   )

Locks the mutex for file handle if AT_HANDLER_MUTEX is defined.

Definition at line 239 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 284 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:
bufoutput buffer for the read
lenmaximum number of bytes to read
Returns:
number of successfully read bytes or -1 in case of error

Definition at line 443 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:
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

Definition at line 531 of file ATHandler.cpp.

int read_int (  )

Reads as string and converts result to integer.

Supports only positive integers.

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

Definition at line 536 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:
stroutput buffer for the read
sizemaximum number of chars to output
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

Definition at line 526 of file ATHandler.cpp.

void remove_urc_handler ( const char *  prefix,
mbed::Callback< void()>  callback 
)

Remove urc handler from linked list of urc's.

Parameters:
prefixRegister urc prefix for callback. Urc could be for example "+CMTI: "
callbackCallback, which is called if urc is found in AT response

Definition at line 198 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:
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)

Definition at line 803 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. Possible sequence: element scope -> information response scope -> response scope

Definition at line 946 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 277 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_millisecondsTimeout in milliseconds
default_timeoutStore as default timeout

Definition at line 266 of file ATHandler.cpp.

void set_default_delimiter (  )

Sets the delimiter to default value defined by DEFAULT_DELIMITER.

Definition at line 559 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:
delimiterchar to be set as _delimiter

Definition at line 554 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:
fhfile handle used for reading AT responses and writing AT commands

Definition at line 151 of file ATHandler.cpp.

void set_filehandle_sigio (  )

Set sigio for the current file handle.

Sigio event goes through eventqueue so that it's handled in current thread.

Definition at line 159 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_seqstring to be set as stop tag

Definition at line 576 of file ATHandler.cpp.

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

Set the urc callback for urc.

If urc is found when parsing AT responses, then call if called. If urc is already set then it's not set twice.

Parameters:
prefixRegister urc prefix for callback. Urc could be for example "+CMTI: "
callbackCallback, which is called if urc is found in AT response
Returns:
NSAPI_ERROR_OK or NSAPI_ERROR_NO_MEMORY if no memory

Definition at line 169 of file ATHandler.cpp.

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

Definition at line 392 of file ATHandler.cpp.

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

Definition at line 422 of file ATHandler.cpp.

void unlock ( void   )

Unlocks the mutex for file handle if AT_HANDLER_MUTEX is defined.

Definition at line 248 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 259 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:
databytes to be written to modem
lenlength of data string
Returns:
number of characters successfully written

Definition at line 1085 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:
paramint to be written to modem as AT command subparameter

Definition at line 1037 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:
paramstring to be written to modem as AT command subparameter
useQuotationsflag indicating whether the string should be included in quotation marks

Definition at line 1054 of file ATHandler.cpp.