We started with a rough idea of how we thought things would come together.  First, we would need to have the outline of the state.  One of the goals was to avoid having a lot of wires and connections on the back of the tri-fold.  To accomplish that, the state boundary outline would have to be a separate piece.  That also satisfied creating a 3D look for the state.  We could have used foam board but I thought quarter inch plywood would hold up better and allow for more precise cuts.  The plan was to use actual state boundary data to generate g-code for our CNC.  We would also plan the precise location of the LEDs and drill holes at those locations on the wood.  The legend would also be wood and would have holes for LEDs and buttons.  The hope was that a single strand of RGB LEDs could be routed around the back side of the state and legend boards and hit all the holes.  We planned to use 50 LEDs in total, 15 on the legend and 35 on the map.  As it turned out, we should have adjusted the holes somewhat but we did pretty well wasting only 2 on the strand which didn’t reach a hole and having to add 2 more to compensate which were plugged into the end of the strand (we wanted to keep the two 25 LED strands we used intact).

Other parts of our plan included use of a wireless remote in addition to the 8 buttons we planned on using on the board.  Since the remote receiver operated at 5 volts, we needed to introduce a level-converter for use with the 3.3 volt Raspberry Pi.  We then needed a switch module which could trigger a full power up from the press of a momentary switch while using very little current to monitor the switch.  We also needed to amplify audio from the Pi to drive a small set of speakers.  As the Pi audio is not always smooth and has occasional clicks and pops (even with some filtering) — this can cause problems if the amplifier is driven from the same supply as the Pi as it can draw enough current to crash the Pi.  So the amplifier would have to have its own power which could be connected when the main power came up.  So all together the hardware needed consisted of:

• Raspberry Pi Model B (Rev 1)
• Adafruit Full Sized Perma-Proto Raspberry Pi Breadboard PCB
• Raspberry Pi GPIO Ribbon Cable
• 2 Strands of 25 12mm Diffused Flat Digital RGB LED Pixels (and 2 LEDs clipped from another WS2801-based 20 RGB LED Chain from Sparkfun as I needed 52 total)
• 4-pin JST SM Plug Set (to connect/disconnect from the LED strand and in our case to fasten a couple extra LEDs to the end of the chain)
• Round tactile buttons
• Stereo 3.7W Class D Audio Amplifier
• 4-channel Bi-directional Logic Level Converter (for optional RF)
• Simple RF M4 Receiver – 315 MHz Momentary Type (for optional RF)
• Keyfob RF Remote Control — 315 MHz (for optional RF)
• 4 D-Cell Battery Holder (joined with the 1 D-Cell holder below)
• 1 D-Cell Battery Holder
• 4 AA-Cell Battery Holder (converted to a 3-cell holder by wiring across one of the cell positions)
• 2 Dual Mini Boards (to cover 4 button areas)
• Right-Angle Audio Adapter (to fit into the Pi’s audio out)
• Stereo Mini Plug
• 5mm Wide-Angle Red LED
• Size M Coaxial DC Power Plug (for fun I attached a Remove Before Flight tag to the drilled out plug to make it clear to pull the plug out when you want to operate it)
• Panel-Mount Size M Coaxial Power Jack
• 2 2″ Paper Cone Midrange Tweeters (4 Ohm)
• Pololu Step-Down Voltage Regulator (for 5 volts, 3.5 Amps)
• Pololu Pushbutton Power Switch SV
• 5VDC SPDT Micro Relay
• 9 2-Position PCB Terminals
• Board Edge Mounting Kit (for the Pi Model B Rev 1 since it doesn’t have mounting holes)
• #8 5/8″ Round Head Wood Screws (with the fender washers below for fastening through cardboard into wood)
• 1/8″ x 1″ Fender Washers
• #4 Machine Screws, Washers, Nuts (for attaching Perma-Proto and battery holders)
• #8 x 1/2″ Sheet Metal Screws (work in lieu of the screws in the board edge mounting kit above to get through 1/4″ plywood — maybe with a washer or two to diminish their length)

We used modular 6-conductor modular phones jacks and plugs for connecting with the button panels.  The legend panel used all 6 conductors for the 5 buttons and we were able to find 6-conductor modular phone cable at a local Radio Shack (this is harder to come by than 4-conductor).  For the power and other buttons we just used two more 4-conductor modular cables.  The cheapest jacks were in 10-packs at Home Depot but the modular cable we had was stranded so it wasn’t quite so easy as just using a punch down tool — we had to work to make sure it made contact — sometimes tinning some of the wire where it came through the channel.  It might be easier although slightly more expensive just to use RJ45s and CAT5 for switch wiring.

The finished control box, mounted on the bottom back of the center section of the tri-fold, is shown below.

Now that we’ve covered an overview of the build and given the materials involved, let’s discuss some of the major steps in detail.

