DISAMBIGUATION:
If you are using an RH2D unit, it uses Actuators from Robotis, in particular the XL320 Actuator, which has a slightly different control table and capabilities. See here the corresponding Control table.

For all other Seed Robotics units, please continue reading.

The Seed Robotics smart actuators run Seed Robotics own firmware that is developed in parallel and, as part, of the EROS architecture.

At present, the micro28, micro57, mini67 and micro44 actuator models are used in different Seed Robotics models.

The control table below applies to all of them. As part of the EROS initiative commitment, we wish that all our hardware is exposed and controlled by the user under one single command and control architecture.

READing vs WRITing

All memory positions are typically readable.

READing from a memory position will return the state of that variable at the time of processing the READ request.
Here are a few examples of READING the control table:

  • If you have set Torque Enable (position 24) to Off (0), you can query the Present Position (memory position 36) while you move the joint with your hand. You will see the values being updated in real time. This technique can be used to capture key frames for example.
  • If you have set a Target Position (memory position 30), you can read memory positions 36 (Present position), 38 (Present speed) and 46 (Moving) to check if the trajectory is being followed. This is especially useful for detecting the arrival at the target or detecting anomalies such as stalling, normally due to external physical blockage

WRITing to a memory position will usually either configure a parameter or trigger an action.

As an example:

  • To make the servo move to a specific position, WRITE your target to the memory position 30 (Target Position). If Torque is not enabled, it will be automatically enabled and servo will seek the Target position.
  • If you wish to control the moving speed, you may WRITE to the memory position 32 (Target Speed) prior to setting your target position.

For more information on how to READ and WRITE to the control table see the protocol documentation: you can do it using the Dynamixel Protocol or the STP Protocol.

WORD values vs BYTE values

The control table entries are either of WORD type (2 bytes) or BYTE type (1 byte) depending on the range of values they handle.

A BYTE value is written directly to the memory position.

A WORD value however is written in Little Endian style, that is, you must break the WORD in two BYTEs. The Low order byte is Stored first, to the memory address shown in the control table, followed by the high byte at the next memory position:
[ADDRESS AT CONTROL TABLE] LOW BYTE
[ADDRESS AT CONTROL TABLE + 1] HIGH BYTE

In pseudo code, it would be:

# PSEUDO CODE. Writing a WORD value 
word OUT_VALUE = 2048
w = new write_command(OUT_VALUE & 0xFF, (OUT_VALUE >> 8) & 0xFF)
uart_send_bytes(w)

It is important to note that WORD values should be written in one single WRITE command.
Splitting the WRITE of a WORD value in two individual commands, and sending them separately as individual Bytes, is unsupported and will yield incorrect results: the first command with the LOW byte is discarded; the next command with the HIGH byte is processed and assumes a low byte of 0 since the low byte was not included in the second command.
Therefore writing WORD values should be done in one single command that will include both the LOW and HIGH bytes simultaneously.

For more information on how to WRITE to the control table see the protocol documentation: you can do it using the Dynamixel Protocol or the STP Protocol.

Control Table

