DIY TiLDA Badge Network

The steps below allow you to setup your own private wireless badge network for your TiLDA badge to connect to. The wireless network lets the badge display the current time, display your name and send notification messages to the badge.

There are quite a lot of steps to getting this working. The instructions below assume the following hardware and software:

• TiLDA Mke
• Raspberry Pi, PSU, keyboard HDMI cable, monitor/TV, Ethernet cable or Wifi
• 2 Ciseco radios: USB + Slice of Radio (for RPi), or a second USB radio instead
  • Actual part numbers to aid in ordering from http://shop.ciseco.co.uk/ - R017 is the slice of radio, R010 is the SRF Stick
• Internet connection for downloading new packages
• 4GB SD Card (or larger)

If you don't have a Raspberry Pi then you may be able to substitute it with another Linux PC.

Network architecture

The key components of the badge network are:

• Master control program (MCP), this stores a central copy of all information and generates the content of the radio messages.
• Gateways, these have the radios and pass the radio messages to and from the MCP.
• Database, this stores the registered gateways, badges and users.
• Web server, this provides a status page and web API
• some example scripts which use the web API to send special messages to the badges

For the purposes of these instructions we run all this software on a single RaspberryPi. These instructions are simplified to assume you just want to run this network for yourself and willing to run everything as the 'pi' user.

Installation steps

Installing initial OS and hardware install

• Download http://director.downloads.raspberrypi.org/raspbian/images/raspbian-2014-09-12/2014-09-09-wheezy-raspbian.zip
• Write to SD card
• Plug SD card into Rpi
• Connect Slice Of Radio
• Connect USB Ciseco radio
• Connect keyboard
• Use Ethernet cable to connect RPi to your network
• Connect HDMI to TV/Monitor
• Power On

OS configuration

When the RPi has booted it will present the raspi-config UI. By default, the raspian software will try to use the serial port connected to the radio for a serial console and this must be disabled otherwise we cannot use the radio:

• Select 'Advanced'
• Select 'A7 Serial - Enable/Disable shell and kernel messages on the serial connection'
• Choose No
• Select "expand filesystem" option
• Select "finish" + and say yes to "reboot now?"

Wait for RPi to reboot After reboot you can choose whether you want to carry on with HDMI + local keyboard or SSH to device using the IP address that is displayed. The default login for the RPi is "pi" + "raspberry"

Package installation

The software relies on several packages which must be downloaded and installed. The installation will take some time. Ignore any errors about being unable to contact the Wolfram package repository.

 sudo apt-get update
 sudo apt-get install -y python-pip python-dev python-requests postgresql postgresql-server-dev-9.1

Checkout Mk2-Software

The forked copy of the software below has a few additions to make the setup and installation work using these instructions

 cd ~
 git clone --branch diy-badge-network https://github.com/jburgess777/Mk2-Software.git

PostgreSQL database configuration

We must add a 'pi' user and create a 'schedule' database used to store information about the gateways, badges and users. The final command will emit several lines of messages as it creates various tables and indexes.

 cd ~/Mk2-Software
 sudo -u postgres createuser -D -R -S pi
 sudo -u postgres createdb -O pi schedule
 psql -f schedule.sql schedule

Setup python software packages

The badge network softwre relies on several python libraries which must be downloaded and built

 sudo ./setup.py develop

Generate radio message signing keys

The messages sent across the badge network are signed with a cryptographic key to ensure that the badges only accept messages from an authorized network. Since we don't have the keys that are in the current TiLDA firmware we must create our own.

 cd ~/Mk2-Software/lib
 make signer
 make keys.txt
 make keys.sh

Running the MCP software

Before starting the MCP we must first load the keys we generated above. When the MCP is started it will display messages about its configuration and start listening for gateways to connect.

 cd ~/Mk2-Software
 source lib/keys.sh
 mcp.py

Running the gateway

Open another connection to the Pi (or switch tty with alt-Fx keys and login as 'pi').

 gateway.py localhost

