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 theATParser.process()
method.The
ATParser
object accepts a new command line to parse via itsprocess()
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 theATCommandHandler
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:
-
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: Return type:
-
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.
- Basic Command. For example
-
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 callhandleBasicCommand('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
-
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
) – TheATCommandResult
to add to this result.
-
appendWithCrlf
(str1, str2)¶ Append a string, joining with a double CRLF. Used to create multi-line AT command replies.
-