Planning LED Placement

An important part of the project was planning the placement of all the LEDs on the map as well as what colors they should be to indicate different products on the legend.  Since the LEDs can change to any color, single LEDs could be used to indicate different products at different times with different colors.  So in planning, one could conserve LEDs by using one LED to represent each region in the state.  Here’s a video of our daughter’s planning process including color selection and RGB value determination:

Cutting Out Your State with a CNC

In our case, we had a small CNC machine we could use to cut the state outline (laser cutting the wood would have been easier).  Since the desired size of the state was larger than the CNC, the plan was to cut it in 4 pieces and join them together.  Ultimately, it all came down to how to generate the g-code for the CNC.  This was accomplished with a mixture of some Python and Java code and could be adapted for other state boundaries.  One million scale U.S. state boundaries can be downloaded here.  I’ve also made a local copy of the statep010_nt00798.tar.gz 2012 boundaries file here.  The archive file has a shape format file inside with boundary data for all the states.  A simple Python program can be used to copy out the latitude, longitude values for the boundary of a given state as follows:

import shapefile
import sys

r=shapefile.Reader("statep010.shp")
sr=r.shapeRecords()
for s in sr:
    if s.record[3]=='Vermont':
        shape=s
f=open("vermont.txt",'w')
for pt in shape.shape.points:
    f.write(str(pt[0]))
    f.write(",")
    f.write(str(pt[1]))
    f.write("\n")
f.close()

The Python program above will need the Python shapefile extension to be installed.  It finds the record associated with the desired state, in this case Vermont, and writes out the latitude, longitude values for the state outlines to an ASCII datafile called vermont.txt that will be used by our next program.  The next set of programs (written in Java and available in vermont.jar) generate g-code for various parts of the project.  These all give graphical previews of the parts they will cut.  The first program (called Plot.java) plots the state boundary from the vermont.txt file but also uses resource files that have the locations of the lights (as interpolated from a Vermont product map) and some city locations (from the lat/lon) to help in understanding where to place city labels.  The holes are roughly to scale which gave us an idea of whether they were too close to the edge or to boundaries of the state quarters.  Some polygon intersections were used in Java to produce the 4 smaller polygons for the parts of the state we needed to cut separately.  We tweaked the cut boundaries until they didn’t cross any of the light hole positions but yet kept the state quarters small enough to cut on the CNC.  Ultimately the program produces 4 g-code files, one for each of the state quarters (vermont1.nc, vermont2.nc, vermont3.nc, and vermont4.nc).

Cutting Title Letters

We also used the CNC to cut the individual letters for Vermont.  I tried out NCPlot which worked pretty well for generating g-code for the letters.  I had to re-order the cuts though on letters like the “R” and “O” since I discovered a little too late that it didn’t cut the holes before it cut the letter boundary itself. Here’s a video of the title letters being cut and sanded:

Planning/Cutting the Legend

We sized the legend panel so that it could accommodate the 15 product entries with LED holes spaced sufficiently.  It also had to fit in the center cardboard panel to the bottom right of the state.  The primary control buttons were also located on the legend panel at the bottom.  So mostly the CNC was used to drill the legend pilot holes for all the LEDs as well as for 5 buttons and to cut out the rectangular border for the panel.

And here’s the legend panel being cut:

Gluing/Sanding/Painting the Wood Parts

The four quarter pieces of the state were glued together with wood glue.  These joins were along straight edges.  Thin strips of wood were used along the seams in the back to strengthen the seams (these had to be cut away from a couple of the holes with a dremel).  The state, letters, and legend pieces were all sanded and painted.  The rivers and water areas on the state were painted with blue glitter paint. Here’s a video of the painting process:

Attaching the LEDs

All the LED holes were drilled so the LEDs protrude through the holes and the flat part containing the ICs are flush against the wood on the back side.  Hot-melt glue holds each LED in place.  The LED chain begins at the bottom of the legend panel where the LEDs fill all the holes from bottom to top and then they jump over to the map where they traverse the 35 holes there.  In a couple of cases an LED didn’t reach a hole and had to be skipped (since we didn’t want to cut the two 25 LED strands).  I debated about actually writing some code to search for the best way to cover the holes with a minimum of skipped LEDs (a familiar algorithms problem) — but missing 2 wasn’t so bad.  As a result, we need to put together a 2 LED extension (using the other JST plug from the set) and add that to the chain.  The photo below shows a top view of the board where you can see the cardboard layer, mounting blocks, and map layer.

Buttons

There are 4 areas where buttons are needed: at the bottom of the legend panel, an “on” button at the bottom left of the state (which includes a power LED), and buttons for the song and the bird located to the left of the upper portion of the state.  All of these are backed by small proto boards whose buttons and leds extend through either the wood or cardboard and which are hot-melt glued on the back.  The 5 legend buttons are connected with a single 6 conductor modular phone cord.  The power button/led is connected with a 4 conductor modular phone cord and then bird and song buttons jointly utilize another 4 conductor modular cord.

