eros:seedactuators_controltable

This is an old revision of the document!


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.

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.

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
uart_write_bytes(OUT_VALUE & 0xFF, (OUT_VALUE >> 8) & 0xFF)

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.

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
20 (0x14) BYTE (1) Emulate 12 bit resolution RW Default=1, set to 12bit mode EEPROM
23 (0x17) BYTE (1) PID 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 (Position control or Direct PWM control) R 0=Position control, 1=PWM Control 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.

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.

PID Tuning Lock

Locks WRITING to the memory positions and adjust the PID values (26 to 28).

This is meant to prevent misconfiguring the unit inadvertently.

If you wish to tune the PID settings, set this flag to 0 first, to enable Writing on the PID-related memory positions.

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: 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 you may contact our support team for guidance.

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 situations: if the actuator is unable to reach the target position (usually due to external mechanical blockage), it will automatically turn off torque and report an OVERLOAD ERROR.
This is meant to protect the hardware from damage due to stalling.

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 (power cycled).
If the actuator is connected to an EROS main board, you can reset power to the internal servos by writing 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 users detects a stall, it can either set the Target Position=Present Position (where the unit is stalling) or Turn torque off momentarily until the external blockage is removed.

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

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.

Different actuator models will have different maximum speeds. On average it is in the range of 50~60RPM.

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 10th 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 aproximate, and may have a maximum error of 10 degrees.

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 by 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-2023 Seed Robotics Ltd

  • eros/seedactuators_controltable.1510753504.txt.gz
  • Last modified: 2017/11/15 13:45
  • by Pedro Ramilo