5.e. Serial Servo Commands

The Maestro has several serial commands for setting the target of a channel, getting its current position, and setting its speed and acceleration limits.

Set Target (Pololu/Compact protocol)

Compact protocol: 0x84, channel number, target low bits, target high bits
Pololu protocol: 0xAA, device number, 0x04, channel number, target low bits, target high bits

The lower 7 bits of the third data byte represent bits 0–6 of the target (the lower 7 bits), while the lower 7 bits of the fourth data byte represent bits 7–13 of the target. The target is a non-negative integer.

If the channel is configured as a servo, then the target represents the pulse width to transmit in units of quarter-microseconds. A target value of 0 tells the Maestro to stop sending pulses to the servo.

If the channel is configured as a digital output, values less than 6000 tell the Maestro to drive the line low, while values of 6000 or greater tell the Maestro to drive the line high.

For example, if channel 2 is configured as a servo and you want to set its target to 1500 µs (1500×4 = 6000 = 01011101110000 in binary), you could send the following byte sequence:

in binary: 10000100, 00000010, 01110000, 00101110
in hex: 0x84, 0x02, 0x70, 0x2E
in decimal: 132, 2, 112, 46

Here is some example C code that will generate the correct serial bytes, given an integer “channel” that holds the channel number, an integer “target” that holds the desired target (in units of quarter microseconds if this is a servo channel) and an array called serialBytes:

serialBytes[0] = 0x84; // Command byte: Set Target.
serialBytes[1] = channel; // First data byte holds channel number.
serialBytes[2] = target & 0x7F; // Second byte holds the lower 7 bits of target.
serialBytes[3] = (target >> 7) & 0x7F;   // Third data byte holds the bits 7-13 of target.

Many servo control applications do not need quarter-microsecond target resolution. If you want a shorter and lower-resolution set of commands for setting the target you can use the Mini-SSC command below.

Set Target (Mini SSC protocol)

Mini-SSC protocol: 0xFF, channel address, 8-bit target

This command sets the target of a channel to a value specified by an 8-bit target value from 0 to 254. The 8-bit target value is converted to a full-resolution target value according to the range and neutral settings stored on the Maestro for that channel. Specifically, an 8-bit target of 127 corresponds to the neutral setting for that channel, while 0 or 254 correspond to the neutral setting minus or plus the range setting. These settings can be useful for calibrating motion without changing the program sending serial commands.

The channel address is a value in the range 0–254. By default, the channel address is equal to the channel number, so it should be from 0 to 23. To allow multiple Maestros to be controlled on the same serial line, set the Mini SSC Offset parameter to different values for each Maestro. The Mini SSC Offset is added to the channel number to compute the correct channel address to use with this command. For example, a Micro Maestro 6-channel servo controller with a Mini SSC Offset of 12 will obey Mini-SSC commands whose address is within 12–17.

Set Multiple Targets (Mini Maestro 12, 18, and 24 only)

Compact protocol: 0x9F, number of targets, first channel number, first target low bits, first target high bits, second target low bits, second target high bits, …
Pololu protocol: 0xAA, device number, 0x1F, number of targets, first channel number, first target low bits, first target high bits, second target low bits, second target high bits, …

This command simultaneously sets the targets for a contiguous block of channels. The first byte specifies how many channels are in the contiguous block; this is the number of target values you will need to send. The second byte specifies the lowest channel number in the block. The subsequent bytes contain the target values for each of the channels, in order by channel number, in the same format as the Set Target command above. For example, to set channel 3 to 0 (off) and channel 4 to 6000 (neutral), you would send the following bytes:

0x9F, 0x02, 0x03, 0x00, 0x00, 0x70, 0x2E

The Set Multiple Targets command allows high-speed updates to your Maestro, which is especially useful when controlling a large number of servos in a chained configuration. For example, using the Pololu protocol at 115.2 kbps, sending the Set Multiple Targets command lets you set the targets of 24 servos in 4.6 ms, while sending 24 individual Set Target commands would take 12.5 ms.

Set Speed

Compact protocol: 0x87, channel number, speed low bits, speed high bits
Pololu protocol: 0xAA, device number, 0x07, channel number, speed low bits, speed high bits

This command limits the speed at which a servo channel’s output value changes. The speed limit is given in units of (0.25 μs)/(10 ms), except in special cases (see Section 4.b). For example, the command 0x87, 0x05, 0x0C, 0x01 sets the speed of servo channel 5 to a value of 140, which corresponds to a speed of 3.5 μs/ms. What this means is that if you send a Set Target command to adjust the target from, say, 1000 μs to 1350 μs, it will take 100 ms to make that adjustment. A speed of 0 makes the speed unlimited. Setting the target of a channel that has a speed of 0 and an acceleration 0 will immediately affect the channel’s position. Note that the actual speed at which your servo moves is also limited by the design of the servo itself, the supply voltage, and mechanical loads; this parameter will not help your servo go faster than what it is physically capable of.

At the minimum speed setting of 1, the servo output takes 40 seconds to move from 1 to 2 ms.

