Mother Node

Jump to: navigation, search

The Mother Node is PC/Linux/Mac software to control the Orb Swarm from the Mothership.

To Do

An ordered list of things to do:

  1. integrate json
    1. build json.jar [done]
    2. specify json messages
    3. put it all together
  2. add PID and other variable display/control
  3. add speed control to smooth paths
  4. implement orb deconfliction in smooth paths


To run the mother node software you will need:

  • computer running one of the following:
    • Windows
    • Linux
    • Mac OS X
  • serial port support (to connect to the zigbee):
    • 1 serial port or 1 USB to serial port adapter if no serial port exists, you might need to install a driver for the specific adapter
    • Mac OS: the group on /var/lock needs to be changed to "uucp"
    • Linux: it may be necessary to install RXTX lib. A version the is packaged into the mother node software. If it does not load and run properly, it may not be compatible with the version of the Linux you are running, you should see errors in the output of the program to this effect. In this case you will need to install the correct version of RXTX into a location that appears in LD_LIBRARY_PATH or DYLD_LIBRARY_PATH.
  • USB support (for joysticks)
    • enough USB ports to connect joysticks (up to six)
    • USB hub(s) will probably be needed. There have been issues with joysticks switching which orb they are connected to. There has been some discussion about possible under-volt conditions with many joysticks. Powered USB hubs might be a good choice.
    • Python (to read USB ports)
      • Python
      • Pyobjc
      • Pygame
  • Java (see Java Technology)
  • swarmcon.jar (see Java Technology)

OS Compatibility Table
Mac OS X Linux Windows
tested OS version 10.4 (joystick problems with 10.3?) [please add] [please add]
Python 2.4.4 [please add] [please add]
pyobjc 1.4 [please add] [please add]
pyGame 1.8.0 [please add] [please add]


After installation, run the program from command line by typing:

  java -jar swarmcon.jar

On most systems you can also double click the jar file to run it.

The first time the software runs on your computer it puts properties file in your home directory:

The dot "." at the start of the name makes this a hidden file on unix based systems. To see this (and all the other hidden files) in your home directory type:

 ls -a ~

Edit the properties file in your home directory to control behavior of the program. You will need to restart the program after you make changes to the properties file to see the effects of your changes.

The properties in the properties file are commented and should be fairly straightforward (if not let me know). Some of the things can can specify in the properties file:

  • a timeline to automatically start
  • a serial port to automatically connect to
  • the total number of orbs
  • exactly which orbs are in use
  • mappings between orbs and joysticks



The completed Mother Node software should provide:

  • A user interface
  • Orb simulation
  • Orb behavior development platform
  • Orb behavior library
  • Choreography development system
  • Real time swarm control
    • Orb serial communications
    • Orb behavior selection
    • Orb lighting control
    • Orb audio control
    • Choreography choreography :)
    • Orb state display
  • Orb health monitoring, alerts (low battery)
  • Telemetry collection and archiving

There are two Mother Node efforts SwarmCon and DashBoard.


SwarmCon is a java program (source code) with following features:

  • A (partial) user interface
  • Orb simulation
  • Orb behavior development platform
  • Some orb behaviors
  • Orb serial communications (stub)

The executable swarmcon.jar can be downloaded and run. It has been tested on Mac OS X (10.4) and Windows (XP). Please give it a try on your system and let me know how it works.


Messages are passed between orbs, joysticks and the mother node. The following is intended to be a complete list of these messages. At the time of this writing not all messages are implemented. Those messages are marked with "*", an asterisk.

Illuminator (lighting) API is documented here: Daughterboard (mpotion control and IMU) API is here:

name description form example sent by received by
steer command signal the orb to swing it ballast port or starboard {<orbid> $s<steer>*} {60 $s87*} mothernode, joystick orb
power command signal the orb to swing it ballast forward or aft {<orbid> $p<power>*} {61 $p28*} mothernode, joystick orb
sound command signal the orb play a particular sound {<orbid> <M1 VPF <mp3>>} {62 <M1 VPF hello.mp3>} mothernode, joystick orb
stop play command signal the orb to stop playing sounds {<orbid> <M1 VST>} {63 <M1 VST>} mothernode, joystick orb
volume command set orb sound volume {<orbid> <M1 VWR B <volume>>} {64 <M1 VWR B 128>} mothernode, joystick orb
light command set the value for a color channel on the orb {<orbid> <L <channel><cvalue>>} {65 <L G128>} mothernode, joystick orb
light duration time to fade to next color in 1/180 second units {<orbid> <L T<ticks>>} {65 <L T500>} mothernode, joystick orb
maneuver command* signal the orb to perform a canned maneuver {<orbid> <tbd>} {60 <tbd>} mothernode, joystick orb
position command* signal the orb to move to a particular utm location {<orbid> $e<east>* $n<north>*} {61 $e499999.999398* $n10012072.763607*} mothernode orb
origin command* inform the orb of the center of it's little universe {<orbid> [o e=<east> n=<north>]} {61 [o e=499999.999398 n=0012072.763607]} mothernode orb
position request* tell the orb send a position report {<orbid> [p?]} {63 [p?]} mothernode orb
info request* tell the orb send a health and status report {<orbid> [i?]} {62 [i?]} mothernode orb
servey request* tell the orb send it's de-biased surveyed position {<orbid> [s?]} {62 [s?]} mothernode orb
waypoint request tell orb which waypoint to go to next {<orbid> [w x=<east> y=<north> p=<heading> pdot=<rate of change of heading ( counterclockwise rad/s )> v=<velocity>]} {62 [w x=1000 y=2000.5 p=1 pdot=0.2 v=10]} mothernode orb
position report* a report containing the orbs position {<cr>@<orbid> p e=<east> n=<north><cr>} {\n@64 p e=499999.999398 n=10012072.763607\n} orb mothernode
survay report* a report containing de-biased survey position {<cr>@<orbid> s e=<east> n=<north><cr>} {\n@64 s e=499999.999398 n=10012072.763607\n} orb mothernode
info report* a report containing the orbs health and status {<cr>@<orbid> i <label>=<value> ...<cr>} {\n@61 i bat=30 yaw=170\n} orb mothernode
waypoint report* an ack that the orb has received a waypoint {<cr>@<orbid> w <cr>} {\n@61 w \n} orb mothernode

Variables Referenced Above
name description type range
<orbid> orb identifier int 60 to 65
<steer> port/starboard ballast swing int -100 to 100
<power> forward/aft ballast swing int -60 to 60
<north> utm northing value double (range of double)
<east> utm easting value double (range of double)
<cr> carrage return char 13
<mp3> name of a sound file string filename
<volume> sound volume int 0-255
<cvalue> color channel value unsigned char 0-255
<ticks> time in 5.5 msec units unsigned short 0-max unsigned short
<tbd> to be decided later - -
<heading> radians counterclockwise from east double (range of double)

Java Technology

To run swarmcon.jar you will need:

To establish your java version, type on the command line:

 java --version 

The jar file can run probably be run by double clicking it. If that doesn't work, the program can be started from command line by typing:

  java -jar swarmcon.jar

To develop SwarmCon you will need:

  • The (source code) from the repository
  • A Java Development Kit (JDK) version 1.5 or later. I recommend JDK 6u1.
  • Apache Ant version 1.7 or later.

To build and run the project, go to the source code directory and type:

  ant run

To generate the java doc type:

  ant doc

The build script has many build targets. To see all build targets type:

  ant -p

Not all of the build targets have been tested.


  • DashBoard is a python program (source code) with the following features:
    • A user interface
    • Joystick control
    • Orb health and state information
    • Has been tested on a live orb and shown to work

Python Technology

Recommended programming environment: Python and wxPython

Python platform-independent object-oriented programming language. Many people I trust swear by it. Very powerful, readable, has modules to support pretty much any computational need.

We will need PySerial to talk to the Zigbee over the serial port. Pyserial on Windows needs Pywin32 windows extension from here:

Python for the Dashboard

You need these setup files to run the Dashboard.

wxPython: A popular cross-platform Python GUI toolkit for Windows and Unix (including Mac) with native look and feel on each platform. Free, open-source, includes joystick module, graphics canvas, controls, just about anything anyone might need, all nicely integrated with Python.

Boa Constructor: Python IDE and wxPython graphical GUI builder, written in, you guessed it, wxPython

(I haven't used this and can't comment on how good it is, but a GUI interface builder is probably really handy. --Jtfoote 00:34, 11 April 2007 (MST)

Just tried it; sourceforge version not compatible with latest wxPython, grrr. CVS version works (see here: but I can't be bothered. --Jtfoote 17:19, 18 April 2007 (MST)