Address Size (nr of bytes to read/write) Description Access Mode Default value/Remarks Storage Persistence
0 (0x0) WORD (2) Model Number R Model number of the Actuator HARD CODED
2 (0x2) BYTE (1) Version of Firmware R Installed Firmware version HARD CODED
3 (0x3) BYTE (1) ID RW Device ID on the bus EEPROM
4 (0x4) BYTE (1) Baud Rate RW See below for the meaning of the Baud Rate byte. EEPROM
5 (0x5) BYTE (1) Return Delay Time R Always 0. This position is made available for backwards comptibility with older libraries. HARD CODED
6 (0x6) WORD (2) CW Angle Limit RW Sets the minimum value accepted as Target Position. Default=0. This value is set in the 10bit or 12 bit range, depending on the setting of Position 0x14. EEPROM
8 (0x8) WORD (2) CCW Angle Limit RW Sets the maximum value accepted as Target Position. Default=1023 or 4095: This value is set in the 10bit or 12 bit range, depending on the setting of Position 0x14. EEPROM
16 (0x10) BYTE (1) Status Return Level RW Default=2, Always return a reply EEPROM
18 (0x12) BYTE (1) Shutdown Conditions RW Default=OVERLOAD or excess TEMPERATURE EEPROM
20 (0x14) BYTE (1) Emulate 12 bit resolution RW Default=1, set to 12bit mode EEPROM
21 (0x15) WORD (2) Zero Offset RW Default=2048 (if in 12 bit mode)/512 (if in 10bit mode) EEPROM
23 (0x17) BYTE (1) PID, Zero_Offset and Resolution Tuning Lock RW Default=1, protects memory positions for PID configuration from inadvertent modification. RAM
24 (0x18) BYTE (1) Torque Enable RW Default=0 (torque disabled, H bridge in Dynamic brake mode) RAM
26 (0x11) BYTE (1) D Gain (Position Controller) R(RW) D Gain for the Position Controlller RAM (initial value read from EEPROM)
27 (0x1B) BYTE (1) I Gain (Position Controller) R(RW) I Gain for the Position Controlller RAM (initial value read from EEPROM)
28 (0x1C) BYTE (1) P Gain (Position Controller) R(RW) P Gain for the Position Controlller RAM (initial value read from EEPROM)
30 (0x1E) WORD (2) Target Position RW Sets the target position to seek. This value is set in the 10bit or 12 bit range, depending on the setting of Position 0x14. RAM
32 (0x20) WORD (2) Target Speed RW Desired target speed while in motion. 0=Maximum speed; any other value will limit the maximum speed. Speed is expressed in units of 0,11RPM. Default=0 RAM
36 (0x24) WORD (2) Present Position R Present Position. This value is expressed in the 10bit or 12 bit range, depending on the setting of Position 0x14. RAM
38 (0x26) WORD (2) Present Speed R Since firmware version 21 this value is expressed in units of 0,11 RPM. RAM
43 (0x2B) BYTE (1) Present Temperature R Approximate temperature inside the actuator, in degrees Celsius RAM
46 (0x2E) BYTE (1) Moving R Indicates if the servo output shaft is moving. RAM
81 (0x51) BYTE (1) Bootloader Password Length R The number of characters that compose the Booloader password. BOOLOADER
82 (0x52) BYTE (1) First Character of the Bootloader Password R This value is the ASCII code of the character. BOOLOADER
85 (0x55) BYTE (1) Bootloader Timeout R Timeout for bootloader activation BOOLOADER
87 (0x57) BYTE (1) UART Comm Health: Framing Errors count R For debugging and troubleshooting purposes RAM
88 (0x58) BYTE (1) UART Comm Health: Processor Buffer overflow count R For debugging and troubleshooting purposes RAM
89 (0x59) BYTE (1) UART Comm Health: Firmware Buffer overflow count R For debugging and troubleshooting purposes RAM
90 (0x5A) BYTE (1) Servo Control Mode R 0=Position control, 1=PWM Control. Default=0 RAM
92 (0x5C) WORD (2) Motor PWM R(RW) Writable if position 0x5A is set to Direct PWM mode RAM

Storage Persistence of values

The meaning of Storage Persistence is shown below:

  • HARD CODED - these values are part of the firmware code and may only be changed by a firmware update
  • EEPROM - values stored in EEPROM will persist after a power cycle and will be permanently recorded.
  • RAM - values stored in RAM will be reset to default after a power cycle.
  • BOOTLOADER - these are special values stored in the Bootloader configuration area. They can only be changed by the bootloader itself, during a Bootloader session.

Model Number

Model number of the actuator.
Each Seed Robotics actuator has a unique model number allowing the user to distinguish them.

Version of Firmware

The version of the firmware installed in the Actuator.
All the actuators have a built in micro processor and the firmware can be updated via a bootloader operation.

Bus ID

The ID of the device on the bus.

The ID is used when sending commands to the Actuator. It uniquely identifies the actuator on the system when sending commands with the Dynamixel or STP protocol.

You should ensure there are no duplicate IDs in your system as this would produce unexpected results and generally incorrect operation.

The new ID becomes effective immediately after changing this parameter.

Baud Rate

Communication between the host and the actuator is done over UART serial communication.
This parameter sets the Baud Rate at which the actuator is listening for and responding to commands.

It is calculated as follows: Baud Rate in BPS = 2000000/([Baud rate setting in memory table]+1)

A Power cycle is required for the new setting to come into effect.

Typical settings are:
3=500kbps
4=400kbps
7=250kbps
16=117 647 bps (communicates with devices at 115200bps, within the UART tolerance of 3%)
34=57 142bps (communicates with devices at 57600bps)
103=19 230bps (communicates with devices at 19200bps)
207=9 615bps (communicates with devices at 9600bps)

