Programming Interface (old version 2)

This page describes the programming capabilities of Thymio. It lists the different variables and functions, and indicates to which elements of the robot they refer.

Buttons

Thymio holds 5 capacitive buttons corresponding to the arrows and to the central button. An array of 5 variables, buttons.binary, holds the state of these buttons (1 = pressed, 0 = released) :

  • buttons.binary[0] : back arrow
  • buttons.binary[1] : left arrow
  • buttons.binary[2] : central button
  • buttons.binary[3] : front arrow
  • buttons.binary[4] : right arrow

Thymio updates this array at a frequency of 20 Hz, and generates the button event after every update.

Distance sensors

Horizontal

Thymio has 7 distance sensors around its periphery. An array of 7 variables, prox.horizontal, holds the values of these sensors:

  • prox.horizontal[0] : front left
  • prox.horizontal[1] : front middle-left
  • prox.horizontal[2] : front middle
  • prox.horizontal[3] : front middle-right
  • prox.horizontal[4] : front right
  • prox.horizontal[5] : back left
  • prox.horizontal[6] : back right

The values in this array vary from 0 (the robot does not see anything) to several thousands (the robot is very close to an obstacle). Thymio updates this array at a frequency of 10 Hz, and generates the prox event after every update.

Ground

Thymio holds 2 ground distance sensors. These sensors are located at the front of the robot and can follow a line on the ground. Three arrays allow to read the values of these sensors:

  • prox.ground.ambiant : ambient light intensity at the ground, vary between 0 (no light) and 1023 (maximum light)
  • prox.ground.reflected : amount of received light while the sensor emits infrared, vary between 0 (no reflected light) and 1023 (maximum reflected light)
  • prox.ground.delta : difference between reflected light and ambient light, linked to the distance and to the ground colour.

For each array, the index 0 corresponds to the left sensor and the index 1 to the right sensor. As with the distance sensors, Thymio updates this array at a frequency of 10 Hz.

Accelerometer

Thymio contains a 3-axes accelerometer. An array of 3 variables, acc, holds the values of the acceleration along these 3 axes:

  • acc[0] : x-axis (from right to left, positive towards left)
  • acc[1] : y-axis (from front to back, positive towards back)
  • acc[2] : z-axis (from top to bottom, positive towards ground)

The values in this array vary from -32 to 32, 1 g corresponding to 23, and therefore a unit corresponds to 0.45 N. Thymio updates this array at a frequency of 15 Hz, and generates the acc event after every update.

Temperature sensor

The temperature variable holds the current temperature in tenths of a degree Celsius. Thymio updates this value at 1 Hz, and generates the temperature event after every update.

LEDs

Thymio holds many LEDs spread around its body. Most of them are associated with sensors and can highlight their activations: by default, the intensity of the LED is linked to the sensor value. However, once LEDs are used in the code, the programmer takes over control and they no longer reflect the sensor values.

Native functions allow the various LEDs to be controlled. For all LEDs, their intensity values range from 0 (off) to 32 (fully lit).

The LED circle on top of the robot

8 yellow LEDs make up a circle on top of the robot, around the buttons.

Default activation: reflects the values of the accelerometer. All LEDs are off when the robot is horizontal. When the robot tilts, a single LED shows the lowest point, with an intensity proportional to the tilt angle.

  • leds.circle(led 1, led 2, led 3, led 4, led 5, led 6, led 7, led 8) where led 1 sets the intensity of the LED at the front of the robot, the others are numbered clockwise.

The RGB LEDs

There are two RGB LEDs on the top of robot, driven together. These are the LEDs that show the behaviour of the robot. There are two other RGB LEDs on the bottom of the robot, which can be driven separately.

Default activation: off when in Aseba mode.

  • leds.top(red, green, blue) sets the intensities of the top LEDs.
  • leds.bottom.left(red, green, blue) sets the intensities of the bottom-left LED.
  • leds.bottom.right(red, green, blue) sets the intensities of the bottom-right LED.

The LEDs of proximity sensors.

Every proximity sensor has a companion red LED on its side (the front sensor has two LEDs, one on each side).

Default activation: on when an object is close to the associated sensor, with an intensity inversely proportional to the distance.

  • leds.prox.h(led 1, led 2, led 3, led 4, led 5, led 6, led 7, led 8) sets the LEDs of the front and back horizontal sensors. led 1 to led 6 correspond to the front LEDs, from left to right, while led 7 and led 8 correspond to the left and right back LEDs.
  • leds.prox.v(led 1, led 2) sets the LEDs associated with the bottom sensors, left and right.

