6.2.1. Binary Command Reference

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.

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-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-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 languanges), 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:

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.

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:

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.

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.

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 by the specified amount (configured deceleration limits are ignored). The Brake Amount byte can have a value from 0 to 32, with 0 resulting in maximum coasting (the motor leads are floating almost 100% of the time) and 32 resulting in full braking (the motor leads are shorted together 100% of the time). Requesting a brake amount greater than 32 results in a Serial Format Error. This command has no serial response.

Example:

To set the motor outputs to 50% braking (a Brake Amount of 16), we would transmit the following compact protocol bytes:

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 variable IDs between 41 and 127 results in a Serial Format Error, and the controller does not transmit a response.

Example:

To request the board temperature (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 (or until our receiving function times out, which could happen if there is a problem):

This response tells us that the temperature is:

30 + 256 * 1 = 286

in units of 0.1 °C, which means the board temperature is 28.6 °C.

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 languanges), 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 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, 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 (or until our receiving function times out, which could happen if there is a problem):

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).

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 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 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):

This response tells us that the product ID is 0x0098 (152) and the firmware version is 1.0.

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.