Tux Droid Basics

Note: This is the print view with all the tutorial pages on one page. The paginated version is available here, if you prefer that. Understanding Tux Droid system organization Introduction View of Tux Droid software and hardware organization Overview Tux Droid is a desktop companion i.e. a funny kind of man-to-machine interface ... The design team has several ideas about what one can do with such a interface but the only thing we are sure about is that Tux Droid Builders (you!) can imagine and create much more. In order to understand "how it works", this section is sketching the internal structure of Tux Droid while providing links to go deeper into detail. Parts of the Tux Droid System Tux Droid system is a mix of hardware and software. The hardware side includes:

Tux Droid itself: the robot part of the system with actuators, sensors, audio in and audio out features. It includes a wireless link connecting it to Tux Dongle...

Tux Dongle : the small fish is an USB device linking the computer and Tux Droid . It is basically a bridge between the radio protocol and the USB protocol.

The software side of Tux has the following layers:

a hardware interface managing low level access to the Tux controls and audio streams a set of software services allowing high level communication with applications the applications software itself

The data exchange between the computer and Tux Droid is achieved through two links:

A wireless RF link allowing full duplex audio streaming and control data transfer between Tux Droid and the dongle A wired USB link allowing exchange between computer and the dongle. It supports 2 USB isochronous endpoints for bidirectional audio streaming and 2 USB interrupt endpoints for control data transfer

The diagram sketches exchanges between the computer and Tux Droid. Because of the different nature and processing requirements we make a clear cut between "audio streams" (wide lines) and "control data" (tiny lines) . Tux Droid interacting with the external environment Tux Droid interacts with the environment in various ways:

Its actuators broadcast information to the environment. They include mechanical movement (3 independent motors), lighting (2 independent blue LED's) and infrared emitting. Actuations are launched by commands received through the RF link. Tux Droid is also able to exhibit stand alone behavior. You can program or modify in every way you want.

The sensors receive information from the external environment. They include various switches (head and wings), a light sensor and infrared receiver. The status of these sensors are available inside Tux Droid. They are sent to computer through the RF link on a regular basis.

Tux Droid comes with an I2C bus. Here you can connect any kind of I2C sensor or actuator to Tux Droid. And all processors in Tux Droid can be reprogrammed through this bus.

Audio-Out: sounds can be generated by Tux Droid in various ways. Tux may simply play an audio stream coming from the computer or produce sounds that ari internally stored in the sound flash memory. Audio-In: Tux Droid is able to sample (8 KHz, 8 bits) sounds with its microphone and to stream those to the computer via the RF link.

Tux Droid Software Data ...

A typical application using Tux Droid has to work with audio streams data and control data. Plugging the Tux Dongle in the USB port opens two bidirectional channels: one for audio streams, the other one for sending command data and receiving status data. These channels are configured in such a way that

audio streams are available for applications through ALSA and the snd_usb_audio driver. Tux Droid appears as a sound card supporting ALSA or OSS. Practically speaking, any application using audio features will be able to use Tux Droid as an audio device and can play or record sounds.

control data can be sent or received directly with libusb (http://libusb.sourceforge.net/). As it is a bit tricky to use libusb for Tux Droid control, applications may access Tux Droid through a service called "Tux Droid Daemon". They simply use TCP/IP messages containing the controls. The daemon converts TCP/IP messages into libusb calls; it's in charge of guaranteeing timing requirements and providing polling features for transparent communication with Tux Droid.

Inside Tux Droid

Electronics architecture on the Tux Droid side Overview Inside Tux Droid you may find a mother board and a daughter board plugged on it as you could see in the photo.

The daughter board is the radio part of Tux linking it to the dongle. The mother board is in charge of audio functionalities, sensors and actuators control plus battery charging.

Modules of Tux Droid Hardware A module is a combination of one processor, firmware running on the processor and discrete hardware components.Tux Droid hardware is built around three modules

the Radio module (on the daughter board) the Audio module (on the mother board) the Core module (on the mother board)

These modules are chained thanks to two bidirectional buses: an SPI bus between the radio and audio modules; an I2C bus between the audio and the core modules.

The radio module includes an RF chip (ATR2406) and a processor (ATMEGA48). The RF chip is in charge of the physical layer. The radio processor manages the transport layer for streaming and control data. In order to provide full duplex audio with limited buffer sizes, the radio link is switching every 1 millisecond between emitting and

receiving. The processor is also in charge of encapsulating / extracting the audio stream and controlling data in / from the RF frames.

The audio module manages the sound aspects of Tux Droid.

o o o

in the downward way, it plays the audio stream coming from the RF module. in the upward way, the audio module samples audio and sends the stream to the RF module. it is also able to play sounds stored in the internal flash memory chip and manages the recording of new sounds in the flash memory.

The sound module also acts as a router forwarding back and forth control data through the I2C bus to the "behavior module"

The core module is in charge of firing actuation commands received on its I2C bus. It also collects sensors status and send them to the audio module for transmission. The core processor can be programmed through the I2C link to exhibit new stand alone behavior.

Tux Droid Mother Board The mother board is composed of the "core" and "audio" modules. The reader may identify the main components on the layout photo.

The link Mother Board Topology will provide you the detailed schematic of the main board.

Developing Firmware for Tux Droid Tux Droid firmware (the software of Tux Droid internal processors) is dedicated to be upgraded. Tux Droid is powered by ATMEGA88 microprocessors, belonging to a widespread class of RISC architecture from Atmel called AVR. Each of them contains a small bootloader program allowing to download new firmware through the I2C hardware port (see manual for locating it on Tux Droid). With a limited knowledge one may develop your own C programs ("firmware") for them and load the HEX file in the processors through an "updater" program. Useful information for firmware developers:

General information about AVR

o

datasheets and application notes can be found at http://www.atmel.com/products/AVR/ Setup the AVR tool chain and compile the firmware will provide you a step by step approach An excellent (GNU) C compiler for AVR processor is available there http://www.avrfreaks.net/AVRGCC http://www.tuxisalive.com/developer-corner/software/by-category/firmware in the "code repository" reference are the current source codes of the processors You will get a lot of practical information from the AVR freaks site : http://www.avrfreaks.net/ Detailed explanations can be found at Updating the firmware

Setting up the AVR development chain

o o

Code examples and comments

o

Upgrading firmware with the "tuxup" utility provided with the tuxsetup package.
o

Understanding I/O pins of the processors and connections with the module. This can be found in the following schematics
o o

Mother Board Topology for the main board A282 radio board schematic for the radio baby board

Tux Dongle Electronics

A description of the electronics inside Tux Dongle The Tux Dongle is a simple protocol bridge between Tux Droid and the computer. The dongle includes a USB chip (AT89C5131) and a RF module very similar to the one between an RF chip and a processor. The USB chip takes care of:

forwarding the audio streams to/from the 2 isochronous USB endpoints from/to the RF module through the internal SPI bus. forwarding the control data to/from the 2 interrupt endpoints from/to the SPI bus. extracting programming data from the downward interrupt endpoint and sending it to I2C for bootloading into the processors..

From the computer side, Tux Dongle is responsible:

making Tux Droid visible to the OS through USB: this step is called "enumeration" in USB vocabulary sending/receiving audio streams and control data in frames programming all Tux Droid and Tux Dongle processors The schematics of the Tux dongle is available at Radio Board Schematic A282 (pdf) and Dongle Schematic (pdf)

Tux Droid Software Architecture

Interfacing Tux Droid with applications Overview Tux Droid services are in background running processes interfacing applications and the Tux Droid system through TCP/IP connections. The Tux Droid Daemon is the core of these services. It enables applications sending and receiving Tux control data trough TCP/IP messaging. Services also provide the applications with Tux Droid software resources such as Text-To-Speech or Speech Recognition: these resources are viewed as extra features by applications. Tux Droid Daemon Service The Tux Droid Daemon provides a high level access to Tux Droid control data:

It splits high level commands into low level "raw" commands send by libusb calls on the USB link It merges "raw status" coming from Tux Droid into a full Tux status

The daemon guarantees appropriate timing required by the Tux Droid hardware and makes polling functions transparent for the application.

Applications communicate with the daemon through a TCP/IP client-server protocol. They connect to the daemon as clients. On the daemon side, the server is listening for connections on a common port. By extension we use the term "applications channel" to refer to these data exchanges. TCP/IP eases management of the following tasks by the daemon:

managing multiple clients requests routing answers to a client ensuring that a client request is always finished

Using TCP/IP for Tux Droid daemon communication provides an easy access to Tux through the network. If authorized, a remote application is able to control a remote Droid through its local daemon. To emphasize on this network connectivity, a TCP/IP client has been added as a mirror of data transfer through libusb in such a way that the Tux Droid daemon is able to drive a "Virtual Tux Droid" running a TCP/IP server: you may imagine to create a 3D Virtual Tux controlled by the daemon. We use the term "Tux Channel" to refer to these data exchanges.

Tux Droid Resource Daemons Applications may also access service resources by sending requests to the Tux Droid Daemon. Resources provide applications with extra Tux Droid features. For example, the tuxsetup includes the BabTTS resource daemon. This one enables the use of high end Text-To-Speech (TTS) functions by sending TCP/IP requests to the resource daemon.

The first goal of the TTS resource service was to feature Tux Droid with voice alerts about your favorite E-bay bids or new incoming messages. Use of TTS has been extended to mail reading. Currently you can build powerful audio based manmachine interfaces thanks to this resource. By extension data exchanges with the TCP/IP resource servers are referred to as "resource channel". Various kinds of resources can be created as simple as noise level detection or as complex as Speech Recognition. Developers have access to the Tux Droid Daemon source code to create their own resource service.

Tux Droid Interface as Man to Machine Interface

One may forecast that the use of Tux Droid will range from just funny up to very useful Man to Machine Interfaces (MMI). This is the reason why the Tux Droid Daemon is designed to interact with software resources such as Text to Speech or Speech Recognition. These resources are available as "resources daemons" and are connected to Tux Droid through TCP/IP sockets ("Resources Socket"). When an application needs to ask a question through Tux Droid, it sends to the Tux Droid Daemon a speech synthesis request and a string. The daemon translates the request to the "TTS resource daemon" which outputs the synthesized audio to Tux Droid.

Tux Droid is currently featured with a license for ACAPELA TTS, one of the best available TTS there is. The software and language is made available in the download section.

Tux Droid Daemon

Details of the Tux Droid Architecture and how to interface it Overview In the "Tux Services" section, the description of the Tux Daemon shows a global view of the Tux Droid software and emphasizes on the links of Tux Daemon with others services and with applications. The purpose of this section is to provide a detailed architecture of the Tux Daemon and to explain the reasons of our choices. Tux Droid Daemon Architecture As described in "Tux Droid Services", Tux Daemon suffers from major limitations.

An application must manage multiples TCP/IP connections to control the Tux Droid system: one for driving the Tux hardware; one per software resource used by application. Interfacing Tux Droid would be easier if the application controls the full set of hardware and software resources through a single TCP/IP client connected to Tux Droid Daemon.

There is no intelligent policy to allocate Tux Droid for applications requests: the daemon TCP/IP facility serves requests in their arrival order (FIFO). It would be useful to configure applications priorities according to user preferences: for example, if you are listening to an internet radio, you would like Tux Droid to let you know when someone is calling you with Ekiga or when you receive an e-mail ...

Communicating with people through Tux Droid will imply to drive more than one Tux Droid simultaneously: it could be one local and many remote Tux Droids or simply many local Tux Droids. Anyway, the final Tux Daemon architecture must support this feature to pretend to be convenient.

To circumvent these limitations we isolate the following rules of thumbs that guide architecture choices of Tux Daemon: 1. Extensibility: Tux Daemon would be able to manage any number of Tux Droids 2. Configuration: global configuration of application priorities for Tux Droids control is required 3. Unity of connection: an application must control Tux's hard and soft resources through a single connection 4. Transparency : driving a local or a remote Tux Droid must be transparent for an application

Extensibility and Configuration To ensure the "configuration" and the "extensibility" properties, the Tux Droid Daemon is built around a unique "master daemon" and multiple instantiations of one "subdaemon" module.

The "master daemon" is in charge of the configuration. It controls data routing of the links between applications and Tux Droid. It provides information about the Tux Daemon configuration: an application can receive the port address to connect a Tux Droid. It instantiates a new subdaemon when requested by an application or when a Tux is plugged into the USB. The configuration of the Tux Droid Daemon would be defined by a specific user-friendly configuration application.

a "subdaemon" manages one connection to Tux Droid. Subdaemons are dynamically created (instantiated) for each Tux Droid controlled by the computer.

The Master Daemon instantiates a new subdaemon dedicated to this Tux when a new Tux is plugged in the USB port, or when an application requests it. To setup a connection with a new subdaemon, an application will first communicate directly with the master daemon which provides all necessary information for the subdaemon connection.

Unity of Connection An application would be able:

to control one Tux Droid to control resources services to get information about the configuration

through a single channel. Data will be routed by the subdaemon to their destination. References of the channel (port number, ...) will be forwarded by the master daemon when setting up the subdaemon.

Communication with the subdaemon takes place through four channels:

the Applications Channel supporting data exchange with applications; the subdaemon is in charge of routing data to the right destination.

the Resources Channel supporting connections between resources and the subdaemon the Tux Channel supporting data exchange with a local or remote Tux Droid the Master Channel supporting configuration data exchange with the Master daemon.The Master Daemon configures the routing features of the subdaemon through this channel.

This property of the Tux Daemon will simplify connection management in the applications: the counterpart is that messages sent by applications will include extra routing information such as the message destination. Routing features must be implemented in the subdaemon; they are managed by the master daemon.

Transparency: adding a Tux Daemon Transport Layer In order to abstract the communication through Tux Daemon, a transport layer has been added. This layer mainly uses a TCP/IP module for communication; meanwhile

it uses a propriety (open) protocol module based on libusb for local the Tux Droid link. it uses a DBUS module for direct communication with existing applications using DBUS as API New Transport Modules could be added when needed The different layers of the Tux Subdaemon:

The data layer is responsible of simple data processing. As an example, the data processing module of the Tux Droid channel aggregates status coming from the USB to build a complete state of Tux. More information can be found in the source code of the Tux Droid Daemon. The routing layer sends data to the destination channel ensuring the priority rules set through the master daemon.

Application Channel Message Structure The Application Channel messages are 16 bytes long and are structured in three fields:

The Destination Header is composed of

o o

a "Destination" byte defining the destination channel a "Sub-destination" byte indicating the Tux Droid Identifier a "Data Type" byte defining the type of data message (control, request, answer,..) a "Sub data type" byte defining the type of control sent (raw command, structured command, status data, information,...)

The Data Header is composed of

o o

Data composed of 12 bytes of data