NOTE 1 These actuators do not support communication above 500kbps.
However when integrated into a Seed Robotics Hand, the whole system can communicate at the speed of the EROS main board (usually in excess of 3Mbps). This is because the EROS main board will perform speed conversion invisibly thus allowing communication with the servos at much higher baud rates.

NOTE 2 To prevent mis configuration, when these actuators are connected to an EROS main board this memory position is hidden and is not writable.
This is because the EROS main board performs the speed conversion mentioned above and requires a preset baud for the conversion to work as expected.
If you need to change the Baud rate to communicate with a Seed Robotics hand you should do it in the Control Table of the Main board only and it will propagate automatically to the actuators (through the speed conversion mechanism mentioned).

CW Angle Limit
CCW Angle Limit

Sets the minimum and maximum angles accepted when writing a Target Position.
This is the same as saying these values clip the range of motion of the actuator.

By default they are set to the minimum (CW) and maximum (CCW) values for the full range of motion.

This functionality is useful as a safeguard in case your robot is assembled in way where you'd want to limit the motion of the joint.

Status Return Level

Sets how the unit responds to requests from the host. Possible values:

0=Reply only to PING commands (this setting will prevent the unit from responding to READ commands)
1=Reply to PING and READ commands only (do not acknowledge WRITE commands)
2=Reply to all commands (same as 1 and, in addition, sends an acknowledgment after every WRITE command)

The default configuration is 2.

Shutdown Conditions

This setting was introduced with Actuator firmware version 27. It is not available in earlier versions.
This setting lets the user disable the Torque Shutdown conditions of OVERLOAD and excess TEMPERATURE.

These checks exist in the unit to protect it against damage by disabling torque when any of these conditions occur.
For more information on how these conditions affect motion and how to prevent them, see setting the Target Position below which frther expands on the topic of shutdown conditions.

This value is a bitmask, composed by the following:

  • ERROR_OVERLOAD 0x20
  • ERROR_TEMPERATURE 0x04

By default, it is set to 36 (0x20 + 0x4 = 0x24 or 36 in Decimal) which corresponds to shutting down torque on an OVERLOAD or excess TEMPERATURE condition.

If you wish to disable any of these conditions, WRITE to this memory position and don't set the appropriate bit (for example setting to 0 disables all Shutdown conditions).

Please note we DO NOT recommend disabling the Shutdown conditions. They are in place to protect the unit. This option should only be changed after careful analysis and consideration.

Emulate 12 bit resolution

This setting applies to CW Limit, CCW Limit, Target Position and Goal Position.

The built-in processor samples natively at 10bits. However modern libraries and frameworks all work at 12 bit.
By oversampling, the actuators can emulate and operate in 12bit resolution mode for compatibility with a variety of frameworks.

By default, this is configured to 1 (12 bit emulation enabled).

If your library or framework works in 10 bit resolution, you may set the unit to 10bit resolution by writing a “0” to this memory position.
The new resolution configuration becomes effective immediately after changing this parameter.

IMPORTANT
If you need to change this setting you must first set memory position 23/0x17 (PID, Zero_Offset and Resolution Tuning Lock) to 0. Without doing this, any attempt to change this setting will fail.

Zero offset

This setting lets the user re-tune the 0 (or center position) for each joint.

This is useful for:

  • joints with double actuation such as Wirst Flexion, Adduction where the settling of tendor fibers may produce minor deviations from the center position
  • Under actuated joints (i.e. closing of fingers) where settling of the tendon fibers causes the finger to start moving only after a set position (and not within the first 10~20units). Previously this required physically readjusting the tendon. Using this option this can now be tuned on the fly.

The default value is 2048 (if in 12bit mode) or 512 (if on 10bit). These numbers correspond to 0.

By reducing this number you are adjusting the zero clockwise; by increasing this number you are adjusting the zero Counterclockwise.

There is a limit to how much this number can be adjusted. Once the offset reaches the extreme limits of the position sensor, increasing or decreasing it no longer produces any effect.

IMPORTANT (1): do not set this to 0, as it would correspond to an adjustment of -2048/-512 (depending on the resolution of operation). Remember, the default zero position is a setting of 2048/512 (depending on the resolution of operation).

IMPORTANT (2)
If you need to change this setting you must first set memory position 23/0x17 (PID, Zero_Offset and Resolution Tuning Lock) to 0. Without doing this, any attempt to change this setting will fail.
This setting was introduced with Actuator firmware version 27. It is not available in earlier versions.

PID, Zero_Offset & Resolution Tuning Lock