Mounting the Boards to the Cardboard Tri-Fold

Both the state and legend boards have wood blocks wood-glued to them in the back to allow space for the LED strand (and buttons) behind them but in front of the cardboard.  Fender washers and wood screws come through the backside of the cardboard into those wood blocks, holding the boards securely on the cardboard.

Design of the Control Box Enclosure

The electronics control box is attached to the bottom of the central cardboard panel on the back.  The box is 24″ long (to match the central tri-fold panel).  Electronics, batteries, and speakers are laid out linearly along the full 24″. To make access easier, an acrylic sliding top is used which can open fully to give access to electronics and batteries.  The components themselves are also mounted to a slideable 1/4″ plywood base which is mounted slightly above the bottom of the box.  The bottom of the box can therefore be flat without the various mounting screws for the board and batteries being exposed.  It’s also convenient to be able to slide the electronics out.  One end piece on the box has both a network jack and an external power jack.  Originally, we used external power but once the battery circuit was fully in place that became much more convenient and we never used external power again during development.  The power jack is wired so that battery power cuts off when external power is applied (but a jumper needs to be removed if you want to provide regulated 5 volt power through the external jack — otherwise a slightly higher voltage needs to be supplied as the internal 5 volt regulator needs a slightly higher voltage — as the 5 “D” cells are providing when it’s on battery).  A dummy plug inserted in the external power jack serves as an effective “safety” so the system isn’t accidentally triggered during transport.  In a nod to the aviation community, it seemed reasonable to attach a “Remove Before Flight” banner to the dummy plug to clearly show its purpose (and I recently witnessed parents at our daughter’s school removing the plug without needed explanation to give it a try).

The photo below shows the end of the enclosure with the network/power connection end removed.  This shows the bottom that the components are connected to.  You can see the Pi board with the circuit board clips which hold it to the base.  Sheet metal screws of the appropriate depth were used with the clips to allow a mount on the 1/4″ plywood.  The speaker normally occupies the space at the center of the photo.  A very short RJ45 male-to-male cable was created to bridge the gap between the Pi and the female-to-female RJ45 which was used as the network connector on the end panel.

The control box is fastened to the cardboard using the same fender washer and wood screws as the state and legend except they come through from the front side of the board and are covered by stickers and maple leaves.  There are three screws, one on the left, one in the middle, and one on the right.  The box has a wiring hole that comes out behind the bottom side of the legend.  The 6-conductor modular cord and 4-pin JST go through that hole. Here’s a clip of our daughter sanding the control box pieces prior to assembly:

Here’s a video of how the sound/ventilation holes were cut in the acrylic:

Software

The Pi is running the Occidentalis distribution from Adafruit (0.2 as of this writing).  The project is run from a single Python routine developed using Adafruit’s WebIDE.  Aside from the Python routine and data files a couple of other changes had to be made to run the code as a service and to perform auto-shutdown.  In using the WebIDE, the files for running Vermont reside in /usr/share/adafruit/webide/repositories/my-pi-projects/Vermont on the Pi.  Vermont.py is the main program.  To run this as a service when the Pi starts up an /etc/init.d/vermont file was added as follows:

#!/bin/sh
# /etc/init.d/vermont
case "$1" in
  start)
    echo "Starting vermont"
    sudo /usr/share/adafruit/webide/repositories/my-pi-projects/Vermont/Vermont.py 2>&1 &
    ;;
  stop)
    echo "Stopping vermont"
    # kill application you want to stop
    LP_PID=`ps auxwww|grep Vermont.py|head -2|awk '{print $2}'`
    kill -9 $LP_PID
    ;;
  *)
    echo "Usage: /etc/init.d/vermont {start|stop}"
    exit 1
    ;;
esac
exit 0

Remember to use “update-rc.d vermont defaults” to register the service to run on boot.

Also, if you’re using the IDE you may want to do an “/etc/init.d/vermont stop” in the shell to ensure the service isn’t also running as you run another from the IDE.  Since our code had timed auto-shutdown built in, we had to be careful to set the timeout higher or to not run the code very long during development or it might shut down if we hadn’t hit any buttons.  For auto-shutdown use we put a shutdown.py script on the Pi as follows:

#!/usr/bin/python
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(4,GPIO.OUT)
GPIO.output(4,True)

Since our board uses the GPIO #4 line to tell the Pololu switch to kill power, this script will immediately shut off power.  But we want a graceful shutdown first, so we modified the halt routine to invoke it when a power down was requested.  The halt script is modified to include the shutdown.py call between the “Will now halt” line and the actual halt call:

...
log_action_msg "Will now halt"
/usr/bin/python /home/pi/shutdown.py
halt -d -f $netdown $poweroff $hddown
...

