AT Command Set and Register Summary for NM-8AM-V2, NM-16AM-V2, WIC-1AM, and WIC-2AM Analog Modem WAN Interface Cards
2: Syntax and Procedures
Downloads: This chapterpdf (PDF - 221.0KB) The complete bookPDF (PDF - 1.89MB) | Feedback

Syntax and Procedures

Table Of Contents

Syntax and Procedures

2.1  Alphabet

2.2  DTE Commands Lines

2.2.1  Command Line General Format

2.2.2  Command Line Editing

2.2.3  Command Line Echo

2.2.4  Repeating a Command Line

2.2.5  Types of DTE Commands

2.3  Basic Syntax Commands

2.3.1  Basic Syntax Command Format

2.3.2  S-Parameters

2.4  Extended Syntax Commands

2.4.1  Command Naming Rules

2.4.2  Values

2.4.3  Action Commands

2.4.4  Parameter Commands

2.4.5  Additional Syntax Rules

2.5  Issuing Commands

2.6  Executing Commands

2.6.1  Aborting Commands

2.6.2  Handling of Invalid Numbers and S-Parameter Values

2.7  Modem Responses

2.7.1  Responses

2.7.2  Extended Syntax Result Codes

2.7.3  Information Text Formats for Test Commands


Syntax and Procedures


The command and response syntax and procedures generally conform to referenced recommendations and standards. Since these recommendations and standards describe characteristics universal to a large installed base of modems to a maximum degree, there may be syntax and procedural differences due to extensions and behavioral differences in implemented commands, parameters, and responses beyond that described in these recommendations and standards.

The syntax and procedures described in this section are based on V.250 and V.253 with additional information included for implemented extensions, behavioral differences beyond V.250, and legacy commands.

2.1  Alphabet

The T.50 International Alphabet 5 (IA5) is used in this document. Only the low-order seven bits of each character are significant to the modem; any eighth or higher-order bit(s), if present, are ignored for the purpose of identifying commands and parameters. Lower-case characters are considered identical to their upper-case equivalents when received by the modem from the DTE. Result codes from the modem are in upper case.

2.2  DTE Commands Lines

Words enclosed in <angle brackets> are references to syntactical elements. The brackets are not used when the words appear in a command line, the brackets are not used. Words enclosed in [square brackets] represent optional items which may be omitted from the command line at the specified point. The square brackets are not used when the words appear in the command line. Other characters that appear in syntax descriptions must as included as shown.

Any modem responses are mentioned in terms of their alphabetic format; the actual response issued will depend on the setting of parameters that affect response formats, for example, Q and V commands.

2.2.1  Command Line General Format

A command line is made up of three elements: the prefix, the body, and the termination character.

The command line prefix consists of the characters "AT" or "at" or, to repeat the execution of the previous command line, the characters "A/" or "a/".

The body is made up of individual commands described in this document. Space characters (IA5 2/0) are ignored and may be used freely for formatting purposes, unless they are embedded in numeric or string constants. The termination character may not appear in the body. The modem can accept at least 50 characters in the body.

The termination character may be selected by a user option (parameter S3), the default being CR.

2.2.2  Command Line Editing

The character defined by parameter S5 (default, BS) is interpreted as a request from the DTE to the modem to delete the previous character. Any control characters (IA5 0/0 through 1/15, inclusive) that remain in the command line after receipt of the termination character are ignored by the modem.

The modem checks characters from the DTE first to see if they match the termination character (S3), then the editing character (S5), before checking for other characters. This ensures that these characters will be properly recognized even if they are set to values that the modem uses for other purposes. If S3 and S5 are set to the same value, a matching character will be treated as matching S3 (S3 is checked before S5).

2.2.3  Command Line Echo

The modem may echo characters received from the DTE during command state and online command state back to the DTE, depending on the setting of the E command. If enabled, characters received from the DTE are echoed in the same format as received. Invalid characters in the command line or incomplete or improperly-formed command line prefixes may not be echoed.

2.2.4  Repeating a Command Line

If the prefix "A/" or "a/" is received, the modem immediately executes once again the body of the preceding command line. No editing is possible, and no termination character is necessary. A command line may be repeated multiple times in this manner. Responses to the repeated command line are issued using format of the original command line. If "A/" is received before any command line has been executed, the preceding command line is assumed to have been empty (that results in an OK result code).

2.2.5  Types of DTE Commands

There are two types of commands: action commands and parameter commands. Commands of either type may be included in command lines, in any order.