Unlocks/Locks WRITING to the memory positions 20-23 and 26-28, which adjust the Zero offset, enable/Disable 12bit resolution mode and tune the PID gains.

This is meant to prevent inadvertent misconfiguration of the unit, mostly because some libraries for the Dynamixel protocol (i.e. Pypot) make assumptions about the hardware and try to re-tune these values incorrectly, which results in improper operation.

Therefore if you wish to adjust the Zero offset, enable/Disable 12bit resolution mode or tune the PID gains, set this flag to 0 first, to enable Writing to the memory positions where these configurations are saved.
On every boot, this flag is set to 1 to protect these tuning parameters.

Torque Enable

Enables or disables torque output.

If set to 0, the unit stops seeking the Target position and the joint becomes free moving. The joint is placed in Dynamic Brake mode.

If set to 1, enables Torque output. When transitioning from 0 to 1, the unit automatically sets the Target Position = Present Position.
This ensures the unit is torqued at the current position in order to avoid any jumping or inadvertent movement.

Also note that WRITing a Target Position or a Target Speed, automatically enables Torque. Once again, this is implemented for compatibility with third-party libraries.

D, I, P Gain

Sets the gains of the position controller of the actuator.

We generally DON'T recommend tweaking these values as PID tuning is an advanced topic.

By default, the units come tuned for the fastest output response at maximum torque.
If you wish to attempt tuning a more elastic behavior you may want to try reducing the P and increasing the I.

Changes to the P,I,D gains are stored in RAM only. They will be reset to factory default after a power cycle.

IMPORTANT (1) some joints are mounted with physical mechanical limits. Misconfiguration of the PID gains may result in uncontrolled motion and possible collision with the mechanical limits and consequent damage to the unit.
If you are unsure or require assistance for PID tuning, please contact our support team for guidance (support@seedrobotics.com).

IMPORTANT (2)
If you need to change this setting you must first set memory position 23/0x17 (PID, Zero_Offset and Resolution Tuning Lock) to 0. Without doing this, any attempt to change this setting will fail.

Target Position

Writing to this memory position will make the Actuator move to the Target provided.

The actuator will actively seek the target position at all times. This means it will move to find the target position and hold torque at that position.
(until torque is disabled at position 24 or a new Target Position is given).

When writing a Target Position, if Torque (position 24) is disabled, it will be automatically enabled.

OVERLOAD or OVERHEATING conditions: if the actuator is unable to reach the target position or starts overheating (usually due to external mechanical blockage or due to excess load), it will generate an OVERLOAD ERROR or TEMPERATURE ERROR and release torque to protect the unit.
This is meant to protect the hardware from damage due to stalling in controllable and predictable scenarios. However, this functionality does not replace the user's responsibility in observing the maximum ratings for the unit and the actuators when in operation.
(if the user wishes, the check for Shutdown Conditions can be disabled in memory position 18 (Shutdown Conditions) )

The Overload error is reported in the RETURN PACKET after a command is sent to the unit.
- When the unit has an OVERLOAD error, Torque can't be re-enabled until the unit is rebooted.
You can reboot the actuator by sending a REBOOT packet over the Dynamixel protocol or by power cycling the unit. If the actuator is connected to an EROS mainboard, you can reset power to the internal actuators by WRITING a 1 to memory position 67 (Internal PSU Reset) in the Eros Main Board control Table.

To prevent overload errors, the user is advised to accompany the motion of the unit by querying the Present Position parameter (position 36) and ensuring that it is varying.
If the user detects a stall, it can either set the Target Position=Present Position (where the unit is stalling) momentarily until the external blockage is removed. If the cause of the stall is excess load, users are advised to Turn off torque (memory position 20) to avoid damage to the unit.

If you are making a movement to grasp an object the recommended approach is to set a low Target Speed near the target (5 RPM or less) which gives you a larger time window to query the Present Position and stop the motion when you detect movement has stalled (by setting Target Position=Present Position). Stalling, in this situation, would typically mean the object has been grabbed.

You can also check the Temperature of the actuator, by reading memory position 43 (Present Temperature).

Target Speed

The maximum speed at which the actuator moves. This value is in units of 0,11RPM.
If set to 0, the unit will move at maximum speed. This is the default setting.

The maximum value accepted for this parameter is 1023.
Different actuator models will have different maximum speeds. On average it is in the range of 50~60RPM; therefore if the user sets a Target Speed higher then the maximum physical speed, the actuator will move at its maximum physical speed.

When writing a Target Speed, if Torque (position 24) is disabled, it will be automatically enabled.

