API

class atcmd.parser.ATParser

An AT (Hayes command) parser based on a subset of the ITU-T V.250 standard.

Conformant with the subset of V.250 required for implementation of the Bluetooth Headset and Handsfree Profiles, as per Bluetooth SIP specifications. Also implements some V.250 features not required by Bluetooth - such as chained commands.

Command handlers are registered with an ATParser instance. These handlers are invoked when command lines are processed by the ATParser.process() method.

The ATParser object accepts a new command line to parse via its process() method. It breaks each command line into one or more commands. Each command is parsed for name, type, and (optional) arguments, and an appropriate external handler method is called through the ATCommandHandler interface.

The command types are:

  • Basic Command. For example "ATDT1234567890". Basic command names are a single character (e.g. "D"), and everything following this character is passed to the handler as a string argument (e.g. "T1234567890").
  • Action Command. For example "AT+CIMI". The command name is "CIMI", and there are no arguments for action commands.
  • Read Command. For example "AT+VGM?". The command name is "VGM", and there are no arguments for get commands.
  • Set Command. For example "AT+VGM=14". The command name is "VGM", and there is a single integer argument in this case. In the general case there can be zero or more arguments (comma delimited) each of integer or string type.
  • Test Command. For example "AT+VGM=?". No arguments.

In V.250 the last four command types are known as Extended Commands, and they are used heavily in Bluetooth for example.

Basic commands cannot be chained in this implementation. For Bluetooth headset/handsfree use this is acceptable, because they only use the basic commands ATA and ATD, which are not allowed to be chained. For general V.250 use we would need to improve this class to allow Basic command chaining - however it’s tricky to get right because there is no delimiter for Basic command chaining.

Extended commands can be chained. For example:

AT+VGM?;+VGM=14;+CIMI

This is equivalent to:

AT+VGM?
AT+VGM=14
AT+CIMI

Except that only one final result code is returned (although several intermediate responses may be returned), and as soon as one command in the chain fails the rest are abandoned.

Handlers are registered by there command name via register(Char c, ...) or register(String s, ...). Handlers for basic command should be registered by the basic command character, and handlers for Extended commands should be registered by string.

References:

  • ITU-T Recommendation V.250
  • ETSI TS 127.007 (AT Command set for User Equipment, 3GPP TS 27.007)
  • Bluetooth Headset Profile Spec (K6)
  • Bluetooth Handsfree Profile Spec (HFP 1.5)
clean(data)

Strip input of whitespace and force uppercase - except sections inside quotes. Also fixes unmatched quotes (by appending a quote). Double quotes ” are the only quotes allowed by V.250.

Parameters:data (str) – Command string.
Return type:str
findChar(ch, data, fromIndex)

Find a character ch, ignoring quoted sections.

Return length of data if not found.

Parameters:
  • ch (str) –
  • data (str) –
  • fromIndex (int) –
findEndExtendedName(data, index)

Return the index of the end of character after the last character in the extended command name. Uses the V.250 spec for allowed command names.

Parameters:
  • data (str) – The extended command name.
  • index (int) –
Return type:

int
generateArgs(data)

Break an argument string into individual arguments (comma delimited). Integer arguments are turned into integers. Otherwise a string is used.

Parameters:data (str) – The argument string.
Return type:list
isAtoZ(char)

Indicates if char is a character between A and Z.

Parameters:char (str) –
Return type:bool
process(data)

Processes an incoming AT command line.

This method will invoke zero or one command handler methods for each command in the command line.

Parameters:data (str) – The AT input, without EOL delimiter (e.g. <CR>).
Returns:Result object for this command line. This can be converted to a string response with ATCommandResult.toString().
Return type:ATCommandResult
register(command, handler)

Register a basic or extended command handler.

Basic command handlers are later called via their handleBasicCommand(args) method.

Extended command handlers are later called via:

  • handleActionCommand()
  • handleGetCommand()
  • handleSetCommand()
  • handleTestCommand()

Only one method will be called for each command processed.

Parameters:
  • command (str) – Command name - a single character for basic commands or multiple characters for extended commands.
  • handler (ATCommandHandler) – Handler to register for the command.
class atcmd.parser.ATCommandHandler

Bar.

handleActionCommand()

Handle Actions command "AT+FOO".

Action commands are part of the Extended command syntax, and are typically used to signal an action on "FOO".

:return The result of this command.

handleBasicCommand(arg)

Handle Basic command "ATA".

These are single letter commands such as ATA and ATD. Anything following the single letter command ('A' and 'D' respectively) will be passed as 'arg'.

For example, 'ATDT1234' would result in the call handleBasicCommand('T1234').

Parameters:arg (str) – Everything following the basic command character.
Returns:The result of this command.
handleReadCommand()

Handle Read command "AT+FOO?".

Read commands are part of the Extended command syntax, and are typically used to read the value of "FOO".

:return The result of this command.

handleSetCommand(args)

Handle Set command "AT+FOO=...".

Set commands are part of the Extended command syntax, and are typically used to set the value of “FOO”. Multiple arguments can be sent. For example:

AT+FOO=[<arg1>[,<arg2>[,...]]]

Each argument will be either numeric (int) or string. handleSetCommand() is passed a generic Object[] array in which each element will be an Integer (if it can be parsed with parseInt()) or String.

Missing arguments ",," are set to empty strings.

Parameters:args (list) – List of string and/or integers. There will always be at least one element in this list.
Returns:The result of this command.
handleTestCommand()

Handle Test command "AT+FOO=?".

Test commands are part of the Extended command syntax, and are typically used to request an indication of the range of legal values that "FOO" can take.

By default an OK result is returned to indicate that this command is at least recognized.

Returns:The result of this command.
class atcmd.parser.ATCommandResult(resultCode=0, response=None)

Foo.

ERROR = 1

Error result code

ERROR_STRING = 'ERROR'

Error response string

OK = 0

Success result code

OK_STRING = 'OK'

Success response string

UNSOLICITED = 2

Unsolicited result code

addResponse(response)

Add another line to the response.

Parameters:response (str) –
addResult(result)

Add the given result into this ATCommandResult instance.

Used to combine results from multiple commands in a single command line (command chaining).

Parameters:result (ATCommandResult) – The ATCommandResult to add to this result.
appendWithCrlf(str1, str2)

Append a string, joining with a double CRLF. Used to create multi-line AT command replies.

getResultCode()
Return type:int
toString()

Generate the string response ready to send.

Return type:str