6.3. ASCII Commands

6.3.1. ASCII Command Reference

When configured in “ASCII” serial mode, the Simple Motor Controller offers a simple serial interface based on ASCII characters. This mode makes it easy to interact with the Simple Motor Controller through a terminal program, such as HyperTerminal, and it can provide a more intuitive interface for users who would rather deal with character strings than bits and bytes.

There are some limitations when using ASCII mode, however:

  • The commands are longer than their Binary-mode Compact Protocol counterparts, so they will take longer to send when using a TTL serial connection.
  • Automatic baud detection is not available; you must configure the Simple Motor Controller to the appropriate fixed baud rate ahead of time if you are communicating using TTL serial.
  • CRC error detection is not available.
  • The ASCII-mode serial responses might be harder to parse with some programming languages than the Binary-mode responses.

Command Format

ASCII commands consist of a command string, which is typically a single letter, followed by a comma-separated list of numbers representing the arguments to the command. Not all commands take arguments, and only one command (Set Motor Limit) takes multiple arguments. All commands must be terminated by a special termination character, such as a carriage return (<CR>).

Expressed generally, the format is:

command string + [argument 1 + [‘,’ + argument 2]] + termination character

For example, to command the motor to drive forward at speed 3200 (full speed), we could send the following ASCII command:

“F3200<CR>”

Here the command string is “F”, the argument string is “3200”, and the termination character is <CR>.

ASCII commands are case-insensitive and white-space is ignored, so “F3200<CR>” has the same effect as “f  3200 <CR>”.

The specific commands are documented in Section 6.3.1.

Command Strings

The following table lists all of the available command strings:

Command String Command Name
“GO” Exit Safe-Start
“F” Motor Forward
“R” Motor Reverse
“B” Motor Brake
“D” Get Variable
“L” Set Motor Limit
“V” Get Firmware Version
“X” Stop Motor

Argument Strings

Command arguments are expressed as strings of ASCII digits. By default, the string is interpreted as a decimal (base 10) value, but an “H” can be appended to the end of the string to tell the Simple Motor Controller to interpret it as a hexadecimal (base 16, or hex) value. For example, you can represent an argument value of 127 with “127” or “7FH” (0x7F is the hex representation of 127). The arguments to the three motor commands (“F”, “R”, and “B”) can also be written as percentages by appending a “%” to the end of the argument. For example, you can represent full motor speed with the argument “3200” or with the argument “100%”.

Termination Characters

ASCII mode accepts three different termination characters:

  • Carriage Return: A carriage return is the character sent when you press the Enter key in a terminal program. It is often written as <CR> and has a character value of 13. In C, this special character can be written as ‘\r’.
  • NL Line Feed: Also known as “new line”, this character is often written as <LF> and has a character value of 12. In C, this special character can be written as ‘\n’.
  • Null Character: This character is used to terminate strings in C. It is often written as <NUL> and has a character value of 0. In C, the string “abc” is comprised of the four characters: ‘a’, ‘b’, ‘c’, and <NUL>.

One of the above three characters must be the last character in your ASCII command string.

Responses

Any ASCII mode command string that contains more than just a termination character will generate a serial response from the Simple Motor Controller. The first character of the response gives you information about the status of the Simple Motor controller; it can be one three possible characters:

Status Character Meaning
‘.’ The last command was understood and no errors are stopping the motor.
‘!’ The last command was understood and errors are stopping the motor.
‘?’ The last command was not understood (a Serial Format Error has occurred).

If the command sent responds with data (e.g. the Get Variable command), the data follows the status character as a decimal (base 10) string of ASCII digits.

The ASCII mode serial response is always terminated by a carriage return (<CR>) followed by a line feed (<LF>).

For example, if we send a Motor Forward command while no errors are stopping the motor, the response would be “.<CR><LF>”. If we send a Get Variable command while errors are stopping the motor, the response might be “!123<CR><LF>”, which would indicate that the requested variable has a value of 123.

Commands that consist only of termination characters do not result in a serial response from the Simple Motor Controller. All other commands, even invalid ones, cause the Simple Motor Controller to respond when a termination character is received.

Using a Terminal Program

ASCII mode makes it easy to communicate with the Simple Motor Controller from a terminal program, such as HyperTerminal. The responses are formatted so that they will appear nicely in the terminal window.

We recommend you enable local echoing of transmitted characters when typing commands into a terminal program. The following picture shows our recommended ASCII settings when using HyperTerminal:

You can get to this dialog by going to the File > Properties menu and clicking on the ASCII Setup… button under the Settings tab.