Depending on the Joint Type, different Target Speeds are recommended:

  • Wrist Rotation: any speed
  • Wrist Flexion: any speed (note that certain models, due to inertia may not achieve maximum speed, even if set to do so)
  • Wrist Adduction: any speed (note that certain models, due to inertia may not achieve maximum speed, even if set to do so)
  • Thumb Adduction: <20RPM
  • Finger Flexion (any finger): <20RPM

These are the recommended values to best operation when closing but, most importantly, when opening, to ensure the springs in the fingers and tendons open the DoF correctly and in sync.

NOTE: The minimum speed for smooth operation is ~1 RPM ( a setting of 10 ). Lower values will be accepted, not to limit the user, but discretization of the movement may be observed.

Present Position

Returns the Present Position as measured by the Position Sensor built into the actuator.

This will be in the range of 0~1023(10bit) or 0~4095(12bit) depending on the setting of memory position 20 (Emulate 12 bit resolution)

Present Speed

Returns the present speed as measured by the internal sensor.

This value is and Unsigned WORD value. However direction of movement can be determined by reading the 11th bit of the value returned.
(in practice if value ⇐1023 it is moving on CCW direction; if value >1023 it is moving is CW direction)

Present Temperature

Present temperature inside the actuator in degrees Celsius.

This value is approximate (it may have a small error of a few degrees, due to inherent behavior of the sensor).

Moving

Indicates if the servo is Moving (1) or not (0).

It is the same as checking if Present Speed != 0.

Bootloader Password Length

Length of the device bootloader password.
Bootloader passwords are used to enable individual firmware upgrade of the servos without physical interaction amd while connected to the daisy chain bus.

When assembled on a Seed Robotics unit, passwords are typically set with just 1 character at the time of manufacturing.

First Character of the Bootloader Password

The ASCII code of the first character of the Bootloader password.
If the password has a length of more than 1 character, only the first character is reported in the control table.

Bootloader Timeout

The bootloader timeout byte.
This information is for debugging purposes only for the use of Seed Robotics support personel.

UART Comm Health
Framing Errors count
Processor Buffer overflow count
Firmware Buffer overflow count

This information is for debugging purposes only for the use of Seed Robotics support personel.

Servo Control Mode

NOTE: DIRECT PWM CONTROL MODE IS NOT YET IMPLEMENTED. THIS IS DOCUMENTED AS PART OF OUR ROADMAP AND WILL BE MADE AVAILABLE OVER THE COMING MONTHS.
At the moment this set to the default of POSTITION CONTROL mode, which is the typical control mode for any servo motor.

0=Position Control Mode
1=Direct PWM Control mode

About Direct PWM Control mode: By querying Current Drawn by the motor through the control table on the EROS main board, and since Current is directly proprotional to PWM, by controlling the PWM on the motor users are able to build a closed loop control cycle for true Force Estimation and Torque Control.

When Direct PWM Control Mode is enabled, the PID position controller is disabled which provides a cleaner signal on the the Current Reading and eliminates unknowns such as peaks due to acceleration and not necessarily force.

The Present Position will continue to be reported in real time and the unit will continue to enforce verification of physical bounds to prevent damage due to a crash or malfunction in the main controller.

However PWM applied to the motor will be directly controlled by the user, by writing to memory position 92 (Motor PWM).

Motor PWM

When memory position 90 is set to Position Control Mode, this will report the current PWM applied to the motor.

In this mode, this value is READ ONLY.

This value is unsigned but by reading the 9th bit the users may determine the direction of the PWM applied.
This is the same as saying that if value < 255 it is moving CCW; if value > 255 it is moving CW.

Knowing the direction of PWM is helpful when building an incremental PID controller based on Current Reading (from the main board control table) and Position. Since the current is read as a modus it does not provide any information about direction. That can be retrieved from this memory position.

When memory position 90 is set to Direct PWM Control Mode, users should write the desired PWM to this memory position.
NOTE: DIRECT PWM CONTROL MODE IS NOT YET IMPLEMENTED. THIS IS DOCUMENTED AS PART OF OUR ROADMAP AND WILL BE MADE AVAILABLE OVER THE COMING MONTHS.

When specifying the desired PWM the 9th bit will indicate the direction of PWM to the applied (CCW/CW)

The actuator can cope with very high frame rate updates (the typical turn around time for a command is 1.2ms).
If you are operating in this mode we recommend updating this value every 4-5ms.

Copyright © 2015-2018 Seed Robotics Ltd