The call to perform an immediate graceful shutdown with power off is then “shutdown -h now”.  This is what our application does when the user hits the “Off” button.

The full listing of the Vermont.py application is included here.  In addition, numerous wav files were recorded for use and are located in a subdirectory called “voice” under the main “vermont” directory.  Files were recorded/edited/merged with the excellent Audacity tool.  Some of the original songs and sounds were in MP3 format.  While the Pi can play those fine with MPG321, it was discovered that performance was a bit better if they were converted to WAV format.  The MPG321 tool can actually be used to do the conversion on the Pi itself.  Then we uniformly used the “aplay” tool to play the WAV files.  For the most part, audio is played asynchronously and is intentionally interrupted should another sound need to play.  This is accomplished with a call like:

os.system("killall aplay;aplay mysound.wav &")

Basically, this kills any current instances of aplay and backgrounds a new one.  A synchronous version would just omit the ampersand and would block until the audio is played. We do that in a few places to simplify the logic.

The ability to background thread the audio makes it possible for us to poll buttons and cause LED changes while the audio is playing (an alternative would have been to use interrupts to service buttons).  In some places we simplified the audio to be backgrounded by merging clips into a single file (often with “combo” in the name).  That avoided need to background a sequence of play operations.

The application has 4 modes of operation controlled by the “Mode” button: manual, automatic, quiz, and settings.  In manual mode, the up and down arrows and select can be used to highlight elements on the legend and to show where those are on the map.  Pressing select plays audio associated with the item.  Automatic mode will automatically cycle through the legend.  Select will still work but hitting up or down will jump back to manual mode.  Quiz mode will quiz users on Vermont facts and they need to use the up and down and select to choose one of the legend items to answer each question.  Settings mode allows the auto shutoff time to be change from 5 minutes up to 60 minutes.  The default is 5 minutes to conserve power.  The state song and bird song buttons can be selected in manual or automatic mode.  The “Off” button shuts the project down (giving you a couple chances to bail out before the real shutdown starts).  The “On” button is used to power up (but it actually will perform an emergency shutdown if pressed again — an artifact of the way the Pololu switch module works).

The application is highly data driven with a “highlights” list giving the sounds, colors, and associated lights to play together.  A “quiz” list gives a list of quiz questions and answers.

Structuring the Python so that most customizations can be performed through editing the data makes it more accessible to kids who can create the details themselves (our 2nd grader did, see the video below as she uses the Adafruit WebIDE to enter her custom data).  Keeping the rest of the code modular (we could have probably done better) makes it easier for kids to contribute some of the logic (say for the quiz section) without needing to think about all the more complex interactions.

Traditional Poster Work of Captioning and Gluing Elements to the Board

Beyond the electronic elements, the poster had all the traditional aspects of mounting photos and printed materials to the board. We inkjet printed the labels onto either white or transparent full page sticker paper and then cut those up for the legend and product labels. Our daughter also came up with the idea of gluing Maple Leaves onto the poster (due to the Sugar Maple and Maple Syrup in Vermont). This helped to hide a couple of the screw holes on the bottom and where the wires bridge from the legend to the map. Here’s a condensed video of some of the elements of pasting/gluing elements to the board:

Looking at the Electronics in More Details

Let’s take a look at the layout of components in the enclosure first.  On the left is the mounting position for the Pi which directly connects with the network jack on the outside — which is handy for adjusting the program with the WebIDE.  The right speaker also fits there (it’ll be the right as you face the front of the board).  The external power jack is tucked under the speaker opposite the network jack.  You can also see the hole that carries the LED cable and the 6-conductor button cord to just under the legend panel.

In the center is the Perma-Proto board which comprised most of the soldering work.  We’ll look at it’s layout below.  You can see on the left is the ribbon cable connected to the Pi.

On the right side we have the two battery packs.  The 5 “D” cells power the Pi and the LED strand.  The 3 “AA” cells power the audio amplifier (so as to be isolated from the main supply).  On the far right is the left speaker.  Altogether it’s a pretty tight fit but it nicely keeps the poster stable — as a counter-weight to the wood and LEDs on the front — and keeps the center of gravity low.

The photo below shows an enlarged view of the Perma-Proto board.  Just to the right of the ribbon connector is the level converter.  The RF receiver board which sits vertically right above it operates at 5 volts and the level shifter converts the 4 digital outputs of the RF receiver board to the 3.3 volt level for the Pi.  The pinouts match pretty well so a 7 pin socket can share the same pins with the level converter (see the second photo of the Perma-Proto with RF receiver, amplifier, and voltage regulator removed).
In the center of the board is the Pololu switch module which lets a momentary switch power up the system.  It operates directly off the voltage provided by either the external power or the 5 “D” cells.  A 5 volt regulator is optionally patched in through a jumper and PCB terminals (green board at the top).  The only case you wouldn’t use it is if you had a regulated external 5 volt supply.  Mainly because it was handy a 5 volt relay (to the right of the power module) is used to trip power on to the audio amplifier through it’s separate supply when the main power comes up.  This is basically providing isolation so the audio amplifier’s potential power spikes don’t bring down the Pi.  The amplifier itself fits into a socket to the right of the relay at the far right side of the board.  Socketing the amplifier makes it easy to remove the speakers and amp as a unit.  The amplifier also includes a jumper to control gain.

