UGA Logo

TellDarwin Reference

The content and opinions expressed on this Web page do not necessarily reflect the views of nor are they endorsed by the University of Georgia or the University System of Georgia.

Table Of Contents

Darwin Standing
  1. Getting Started
    1. What is TellDarwin
    2. Download
      1. TellDarwin
      2. Example Max Patches
    3. Installation Instructions
    4. Invocation Options
    5. Demo Videos
  2. General
    1. Sending / Receiving Requests
      1. Max/MSP
      2. Stdin / Netcat
    2. Interpreter Behavior
    3. Pitch, Roll, Yaw / X, Y, Z
  3. Servos
    1. One At A Time
    2. All At Once
    3. Gripper Arms
    4. Servo Errors
  4. Sensors / LEDs
    1. Eyes / Forehead
    2. Accelerometer
    3. Gyroscope
    4. Ears
    5. Foot Pressure
  5. Multimedia
    1. Camera
    2. Microphone
    3. Speaker
    4. USB Microphone
  6. ROBOTIS functionality
    1. Walking
    2. Actions
  7. Misc Commands
    1. Speak
    2. System
  8. More
    1. Bugs
    2. Contact The Author
    3. Links

What Is TellDarwin?


TellDarwin is a command interpreter for DARwIn-OP Robot running Linux (designed and tested on Ubuntu 9.10). It was written by Michael Krzyzaniak at the University of Georgia, Ideas for Creative Exploration (ICE). It allows users to send simple, intuitive requests like

start walking
set eye color 0.5 0.2 1
get accelerometer
start camera
set head position 30 degrees

to the robot wirelessly from a remote computer, and have it respond as expected. The software is intended to receive requests from Max/MSP (a graphical programming language for OSX or Windows that is popular in the Arts), but also has options that allow users to send requests from the command-line locally using the robot's stdin, or remotely with netcat (nc, available for any OS) or other software that can send simple ASCII messages over TCP. These options allow users to easily write scripts that control the robot.

Table Of Contents

Where Can I Download TellDarwin?

All versions are here, current is on top:
Version History
VersionDate OS Link
2.0 07.01.12LinuxDownload
1.1 12.15.11LinuxDownload
1.0 06.11.11LinuxDownload

Table Of Contents

Where Can I Get Example Max Patches?

Download Example Max Patches

Furthermore, Max is here. There is a free 30 day demo. If you don't want to purchase Max, you can have the Max 'runtime' for free forever, which will allow you to run patches but not edit them. Is the author, you ask, conflicted about combining an open-source robot and his own open-source code with greedy, money-hungry proprietary software? My reply is that I just work here and only do as I am told without asking questions.

Table Of Contents

How Do I Install TellDarwin?

TellDarwin uses the ROBOTIS framework, which must be installed first. It can be obtained here:

TellDarwin version 2.0 uses the ROBOTIS framework version 1.5, and is not backwards compatible. Note also that ROBOTIS 1.5 requires version 30 of the Dynamixel firmware. TellDarwin may or may not work with future releases of the framework, as sometimes asinine changes in syntax require the software to be rewritten.

TellDarwin also uses the ALSA (Advanced Linux Sound Architecture) user-land library, which must be installed before TellDarwin can be compiled. ALSA can be installed with:

sudo apt-get install libasound2-dev

TellDarwin can then be downloaded and unzipped. The entire unzipped folder should be moved to /darwin/Linux/project/. Then, using the terminal, navigate there with:

cd /darwin/Linux/project/TellDarwin/

and then compile by entering:


TellDarwin can then be run with:

sudo /darwin/Linux/project/TellDarwin/TellDarwin

Notice that TellDarwin must be run as root to access the actuators and sensors. If you don't want to have to type all that every time, you can put a shortcut in your $PATH by executing something like the following all at once:

echo "sudo /darwin/Linux/project/TellDarwin/TellDarwin \"\$@\"" >> /usr/local/bin/td;
chmod a+x /usr/local/bin/td

which then allows you to run TellDarwin at any time with the command


and optional invocation options. You can then test TellDarwin with

sudo echo "get accelerometer" | td -sq

which should print out the accelerometer reading, roughly like:

0.005378 0.957893 0.013457

Table Of Contents

How Do I Invoke TellDarwin?

Assuming you followed the installation instructions,