Action commands may be "executed" (to invoke a particular function of the equipment, which generally involves more than the simple storage of a value for later use), or "tested" (to determine whether or not the equipment implements the action command, and, if subparameters are associated with the action, the ranges of subparameter values that are supported).

Parameters may be "set" (to store a value or values for later use), "read" (to determine the current value or values stored), or "tested" (to determine whether or not the equipment implements the parameter, and the ranges of values supported).

2.3  Basic Syntax Commands

2.3.1  Basic Syntax Command Format

The format of Basic Syntax commands, except for the D and S commands, is as follows:

<command>[<number>]

where <command> is either a single character, or the "&" character followed by a single character per V.250. In addition, <command> can be the "%" character followed by a single character, the "*" character followed by a single character, or the "^" character followed by a single character.

<number> may be a string of one or more characters from "0" through "9" representing a decimal integer value. Commands that expect a <number> are noted in the description of the command. If a command expects <number> and it is missing (<command> is immediately followed in the command line by another <command> or the termination character), the value "0" is assumed. If a command does not expect a <number> and a number is present, an ERROR is generated. All leading "0"s in <number> are ignored by the modem.

Additional commands may follow a command (and associated parameter, if any) on the same command line without any character required for separation. The actions of some commands cause the remainder of the command line to be ignored (for example, A).

See the D command for details on the format of the information that follows it.

2.3.2  S-Parameters

Commands that begin with the letter "S" are known as "S-parameters". The number following the "S" indicates the "parameter number" being referenced. If the number is not recognized as a valid parameter number, an ERROR result code is issued.

Immediately following this number, either a "?" or "=" character must appear. "?" is used to read the current value of the indicated S-parameter; "=" is used to set the S-parameter to a new value.

S<parameter_number>?

S<parameter_number>=[<value>]

If the "=" is used, the new value to be stored in the S-parameter is specified in decimal following the "=". If no value is given (i.e., the end of the command line occurs or the next command follows immediately), the S-parameter specified may be set to 0, or an ERROR result code issued and the stored value left unchanged. The ranges of acceptable values are given in the description of each S-parameter.

If the "?" is used, the modem transmits a single line of information text to the DTE. The text portion of this information text consists of exactly three characters, giving the value of the S-parameter in decimal, with leading zeroes included.

2.4  Extended Syntax Commands

2.4.1  Command Naming Rules

Both actions and parameters have names, which are used in the related commands. Names always begin with the character "+". Following the "+", from one to 16 additional characters appear in the command name. These characters will be selected from the following set:

A through Z

(IA5 4/1 through 5/10)

0 through 9

(IA5 3/0 through 3/9)

!

(IA5 2/1)

%

(IA5 2/5)

-

(IA5 2/13)

.

(IA5 2/14)

/

(IA5 2/15)

:

(IA5 3/10)

_

(IA5 5/15)


The first character following the "+" is an alphabetic character in the range of "A" through "Z". This first character generally implies the application in which a command is used (for example, F for Fax or V for voice).

The modem considers lower-case characters to be the same as their upper-case equivalents.

2.4.2  Values

When subpar a meters are associated with the execution of an action, or when setting a parameter, the command may include specification of values. This is indicated by the appearance of <value> in the descriptions below.

<value> consists of either a numeric constant or a string constant.

Numeric Constants

Numeric constants are expressed in decimal, hexadecimal, or binary.

Decimal numeric constants consist of a sequence of one or more of the characters "0" through "9", inclusive.

Hexadecimal numeric constants consist of a sequence of one or more of the characters "0" through "9", inclusive, and "A" through "F" inclusive. The characters "A" through "F" represent the equivalent decimal values 10 through 15.

Binary numeric constants consist of a sequence of one or more of the characters "0" and "1".

In all numeric constants, the most significant digit is specified first. Leading "0" characters are ignored by the modem. No spaces, hyphens, periods, commas, parentheses, or other generally-accepted numeric formatting characters are permitted in numeric constants; note in particular that no "H" suffix is appended to the end of hexadecimal constants.

String Constants

String constants consist of a sequence of displayable IA5 characters, each in the range from 2/0 to 7/15, inclusive, except for the characters `"' (IA5 2/2) and "\" (IA5 5/12). String constants are bounded at the beginning and end by the double-quote character (`"', IA5 2/2).

