Getting started with your Seed Robotics unit

In our first blog post we would like to address the process of getting started with your unit.
We will cover connection and writing a first script (in Python) to get joints moving and hand opening and closing.

Upon completing the tutorial in this post you should be able to make each joint of your Seed Robotics unit move to your desired position.
In subsequent posts we will focus on expanding these examples with queries on the real-time feedback of the unit.

For this exercise we will be communicating with the unit via the main Communication port. This is located on the back of the unit and is a 3pin or 4pin connector (whether your unit communicates over One Wire TTL UART or RS485/Full Duplex TTL UART).

The unit needs to be (1) supplied with power and (2) connected to your computer where we will be running the Python script.

a) If you ordered your unit with the PC Interface Board + Power Interface board, please proceed as follows:

Connect one of the cables to the main Communication port at the back of your Seed Robotics unit.
Run that cable to the Power Interface board
If you have a PC Interface board that does not come with a 3pin or 4pin cable already, connect one to the unit
Connect that cable to the same Power Interface board of point 2) above.
Finally connect the Power Supply to the Power Interface board (it should be a barrel jack connector)

b) If you didn't get the PC Interface Board + Power Interface board, you will need to build your own cable.

You can find the Connector Pinout on the dedicated Knowledge Base page.

We won't get into the details on building the cable (that would be a blog post on its own) but if you need assistance email support@seedrobotics.com and we'll be happy to clarify any question you may have.

When you power the unit the LED will turn on and it will be in a Purple of Green color. This signals the unit is enumerating the internal actutaors and performing some additional start-up tasks. This may take up to 5 seconds.

Once the unit is ready to receive commands and begin operation, the LED becomes white (on the RH4Ds) or go into a 3 colour state (where the 3 colours blend into white at the center of the logo).

Another point of notice is that the cooling fan (if your model has one) will typically start at a fast speed and then slow down once the unit has completed booting.

For the purposes of this tutorial we'll be using Python and an Open Source Python Library to control the unit, by sending Dynamixel 1 commands to control it. Dynamixel 1 is the default serial protocol used to communicate with Seed Robotics units through the main communication port, at the time of writing.

NOTE: In this exercise we'll be using Python 2.7. The Open Source library we'll be using may work with Python 3 but we strongly recommend using Python 2.7 to complete this exercise.

You can find instructions on how do that on various Operating Systems in the https://www.python.org/downloads/release/python-2713/

PySerial is a cross-platform library for communicating via a Serial port (whether physical or using USB to Serial adapters).

It is required to pass the commands to our Seed Robotics unit, since it communicates over a Serial Interface.

To install the pySerial package, open a command prompt, browse to your Python installation folder and type:

pip install pyserial

For guidance on using pip see the page Installing Packages in the Python Documentation.

The Python Dynamixel package is an open source package originally written to support the Dynamixel 1 protocol.

To install the dynamixel package, open a command prompt, browse to your Python installation folder and type:

pip install dynamixel

For guidance on using ‘pip’ see the page Installing Packages in the Python Documentation.

The package has several abstractions built-in, but we will be using the simplest, low level, commands for the purpose of this learning tutorial.

As we mentioned, we'll be using Python to write our first program.
If you are new to Python, you need to get a Text Editor to write our programs.
There is a great introduction (with a suggestion of a Text Editor) at Learnpythonthehardway.com. Despite the name, the page is quite friendly and should provide you with a comfortable starting experience.

We're now ready to start coding and make joints move. Exciting stuff!

Fire up you Text Editor and let’s start typing:

We need to begin by setting the PC Serial Port name where our unit is connected.

If you are on Windows it should be COMxx, where xx is a number. To find the available port numbers you can bring up Device Manager. Press the WINDOWS KEY + R simultaneously to bring up the “Run” dialog. Enter devmgmt.msc and click OK.
Once the Device Manager Window opens, browse to “Ports (COMM & LPT)” and double click the node to expand it. You will see the numbers of the ports connected to your computer.

If you are on Linux or MacOS, the serial port name should be /dev/ttySxx or /dev/ttyACMxx. To list the available Serial Interfaces, open a Terminal window and type ls /dev/ttyS* and then ls /dev/ttsACM*.
If you are using a USB to Serial adapter, it will likely be ttyACMx.