In the photo, the RF antenna is coiled up.  Reception was improved by stretching out the antenna to the full length of the box — but range was still fairly weak.  I’m not sure we’d include the RF receiver if we were to do this again.  It would be useful to design a board for the Pi with this combination of features (power, LED strands, amplifier, and possibly RF).

Well that concludes one of my longest writeups. I hope I’ve provided enough detail for those who might want to tackle something similar. Working with our daughter on a complex project like this was a pretty amazing experience — I still marvel at the variety of work she did in looking back on the videos we took — but it really is possible if the work is spread over a number of weeks.

The photo below shows the Arduino, Electric Imp Shield, and my “Alarm Monitoring Shield” on top.  In the photo, it’s being powered by the USB cable.  Considering the red wire on the alarm bus is 12V, it would also be straight-forward to add a step down converter to the Alarm Shield to power the stack from the alarm bus itself.

The Arduino monitoring routine given in my original post needed only a minor tweak — to send a copy of the data via software serial on pin 9.  Here’s a link to the new Alarm.ino version.  I then translated the Python program I’d been running on the Raspberry Pi to Electric Imp’s Squirrel language.  The translation was fairly straight-forward and only minor changes needed to be made.  Here’s a copy of Alarm.nut (yes, squirrel programs are exported to nut files).  Just as we used the Raspberry Pi to offload interpretation of the alarm state changes from the Arduino, the Electric Imp and it’s embedded processor do the same thing.  To get the code onto your Imp, you can upload the nut file onto their site and configure your Imp to use that program (or edit it directly on the web).  The most reliable way to get the Imp to update its software (especially if it’s busy running a previous version of your code), is either to power cycle the board or to pop out and pop in the Imp from the SD socket.  The Imp will quickly update its code and start running.  Imp’s web-based planner interface, shown below, includes a rectangular box for the Imp.  The current program “Alarm State” is shown at the top and any messages transmitted to the server with the server.show command are displayed below (e.g. “ALL,INSTANT,ON”).  When connected with my live system, I was impressed that the state change and display was nearly instantaneous (despite their warnings that their servers were on the West Coast and I’m on the East Coast).  The result could also be sent to other destinations through HTTP by modifying the squirrel routines to output the state and connecting the output of the Imp box with the input of an appropriately configured HTTP Request box.

System designers often choose to transmit system state through serial protocols.  For instance, one such system is described here.  Systems like this use a common bus between keypads and the central system with power, ground, and clock and data lines.  It would be nice to make use of such system state information on computers like the Raspberry Pi.  But one has to be careful not to damage the Pi’s digital inputs as the voltages may be quite a bit higher (e.g. 12V) than the Raspberry Pi can handle.  Opto-isolators can be useful in protecting the Raspberry Pi or micro-controllers like the Arduino.  Depending on the speeds of the serial signals you’re seeking to monitor, reading them reliably on the Raspberry Pi can be a challenge.  For the signals I was seeking to read, while the Raspberry Pi was capable of reading them, reliability was poor even when I gave the process priority because of the possibility of it being pre-empted.  And if the serial signal being transmitted has no checksums or other mechanism built in to detect errors, one really can’t afford to miss any parts of the transmission.  This is a perfect example of where the Raspberry Pi can work cooperatively with a micro-controller like the Arduino.  If the Arduino could do the monitoring and report state changes to the Raspberry Pi over its serial connection, the Pi could handle the more sophisticated signal interpretation and notifications.

In the configuration shown below, the Raspberry Pi both powers and receives serial information from an Arduino Uno and custom shield by USB.  The Raspberry Pi is shown with WiFi dongle, case, and  low-profile microSD card adapter from Adafruit.

I used an Adafruit Proto Shield to mount the terminal blocks and opto-isolator for the Arduino.  I happened to have some TLP-624-4 chips on hand so I used one but I only needed two of the four channels that chip provides (to handle clock and data).  In my case, I needed 1K resistors on the input side and actually 180 Ohm pull-ups on the output side to read the signal reliably.  In the case of the Arduino, the output pull-ups are to 5v and earlier when I was reading the outputs using the Gpio lines on the Raspberry Pi, they were pulled up to the 3.3v line.  The terminal blocks on the left of the photo are to the monitored system.  I added the optional terminal blocks on the right if I wanted to pass the signals through to another device on the bus.  The higher voltage red power wire is only there for the purpose of the pass through to other devices.  Any two digital lines on the Arduino would suffice for reading the signal — I chose 6 & 7 (actually originally I chose 7 & 8 but realized that I might want to try the shield with the Electric Imp Shield for wireless transmission which uses 8 & 9 by default).  I’ve included a Fritzing-generated breadboard and schematic diagram later in the article to make the circuit more clear.

