Mother Node
The Mother Node is PC/Linux/Mac software to control the Orb Swarm from the Mothership.
Contents
To Do
An ordered list of things to do:
- integrate json
- build json.jar [done]
- specify json messages
- put it all together
- add PID and other variable display/control
- add speed control to smooth paths
- implement orb deconfliction in smooth paths
Installation
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 librxtxSerail.so 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)
| 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] |
Running
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:
.swarmcon.properties
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
Features
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
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.
Communications
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: http://svn.lee.org/swarm/trunk/Illuminator/illuminator_src/Illuminator_API.txt Daughterboard (mpotion control and IMU) API is here: http://svn.lee.org/swarm/trunk/dboard/daughterboard_API.txt
| 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 |
| 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:
- The swarmcon.jar file (duh!)
- A Java Runtime Environment (JRE) version 1.5 or later. I recommend Java Runtime Environment (JRE) 6u1.
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
- 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 http://www.python.org/ 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.
- Download here: http://www.python.org/download/ (I recommend we standardize on version 2.5)
- Get started here: http://www.python.org/about/gettingstarted/
- Quick start to syntax from the tutorial: http://www.python.org/doc/current/tut/node5.html
- Get modules: http://cheeseshop.python.org/pypi
We will need PySerial to talk to the Zigbee over the serial port. http://cheeseshop.python.org/pypi/pyserial/1.20 Pyserial on Windows needs Pywin32 windows extension from here: https://sourceforge.net/projects/pywin32/
Python for the Dashboard
You need these setup files to run the Dashboard.
- Python 2.5 http://www.python.org/download/
- wxPython for Python 2.5 http://www.wxpython.org/download.php Get the "Docs, Demo, Samples, etc." too.
- NumPy http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103
- PySerial http://cheeseshop.python.org/pypi/pyserial/1.20
- PyWin (for windows users only) https://sourceforge.net/projects/pywin32/
wxPython: http://www.wxpython.org 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.
- Download - http://www.wxpython.org/download.php Get the "Docs, Demo, Samples, etc." too, you want them.
- Learning wxPython - http://wiki.wxpython.org/index.cgi/How_to_Learn_wxPython
Boa Constructor: Python IDE and wxPython graphical GUI builder, written in, you guessed it, wxPython http://boa-constructor.sourceforge.net/
(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: http://sourceforge.net/forum/forum.php?thread_id=1637828&forum_id=5483) but I can't be bothered. --Jtfoote 17:19, 18 April 2007 (MST)
