Controller Software Design

From molecubes
Jump to navigation Jump to search

The controller Molecube supports several functional modes of operation. Here, we will discuss each of these modes.

Available Terminal Modes

Locating controller Molecube buttons

Molecube control interfaces are available to the user through the following three terminal modes:

  1. The first utilizes the two buttons are the controller itself. Pressing Button 1 (Left most when facing controller cube oriented with USB port above buttons, see picture) starts the Dynamic Address Assignment Algorithm resulting in a Molecubes Morphology File. Pressing Button 2 (right most button) executes the default Molecubes Sequence File present on the microSD memory card.
  2. The second and third interfaces are both terminal based, the medium of data transport is the only difference. The second interface uses a USB connection and the supplied driver emulates a COM port which can be accessed with your terminal software of choice. Pressing the '?' button at the command prompt reveals all available commands.
  3. The third interface utilizes Bluetooth COM port emulation. When the host pc connects to the Bluetooth device on-board the controller, a COM port is created and again can be accessed using your terminal software of choice. The command interface is exactly the same as above. The only notable difference is a different compilation flag must be set when switching between these two. This means either the user must use the USB interface or the Bluetooth interface, these options are mutually exclusive.

Dynamic Address Assignment

Before commands can be issued, cube morphology addresses must be assigned to all connected cubes. This procedure is described in the Dynamic Address Assignment Algorithm. This process produces a Molecubes Morphology File which is saved to the microSD memory card on board the controller.

This file identifies each type of cube, the addressed assigned to this cube and how each cube is oriented relative to the cubes it is attached to. Each possible cube configuration can be uniquely identified using this approach. This Molecubes Morphology File (identified by a .mmf extension) can be loaded by the Simulator and the physical configuration of the robot is automatically reproduced in the simulation environment.

Motion Sequence Execution

Motion sequences are specified as a list of commands bundled in the form of a Molecubes Sequence File. This file indicates a timestamp of execution and all addressing information required to properly transmit a command to an attached molecube.

The controller runtime is setup by default to run a sequence file called test.msf in the root directory of the installed microSD flash memory card. It is currently up to the user to ensure a valid sequence file is going to be executed. No cross checking with the morphology occurs although it would be a good idea to prevent motions which may inadvertently cause damage to the robot.

The sequence execution is currently setup to loop endlessly. Because of the manner in which sequences are loaded and removed from the queue based datastructure, the msf file is reloaded from the microSD card on each cycle. The resulting delay is on the order of 100ms or less. If the microsd card is removed or is accidentally ejected during execution, this read will fail and the sequence will halt on the next iteration.

Motion Sequence Logging

The Morphology file definition contains a generic state listing which is intended for two purposes, initial state representation and state logging. The state descriptor is defined as follows

State Descriptor
Item Range Description
ID 0 - 255 Molecube address
class 0 - 255 Molecube class
timestamp 0 - 2^32 Time of state sample
channel 0 - 255 Telemetry Channel Represented
value 0 - 2^32 Telemetry Channel Value

Any internally sensed value or register setting on a Molecube can be assigned a channel definition and logged in this manner. It is important to note that the controller software is responsible for gathering this data. Currently no runtime framework for logging has been implemented. Each cube class is therefore able to have its own range of telemetry channel definitions defined in the following table.

Telemetry Channel Definitions
Class Channel Description
0xFA Actuator Molecube
0x00 Actuator position in 10ths of degrees
0xF8 Gripper Molecube
0x00 Gripper position

Note: see Molecubes Morphology File or GitHub for the most up to date specification.

Communications Interface

The user interface is very simple, it is based on single character commands which start different execution modes. The controller initially starts up and simply waits for user input. An error will be printed to the terminal unless the microSD card is installed properly. A terminal connection is assumed to be setup for this procedure.

Step 1: Press '?' to see all available commands

Step 2: Press 'r' to generate the cube morphology file. This will be placed in the hardcoded file location CUBES.MMF located in the root directory on the installed microSD card.

Step 3: Press 'x' to execute the hardcoded command sequence in the file location test.msf

Direct command injection

This can be tested with a good terminal program such as RealTerm. Command packets are issued through the emulated comm port interface. Ideally a piece of software will automate this process. The byte sequence to transmit is as follows

Header Device Class Address Parameter Count Instruction Parameters 0 - n
0x01 0xFC 0x00 0x04 0x12 0x00 0xFF 0x00 0x00

The above example sets the LED on the main side of the controller cube to the color red. See the AVR Command List to completely understand the command sent above. The flag 0x01 byte that is sent first indicates to the controller that a packet follows. The controller is then prepared to parse the following bytes that are sent. The response bytes are dumped directly to the terminal interface as well. The following example queries the joint angle of an actuator Molecube addressed as device 1:

Header Device Class Address Parameter Count Instruction Parameters 0 - n
0x01 0xFA 0x01 0x00 0x07

This interface is functionally independent of the terminal mode. This means these commands are valid via Bluetooth or USB interfaces. It works the same way either way. It is important to note that Molecubes won't work unless the morphology has been generated and addresses have been assigned as a result.

Configuration Modes

Discussed below are directions for configuring controller software into several operational modes. A few #define statements are used to control the current configuration of the controller software.


The Bluetooth mode is wireless which is convenient communication is reliable, loss is highly unlikely. Difficulty with this mode is often in configuring the bluetooth device with your computer. This is a newish technology and our experience has been that bluetooth support has generally ranged from tolerable to unusable. Tested configurations are listed below.

To use this functionality, uncomment line 17 in runtime.h in the controller runtime code. Recompile and re-program the LPC-H2148. If the daughterboard is assembled correctly, the blue LED on the daughterboard should be flashing slowly (~1 sec period). The controller hardware is now configured for use. Next, the host computer must connect. Follow these instructions for direction.


Lenovo Thinkpad laptop (Winxp): Worked
Dell (Winxp) + Dlink Bluetooth dongle: Worked but initial connection is unreliable
Mac Powerbook Pro (Winxp via Bootcamp): Unusable, connection is nearly impossible
Mac Powerbook Pro OSX 10.5: Worked

USB Reliable (requires USB connection)

This mode is most useful when troubleshooting and it is necessary to see debug output from the controller. In this mode, the controller will crash if it tries to print something and no USB device is connected. To avoid this problem, a 5 second delay has been inserted after the device is reset before anything is sent to the console.

Configuration of this mode is very similar to the Bluetooth setup above. In runtime.h in the controller runtime code:

Step 1: Comment out line 17: //#define BLUETOOTH_ENABLE

Step 2: Uncomment line 20: #define RELIABLE_USB

Step 3: Recompile and reload the runtime. Reset the controller and connect with a terminal to the emulated comm port to view controller output.

USB Unreliable (will run without USB connection)

Under this configuration, bytes may be dropped if the output USB buffer overflows. This only occurs with rapid bursts of lots of text. In runtime.h in the controller runtime code:

Step 1: Comment out line 17: //#define BLUETOOTH_ENABLE

Step 2: Comment line 20: //#define RELIABLE_USB

Step 3: Recompile and reload the runtime. Reset the controller and connect with a terminal to the emulated comm port to view controller output.