The logic trace below shows an example of data being received from the bus.  The SPI protocol analyzer on the Saleae Logic Analyzer does a good job of interpreting the bytes being transmitted (Caution: make sure you know the voltage levels you are testing are within the allowable range for your analyzer).  In this case, I took data to be valid on the trailing edge of the clock pulse.

The trace below shows a similar system state (but a different sample) as seen after the opto-isolator.  As a result of the circuit, the original signal is inverted — which actually turns out to be convenient in interpreting system state.

In the case of this serial signal, I’m interested in elements of the system state which are being repeatedly transmitted (e.g. the first 5 bytes of the transmitted 7 byte groups).  So I’d like the Arduino to transmit any groups where  a change happens in the first 5 bytes.  A simple Arduino program to do this is shown below.

//Capture Serial Bytes

#define CLK 7 //clock pin
#define DAT 6 //data pin
#define LEN 7 //# of serial bytes to read per group
#define SIG 5 //# of signicant bytes to detect state change

int buf[LEN];
int last[LEN];
int thresh=4000; //minimum delay per group start (on 328p)
int msk=0x80;
int cnt,i,j,scnt,pnt,cur,bit,bcnt,dif;

void setup(){
  Serial.begin(9600);
  pinMode(CLK,INPUT); //needed external pullups
  digitalWrite(CLK,1);
  pinMode(DAT,INPUT); //needed external pullups
  digitalWrite(DAT,1);
}

void loop(){
  pnt=0;
  bcnt=0;
  msk=0x80;
  cur=0;
  while(1) {
    while(digitalRead(CLK)==0);
    cnt=0;
    while(digitalRead(CLK)==1) {
      cnt++;
    }
    if (cnt>thresh) break;
  }
  scnt=cnt;
  while(1) {
    while(digitalRead(CLK)==0);
    bit=digitalRead(DAT);
    bcnt++;
    if (bit==1) {
      cur|=msk;
    }
    msk>>=1;
    if (msk==0) {
      msk=0x80;
      buf[pnt++]=cur;
      cur=0;
    }
    if (bcnt>(LEN*8-1)) break;
    while(digitalRead(CLK)==1);
  }
  dif=0;
  for(i=0;i<SIG;i++) {
    if (last[i]!=buf[i]) {
      dif=1;
      break;
    }
  }
  if (dif==1) {
    //Serial.print("scnt=");
    //Serial.println(scnt);
    Serial.write(LEN);
    for(i=0;i<LEN;i++) {
      //Serial.print(String(buf[i],HEX));
      //Serial.print(" ");
      Serial.write(buf[i]);
    }
    //Serial.println();
    for(i=0;i<SIG;i++) last[i]=buf[i];
  }
}

My relatively simple protocol was to send a length count followed by that number of bytes from the Arduino every time a state change was observed.

On the Raspberry Pi, I wrote a Python program to interpret the state information coming back from the Arduino and to email change notifications.  The interpretation starts at the bit level and uses a set of re-write rules to provide a flexible way to build up higher-level interpretations or to re-arrange the way the text appears.  One shortcoming is that I don’t yet detect cycles in the state information.  In certain situations, a sequence of messages itself represents a state (e.g. when one or more doors/windows are open).  Because the current logic waits for state changes to stop before sending — the result could be a pretty long notification.  I’m planning to update the code shortly to recognize cyclic sets of state notifications as a single state.  Additionally, the code should be updated to provide different levels of detail for different addresses or means of notification.  The code shown here sends every displayed state change (like a door opening) — while one might want only priority notifications of actual alarm conditions when the system is armed.

In order to run the Python program as a service which automatically starts on the Pi, I used a script which I stored as /etc/init.d/monitor.  Then I used “update-rc.d monitor defaults” to ensure that it starts on boot.  You can start and stop the program manually with “/etc/init.d/monitor start” and “/etc/init.d/monitor stop”.

When you launch a Romo app and it says “Waiting for controller devices”, it sends out a multi-cast packet (on 235.8.13.21:21135) which advertises that the Romo is present and gives its name.  That’s how controller apps know which Romos they can select for control.  The packet also gives the IP address of the Romo.  If you choose to control a specific Romo in the controller mode of the app, it starts sending UDP packets to communicate with the Romo.  These packets tell the Romo to show different emotions, to flip which camera is used, to move in one of 8 ways, and to start streaming video.  If video is requested, a sequence of JPG images are streamed back from the Romo to the controller using that same UDP port (port 21133).