Any character value may be included in the string by representing it as a backslash ("\") character followed by two hexadecimal digits. For example, "\0D" is a string consisting of the single character <CR> (IA5 0/13). If the "\" character itself is to be represented in a string, it is encoded as "\5C". The double-quote character, used as the beginning and ending string delimiter, is represented within a string constant as "\22".

A "null" string constant, or a string constant of zero length, is represented by two adjacent delimiters ("").

Compound Values

Actions may have more than one subparameter associated with them, and parameters may have more than one value. These are known as "compound values", and their treatment is the same in both actions and parameters.

A compound value consists of any combination of numeric and string values (as defined in the description of the action or parameter). The comma character must be included as a separator, before the second and all subsequent values in the compound value. If a value is not specified (i.e., defaults assumed), the required comma separator must be specified; however, trailing comma characters may be omitted if all associated values are also omitted.

2.4.3  Action Commands

Action Execution Command Syntax

There are two general types of action commands: those that have associated subparameter values that affect only that invocation of the command, and those that have no subparameters.

If subparameters are associated with a command, the definition of the action command indicates, for each subparameter, whether the specification of a value for that subparameter is mandatory or optional. For optional subparameters, the definition indicates the assumed (default) value for the subparameter if no value is specified for that subparameter; the assumed value may be either a previous value (i.e., the value of an omitted subparameter remains the same as the previous invocation of the same command, or is determined by a separate parameter or other mechanism), or a fixed value (for example, the value of an omitted subparameter is assumed to be zero). Generally, the default value for numeric subparameters is 0, and the default value for string subparameters is "" (empty string).

The following syntax is used for actions that have no subparameters:

+<name>

The following syntax is used for actions that have one subparameter:

+<name>[=<value>]

The following syntax is used for actions that have two or more subparameters:

+<name>[=<compound_value>]

For actions that accept subparameters, if all subparameters are defined as being optional, and the default values for all subparameters are satisfactory, the data terminal equipment (DTE) may use the first syntax above (i.e., omit the "=" from the action execution command as well as all of the subparameter value string).

If all other relevant criteria are met (for example, the modem is in the proper state), the command is executed with any indicated subparameters. If <name> is not recognized, the modem issues the ERROR result code and terminates processing of the command line. An ERROR is also generated if a subparameter is specified for an action that does not accept subparameters, if too many subparameters are specified, if a mandatory subparameter is not specified, if a value is specified of the wrong type, or if a value is specified that is not within the supported range.

Action Test Command Syntax

The DTE may test if an action command is implemented in the modem by using the syntax:

+<name>=?

If the modem does not recognize the indicated name, it returns an ERROR result code and terminates processing of the command line. If the modem does recognize the action name, it returns an OK result code. If the named action accepts one or more subparameters, the modem sends an information text response to the DTE, prior to the OK result code, specifying the values supported by the modem for each such subparameter, and possibly additional information. The format of this information text is defined for each action command.

2.4.4  Parameter Commands

Parameter Types

Parameters may be defined as "read-only" or "read-write". "Read-only" parameters are used to provide status or identifying information to the DTE, but cannot be set by the DTE; attempting to set their value is an error. In some cases (specified in the description of the individual parameter), the modem may ignore attempts to set the value of such parameters rather than respond with an ERROR result code, if the continued correct operation of the interface between the modem and DTE will not be affected by such action. Read-only parameters may be read and tested.

"Read-write" parameters may be set by the DTE, to store a value or values for later use. Read-write parameters may be set, read, and tested.

Parameters may take either a single value, or multiple (compound) values. Each value may be either numeric or string; the definition of the parameter will specify the type of value for each subparameter. Attempting to store a string value in a numeric parameter, or a numeric value in a string parameter, is an error.

Parameter Set Command Syntax

The definition of the parameter indicates, for each value, whether the specification of that value is mandatory or optional. For optional values, the definition indicates the assumed (default) value if none is specified; the assumed value may be either a previous value (i.e., the value of an omitted subparameter retains its previous value), or a fixed value (for example, the value of an omitted subparameter is assumed to be zero). Generally, the default value for numeric parameters is 0, and the default value for string parameters is "" (empty string).

The following syntax is used for parameters that accept a single value:

+<name>=[<value>]

The following syntax is used for parameters that accept more than one value:

+<name>=[<compound_value>]

For each implemented parameter, if all mandatory values are specified, and all values are valid according to the definition of the parameter, the specified values are stored. If <name> is not recognized, one or more mandatory values are omitted, or one or more values are of the wrong type or outside the permitted range, the modem issues the ERROR result code and terminates processing of the command line. An ERROR is also generated if too many values are specified. In case of an error, all previous values of the parameter are unaffected.

Parameter Read Command Syntax

The DTE may determine the current value or values stored in a parameter by using the following syntax:

+<name>?

The modem responds by sending the current values stored for the parameter to the DTE in an information text response. The format of this response is described in the definition of the parameter. Generally, the values are sent in the same form in which they would be issued by the DTE in a parameter setting command; if multiple values are supported, they will generally be separated by commas, as in a parameter setting command.

Parameter Test Command Syntax

The DTE may test if a parameter is implemented in the modem, and determine the supported values, by using the syntax:

+<name>=?

If the modem does not recognize the indicated name, it returns an ERROR result code and terminates processing of the command line. If the modem does recognize the parameter name, it returns an information text response to the DTE, followed by an OK result code. The information text response indicates the values supported by the modem for each such subparameter, and possibly additional information. The format of this information text is defined for each parameter.

2.4.5  Additional Syntax Rules

Concatenating Commands after Extended Syntax Commands

Additional commands may follow an extended-syntax command on the same command line if a semicolon (";") is inserted after the preceding extended command as a separator. The semicolon is not necessary when the extended syntax command is the last command on the command line.

Concatenating Commands after Basic Format Commands

Extended syntax commands may appear on the same command line after a basic syntax command without a separator, in the same manner as concatenation of basic syntax commands.

2.5  Issuing Commands

All characters in a command line must be issued at the same data rate, and with the same parity and format.

The modem will ignore any command line that is not properly terminated. The modem may consider 30 seconds of mark idle time between any two characters as an improperly terminated command line. In this case the modem may or may not generate an ERROR message. The modem will ignore any characters received from the DTE that are not part of a properly-formatted command line.

If the maximum number of characters that the modem can accept in the body is exceeded, an ERROR result code is generated after the command line is terminated.

The DTE will not begin issuing a subsequent command line until at least one-tenth of a second has elapsed after receipt of the entire result code issued by the modem in response to the preceding command line.

2.6  Executing Commands

Upon receipt of the termination character, the modem commences execution of the commands in the command line in the order received from the DTE. Should execution of a command result in an error, or a character be not recognized as a valid command, execution is terminated, the remainder of the command line is ignored, and the ERROR result code is issued. Otherwise, if all commands execute correctly, only the result code associated with the last command is issued; result codes for preceding commands are suppressed. If no commands appear in the command line, the OK result code is issued.

2.6.1  Aborting Commands

Some action commands that require time to execute may be aborted while in progress; these are explicitly noted in the description of the command. Aborting of commands is accomplished by the transmission from the DTE to the modem of any character. A single character is sufficient to abort the command in progress; however, characters transmitted during the first 125 milliseconds after transmission of the termination character are ignored (to allow for the DTE to append additional control characters such as line feed after the command line termination character). To ensure that the aborting character is recognized by the modem, it should be sent at the same rate as the preceding command line; the modem may ignore characters sent at other rates. When such an aborting event is recognized by the modem, the modem terminates the command in progress and returns an appropriate result code to the DTE, as specified for the particular command.

2.6.2  Handling of Invalid Numbers and S-Parameter Values

The modem reacts to undefined numbers and S-parameter values in one of three ways:

1. Issue the ERROR result code, and leave the previous value of the parameter unchanged;

2. Issue the OK result code, and leave the previous value of the parameter unchanged; or,

3. Issue the OK result code, and set the parameter value to the valid value nearest to that specified in the command line.

The description of each command specifies which of these three techniques is used to handle invalid parameter values for that command or parameter.

2.7  Modem Responses

While in command state and online command state, the modem will issue responses using the same rate, word length, and parity as the most recently received DTE command line. In the event that no DTE command has yet been received, rate, word length, and parity used will depend on the capabilities of the modem.

When the modem transitions from the command state or online command state to the online data state, the result code CONNECT should be issued at the bit rate and parity used during the command state. When the modem transitions from the online data state to the command state or online command state, the result codes should be issued at the bit rate used during the online data state. Thereafter, any unsolicited result codes should use the bit rate and parity of the last command line issued by the DTE to the modem.

The characters of a response will be contiguous, with no more than 100 milliseconds of mark idle issued between characters in addition to stop elements.

2.7.1  Responses

There are two types of responses that may be issued by the modem: information text and result codes.

Information Text. Information text responses consist of three parts: a header, information text, and a trailer:

1. The characters transmitted for the header are determined by the V command.

2. The trailer consists of two characters, being the character having the ordinal value of parameter S3 followed by the character having the ordinal value of parameter S4.

3. Information text usually consists of a single line; information text returned in response to some commands may contain multiple lines, and the text may therefore include CR, LF, and other formatting characters to improve readability.

Result Code Parts. Result codes consist of three parts: a header, the result text, and a trailer.

1. The characters transmitted for the header and trailer are determined by the V command setting.

2. The result text may be transmitted as a number or as a string, also depending on a the V command setting.

Result Code Types. There are three types of result codes: final, intermediate, and unsolicited. Result codes are described in Section 3.5.

1. A final result code indicates the completion of a full modem action and a ability to accept new commands from the DTE.

2. An intermediate result code is a report of the progress of an modem action. The CONNECT result code is an intermediate result code. In the case of a dialing or answering command, the modem switches from command state to online data state, and issues a CONNECT result code. This is an intermediate result code for the modem because it cannot accept commands from the DTE while in online data state. When the modem switches back to the command state it then issues a final result code (such as OK or NO CARRIER).

3. Unsolicited result codes (such as RING) indicate the occurrence of an event not directly associated with the issuance of a command from the DTE.

2.7.2  Extended Syntax Result Codes

Extended syntax result codes may be issued in response to either basic or extended commands, or both. The appropriate responses are specified in the definitions of the commands, the responses, or both.

The general format of extended syntax result codes is the same as result codes defined in TIA-602 with regard to headers and trailers. The characters specified in S-parameters S3 and S4 are used in headers and trailers of extended syntax result codes as they are in basic format result codes. The setting of the V command affects the headers and trailers associated with extended syntax result codes in the same manner as basic format result codes; however, unlike basic format result codes, extended syntax result codes have no numeric equivalent, and are always issued in alphabetic form.

Extended syntax result codes are subject to suppression by the Q1 command, as with basic format result codes. The issuance of extended syntax result codes are not be affected by the setting of the X command.

Extended syntax result codes may be either final, intermediate, or unsolicited; the type being indicated in the definition of the result code.

Extended syntax result codes are prefixed by the "+" character to avoid duplication of basic format result codes specified in TIA-602. Following the "+" character, the name of the result code appears; result code names follow the same rules as command names.

Extended syntax result codes may include the reporting of values. The definition of the result code specifies whether or not values are appended to the result code, and, if so, how many, their types, and their assumed default values if omitted.

Data/voice Modes. When no values are to be reported, the result code appears in the simplest form:

+<name>

If a single value is to be reported, the form of the result code is:

+<name>: <value>

A single space character separates the colon character from the <value>; no space appears between the result code name and the colon. If multiple values are to be reported with the result code, the form is:

+<name>: <compound_value>

Fax Modes. If a single value is to be reported, the form of the result code is:

<value> or (<value>)

2.7.3  Information Text Formats for Test Commands

In general, the format of information text returned by extended syntax commands is described in the definition of the command.

The modem may insert intermediate <CR> characters in very long information text responses in order to avoid overrunning DTE receive buffers. If intermediate <CR> characters are included, the modem does not include the character sequences "0 <CR>"or "OK<CR>", so that DTE can avoid false detection of the end of these information text responses.

Range of Values

When the action accepts a single numeric subparameter, or the parameter accepts only one numeric value, the set of supported values may be presented in the information text as an ordered list of values. The list is preceded by a left parenthesis ((), and is followed by a right parenthesis ()). If only a single value is supported, it appears between the parentheses. If more than one value is supported, then the values may be listed individually, separated by comma characters, or, when a continuous range of values is supported, by the first value in the range, followed by a hyphen character (-), followed by the last value in the range. The specification of single values and ranges of values may be intermixed within a single information text. In all cases, the supported values are indicated in ascending order.

For example, the following are some examples of value range indications:

(0)

Only the value 0 is supported.

(1,2,3)

The values 1, 2, and 3 are supported.

(1-3)

The values 1 through 3 are supported.

(0,4,5,6,9,11,12)

The several listed values are supported.

(0,4-6,9,11-12)

An alternative expression of the above list.


Compound Range of Values

When the action accepts more than one subparameter, or the parameter accepts more than one value, the set of supported values is presented as a list of the parenthetically-enclosed value range strings described above, separated by commas. For example, the information text in response to testing an action that accepts three subparameters, and supports various ranges for each of them, could appear as follows:

(0),(1-3),(0,4-6,9,11-12)

This indicates that the first subparameter accepts only the value 0, the second accepts any value from 1 through 3 inclusive, and the third subparameter accepts any of the values 0, 4, 5, 6, 9, 11, or 12.