The speed setting has no effect on channels configured as inputs or digital outputs.

Set Acceleration

Compact protocol: 0x89, channel number, acceleration low bits, acceleration high bits
Pololu protocol: 0xAA, device number, 0x09, channel number, acceleration low bits, acceleration high bits

This command limits the acceleration of a servo channel’s output. The acceleration limit is a value from 0 to 255 in units of (0.25 μs)/(10 ms)/(80 ms), except in special cases (see Section 4.b). A value of 0 corresponds to no acceleration limit. An acceleration limit causes the speed of a servo to slowly ramp up until it reaches the maximum speed, then to ramp down again as position approaches target, resulting in a relatively smooth motion from one point to another. With acceleration and speed limits, only a few target settings are required to make natural-looking motions that would otherwise be quite complicated to produce.

At the minimum acceleration setting of 1, the servo output takes about 3 seconds to move smoothly from a target of 1 ms to a target of 2 ms.

The acceleration setting has no effect on channels configured as inputs or digital outputs.

Set PWM (Mini Maestro 12, 18, and 24 only)

Compact protocol: 0x8A, on time low bits, on time high bits, period low bits, period high bits
Pololu protocol: 0xAA, device number, 0x0A, on time low bits, on time high bits, period low bits, period high bits

This command sets the PWM output to the specified on time and period, in units of 1/48 μs. The on time and period are both encoded with 7 bits per byte in the same way as the target in command 0x84, above. For more information on PWM, see Section 4.a. The PWM output is not available on the Micro Maestro.

Get Position

Compact protocol: 0x90, channel number
Pololu protocol: 0xAA, device number, 0x10, channel number
Response: position low 8 bits, position high 8 bits

This command allows the device communicating with the Maestro to get the position value of a channel. The position is sent as a two-byte response immediately after the command is received.

If the specified channel is configured as a servo, this position value represents the current pulse width that the Maestro is transmitting on the channel, reflecting the effects of any previous commands, speed and acceleration limits, or scripts running on the Maestro.

If the channel is configured as a digital output, a position value less than 6000 means the Maestro is driving the line low, while a position value of 6000 or greater means the Maestro is driving the line high.

If the channel is configured as an input, the position represents the voltage measured on the channel. The inputs on channels 0–11 are analog: their values range from 0 to 1023, representing voltages from 0 to 5 V. The inputs on channels 12–23 are digital: their values are either exactly 0 or exactly 1023.

Note that the formatting of the position in this command differs from the target/speed/acceleration formatting in the other commands. Since there is no restriction on the high bit, the position is formatted as a standard little-endian two-byte unsigned integer. For example, a position of 2567 corresponds to a response 0x07, 0x0A.

Note that the position value returned by this command is equal to four times the number displayed in the Position box in the Status tab of the Maestro Control Center.

Get Moving State (Mini Maestro 12, 18, and 24 only)

Compact protocol: 0x93
Pololu protocol: 0xAA, device number, 0x13
Response: 0x00 if no servos are moving, 0x01 if servos are moving

This command is used to determine whether the servo outputs have reached their targets or are still changing and will return 1 as long as there is at least one servo that is limited by a speed or acceleration setting still moving. Using this command together with the Set Target command, you can initiate several servo movements and wait for all the movements to finish before moving on to the next step of your program.

The Get Moving State command only works on the Mini Maestros. The Micro Maestro 6-channel controller implements the command, but it has a bug that could make this command return 0 when it should return 1. (The bug does not affect the GET_MOVING_STATE command in the scripting language, and it does not affect the Mini Maestros.) Therefore, we do not recommend using this command on a Micro Maestro. Instead, as a workaround, you could load the following script onto the Micro Maestro:

sub wait_for_movement_to_end
  begin get_moving_state while repeat
  quit

This script loops until GET_MOVING_STATE returns 0. You can use the “Restart Script at Subroutine” serial command to start the script and the “Get Script Status” serial command to check whether it is still running. These commands are documented in Section 5.f. If you start the script and then wait for it to stop running, it will mean that the servos have stopped moving.

Get Errors

Compact protocol: 0xA1
Pololu protocol: 0xAA, device number, 0x21
Response: error bits 0-7, error bits 8-15

Use this command to examine the errors that the Maestro has detected. Section 4.e lists the specific errors that can be detected by the Maestro. The error register is sent as a two-byte response immediately after the command is received, then all the error bits are cleared. For most applications using serial control, it is a good idea to check errors continuously and take appropriate action if errors occur.

Go Home

Compact protocol: 0xA2
Pololu protocol: 0xAA, device number, 0x22

This command sends all servos and outputs to their home positions, just as if an error had occurred. For servos and outputs set to “Ignore”, the position will be unchanged.

Note: For servos marked “Off”, if you execute a Set Target command immediately after Go Home, it will appear that the servo is not obeying speed and acceleration limits. In fact, as soon as the servo is turned off, the Maestro has no way of knowing where it is, so it will immediately move to any new target. Subsequent target commands will function normally.