should do it. Additionally, the following options are available:
command-line options
option mnemonicdescription
-h help print this help and exit
-l laptop laptop mode (do not initialize the Robot's frameworks)
-m MAX listen for requests from Max/MSP (default)
-n Netcat listen for requests from netcat
-s stdin listen for requests from stdin
-p[int] port listen on the specified port (default 7400)
-q quiet suppress the printing of all messages
-v verbose print more messages than normal
In general, -q should probably be used with -n and -s. On the other hand, -p has no effect with -s, for obvious reasons. -l probably has no use to anyone other than me (it saves me from hauling my sorry ass all the way the hell across campus to the engineering center every time I want to test some minor change).

Table Of Contents

What Does TellDarwin Do?

TellDarwin can be used as an educational tool that helps students learn about robotics, programming and technology in general. It can aid robotics researchers in the rapid prototyping of complex algorithms that extend the functionality of the robot. It can be used to create interactive performance pieces. It can be used to enslave the human race...

Okay. How about a quick demo video:

Dr. David Saltz wrote software in Max/MSP called DarwinAnimator that runs on top of TellDarwin. DarwinAnimator allows theater students to record complicated robotic sequences with out any programming:

Here is a video that shows what students of UGA's THEA 5870/7870 (Interactive Media & Live Performance) did with DarwinAnimator running on top of TellDarwin during Fall 2011.

TellDarwin and Darwin Animator competed in the Darwin-Op Application Challenge at the International Conference on Robotis and Automation (ICRA) in St. Paul in 2012. Here is a video of the presentation:

Table Of Contents

How Do I Communicate With The Robot Using Max/MSP?

Max udpsend example

Communication with the robot is done through is done through the udpsend and udpreceive objects. The robot's IP is likely to be different each time you use it, but will be if you are connected by ethernet cable. Normally, the interpreter will print out the robot's current IP when you start TellDarwin. By default, the port number is 7400, although that can be changed with the -p [port] option when starting the interpreter. TellDarwin understands anything that can be connected to udpreceive, including any combination of ASCII strings, symbols, floats and ints alone or together in any order. Words send requests to the interpreter and numbers repeat the previous request with a new value. It also understands toggle, which is interpreted as the integer 0 or 1, and bang, which repeats the last request (its us is not recommended). The image to the left demonstrates some of these possibilities.

Max udpreceive example

In Max/MSP mode, get requests return the requested value(s) as a float or a list of floats, preceded by an ASCII tag that describes the data. This facilitates the routing of data coming out of udpreceive objects. This is not intended to be a Max/MSP tutorial, but for clarity, the example to the right is provided to show what the returned messages "look like", and how to handle them. In the example, the three components of the gyroscope are preceded by the tag "GYRO". Below is a list of the return tags that precede the various values you can get from the robot, and the number of values that follow the tag.

Return Tags For get Requests (Max/MSP version only)
Request Tag Number of Values Units
body position BODY 1 per servo (usually 20) deg, rad
right shoulder pitch position R_SHOULDER_X 1 deg, rad
left shoulder pitch position L_SHOULDER_X 1 deg, rad
right shoulder roll position R_SHOULDER_Z 1 deg, rad
left shoulder roll position L_SHOULDER_Z 1 deg, rad
right elbow position R_ELBOW 1 deg, rad
left elbow position L_ELBOW 1 deg, rad
right hip yaw position R_HIP_Y 1 deg, rad
left hip yaw position L_HIP_Y 1 deg, rad
right hip roll position R_HIP_Z 1 deg, rad
left hip roll position L_HIP_Z 1 deg, rad
right hip pitch position R_HIP_X 1 deg, rad
left hip pitch position L_HIP_X 1 deg, rad
right knee position R_KNEE 1 deg, rad
left knee position L_KNEE 1 deg, rad
right ankle pitch position R_ANKLE_X 1 deg, rad
left ankle pitch position L_ANKLE_X 1 deg, rad
right ankle roll position R_ANKLE_Z 1 deg, rad
left ankle roll position L_ANKLE_Z 1 deg, rad
head pan position HEAD_Y 1 deg, rad
head tilt position HEAD_X 1 deg, rad
right hand position R_HAND 1 deg, rad
left hand position L_HAND 1 deg, rad
right arm yaw position R_ARM_Y 1 deg, rad
left arm yaw position L_ARM_Y 1 deg, rad
body speed BODY_SPEED 1 per servo (usually 20) deg/sec, rad/sec
right shoulder pitch speed R_SHOULDER_X_SPEED 1 deg/sec, rad/sec
left shoulder pitch speed L_SHOULDER_X_SPEED 1 deg/sec, rad/sec
right shoulder roll speed R_SHOULDER_Z_SPEED 1 deg/sec, rad/sec
left shoulder roll speed L_SHOULDER_Z_SPEED 1 deg/sec, rad/sec
right elbow speed R_ELBOW_SPEED 1 deg/sec, rad/sec
left elbow speed L_ELBOW_SPEED 1 deg/sec, rad/sec
right hip yaw speed R_HIP_Y_SPEED 1 deg/sec, rad/sec
left hip yaw speed L_HIP_Y_SPEED 1 deg/sec, rad/sec
right hip roll speed R_HIP_Z_SPEED 1 deg/sec, rad/sec
left hip roll speed L_HIP_Z_SPEED 1 deg/sec, rad/sec
right hip pitch speed R_HIP_X_SPEED 1 deg/sec, rad/sec
left hip pitch speed L_HIP_X_SPEED 1 deg/sec, rad/sec
right knee speed R_KNEE_SPEED 1 deg/sec, rad/sec
left knee speed L_KNEE_SPEED 1 deg/sec, rad/sec
right ankle pitch speed R_ANKLE_X_SPEED 1 deg/sec, rad/sec
left ankle pitch speed L_ANKLE_X_SPEED 1 deg/sec, rad/sec
right ankle roll speed R_ANKLE_Z_SPEED 1 deg/sec, rad/sec
left ankle roll speed L_ANKLE_Z_SPEED 1 deg/sec, rad/sec
head pan speed HEAD_Y_SPEED 1 deg/sec, rad/sec
head tilt speed HEAD_X_SPEED 1 deg/sec, rad/sec
right hand speed R_HAND_SPEED 1 deg/sec, rad/sec
left hand speed L_HAND_SPEED 1 deg/sec, rad/sec
right arm yaw speed R_ARM_Y_SPEED 1 deg/sec, rad/sec
left arm yaw speed L_ARM_Y_SPEED 1 deg/sec, rad/sec
body enable BODY_ENABLE 1 per servo (usually 20) 0 or 1 Boolean
right shoulder pitch enable R_SHOULDER_X_ENABLE 1 0 or 1 Boolean
left shoulder pitch enable L_SHOULDER_X_ENABLE 1 0 or 1 Boolean
right shoulder roll enable R_SHOULDER_Z_ENABLE 1 0 or 1 Boolean
left shoulder roll enable L_SHOULDER_Z_ENABLE 1 0 or 1 Boolean
right elbow enable R_ELBOW_ENABLE 1 0 or 1 Boolean
left elbow enable L_ELBOW_ENABLE 1 0 or 1 Boolean
right hip yaw enable R_HIP_Y_ENABLE 1 0 or 1 Boolean
left hip yaw enable L_HIP_Y_ENABLE 1 0 or 1 Boolean
right hip roll enable R_HIP_Z_ENABLE 1 0 or 1 Boolean
left hip roll enable L_HIP_Z_ENABLE 1 0 or 1 Boolean
right hip pitch enable R_HIP_X_ENABLE 1 0 or 1 Boolean
left hip pitch enable L_HIP_X_ENABLE 1 0 or 1 Boolean
right knee enable R_KNEE_ENABLE 1 0 or 1 Boolean
left knee enable L_KNEE_ENABLE 1 0 or 1 Boolean
right ankle pitch enable R_ANKLE_X_ENABLE 1 0 or 1 Boolean
left ankle pitch enable L_ANKLE_X_ENABLE 1 0 or 1 Boolean
right ankle roll enable R_ANKLE_Z_ENABLE 1 0 or 1 Boolean
left ankle roll enable L_ANKLE_Z_ENABLE 1 0 or 1 Boolean
head pan enable HEAD_Y_ENABLE 1 0 or 1 Boolean
head tilt enable HEAD_X_ENABLE 1 0 or 1 Boolean
right hand enable R_HAND_ENABLE 1 0 or 1 Boolean
left hand enable L_HAND_ENABLE 1 0 or 1 Boolean
right arm yaw enable R_ARM_Y_ENABLE 1 0 or 1 Boolean
left arm yaw enable L_ARM_Y_ENABLE 1 0 or 1 Boolean
accelerometer ACCEL 3 (X, Y, Z) g (9.81*m/s^2)
accelerometer x ACCEL_X 1 g (9.81*m/s^2)
accelerometer y ACCEL_Y 1 g (9.81*m/s^2)
accelerometer z ACCEL_Z 1 g (9.81*m/s^2)
gyroscope GYRO 3 (X, Y, Z) deg/sec, rad/sec
gyroscope x GYRO_X 1 deg/sec, rad/sec
gyroscope y GYRO_Y 1 deg/sec, rad/sec
gyroscope z GYRO_Z 1 deg/sec, rad/sec
ear EARS 2 (L, R) -1 to 1 arbitrary
right ear R_EAR 1 -1 to 1 arbitrary
left ear L_EAR 1 -1 to 1 arbitrary
eye EYE 3 (R, G, B) 0 to 1 arbitrary
eye red EYE_R 1 0 to 1 arbitrary
eye green EYE_G 1 0 to 1 arbitrary
eye blue EYE_B 1 0 to 1 arbitrary
forehead FOREHEAD 3 (R, G, B) 0 to 1 arbitrary
forehead red FOREHEAD_R 1 0 to 1 arbitrary
forehead green FOREHEAD_G 1 0 to 1 arbitrary
forehead blue FOREHEAD_B 1 0 to 1 arbitrary
walking angle WALK_DIRECTION 1 deg/step, rad/step
walking speed x WALK_X 1 cm/sec
walking speed y WALK_Y 1 cm/sec
walking speed z WALK_Z 1 cm/sec
walking period WALK_PERIOD 1 Hz
walking balance WALK_BALANCE 1 0 or 1 Boolean
walking enable WALK_ENABLE 3 (head, r arm, l arm) 0 or 1 Boolean
camera brightness CAMERA_BRIGHT 1 0 to 1 arbitrary
camera contrast CAMERA_CONTR 1 0 to 1 arbitrary
camera saturation CAMERA_SAT 1 0 to 1 arbitrary
camera gain CAMERA_GAIN 1 0 to 1 arbitrary
camera exposure CAMERA_EXP 1 0 to 1 arbitrary
right foot pressure R_FSR 4 Newtons
left foot pressure L_FSR 4 Newtons
right foot pressure x R_FSR_X 1 0 to 1 arbitrary
left foot pressure x L_FSR_X 1 0 to 1 arbitrary
right foot pressure z R_FSR_Z 1 0 to 1 arbitrary
left foot pressure z L_FSR_Z 1 0 to 1 arbitrary

Table Of Contents

How Do I Communicate With The Robot Using The Command-Line?

If you want to send requests from the robot's stdin, start the software with

td -sq

and then start typing requests. Each request is processed when a newline character is received (i.e. the 'return' key is pressed). Values returned from get requests are printed to stdout as ASCII digits.

If you want to send requests from a remote computer, start the software with

td -nq

This causes the interpreter to wait for a TCP connection on port 7400 (this can be changed with the -p option). Then, start netcat on the the computer you want to send commands from. Assuming that DARwIn's IP is (you can find out what it actually is with by typing ifconfig into DARwIn's terminal), the command to start netcat will be:

nc 7400

You may then start typing requests. Each request is processed when a newline character is received. Values returned from get requests are sent back over TCP as ASCII digits.

If you want to write shell scripts, you will probably need a shell that supports floating-point numbers, at least if you want to perform math on values returned by get requests. Bash does not support floats . Zsh does . From the robot's stdin, (assuming TellDarwin is in your $PATH) you should be able to move the robot's head with a command like:

echo "set head position 40 degrees" | sudo TellDarwin -s

TellDarwin will exit when EOF is reached, or can be terminated explicitly by sending the request kill to the interpreter. You can send several requests at once by separating them by newlines or semicolons, as in

echo "set head position 40 degrees; pause 1000; -40" | sudo TellDarwin -s

The request pause causes the interpreter to sleep for the specified number of milliseconds. You can also get values from the robot. The expression

red=$(echo "get eye red;" | sudo TellDarwin -qs)

sets the shell variable $red to the value of the red component of the robots eyes. Note that TellDarwin was invoked with -q to prevent $red from being set to whatever system error messages or other gobbledegoo may have otherwise been printed to stdout.

Assuming that TellDarwin is already running on DARwIn in netcat mode, the above requests can also be piped into netcat on the remote machine, as in:

echo "set head position 40 degrees" | nc 7400
echo "set head position 40 degrees; pause 1000; -40" | nc 7400
red=$(echo "get eye red;" | nc 7400)

Table Of Contents

How Does The Interpreter Behave?