The Button LEDs

Four red LEDs are placed between the buttons.

Default activation: For each arrow button, one LED lights up when it is pressed. When the centre button is pressed, all four LEDs light up.

  • leds.buttons(led 1, led 2, led 3, led 4) control these LEDs, with led 1 corresponding to the front LED, then clockwise numbering.

The LED of the RC receiver

This red LED is located close to the remote-control receiver.

Default activation: blinks when the robot receives an RC5 code.

  • leds.rc(led) controls this LED.

The LEDs of the temperature sensor

These two LEDs (one red and one blue) are located close to the temperature sensor (NTC resistor).

Default activation: red if the temperature is over 28°C, red and blue between 28° and 15°, blue if the temperature is below 15°.

  • leds.ntc(red, blue) controls this LED.

The microphone LED

This blue LED is located close to the microphone.

Default activation: off.

  • leds.sound(led) controls this LED.

There are also other LEDs that the user cannot control:

  • 3 green LEDs on the top of the robot show the battery voltage
  • a blue and a red LED on the back of the robot show the charge status
  • a red LED on the back of the robot shows the SD-card status

Motors

You can change the wheel speeds by writing in the array motor.target :

  • motor.target[0]: requested speed for left wheel
  • motor.target[1]: requested speed for right wheel

You can read the real wheel speeds from the array motor.speed:

  • motor.speed[0] : real speed of left wheel
  • motor.speed[1] : real speed of right wheel

The first value corresponds to the left wheel and the second to the right wheel. The values range from -500 to 500. A value of 500 approximately corresponds to a linear speed of 20 cm/s. You can read the value of the motor commands in the array motor.pwm.

Sound

If you have installed a micro-SD card formatted as FAT, you can record and play sounds. The files are stored in the micro-SD card, in raw format, 8-bit unsigned, 8 kHz.

Recording

You can record sounds using the sound.record native function. This function takes as parameter a record number from 0 to 9. Files are stored on the micro-SD card under the name RX.RAW where X is the parameter passed to the sound.record function. To stop a recording, call the sound.record function with the value of -1.

The replay of the sound is currently under development and will be available in a future firmware upgrade.

Creating sound from your computer

You can create sounds for Thymio II using your computer. The most efficient way to do so is to use the Audacity software, version 1.3, which exists for various operating systems. Here are the steps to create a sound compatible with the Thymio:

  • Once Audacity has started, change the project rate from 44100 Hz (default) to 8000 Hz. This setting is located at the bottom-left of Audacity's window.
  • Record your sound with the red record key in the top-left part of the window. You should see the cursor advancing and the wave changing. Stop with the stop button.
  • Go to the File menu under Export…
  • Give a file name, for instance p0.raw for the first file to play using the sound.play native function.
  • Choose other uncompressed files as format format.
  • Under options, choose a RAW (header-less) header and as Encoding, choose Unsigned 8 bit PCM.
  • Save or copy the file to the micro-SD card.

To do a quick test, you can save this file under the name poweron.raw. Thymio will play it when it starts.

Play

You can play sounds using the sound.play native function, which takes a record number from 0 to 9 as parameter. The file must be available on the micro-SD card under the name PX.RAW where X is the parameter passed to the sound.play function. To stop playing a sound, call the sound.play function with the value -1.

You can play system sounds by specifying a negative value to sound.play. The following sounds are available:

  • -1 : stop playing sound
  • -2 : startup sound
  • -3 : shutdown sound
  • -4 : arrow-button sound
  • -5 : free-fall sound
  • -6 : collision sound
  • -7 : central-button sound
  • -8 : wall-following sound
  • -9 : target-detection sound for following

Remote control

Thymio contains a receiver for infrared remote controls compatible with the RC5 protocol. When Thymio receives an RC5 code, it generates the rc5 event. In this case, the variables rc5.address and rc5.command are updated.

Table of local events

event description frequency (Hz) result
button button values have been probed 20 buttons.binary[0-4]
acc the accelerometer was read 15 acc[0-2]
prox proximity sensors were read 10 prox.horizontal[0-7], prox.ground.ambiant[0-1], prox.ground.reflected[0-1] and prox.ground.delta[0-1]
temperature temperature was read 1 temperature
rc5 the infrared remote-control receiver got a signal upon signal reception rc5.address and rc5.command
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License