Note: As this protocol is internal to the Romotive app, it may very well change if they need to restructure how they do things (for instance, if they add motor speed control instead of just direction).

I recently learned Python (actually because I had fun taking Sebastian Thrun’s self-driving car class on Udacity and that was the language used for the course).  In an attempt to learn it better, I’ve been trying to use it more often when I need a quick program.  So I cranked out a  program to do the Romo control.  Keep in mind this is a programmatic way to control the Romo from any machine that can route UDP to the Romo — not a UI (although there are a number of ways to expand it to be a cross-platform UI).  (Note: a UI version is now available — see the updates at the bottom of this article)  You can download the full romo.py file here.  The full listing has more comments and instructions.  Here’s an abbreviated listing with mostly just the code:

import socket
import time
import threading

#Edit the following 3 variables to match your configuration

image_directory="e:/romo-images" #directory to store images
my_ip=[192,168,123,2] #your IP
romo_ip=[192,168,123,3] #IP of the romo

romo_port=21133
romo_ip_str=".".join(map(str,romo_ip))
my_ip_str=".".join(map(str,my_ip))

buf=""
for oct in my_ip:
    buf+=chr(oct)
for oct in romo_ip:
    buf+=chr(oct)
for i in range(4):
    buf+=chr(0)

#faces

smile="\xc8"
love="\xc9"
excited="\xca"
wink="\xcb"
random="\xcc"
frown="\xcd"
angry="\xce"
confused="\xcf"
hush="\xd0"
crying="\xd1"

#camera

flipcam="\x8c" #flips the camera from front to back or back to front

#moves (for some reason the first move may need to be sent twice)
s="\x70" #stop
fl="\x69" #forward left
f="\x64" #forward straight
fr="\x65" #forward right
rl="\x78" #rotate left
rr="\x68" #rotate right
bl="\x77" #back left
b="\x7c" #back straight
br="\x7b" #back right

#control commands

init="\x01"
startvideo="\x06"
shutdown="\x08"

abort=threading.Event()
sock=socket.socket(socket.AF_INET,socket.SOCK_DGRAM)

#for type 3 face and move commands
def send(cmd):
    tmp="\x03"+cmd+buf
    sock.sendto(tmp,(romo_ip_str,romo_port))

#for type 2 commands like init, startvideo, shutdown
def ctrl(cmd):
    if cmd==shutdown:
        abort.set() #let thread shut down
        time.sleep(1)
    elif cmd==startvideo:
        t=ThreadClass()
        t.start()
    tmp="\x02"+cmd+buf
    sock.sendto(tmp,(romo_ip_str,romo_port))

class ThreadClass(threading.Thread):
    def run(self):
        vsock=socket.socket(socket.AF_INET,socket.SOCK_DGRAM)
        vsock.bind((my_ip_str,romo_port))
        cnt=0
        print("Image fetching thread started.")
        while not abort.isSet():
            data,addr=vsock.recvfrom(15000) #Photos are less than 15K
            cnt+=1
            scnt=str(cnt)
            for i in range(4-len(scnt)):
                scnt="0"+scnt
            if ord(data[0])==5 and ord(data[1])==0: #JPEG Image
                f=open(image_directory+"/image"+scnt+".jpg","w")
                f.write(data[14:])
                f.close()
        vsock.close()
        print("Image fetching thread finished.")

ctrl(init)
#time.sleep(1)
#ctrl(startvideo)       

#ctrl(shutdown) will shutdown the image capture thread, disconnect from the romo, and allow one to quit() the python interpreter

A typical session that tells the Romo to smile, express love, move forward, and then stop might be:

python -i romo.py
>>>send(smile)
>>>send(love)
>>>send(f)
>>>send(s)
>>>quit()

A video capture session which starts video capture, moves forward, flips to the back camera, moves backward, and shuts down might be:

python -i romo.py
>>>ctrl(startvideo)
>>>send(f)
>>>send(s)
>>>send(flipcam)
>>>send(b)
>>>send(s)
>>>ctrl(shutdown)
>>>quit()

Be careful in your use of video capture, the frames come rather quickly and are a little less than 15K each.  When you turn on video capture in the script, it starts a background thread which captures them and writes them out to the specified directory as a sequence of JPEG files (I only pad for a 4 digit count).  If you write a UI based on this, you’d normally just refresh the image every time a new one comes in.  You could also do the same if you just want to add a command to copy out whatever the last received frame is (rather than keeping them all).  Have fun!