Words Understood by the Interpreter
Category Word Synonyms
Request Type get None
Request Type set None
Request Type increment None
Request Type start begin
Request Type stop quit
- - -
Body Part body None
Body Part head neck
Body Part shoulder arm
Body Part elbow None
Body Part hip leg
Body Part knee None
Body Part ankle foot
Body Part hand None
Body Part accelerometer accel
Body Part gyroscope gyro
Body Part ear ears
Body Part eye eyes
Body Part forehead None
Body Part camera video
Body Part microphone mic
Body Part speaker None
Body Part usbmic usbmicrophone
Body Part walk walking
- - -
Side right None
Side left None
- - -
Component x pitch, tilt, red
Component y yaw, pan, green
Component z roll, blue
Component red x
Component green y
Component blue z
- - -
Unit degrees degree
Unit radians radian
- - -
Property angle position, direction
Property speed velocity
Property enable enabled
Property pressure None
Property balance None
Property period None
Property brightness None
Property saturation None
Property contrast None
Property gain None
Property exposure None
- - -
No Category clear None
No Category speak say
No Category sleep pause
No Category kill
No Category system None

The interpreter interprets requests. A request is some combination of words and/or numbers. In Max/MSP mode, an individual request usually occupies an individual message box. In netcat or stdio mode, individual requests are separated by semicolons or newline characters. Requests are case-insensitive. Each word that the interpreter understands belongs to a category, listed in the table to the right. A complete request contains one word from each category. Aside from a few special exceptions (described below) words may occur in any order. A typical request might be:

get right shoulder roll position degrees

which causes the robot to return the current angle of the requested servo. Some request types require an additional numeric value to be complete. The number usually may come by itself, in a separate request, after the words. For example

set left hip x position radians

causes the robot to wait for a value. Subsequently, any int, float or numeric string will move the left hip, until another request comes that overrides the one at hand. The number may also be included in the request along with the words, so

set left hip x position -0.5 radians

causes the hip to move immediately. Any subsequent int or float also causes the hip to move. Again, the words and numbers may be mixed up in any order within the request.

In general it is not necessary to send complete requests, for two reasons. 1) The interpreter attempts to be syntactic. Many combinations of words do not make sense, so the nonsensical words are ignored. For instance if you are trying to set the position of the head, the specified side (right or left) is ignored, because the robot has only one head and it is lies in the center of the midsagittal plane. Furthermore, although you can set the position or speed of the head, you cannot set its exposure, so in this case the interpreter assumes that you mean position when a nonsensical value is given. 2) The interpreter attempts to be context-sensitive by remembering the word from each category of the previous request, so any request only needs to contain words from the categories that are different from the previous request. So the request


when immediately preceded by the request

get right ankle roll speed degrees

is sufficient to return the speed, in degrees/sec, of the servo that controls the left ankle roll. Thus a program that performs all calculations in radians need only send the request radians once at the beginning of the program, and it may be omitted from all subsequent requests. If you just previously set the position of a particular servo, you can set its speed with only the request speed and a value. If you just got the x component of the accelerometer, the request y will return the y component of the same. In MAX, it is useful to combine subsequent requests in a single message box, separated by a comma, thus:
Compound Requests
The requests in the "No Category" category are handled differently than other words: they do not reside in any category, and they are not remembered between requests, nor do they affect any of the remembered categories. Most of these words are also, unlike other words, order sensitive. For instance

speak get accelerometer x

causes the robot to say "get accelerometer x", while the request

get accelerometer speak x

is a kludge that causes the robot to say "x" and return all three components of the accelerometer. Unknown and misspelled words are ignored.

Table Of Contents

Can You Explain Pitch, Roll and Yaw / X, Y, Z Axes?


The software defines the X axis as the axis that runs from left to right through the robot. The Y axis runs from head to toe, and the Z axis runs from behind the robot to in front of it. "Pitch" refers to the X axis, "Yaw" to Y, and "Roll" to Z, as in the image at left.

It is important to remember that pitch, roll and yaw mean "rotating about the corresponding axis", not "moving along the corresponding axis". An analogy may be made with a boat. Roll is how the boat moves when waves are crashing into its side, so that it rocks from side to side, because under these conditions it rotates about the Z axis. Pitch is how the boat moves when waves are crashing into its front, so that the bow dives in and out of the water, because it rotates about the X axis. Yaw is how the boat moves when it is in the eye of the malestrøm, because it rotates about the Y axis.

