pyatcommand 0.5.3

An interface for V.25 Hayes AT commands

ITU-T V.250 AT Command Parser for Python

This was developed due to seeming lack of a generalized AT command processing library in the PyPI ecosystem. Several other implementations exist for more specific purposes but miss certain functions such as non-verbose (V0) mode, echo on/off (E1), or unsolicited result codes (URC) and related complexities involving solicited/unsolicited race conditions.

Data Terminating Equipment DTE refers to the device talking to the modem i.e. originating commands and would implement the AtClient.

Data Communications Equipment DCE refers to the modem responding to commands or emitting unsolicited information and would implement the AtServer.

Use of Verbose mode (ATV1) is generally recommended to disambiguate responses, errors and URCs.

Use of Echo (ATE1) is generally recommended to disambiguate responses from URCs.

Although the standard allows changing the <cr> and <lf> characters, this is rarely practical in modern systems, and is generally discouraged.

Client

The client functionality is used to talk to a modem (or anything similar that supports ITU-T V.250 style AT commands).

Allows for processing of command/response or receipt of unsolicited result code (URC) emitted by the modem. Also includes an optional 16-cit CRC validation supported by some modems.

Output from the modem

Connection and Initialization

The AtClient instance can be configured with settings using initialization parameters or when using the connect() method. Typical parameters include:

• The serial port name
• baudrate (default 9600)
• echo (default True)
• verbose (default True)
• autobaud (default True) will cycle through supported baudrates trying to attach using a validated AT command

Once the basic AT command returns a valid response, the background listening thread is started and the device gets initialized to a known AT configuration for echo and verbose.

Command/Response

This is the main mode of intended use. The logic flow is as follows:

An AT commmand, with optional timeout, is submitted by calling send_command() which blocks until either a response is received or a timeout expires:

• Uses a threading.Lock to ensure thread safety;
• Clears the last error code;
• Clears the response buffer;
• (Optional) calculates and applies CRC to the command;
• Applies the command line termination character (default \r);
• Sends the command on serial and waits for all data to be sent;
• Sets the pending command state;
• Waits for a response or timeout;
• If no timeout is specified, the default is 0.3 seconds (AT_TIMEOUT).
  • A default timeout can be set with AT_TIMEOUT environment variable or by using the command_timeout init parameter or property.
• A timed-out response returns None;
• A valid response returns an AtResponse object with properties:
  • ok (bool) Indicating a successful result
  • info (str) If the response included text. Multiple lines are separated by newline ('\n'). Any CME/CMS ERROR results will be placed in info when ok is False
  • crc_ok (bool or None) If CRC feature is supported, indicates if the response had a valid CRC.
• Alterntively to the AtResponse object, you can pass kwarg raw=True to receive the complete response as an ASCII string.

Unsolicited Response Codes (URC)

Once the connection is established and the AT command parameters configured, a background thread is started to listen for any incoming serial data. Check for unsolicited data using get_urc() which returns the next queued URC.

URCs are assumed to always be prefixed and suffixed by <cr><lf> regardless of the Verbose setting. URCs are also assumed to be a single line i.e. no <cr><lf> in the middle of a URC.

Race conditions can occur when a URC arrives just as a command is being sent resulting in the possibility of the URC(s) being prepended to the response. To avoid such conditions you can ensure Echo is enabled so that responses can be distinguished from unsolicited by the presence of an echo.

CRC Error Detection

An optional CRC-16-CCITT feature is supported that appends a 16-bit error detection mechanism when supported by the device. A crc_sep separator can be defined (default *) that is followed by a 4-character hexadecimal value. The CRC is applied before the command terminator (e.g. AT*3983\r) or after the result code (e.g. \r\nOK\r\n*86C5\r\n).

The command string must be specified in the property crc_enable e.g. client.crc_enable = 'AT%CRC=1'. The corresponding disable string can either be derived as the numeric zero of the enabler, or manually set using the crc_disable property.

CRC support

Currently a CCITT-16-CRC option is supported for commands and responses. The enable/disable command may be configured using +CRC=<1|0>. (%CRC=<1|0> also works)

Debugging

Low-level debugging of serial exchanges is supported by configuring various levels:

• Standard logging level DEBUG will show exchanges in a single line with special characters embedded in angle brackets e.g. <cr>.
• Using an environment variable LOG_VERBOSE allows for more detailed analysis:
  • atclient reveals additional details about the parsing process/algorithm
  • atclientdev reveals even lower level details
• Using an environment variable AT_RAW set to 1 or true will output individual characters (specials wrapped in angle brackets) to stdout with line headers indicating the direction of transmission (TX/RX)

Server (Work in Progress)

The server concept is to act as a modem/proxy replying to a microcontroller.

You register custom commands using add_command() with a data structure that includes the command name and optional callback functions for read, run, test and write operations.

Verbose and Echo features are supported using the standard V and E commands defined in the V.25 spec.

CRC is an optional extended command to support 16-bit checksum validation of requests and responses that can be useful in noisy environments.

Feature considerations

• Repeating a command line using A/ or a/ is not supported;
• No special consideration is given for numeric or string constants, those are left to custom handling functions;
• Concatenation of basic commands deviates from the standard and expects a semicolon separator;

Acknowledgements

The server idea is based somewhat on the ATCommands library which had some shortcomings for my cases including GPL, and cAT but reframed for C++. Many thanks to those developers for some great ideas!