Support » Pololu Simple Motor Controller G2 User’s Guide » 6.2. Binary commands »
6.2.1. Binary command reference
Exit safe-start (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | |
---|---|---|---|
Compact Protocol | 0x83 (131) | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x03 (3) |
Description: If the input mode is Serial/USB, and you have not disabled safe-start protection, then this command is required before the motor can run. Specifically, this command must be issued when the controller is first powered up, after any reset, and after any error stops the motor. This command has no serial response.
If you just want your motor to run whenever possible, you can transmit exit safe start and motor speed commands regularly. The motor speed commands are documented below. One potential problem with this approach is that if there is an error (e.g. the battery becomes disconnected) then the motor will start running immediately when the error has been resolved (e.g. the battery is reconnected).
If you want to prevent your motor from starting up unexpectedly after the controller has recovered from an error, then you should only send an exit safe start command after either waiting for user input or issuing a warning to the user.
Motor forward (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | Data Byte 4 | |
---|---|---|---|---|---|
Compact Protocol | 0x85 (133) | speed byte 1 | speed byte 2 | - | - |
Compact alternate use | 0x85 (133) | 0 | speed % | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x05 (5) | speed byte 1 | speed byte 2 |
Pololu alternate use | 0xAA (170) | device number | 0x05 (5) | 0 | speed % |
Description: This command lets you set the full-resolution motor target speed in the forward direction. The motor speed must be a number from 0 (motor stopped) to 3200 (motor forward at full speed) and is specified using two data bytes. The first data byte contains the low five bits of the speed and the second data byte contains the high seven bits of the speed.
The first speed data byte can be computed by taking the full (0 to 3200) speed modulo 32, which is the same as dividing the speed by 32, discarding the quotient, and keeping only the remainder. We can get the same result using binary math by bitwise-ANDing the speed with 0x1F (31). In C (and many other programming languages), these operations can be carried out with the following expressions:
speed_byte_1 = speed % 32;
or, equivalently:
speed_byte_1 = speed & 0x1F;
The second speed data byte can be computed by dividing the full (0 to 3200) speed by 32, discarding the remainder, and keeping only the quotient (i.e. turn the division result into a whole number by dropping everything after the decimal point). We can get the same result using binary math by bit-shifting the speed right five places. In C (and many other programming languages), these operations can be carried out with the following expressions:
speed_byte_2 = speed / 32;
or, equivalently:
speed_byte_2 = speed >> 5;
This command has no serial response.
Example:
If we want to set the motor target speed to half-speed forward, we can use the above equations to compute that the first speed byte must be the remainder of 1600/32, or 0, and the second speed byte must be the quotient of 1600/32, or 50. Therefore, we can send the following compact protocol bytes:
We send:
Command Byte | Data Byte 1 | Data Byte 2 | |
---|---|---|---|
Compact Protocol | 0x85 (133) | 0x00 (0) | 0x32 (50) |
Alternate interpretation: The allowed values for the second speed data byte are 0–100, so you can ignore the first speed data byte (always set it to 0), and consider the second data byte to simply be the speed percentage. For example, to drive the motor at 53% speed, you would use byte1=0 and byte2=53.
Motor reverse (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | Data Byte 4 | |
---|---|---|---|---|---|
Compact Protocol | 0x86 (134) | speed byte 1 | speed byte 2 | - | - |
Compact Alternate Use | 0x86 (134) | 0 | speed % | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x06 (6) | speed byte 1 | speed byte 2 |
Pololu Alternate Use | 0xAA (170) | device number | 0x06 (6) | 0 | speed % |
Description: This command lets you set the full-resolution motor target speed in the reverse direction. The motor speed must be a number from 0 (motor stopped) to 3200 (motor reverse at full speed) and is specified using two data bytes, the first containing the low five bits of the speed and the second containing the high seven bits of the speed. This command behaves the same as the Motor Forward command except the motor moves in the opposite direction.
Motor forward 7-Bit (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | |
---|---|---|---|---|
Compact Protocol | 0x89 (137) | speed | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x09 (9) | speed |
Description: This command sets the motor target speed in the forward direction based on the specified low-resolution (7-bit) Speed byte. The Speed byte is a number from 0 (motor stopped) to 127 (motor forward at full speed). This command has no serial response.
Example:
To set the motor target speed to approximately half-speed forward (63), we could send the following compact protocol bytes:
We send:
Command Byte | Data Byte 1 | |
---|---|---|
Compact Protocol | 0x89 (137) | 0x3F (63) |
Motor Reverse 7-Bit (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | |
---|---|---|---|---|
Compact Protocol | 0x8A (138) | speed | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x0A (10) | speed |
Description: This command sets the motor target speed in the reverse direction based on the specified low-resolution (7-bit) speed byte. The speed byte is a number from 0 (motor stopped) to 127 (motor reverse at full speed). This command has no serial response.
Set speed Mini SSC (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | |
---|---|---|---|
Mini SSC Protocol | 0xFF (255) | device number | speed |
Description: This is the Mini SSC Protocol command for setting the motor speed. This command has no serial response. See Section 6.2 for complete documentation of this command.
Motor Brake (Serial/USB input mode only)
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | |
---|---|---|---|---|
Compact Protocol | 0x92 (146) | brake amount | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x12 (18) | brake amount |
Description: This command causes the motor to immediately brake or coast (configured deceleration limits are ignored). The brake amount byte can have a value from 0 to 32, with 0 resulting in coasting (the motor outputs are disabled) and any non-zero value resulting in braking (the motor outputs are driven low). Requesting a brake amount greater than 32 results in a serial format error. This command has no serial response.
Example:
To make the motor brake, we would transmit the following compact protocol bytes:
We send:
Command Byte | Data Byte 1 | |
---|---|---|
Compact Protocol | 0x92 (146) | 0x20 (32) |
Get variable
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | |
---|---|---|---|---|
Compact Protocol | 0xA1 (161) | variable ID | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x21 (33) | variable ID |
Response format:
Response Byte 1 | Response Byte 2 |
---|---|
variable low byte | variable high byte |
Description: This command lets you read a 16-bit variable from the Simple Motor Controller. See Section 6.4 for a list of all of available variables. The value of the requested variable is transmitted as two bytes, with the low byte sent first. You can reconstruct the variable value from these bytes using the following equation:
variable_low_byte + 256 * variable_high_byte
If the variable type is signed and the above result is greater than 32767, you will need to subtract 65536 from the result to obtain the correct, signed value. Alternatively, if it is supported by the language you are using, you can cast the result to a signed 16-bit data type.
Requesting an invalid variable ID results in a serial format error, and the controller does not transmit a response.
Example:
To request the temperature A reading (variable ID 24), we would transmit the following compact protocol bytes and wait until we have received two bytes in response from the Simple Motor Controller G2:
We send:
Command Byte | Data Byte 1 | |
---|---|---|
Compact Protocol | 0xA1 (161) | 0x18 (24) |
We receive:
Response Byte 1 | Response Byte 2 |
---|---|
0x1E (30) | 0x01 (1) |
This response tells us that the temperature is:
30 + 256 * 1 = 286
in units of 0.1 °C, which means the temperature is 28.6 °C.
Set motor limit
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | Data Byte 4 | Data Byte 5 | |
---|---|---|---|---|---|---|
Compact Protocol | 0xA2 (162) | limit ID | limit byte 1 | limit byte 2 | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x22 (34) | limit ID | limit byte 1 | limit byte 2 |
Response format:
Response Byte 1 |
---|
response code |
Description: This command lets you change the temporary motor limit variables documented in Section 6.4. The ID of the limit to set is specified by the first compact protocol data byte, and the value of the limit is specified by the next two data bytes, the first of which (limit byte 1) contains the low seven bits of the value and the second (limit byte 2) contains the high seven bits. Limit IDs from 0 to 3 affect both forward and reverse limits equally (they are “symmetric”). Limit IDs from 4 to 7 affect only forward limits and limit IDs from 8 to 11 affect only reverse limits. The following table provides the limit IDs for all of the temporary motor limit variables along with the allowed limit values:
ID | Name | Allowed values | Units |
---|---|---|---|
0 or 4 | Max speed forward | 0–3200 | 0=0%, 3200=100% |
1 or 5 | Max acceleration forward | 0–3200 (0=no limit) | Δspeed per update period |
2 or 6 | Max deceleration forward | 0–3200 (0=no limit) | Δspeed per update period |
3 or 7 | Brake duration forward | 0–16384 | 4 ms |
0 or 8 | Max speed reverse | 0–3200 | 0=0%, 3200=100% |
1 or 9 | Max acceleration reverse | 0–3200 (0=no limit) | Δspeed per update period |
2 or 10 | Max deceleration reverse | 0–3200 (0=no limit) | Δspeed per update period |
3 or 11 | Brake duration reverse | 0–16384 | 4 ms |
Note: The brake duration units used by this command are 4 ms, which differs from 1 ms units used by the brake duration variables returned by the “Get variable” command.
The first limit value byte, limit byte 1, can be computed by taking the full limit value modulo (or “mod”) 128, which is the same as dividing the value by 128, discarding the quotient, and keeping only the remainder. We can get the same result using binary math by bitwise-ANDing the limit with 0x7F (127). In C (and many other programming languages), these operations can be carried out with the following expressions:
limit_byte_1 = limit % 128;
or, equivalently:
limit_byte_1 = limit & 0x7F;
The second limit value byte, limit byte 2, can be computed by dividing the full limit value by 128, discarding the remainder, and keeping only the quotient (i.e. turn the division result into a whole number by dropping everything after the decimal point). We can get the same result using binary math by bit-shifting the limit right seven places. In C (and many other programming languages), these operations can be carried out with the following expressions:
limit_byte_2 = limit / 128;
or, equivalently:
limit_byte_2 = limit >> 7;
Note that the hard motor limit settings place restrictions on the limit values you can set with this command (see Section 5.2 for more information on the hard motor limits). The hard limits configured through the Simple Motor Control Center G2 are considered minimal safety requirements, and the temporary limits cannot be changed in a way that makes the controller “less safe” than this. This means that the maximum speed, acceleration, and deceleration temporary limits cannot be increased beyond their hard-limit counterparts and the brake duration limits cannot be decreased below their hard-limit counterparts. If you try to set a temporary limit in a way prohibited by the corresponding hard limit, the temporary limit value is set to the hard limit and the response code byte indicates that the value could not be set as requested.
If the arguments to this command are valid, the controller responds to this command with a single-byte code:
Response code | Description |
---|---|
0 | No problems setting the limit. |
1 | Unable to set forward limit to the specified value because of hard motor limit settings. |
2 | Unable to set reverse limit to the specified value because of hard motor limit settings. |
3 | Unable to set forward and reverse limits to the specified value because of hard motor limit settings. |
Limit IDs above 11 and limit values outside of their allowed value ranges result in a serial format error and no response is transmitted by the controller.
The limit values set with this command persist only until the controller is next reset or the “Apply settings” button is next clicked in the Simple Motor Control Center G2, at which point the temporary limit settings are all reinitialized to the hard limit settings.
Example:
To set the reverse deceleration limit (limit ID 10) to 500, we can use the above equations to compute that limit byte 1 must be the remainder of 500/128, or 116, and limit byte 2 must be the quotient of 500/128, or 3. Therefore, we can send the following compact protocol bytes and wait until we have received one byte in response from the Simple Motor Controller G2:
We send:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | |
---|---|---|---|---|
Compact Protocol | 0xA2 (162) | 0x0A (10) | 0x74 (116) | 0x03 (3) |
We receive:
Response Byte 1 |
---|
0x00 (0) |
This response tells us the temporary limit was set as requested. If our max deceleration reverse hard motor limit was below 500, we would receive a response code of 2, which would tell us that the temporary limit was not set as requested (rather, it was set equal to whatever the hard limit is).
Set current limit
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | Data Byte 3 | Data Byte 4 | |
---|---|---|---|---|---|
Compact Protocol | 0x91 (145) | current byte 1 | current byte 2 | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x11 (17) | current byte 1 | current byte 2 |
Description: This command lets you change the hardware current limit threshold temporarily. See Section 5.2 for information about hardware current limiting and how to calculate a value to use with this command.
The value of the current limit is specified by the two data bytes. The first (current byte 1) contains the low seven bits of the value, and the second (current byte 2) contains the high seven bits.
The first data byte, current byte 1, can be computed by taking the full value modulo (or “mod”) 128, which is the same as dividing the value by 128, discarding the quotient, and keeping only the remainder. We can get the same result using binary math by bitwise-ANDing the limit with 0x7F (127). In C (and many other programming languages), these operations can be carried out with the following expressions:
limit_byte_1 = limit % 128;
or, equivalently:
limit_byte_1 = limit & 0x7F;
The second limit value byte, limit byte 2, can be computed by dividing the value by 128, discarding the remainder, and keeping only the quotient (i.e. turn the division result into a whole number by dropping everything after the decimal point). We can get the same result using binary math by bit-shifting the limit right seven places. In C (and many other programming languages), these operations can be carried out with the following expressions:
limit_byte_2 = limit / 128;
or, equivalently:
limit_byte_2 = limit >> 7;
The current limit set with this command persists only until the controller is next reset or the “Apply settings” button is next clicked in the Simple Motor Control Center G2, at which point the current limit is reinitialized to the value stored in the settings.
Get firmware version
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | |
---|---|---|---|
Compact Protocol | 0xC2 (194) | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x42 (66) |
Response format:
Response Byte 1 | Response Byte 2 | Response Byte 3 | Response Byte 4 |
---|---|---|---|
product ID low byte | product ID high byte | minor FW version (BCD format) | major FW version (BCD format) |
Description: This command lets you read the Simple Motor Controller G2 product number and firmware version number. The first two bytes of the response are the low and high bytes of the product ID (each Simple Motor Controller G2 version has a unique product ID), and the last two bytes of the response are the firmware minor and major version numbers in binary-coded decimal (BCD) format. BCD format means that the version number is the value you get when you write it in hex and then read it as if it were in decimal. For example, a minor version byte of 0x15 (21) means a the minor version number is 15, not 21.
Example:
To request the product ID and firmware version, we would transmit the following compact protocol byte and wait until we have received four bytes in response from the Simple Motor Controller (or until our receiving function times out, which could happen if there is a problem):
We send:
Command Byte | |
---|---|
Compact Protocol | 0xC2 (194) |
We receive:
Response Byte 1 | Response Byte 2 | Response Byte 1 | Response Byte 2 |
---|---|---|---|
0x98 (152) | 0x00 (0) | 0x00 (0) | 0x01 (1) |
This response tells us that the product ID is 0x00A3 (152) and the firmware version is 1.0.
Stop motor
Command format:
Command Byte | Data Byte 1 | Data Byte 2 | |
---|---|---|---|
Compact Protocol | 0xE0 (224) | - | - |
Pololu Protocol | 0xAA (170) | device number | 0x60 (96) |
Description: This command sets the motor target speed to zero and makes the controller susceptible to a safe-start violation error if safe start is enabled. Put another way, this command will stop the motor (configured deceleration limits will be respected) and not allow the motor to start again until the Safe-Start conditions required by the Input Mode are satisfied. This command has no serial response.