Once we’ve determined the name of our Serial port we can add it to the code below:

# Lines that begin with a # are comments;
# Comments can be used to write actual comments or to enable or disable a line of code by adding a # at the beginning of the line

# Begin by declaring and Import the necessary libraries
# needed for our tutorial
import os
import dynamixel
import sys
import subprocess
import time

# Replace "COM1" below with the actual COMM number if you are on Windows
# or with the full "/tty/..."  if you are on Linux of MacOS
SERIAL_PORT_NAME = "COM1"

# We'll also set the Baud Rate. By default the main communications port is configured 
# to operate at 1Mbps=1000000 bps, so you can leave this unchanged (unless you
# have actually changed this configuration on your unit)
SERIAL_PORT_BAUD = 1000000

Next we'll create an instance of the necessary objects for communication.
Once we do it, we will query the bus and list the Actuator IDs (joints) found.

# Instantiate a Serial communication stream
serial = dynamixel.SerialStream(port=SERIAL_PORT_NAME, baudrate=SERIAL_PORT_BAUD, timeout=1)

# Instantiate an actuators network object
net = dynamixel.DynamixelNetwork(serial)

# To help us identify our internal Actuator IDs 
# and for troubleshooting purposes, we will now
# search for actuators (one for each joint) that are accessible on the bus
# This is called PING'ing

print "Scanning for Actuator IDs..."
net.scan(1, 253)

print "Found the following IDs: "
for dyn in net.get_dynamixels():
	print dyn.id

# Make sure we actually found actuator ids/joints
if not settings['servoIds']:
	print 'No Actuator ids have responded to our PING command. Are you sure you have entered the correct COMM port name? Is your Serial adapter correctly connected to the PC and the Seed Robotics unit?'

	#if nothing was found, terminate the program
	sys.exit(0)

We are now ready to start writing the code to move joints. At this point it is important to understand a few key concepts: Underactuation and Actuator-to-joint relation: - Some joints such as wrist rotation, wrist flextion and adduction have a dedicated actuator for that joint. - Other joint sets such as the fingers are “under actuated”, which means one actuator will move the 3 finger joints. (one actuator for 3 joints, hence the “under actuated” designation). Actuator IDs: Each actuator has a unique ID, and in addition the main control board also has a unique ID.
To move or query an actuator (and associated joints) we address the actuator directly by its unique ID.

In addition to the unique IDs, the Dynamixel protocol has a neat feature called the Broadcast ID, which is 0xFE. When we send a command to this ID, all actuators on the bus will execute the command as if it was addressed individually to them.
(this is useful for system wide commands such as turning torque on or off. The torque on/off setting changes the joint behavior from free moving to stiff)

Actuator Control Table: So far we’ve established we can address actuators by their unique ID or using the Broadcast ID.
We now need to know how to request each specific function from the actuator.

This is done via the Control Table of the Actuator.

The Control table is a list of memory addresses that perform well documented functions.
For example, writing a “1” to Control table position 30 (0x24) of an Actuator will turn torque on; writing a “0” will turn it off.
Writing to Control table position XXXX will set the actuator moving speed in the same way that writing to Control table position YYYY will set the actuator target position and thus make it move to that desired position.

Now that we’ve covered all this, the only thing left, is to find out the IDs of the actuators in your unit.
This varies depending on the model you have, because different models have a different number of actuated joints. You can find the default, factory assigned IDs, for your unit, in the Model's Documentation:

(the ID of the actuators can be changed if the user chooses to do so; assuming you haven’t reconfigured yours, they should be set to the default, factory assigned, IDs).

To command a joint we need to WRITE to TARGET POSITION address in the in that Joint.

We wont get into the subject of the Control tables in this post but for the purpose of the task at hand we must explain the following:

In abstract terms, each actuated joint is operated by an Actuator. We can talk to this actuator using its unique ID.
The actuator has a Control Table, where each line number coresponds to a functionality.

For our case at hand, if we write to Control Table Position 30, we will write the Target Position.
As soon as we write this information to the actuator, it will move the Target position we just sent.