Update: I couldn’t resist putting together a simple Python UI with a real-time video window and keyboard controls.  You can download the full romo-ui.pyw program here.  The UI requires a standard Python release which includes the Tkinter UI modules.  It also requires the PIL library for the JPG image handling.  The details about how to get these are in the comments to the program.  If you’ve installed the Python environment with Tkinter, you can just launch the romo-ui.pyw program to start it — make sure the phone on your Romo is already waiting for connections.  You can exit the app either by typing “q” or deleting the window.  Both should exit gracefully.  The steering controls take advantage of the 9 key keypad (if you’ve got one).  It should work in either numeric or non-numeric mode (see the code for the key mappings).  Flipping the camera view is the “-” key and the faces are controlled by generally logical letter keys.  It works great on my Romo (even with my hyper speed motor mod).

Update2: I added automated discovery capability for Romos.  You can download the full romo-ui2.pyw program here.  You currently can’t choose from multiple Romos (unless you hardcode the address) but it will auto-discover the first one it finds and connect to it.  This involves both announcing that it’s looking for Romos on the multicast channel as well as listening for responses (the default is only to look for about 5 seconds — you can lengthen that time by setting it in the script).  This was tested with the latest Romo iPhone app (v1.05).

The Gottlieb Decagon score reels use a solenoid to advance the reel.  They also have a number of connections so the numeric position of the reel can be sensed.  The solenoids are usually triggered by 24VAC.  I found that an old 18V DC 2.23 Amp printer power supply I had was sufficient to trigger the solenoids — albeit one at a time.  I used only 4 of the numerous wires coming from each reel.  I used two wires which get connected when the zero is displayed.  And then, of course, the two wires to energize the solenoid.  I had some 5V DC relays (Axicom D2n) on hand which could be directly driven from an Arduino and could handle the current and voltage for the solenoids.

I haven’t put a case on the unit yet — since I have some more Decagon units waiting to join in (I got 4 more Decagons recently for half the price of my first 3 but I’ll need to clean them to get them into working order).  I used 10-24 threaded rod and nuts to connect and space the reels appropriately  (1.6″ between the metal mounting plates worked well).

The video below shows the unit being set through the browser on an iPhone.  My original plan was to use a set of 4 reels for a clock but I’m also thinking about using it for a web hit counter.

On the other end of the CAT5 patch cable from the Perma-Proto interface board is the Arduino stack itself.  In this case, I wanted to make the counter controllable over WiFi so I stacked an Arduino Uno with a WiFly shield with the Patch shield on top.  When using the step-down the power comes over the CAT5 as well so no other connections are needed with the Arduino stack.  The Arduino sketch runs a small web server which accepts new reading values for the score reels.  When the unit powers up, it zeroes all the reels.  Whenever more than one reel needs to change, I stagger energizing the reel solenoids to limit the needed power.  The settings I found that worked best for my reels was 50ms to pull the solenoid down and a delay of 300ms to allow the solenoid to pop back up and the reel to turn.  If I energize the reels in sequence, the reels do actually overlap in their movement due to the longer time for the mechanical movement of the reels to take place.  Here’s a link to the current sketch that’s running on the Arduino.  I’ll generalize it further and make improvements as I add additional reels.  I put the wiring for the Perma-Proto into Fritzing but haven’t had the time to add the needed terminal blocks, DPDT relays, and the Perma-Proto itself to the Fritzing libraries.

Here’s the supply I used from an old HP printer.

The phone mounts very securely on the base. The front also has three accessory ports which could be utilized by various effectors (but probably not sensors unless other connections to the phone are utilized).

Romotive took advantage of alot of Pololu parts in designing the robot. Quite literally why re-invent the wheel (or track) when Pololu’s got some excellent parts including the tracks, motors, and motor mounts. I think the original motors are probably the 100:1 #992 motors from Pololu.  The Romotive guys also said they required about 10 oz-in of torque and that the limit on the H-bridges was about 1 amp as reported in this thread.  The original Romo actually moves kind of slow and I thought speeding it up might be nice.  I couldn’t quite find another micro gear motor on the Pololu site that met the specs.  But one of the posts on the previous thread mentioned a nice 56:1 gear motor that met the specs.  So I decided to give it a try.  I used a couple of JST connectors and wires I had around (since the Romo uses JST connectors for the motors) and I soldered the new motors onto the leads.  After installing, the result is a much higher-speed Romo as shown in the video below.

This operates the Romo a bit faster than the original software was designed for.  It would be nice to get some enhancements to the default applications to support this.  For instance, better motor speed control would be nice or at least a mode where it slows down for turning in place.  Also the Romo may more easily sense that it’s been shaken and makes a noise and a confused expression — but this happens much more often at high speed and it would be nice to turn it off.  I also somehow ended up with the motor polarities on the new motors exactly backwards even though I carefully mirrored the way the wiring was done with the other motors.  This could obviously be a quick fix with a motor polarity software setting but unfortunately there’s no such setting in the app.  The Romo is a lot of fun and the high-speed version will certainly speed up my exploring.