Shaking your head "No" is changing its yaw, "Yes" is its pitch, and "I don't know" (touching an ear to a shoulder) is its roll (you cannot control the roll of DARwIn's head).

shoulder pitch

In this animation, Glutmech, the Vulcan Gunner is changing his shoulder pitch (i.e. he is rotating them about the X axis). DARwIn can do this with her head, right and left shoulder, elbow, hip, knee and ankle.

shoulder roll

Here, Glutmech is changing his shoulder roll (i.e. he is rotating them about the Z axis). DARwIn can do this with her right and left shoulder, hip, and ankle. On DARwIn, shoulder roll is confusing, because that servo is mounted on top of the shoulder pitch servo, like so:
shoulder servos
So, as the pitch servo rotates, so does the axis about which the roll servo rotates. This means that the roll servo is oriented about the roll axis only if the shoulder pitch servo is at 0 or 180 degrees (straight down or up). Nonetheless, that servo is always accessed by the request shoulder roll.


In this animation, Glutmech (and the background) is rotating about the yaw (i.e. Y) axis. DARwIn can do this with her head and right and left hip.

Table Of Contents

How Do I Use The Servos?

VERY CAREFULLY! It is physically possible to move the servos into positions that will break the robot. For instance, rolling the hips far outwards and then trying to adjust their pitch will cause the plastic part of the leg to jam into the metal servo housing. Don't do this. Zero Degrees Christo Redentor

The robot has 20 servos. You can get, set or increment the angle or speed of any servo in radians or degrees (which are understood to mean radians/second or degrees/second for speed requests). Servos can be accessed by referring to the body part, side of body if applicable, and component, if applicable, like head yaw, right knee, or left shoulder roll.

When the servos are all set to 0 degrees, the robot is in a Christ-The-Redeemer position (except that Darwin's palms face down), as in the image to the right. The head points forward, arms point outwards, elbows are straight, legs are straight and parallel and feet are flat on the ground.

The angle ranges are different for each servo, thus:

Servo Angle Limits Imposed by Software
Servo Min Max Positive Direction
left same as right) (degrees) (degrees) (from the "0 degree" stance)
shoulder pitch -180 180 Palm Rotates Forward
shoulder roll -120 84 Arm Moves Up
elbow -4 156 Less Extended
hip yaw -30 50 Toes Point Out
hip pitch -29 96 Leg Moves Forward
hip roll -5 57 Legs Move Apart
knee -132 0 More Extended
ankle pitch -51 79 Toe Moves Up
ankle roll -57 37 Outside Of Foot Moves Up
head tilt -25 40 Looks Up
head pan -120 120 Looks To His Right

The servos have a speed range of 1 to 326 degrees/second. By default, they are all set to the maximum speed.

You can also disable any servo so it goes limp, the way it is when you first power the robot on. The request

set right elbow enable 0

will make that servo go limp. You can still read the position of the servo while it is limp, which is useful for manually finding servo positions for complicated poses. You can re-enable the servo either with

set right elbow enable 1

or by just setting its position to some value. Enabling it also checks for and clears servo errors. incrementing the enable property toggle it.

Table Of Contents

How Do I Access All Servos In One Request?

The body body part allows all servos to be accessed in one request. get requests will return a list of numbers, one number corresponding to each servo. The numbers in the list occur in the following order:

right shoulder pitch
left shoulder pitch
right shoulder roll
left shoulder roll
right elbow
left elbow
right hip yaw
left hip yaw
right hip roll
left hip roll
right hip pitch
left hip pitch
right knee
left knee
right ankle pitch
left ankle pitch
right ankle roll
left ankle roll
head pan
head tilt

If your robot has more servos (i.e. gripper arms, etc...), extra values will be appended to the end of this list in the order of the servo IDs, given that the IDs are sequential with no gaps. For example, the request:

get body position degrees

returns a list containing the current position of each servo. This also works with the speed and enable properties.

For set and increment requests, if one value is received with the request, all servos are set to or incremented by that value. For example, the request:

increment body speed -50 degrees

slows each servo down by 50 degrees per second. If a list of at least 20 numbers is sent with the request, then the numbers are distributed amongst the servos in the same order as they are returned for set requests. For instance, the request:

set body position degrees -48.35 -41.31 -62.87 -62.58 119.3 119.59 0. -0. 0.29 0.29 34 34 -52.45 -52.45 31.35 31.35 -0.59 -0.59 -0. 39.85

puts the robot in the 'walk-ready' pose. If there are more numbers than servos, the extra values are ignored. If there are more than 20 servos and fewer numbers than servos, then as many servos as there are numbers are accessed and the remaining servos are unaffected. This should provide cross-compatibility between robots with and without custom appendages. Requests containing more than 1 and fewer than 20 numbers are ignored as mistakes.

It is often useful to initialize all servos at the beginning of a program. This can be done in Max/MSP like so:

set body position 0 degrees, speed 326, enable 1

which puts all servos in the 0 degree position, sets them to the maximum speed, and ensures that they are enabled.

Table Of Contents

How Do I Handle Servo Errors?

Occasionally, the red LED on a servo will light up, which indicates a 'warning' if it is blinking and an 'error' if it is steady. In the case of an error, the servo will also become unresponsive and present little resistance against being moved manually. The servo's firmware does this to prevent damage to the motor. TellDarwin checks for these conditions whenever a servo's enable property is set to 1. If such a condition is detected, TellDarwin will clear it, turn off the LED, and print a message about what caused the warning / error to its stdout. These messages should be heeded. For instance, if overheating caused the servo to shut down, you should wait for the servo to cool before proceeding. To demonstrate: If the LED on the right shoulder is blinking, the request

set right elbow enable 1

will clear it. Additionally, the request

set body enable 1

checks and clears all servos. New servos are factory programmed with an active 'overheating error' and 'voltage input error'. These messages will appear the first time a servo is enabled with TellDarwin, although these conditions do not actually exist unless they reassert themselves.

Table Of Contents

Can I Use My Custom Gripper Arms?

Yes, but the author's robot does not have them, so everything related to their use is untested. For other servos, TellDarwin imposes angle limits that restrict the range of motion to prevent damage to the robot. Safe ranges for the additional servos on gripper arms have not yet been ascertained, and their use is therefore currently unrestricted. This may change in the future. In the meantime, it is recommended that users determine safe values empirically, and set the limits within the servos' firmware, using the dxl_monitor program provided by ROBOTIS. Using TellDarwin to attempt to exceed these limits will result in a servo error. Furthermore, the Zero-Degree position is unknown and currently undefined by TellDarwin. This also may change in the future.

The additional servos must be assigned a unique IDs prior to their use with TellDarwin. TellDarwin always expects the right and left elbow to have IDs of 5 and 6, respectively, regardless of the arm. For the sake of backwards compatibility, these servos can be accessed with the request elbow or arm pitch. right elbow, for instance, always accesses servo ID 5, regardless of the component specified. arm only accesses servo ID 5 if the yaw component is not specified. get requests for these servos always come with labels containing "ELBOW", regardless of the wording of the request. TellDarwin expects the hand on gripper models to have IDs of 21 for the right and 22 for the left. These can be accessed with right hand and left hand, respectively. On the yaw-appended models, TellDarwin expects the additional servos to have IDs of 23 (right) and 24 (left). They can be accessed with the requests right arm yaw and left arm yaw, respectively. This is summarized in the images below.

Standard Arm
Gripper Arm
Yaw Appended Gripper Arm

The additional servos can also be used in body requests, by including values for the additional servos at the end of the list. The ID of each servo indicates it ordinal position in the list. TellDarwin ignores the extra values if those servos are not present, so your code will be cross-compatible with robots that do not have them.

Robots that do not have the extra servos ignore set and increment requests, and return 0 for get requests.

Table Of Contents

How Can I Change The Color Of The Robot's Eyes/Forehead?

LED maxpatch

You can get, set, and increment the red, green and blue components of the robot's eyes and forehead. The left eye can NOT be controlled separately from the right one, because they are hard-wired together. The color-components may be accessed individually, or if no component is specified, the interpreter access all three at once. So the requests:

get eye red
get eye green
get eye blue

return the specified component, whereas

get eye

returns all three components in the order: red, green, blue. Likewise the requests,

set eye red 0.5
set eye red

access only the red component. In this case, quod erat demonstrandum, the number may be sent with the words or after, as a separate request: If the number is sent with the words, the component is set immediately. In both cases, subsequent numbers sent to the interpreter will also set the specified component. This, however, is not true if all three components are to be set at once. In that case, the numbers must accompany the words, in the order: red, green, blue. Exempli gratia:

set forehead 0.5 0 1

Subsequent numbers sent to the interpreter have no effect.

Values for each component are in 0 to 1 arbitrary units. The resolution is 5 bits per component, which is about 0.032 arbitrary units. Above is a simple Max/MSP patch to manipulate the LEDs.

Table Of Contents

How Do I Read The Accelerometer?


The request

get accelerometer

returns all three components of the accelerometer, in the order: x, y, z. Components may be retrieved individually thus:

get accelerometer x
get accelerometer y
get accelerometer z

Units are g (9.80 m/s^2), so when the robot is standing still, y should be 1.0, and the others 0. For the x axis, positive values mean that the robot is laying on her right side, and negative is left. For the y axis, positive means she is standing on her feet, and negative is her head. For the z axis, Positive values indicate that she is lying on her stomach, and negative her back. The hardware clips its output at around 4g.

Accelerometers are, in general, very noisy. It is therefore generally recommended to sample the accelerometer several times in rapid succession and use the average. The interpreter will do this for you if, in the request, you specify how many samples to average. For instance, the request

get accelerometer 3

will read each axis 3 times and return the average for each axis. Valid values are between 1 and 20. 3-5 is usually plenty.

It should also be pointed out that a modern physics depends heavily on the postulate (proposed by Einstein in 1909) that it is impossible to determine the difference between gravity and acceleration. This means that if the y axis reads a positive value, it could mean that gravity is pulling her in the direction of her feet, or that she is accelerating in the direction of her head or worse: some unknowable combination of both (if she is oriented at an odd angle, hurtling through space wearing a rocket pack, for instance).

More info is in the "How Do I Communicate With The Robot Using Max/MSP?" section.

Table Of Contents

How Do I Read The Gyroscope?


Electronic gyroscopes measure angular velocity (the rate at which the gyroscope is spinning about a particular axis). The request

get gyroscope

returns all three components of the gyroscope, in the order: pitch, yaw, roll (x, y, z). Components may be retrieved individually thus:

get gyroscope pitch
get gyroscope roll
get gyroscope yaw

Units are either degrees or radians per second. For the pitch axis, positive values mean that the robot is doing a somersault, and negative is a backflip. For the yaw axis, positive means she is performing a pirouette clockwise as viewed from above, and negative is counter-clockwise. For the roll axis, positive values mean that she is doing a cartwheel to her right, and negative is to her left. The hardware clips at about 1600 degrees per second.

Gyro Head Max-patch

Gyroscopes are, in general, very noisy. It is therefore generally recommended to sample the gyroscope several times in rapid succession and use the average. The interpreter will do this for you if, in the request, you specify how many samples to average. For instance, the request

get gyroscope 3

will read each axis 3 times and return the average for each axis. Valid values are between 1 and 20. 3-5 is usually plenty.

In most cases, you will not care how fast the robot is turning. You will want to know how far it has turned since some initial position (this is what mechanical gyroscopes measure). In order to figure this out, you will need to poll the gyroscope at regular intervals. If the polling interval is short enough (say under 100 or so milliseconds), then the number of degrees that the robot has turned between polls is theoretically

NumDegrees=PollingInterval * (PreviousGyroValue + CurrentGyroValue) / 2.0

given that the polling interval is specified in seconds and the gyroscope read in degrees per second. In practice, however, this will have probably have to be adjusted by some mathematical constant to accommodate a number of complicated factors. To the right is a demonstration Max patch that shows how to implement this. It keeps the head looking in a fixed direction, even if the body rotates underneath it: If the body moves 10 degrees to the right, the head will move 10 degrees to the left to compensate.

More info is in the "How Do I Communicate With The Robot Using Max/MSP?" section.

Table Of Contents

How Do I Use The Robot's Ears?

Mic Schematic

DARwIn has a tiny "microphone" embedded in each ear. Because of restrictions in the hardware, these "microphones" are not capable of gathering an actual audio stream (Use the actual built-in microphone or a USB microphone for that). They are basically a sound-pressure sensors that can be used to detect loud sounds and (at least theoretically) determine on what side of the robot the sound originated. Each ear can be accessed separately with the requests

diaphragm animation get right ear
get left ear

and if no side is specified, as in:

get ears

then both values are returned in the order: left, right. (NB: ear is a synonym for ears.) The returned values are in -1 to 1 arbitrary units, which represent the net displacement of the microphone's diaphragm from rest. Zero theoretically indicates that the diaphragm is at rest. 1 means that it is maximally displaced towards one side, and -1 is maximally displaced towards the other side. Sound waves will cause the diaphragm to move from the positive side to 0 to the negative side and back several hundred times per second. So, to figure out the relative amplitude of sound entering an ear, you will have to take the square root of the mean of the square of many rapidly-acquired samples. The ears of the robot that I have been working with actually read about -0.3 in silence (should be 0), which is most likely due to imprecise biasing of the ADC to which they are attached. Whistling loudly next to either side of the head causes them both to oscillate between -0.2 and -0.4.

Table Of Contents

How Do I Read The Foot Pressure Sensors?

The author's robot does not have the optional foot pressure sensors, so their use is untested. TellDarwin expects the FSR units to respond to the device ID's defined in ROBOTIS' FSR.h, which are currently defined as 111 for the right foot and 112 for the left. Judging by online forums, it appears as though the consumer is responsible for assigning the IDs upon purchase. This must be done before TellDarwin will recognize them. Each foot has four sensors, one at each corner of the foot. The request:

get right foot pressure

will return a list containing the value of each sensor in the right foot. Values for either foot are returned in the order: front medial, front lateral, rear lateral, rear medial, as is illustrated in the image below. The unit of the returned value is a Newton (an apple weighs one Newton), and the sensors have a range of 0.493 to 65.535 Newtons. Sensors tend to be noisy, so it is sometimes useful to rapidly acquire several samples and average them. The interpreter will do this for you if you include a number in the request that specifies how many samples to average. The request FSR

get right foot pressure 3

will read each sensor 3 times and return the average of each. The maximum number of samples the interpreter will average is 20, although about 3 is usually plenty.

Each sensor also keeps track of the center of force on each foot. The bottom surface of each foot may be regarded as a 2-dimensional cartesian plane, in which the positive z axis points towards the front of the robot (here is a discussion of axis conventions in TellDarwin) and the positive x axis points towards the lateral side of each foot. You can get the center of force on either axis by including a component in the request, like:

get right foot pressure x

get right foot pressure z

Returned values are in the range of -1 to 1 arbitrary units. 0 represents the center of the foot for either axis. For the x axis, 1 is the lateral edge of the foot, and -1 the medial. For the z axis, 1 is the front edge, and -1 the rear. If the foot is not bearing any force at the time of sampling, the value -10 will be returned for either axis. The interpreter will average several rapidly acquired samples if a number indicating how many samples to average is included in the request, e.g.:

get left foot pressure z 2

averages 2 samples. If the foot is bearing force during some of the rapidly acquired samples but not others, the non-force bearing samples are ignored and only the other samples are averaged.

Table Of Contents

How Do I Use the Robot's Camera?

the request

start camera

causes the robot to attempt to establish a TCP connection as a client with the computer that sent the request (or to the specified IP in stdio mode) on port 7474. For it to succeed, the computer that sent the request must be actively listening on that port. The port number can be changed by sending a number in the request, as in: Camera Patch

start camera 1234

The stream is terminated by the request

stop camera

Once it is connected, the video is sent as a stream of two-dimensional, 320x240, 4-plane, 8-bit signed integer per plane, alpha-first Jitter matrices. The frame rate is very roughly 20 fps, but it constantly varies depending on the position of the moon and planets, what the robot had for dinner and so-forth. It can be received in Max/MSP with a object and viewed with a jit.pwindow object. A simple patch for viewing the video stream looks like this:

Furthermore, you can get, set or increment the brightness, contrast, saturation, gain and exposure of the camera. All values are specified as 0 to 1 arbitrary units.

Table Of Contents

How Do I Use the Robot's Microphone?

the request

start microphone

causes the robot to attempt to establish a TCP connection as a client with the computer that sent the request (or to the specified IP in stdio mode) on port 8080. For it to succeed, the computer that sent the request must be actively listening on that port. The port number can be changed by sending a number in the request, as in: Microphone Patch

start microphone 1234

The stream is terminated by the request

stop microphone

Once it is connected, the audio is sent as a stream of one-dimensional Jitter matrices. It can be received in Max/MSP with a object and converted back to an MSP audio-stream with a jit.release~ object. Note that in Max/MSP, no audio will be processed at all unless there is a dac~ or ezdac~ object running, even if you are not trying to convert the digital stream to analog, and even if the object is not connected to anything. A simple patch to view the robot's microphone's waveform is to the right.

Table Of Contents

How Can I Play Sound Out Of The Robot's Speaker?


the request

start speaker

causes the robot to listen, as a host, for a TCP connection on port 8081 (stdio mode will prompt for an IP, which will then be ignored). The port number can be changed by sending a number in the request, as in: Speaker Patch

start speaker 1234

The stream is terminated by the request

stop speaker

The robot expects to receive the audio as a stream of one-dimensional Jitter matrices. The stream should be 1 channel (there is only 1 speaker), 32-bit big-endian IEEE 754 floats, sent at 44100 Hz. In Max/MSP, an MSP audio stream can be converted into this format using a jit.catch~ object, and sent to the robot using Note that in Max/MSP, no MSP audio signal will be created at all unless there is a dac~ or ezdac~ object running, even though, in this case, you are not trying to convert the digital audio-stream to analog. The dac~ does not need to be connected to anything, it just needs to be on. A simple patch to send a sinusoidal waveform to the robot's speaker is given above.

Table Of Contents

How Can I Get Stereo Audio From A USB Microphone / Audio Device?

The requests

start usbmic
stop usbmic

should do it. This functionality of this request is identical to microphone, except that here the default port is 8082 and the audio stream is stereo. There is, however, one caveat regarding this request. The USB audio device must be plugged in after the robot has been turned on and the operating system has booted. This is because TellDarwin expects the codec on the motherboard to be 'card 0', the mic on the built-in camera to be 'card 1', and an additional device to be 'card 2'. The presence of an additional device at boot will botch the order of enumeration. Any USB compliant, stereo audio capture device supporting 16-bit integers should work. This has been tested with a Samsung H4N Zoom and a Playstation Eye Camera (using only 2 of the 4 built-in mics), but has not been tested on a smaller device that would be more suitable for actual use on the robot.

Table Of Contents

How Can I Make The Robot Walk?

The requests

start walking
stop walking

will do the job. You can also get, set, and increment the walking angle in degrees or radians per step. This is how you steer the robot. The software imposes a limit of 45 to -45 degrees/step to attempt to prevent the robot from falling over. Positive values cause the robot to walk along a path that curves to the right.

It is also possible to get, set, or increment the walking velocity along the x, y and z axes. The z axis corresponds to her forward velocity, negative values cause her to walk backwards. The x axis corresponds to her sideways velocity, positive values cause her to side-step to the right. The y axis corresponds to the step-height. If no axis is specified, the interpreter assumes the z axis. The x and z velocities range from -23 to 23 cm/sec. The y velocity (step height) ranges from 4 - 40 arbitrary units.

Normally, all of the robot's servos are implicated in walking, so TellDarwin ignores requests to set or increment any property of any of the 20 servos (extra servos are not restricted during walking), which would interfere. However the function of the head and arms is not crucial to the walking algorithm. It is therefore possible to revoke their control from the walking algorithm and return it to TellDarwin, while the legs continue to writhe as prescribed. This is done by accessing the enable property of the walking body part. The request expects a list of up to 3 numbers, indicating whether the walking algorithm has control of the head, right arm, and left arm, in that order. the value 0 indicates that the walking algorithm should not have control of those servos (i.e. TellDarwin has control), and all other values indicate that it should. If less than 3 values are specified, 1 is assumed for the missing values. For Instance, the request

set walking enable 0

gives control of the head to TellDarwin, and the arms to the walking algorithm. This is identical to

set walking enable 0 1 1

and the opposite of

set walking enable 1 0 0

Furthermore, the walking algorithm normally attempts to balance the robot by using data from the gyroscope to adjust the gait. In certain situations, this can actually lead to a less stable gait, in which the robot rocks side to side in a volatile fashion. This balancing feature can thus be turned on and off at liberty using the balance property. For example:

set walking balance 0

turns the auto-balance feature off. 1 would turn it on. You may also get and increment this value.

Table Of Contents

Can I Use Robotis' Action Scripts With TellDarwin?

Not as such, but the functionality provided by the Action scripts and Motion Files is a trivial subset of the functionality provided by TellDarwin and Max/MSP. There is a Max patch called "Action.maxpat" included in the examples that re-implements the 'Action' module using the Max language. This allows you to make you to make use of the default motions provided by ROBOTIS, like standing from prone or prostrate, kicking or passing a soccer ball, etc... Normally the sequences of poses ('steps') that comprise these motions ('pages') are hidden in a binary-encoded 'motion file'. However, the following link contains ROBOTIS' default motion file (motion_1024.bin) in human-readable format, with angles converted to values (in degrees) usable by TellDarwin:


The sections labeled "for Max/MSP coll object" are formatted specifically for use with the coll object in the aforementioned Max/MSP example, and may be copied and pasted there at liberty.

If you want to view the contents of other binary 'motion files', you can use the following program to convert them to human-readable HTML:


Table Of Contents

How Can I Make The Robot Talk?

If the command-line utility espeak is installed on the robot, the interpreter can interface with it to cause her to speak. Any words in any request that come after the word


will be sent to the espeak program. Alteration of the espeak invocation options (i.e. different voices, speaking speeds, etc) may be done with the system request instead of speak. The espeak program is very buggy, always prints error messages that cannot be suppressed, and often stops speaking before it has finished. In the author's opinion, it is not suitable for mission-critical applications like live demonstrations. In such cases it is better to save pre-recorded speech as audio files to the robot's hard disk and play them with aplay or mpg321 using, again system. speak is therefore provided as a quick-and-dirty convenience only. It should furthermore be noted that a clever person could use speak to hack the robot's operating system.

Table Of Contents

Can I Pass A Command Directly To The OS?

Of course you can. That is what the system request is for. This will allow you to access a number of command-line programs that may be useful, such as aplay or mpg321 (to play an audio file stored on the robot's hard drive), or espeak (if the speak request doesn't do what you want). Anything following system will be sent directly to the OS, and the case will be preserved. Just remember that Max/MSP will get rid of certain characters like quotes, commas, and semicolons unless you escape them (i.e. precede them with a backslash). Here are some examples of shell commands and their corresponding Max message:

espeak "hello world" &system espeak

mpg321 ~Desktop/Filename.mp3 &system mpg321

Notice that these commands both end with "&". On most Unix/Linux shells, this will cause the command to be executed in the background. Without the "&", TellDarwin will wait for the command to finish (the robot to finish speaking or the audio file to finish playing) before doing anything else. With the "&" TellDarwin will continue interpreting requests while the command happens in the 'background'. Just don't do this (or anything else that you don't know what it is):
Fork Bomb
because it will cause UNIX/Linux to crash in the most spectacular fashion (it is known as the UNIX "fork bomb")!

Note, however, that anyone on your network could send this message (or other even more harmful ones) to TellDarwin over UDP, particularly if you are using the -n option. So if you store credit-card information on the robot, or are paranoid about your bot joining the botnet, or whatever, secure your network (i.e. don't put it on a huge university network), use an ethernet cable or, better yet, don't use TellDarwin.

Table Of Contents

Are There Any Known Bugs?

  1. Closing TCP hangs on TIME_WAIT, which can cause annoying behaviour when restarting the speaker, and potentially when repeatedly piping messages into netcat. Workaround: try another port
  2. The context-sensitive nature of the interpreter sometimes causes it to produce unexpected results when it receives malformed requests. Workaround: use well-formed requests
  3. camera exposure not working. Reason unknown. Workaround: Use Jitter.

Table Of Contents

How Can I Report A Problem / Contact The Author?

Table Of Contents
You can get datasheets, C++ source-code provided by the manufacturers, and a variety of other data on these sites:

Table Of Contents