When you start the gateway it opens up the serial ports for the two radios and configures them to communicate with the badges:

  2014-09-24 19:46:46,700 - UsbRadios - INFO - Found radio: /dev/ttyACM0, speed 115200
  2014-09-24 19:46:46,734 - UsbRadios - INFO - Found radio: /dev/ttyAMA0, speed 9600
  2014-09-24 19:46:46,741 - UsbRadios - INFO - Entering AT mode...
  2014-09-24 19:46:47,955 - UsbRadios - INFO - Reading information for /dev/ttyACM0
  2014-09-24 19:46:48,065 - UsbRadios - INFO - Firmware: 0.51B USB
  2014-09-24 19:46:49,428 - UsbRadios - INFO - Reading information for /dev/ttyAMA0
  2014-09-24 19:46:49,557 - UsbRadios - INFO - Firmware: 0.90B SORSRF
  2014-09-24 19:46:50,569 - main - INFO - MAC: 202481588515999
  2014-09-24 19:46:50,698 - main - INFO - Established connection to mcp
  2014-09-24 19:46:50,718 - Gateway - INFO - Transmitter started
  2014-09-24 19:46:52,764 - UsbRadios - INFO - Configuring radio 0 with [u'ATPK08', u'ATCN02', u'ATAC', u'ATDN']
  2014-09-24 19:46:54,081 - UsbRadios - INFO - Applied command 'ATPK08' to radio 0, got 'OK'
  2014-09-24 19:46:54,191 - UsbRadios - INFO - Applied command 'ATCN02' to radio 0, got 'OK'
  2014-09-24 19:46:54,321 - UsbRadios - INFO - Applied command 'ATAC' to radio 0, got 'OK'
  2014-09-24 19:46:54,449 - UsbRadios - INFO - Applied command 'ATDN' to radio 0, got 'OK'
  2014-09-24 19:46:54,452 - UsbRadios - INFO - Configuring radio 1 with [u'ATPK3A', u'ATCN06', u'ATAC', u'ATDN']
  2014-09-24 19:46:55,819 - UsbRadios - INFO - Applied command 'ATPK3A' to radio 1, got 'OK'
  2014-09-24 19:46:55,939 - UsbRadios - INFO - Applied command 'ATCN06' to radio 1, got 'OK'
  2014-09-24 19:46:56,077 - UsbRadios - INFO - Applied command 'ATAC' to radio 1, got 'OK'
  2014-09-24 19:46:56,214 - UsbRadios - INFO - Applied command 'ATDN' to radio 1, got 'OK'
  2014-09-24 19:46:56,226 - Gateway - INFO - Receiver started
  2014-09-24 19:46:56,767 - UsbRadios - DEBUG - Packet send via radio 0: 100
  2014-09-24 19:47:01,625 - UsbRadios - DEBUG - Packet send via radio 0: 200
  ... more radio messages every 5 seconds

If the software cannot initialize the radio then try again, something seems to prevent the radio from working on the first attempt. If it still doesn't work after a couple of attempts then check that you completed the first setup step which told you to turn off the serial console.

Why two radios?

The first radio is used solely to broadcast discovery information to notify the badges about the existance of the gateway. All gateways transmit on the same discovery channel and the badge will connect to the gateway with the strongest signal (RSSI). These discovery messages include information about the channel used by the second radio and the time. Once the badge chooses a gateway it will switch to the channel which is unique to the gateway. This second radio will be used for all future communcation between the badge and the network.

MCP radio messages

The MCP instructs each geateway to send a packet every 5 seconds. This packet includes timing information telling the badges when they should communicate back to the gateway. The content of these messages is displayed in the MCP output:

 
  {"cid":"*", "duration_in_sec":5.2, "event":"add_transmit_window_to_all_connections", "num_queues":1, "origin":"DataQueue", "payload_len":4, "rid":45057, "time":"2014-09-24 19:46:52"}
  {"cid":1, "duration_in_sec":5.2, "event":"add_transmit_window", "origin":"DataQueue", "time":"2014-09-24 19:46:52"}
  b0010000000488e69316cbed2390e1f92ccd85016af2a55000b61abbf83a6ddf77fdb7b1c175803a163cb68a852fb5ddba9f6129329259fe581b
  b0010000138800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
  {"event":"pause_connection_for_duration", "origin":"MainChannelSender", "pause_until":1411588017.319312, "time":"2014-09-24 19:46:52"}
  

The first 2 bytes of all radio messages indicate the message type, or RID. This is 'b001' for the packets above.

The first signs of communication with the badge

Once you have reached this far the badge network should be sending messages which will be picked up by the badge. Turn on badge, wait for a minute or two and then press up/down button to refresh the display. With any luck the "Welcome" at the top of the screen will be replaced with the current time and some status messages will appear at the bottom of the screen showing a randomly generated gateway ID and the radio signal strength.

Update public key in badge firmware

During one of the earlier steps we generated a random key for the radio messages in this badge network. The default badge firmware only trusts messages signed by the official EMF camp signing key which we don't have. To get any further we need to update the public key in the badge firmware to make it trust the messages from your new MCP.

 cd ~/Mk2-Software/lib
 make keys.c

This will output the information you need to add to the firmware source code:

  # To make your badge trust messages signed by your
  # new key pair you must replace the public key in
  # EMF2014Config.h with:
  
  const uint8_t EMF_PUBLIC_KEY[40] = {
    ... lots of hex numbers ...
  };

Open the EMF2014Config.h from the Mk2-Firmware/EMD2014 sketch. Find and replace the EMF_PUBLIC_KEY with the one that was printed above. Open the arduino IDE, connect your badge to via USB, build & flash the new firmware.

Registering the badge on the network

After you have installed the firmware above the badge will reboot. Wait a few minutes and this time the badge should register itself to the network. The output on the gateway program should show it receiving messages from the badge, beginning "9002...". These messages are the badge requesting a badge ID from the MCP:

 
  2014-09-24 20:08:37,274 - UsbRadios - DEBUG - Packet send via radio 0: 26100
  2014-09-24 20:08:42,274 - UsbRadios - DEBUG - Packet send via radio 0: 26200
  2014-09-24 20:08:47,274 - UsbRadios - DEBUG - Packet send via radio 0: 26300
  2014-09-24 20:08:50,303 - Gateway - DEBUG - Received packet with rssi -42: 0a
  2014-09-24 20:08:52,273 - UsbRadios - DEBUG - Packet send via radio 0: 26400
  2014-09-24 20:08:56,250 - Gateway - DEBUG - Received packet with rssi -42: 90020000203132503834353631343031333030360000000000000000000000000000000000000000000000000000000000000000000000000000
  2014-09-24 20:08:58,274 - UsbRadios - DEBUG - Packet send via radio 0: 26500
  2014-09-24 20:09:01,825 - Gateway - DEBUG - Received packet with rssi -42: 90020000203132503834353631343031333030360000000000000000000000000000000000000000000000000000000000000000000000000000
  2014-09-24 20:09:03,274 - UsbRadios - DEBUG - Packet send via radio 0: 26600
  

The MCP window should show it transmitting the signed response packets starting "b002..."

 
  b002000000268f1f16ee0a4f5fe7dcb4a69bacdc0f4038c87d368dc2527a26fe7f86a232e0804bf10645afe414a90d122d8241e200f464f2d7cf
  b0022031325038343536313430313330303600010000000000000000000000000000000000000000000000000000000000000000000000000000
  

If you now select the BadeID app on your TiLDA then it should now say that it has been assigned badge ID EMF0001.

Setting the name on your badge

Each badge has a unique hardware ID which was programned into the CPU by Atmel. This hardware ID is sent to the MCP when the badge asks it to assign a badge ID. This unique hardware ID ensures that you will get the same badge ID each time you reset the badge. The MCP store this in the 'badge' table in the database:

 
  pi@raspberrypi ~ $ psql schedule
  psql (9.1.13)
  Type "help" for help.
  
  schedule=> select * from badge;
   id |               hwid               | date | gwid 
  ----+----------------------------------+------+------
    1 | 20313250383435363134303133303036 |      |    1
  (1 row)
  
 

The badgeID app mentions registering on a web page but we don't have this available. Instead you can add your name and nickname directly into the database and the MCP will tell your badge to display this name next time it registers. You can personalize the name and nickname however the LCD can only display strings of up to 10 characters. You can put spaces in the front to align the text that is displayed. The EMF0001 badge ID is the one that your badge should have obtained earlier.

 
  schedule=> INSERT INTO "user" VALUES ( 'My Name', 'Nickname', 'EMF0001' );
  INSERT 0 1
  schedule=> \q
  

To make your badge learn this new name you must hit reset and wait for it to acquire its badge ID again, check this in the badge app. Now return to the home screen and hold the badge vertically, like it is hanging on a lanyard, with the two large holes in the PCB at the top. When the EMF logo appears your name should now be shown at the top of the screen.

Using the badge network

Web interface

The MCP software runs a web interface and API on port 8888, point your web browser at:

 http://RPi-IP-Address:8888/index.html

Notification messages

The badges and network have the ability to send a text message to a specific badge, or to all badges. The command below sends a message to all badges and this should appear on your badge after a few seconds delay:

 cd ~/Mk2-Software/emfbroadcaster
 ./flashmsg.py "Hello from my DIY badge network"

Or a message to a specific badge number:

 ./dm.py 1 "message to badge one"

Weather

The weather.py script will send weather updates but you must register for a Met Office API key and place this in the ~/Mk2-Software/etc/secret_config.json file.

Schedule

The schedule.py script broadcasts schedule update to the badge. This requires additional information to be added to an 'event' table in the database. There is currently no documentation on how to do this.

Ideas and areas for improvement

• The badge notification messages include LED and sound fields to make the user aware of the alert but these are not implemented in badge firmware.
• The badge sends a packet on RID 9004 which indicates its battery status. Currently the MCP prints a message saying it received this but does nothing else with it. It might be interesting to log the battery information and RSSI into a file or database as an example of how to collect data from the badges.
• Enhance the EMFTris and Snake apps to tell the MCP about the highscores. Record in a log and create a web page showing the highscores for each badge.
• The current badge architecture was designed around the needs of a large distributed system. In an isolated network it would be nice to have a special mode which works with just a single radio. Or perhaps send the data to the badge via the USB serial so no radio is necessary at all.
• Add a voting app which broadcasts a question to all badges, shows the choices on the screen and uses a button to select. Send the response back to the MCP and display the results on a web page.
• The original Mk2-Software relies on a special radio firmware mode 'ATZD3' which indicates the end of paket boundary and RSSI. This firmware was specially made by Ciseco for EMFCamp and this feature is not present in the standard radios. The forked Mk2-Software has some tweaks to make it work with the standard firmware but this lacks the RSSI information and may not work with multiple badges. It might be possible to use one of the other radio debug modes (ATZD1 or ATZD2) which the public firmware supports to provide the same information as ATZD3.