Open Badge V3.0

Intro

This is the second release of the Open Badge as an Open Source project. In this version, we used an nRF51 module and wrote the code in C using SoftDevice stack (instead of RFduino and Arduino). This allows us better flexibility and gives us access to more features, such as scanning for other devices within range.

Directories

eagle/nRF_badge - PCB schematics and layout files in CadSoft EAGLE format
firmware/nRF_badge - Firmware. Arduino code
src/nRF_server - server/base station code

Compiling the firmware

First, you will need to setup the tool-chain for nRF51:

Install the following packages:
- nRF51 SDK for linux, version 8.X (others versions might not work). Can be found here. Install under /opt/nrf51sdk
- JLink Software and documentation pack. Can be found here
- GCC-arm-embedded. Can be found here. Place under /opt/gcc-arm-none-
Set NRF_SDK_PATH in you .cshrc, .bashrc or .zshrc. by adding: export NRF_SDK_PATH=/opt/nrf51sdk
Set GNU_INSTALL_ROOT in /opt/nrf51sdk/components/toolchain/gcc/Makefile.posix to point to the location GCC-arm (e.g. /opt/gcc-arm-none-<version>/)
Add JLinkExe to your shell path. For example ln -s /opt/JLink/JLinkExe /usr/bin/JLinkExe
Some more information can be found in this tutorial - http://www.funwithelectronics.com/?id=168

Next, go to the firmware folder (e.g. firmware/nRF_badge/data_collector). Here, you can find a Makefile that can be used for compiling the code and running various badge-related actions. Each command receives a board/option and an action (or actions): make <board> <action(s)> .

Available board definitions:

badge_03v4 - compiles the code for the latest layout
badge_03v4_noDebug - same as above, with debugging features turned off (no UART message). Useful for production
badge_03v4_tester - compiles a tester code for the badge. Useful for testing new badges

Actions:

flashUnlock - set flags required to enable erasing/programming of flash (only required for brand new NRF51 chips)
flashErase - erase all flash (including softdevice)
flashS130 - flash S130 (BLE simultaneous central/peripheral) softdevice"
flashAPP - flash the badge firmware (after the softdevice)

For example, make badge_03v4_noDebug flashUnlock flashErase flashS130 flashAPP will compile production code, unlock the badge, erase existing code, and then load SoftDevice 130 and the badge code.

Note - there are additional make commands, most of them are relevant only for earlier revisions of this badge.

Building a programmer

In order to load the code to the badge, you will need a programmer.

What you'll need:

Nordic's nRF51 Development Kit, NRF51-DK. This development kit has a Segger J-link that can be used for programming
Micro-USB cable, for connecting the NRF51-DK to your computer
Custom adapter. A custom adapter is requirded for connecting the programmer to the programming pins. Eagle schematics for this adapter can be found here. You can either order
16 x long male headers, 2.54mm spacing (0.1")
8 x female headers, 2.54mm spacing (0.1")
2x3 header
Optional - Sparkfun ISP Pogo Adapter and a 6-pin cable. Alternatively, solder female programming headers to the bottom of the badge and connect it directly to the programmer

After you fabricate the adapter, add the programming headers as shown in these images:

When using the programmer, make sure to align the programming pins correctly.

Badge Server

Background

Once you finish programming all of your badges, you can use the badge server to initialize the badges and periodically pull data. For this version of the badges, we use a Python-based server to perform these operations. The code was tested mainly on Ubuntu (14.04) and Raspbian.

Every time a badge is turned on, it will wait for a server to connect and send the current time so it can initialize the badge's internal clock.

installation

Install dependencies:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get -y install libdbus-1-dev libdbus-glib-1-dev libglib2.0-dev libical-dev libreadline-dev libudev-dev libusb-dev make

Download and install BlueZ version 5.29 or higher:

wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.37.tar.xz
tar xf bluez-5.37.tar.xz
cd bluez-5.37
mkdir release
./configure --disable-systemd
make -j4
sudo make install

Then you need to establish a new Python Virtualenv

cd Place/Where/You/Store/Envs/
virtualenv env
source env/bin/activate

Finally clone the project and install the requirements

git clone https:/HumanDynamics/OpenBadge.git
cd OpenBadge
sudo pip install -r requirements.txt

Usage

Go to the Badge server library: src/nRF_server
Create a file called "device_macs.txt", and enter the MAC addresses of your badges. The format for this file is . Please use the following format for the MAC address: AA:BB:CC:DD:EE:FF
Start the server: sudo ./badge_server.py pull

The pull command continuously scans for badge within range, sends date for uninitialized badges, and pulls data when available.

Data and data format

The badge server stores the data received from each badge in a separate file (each file name is based on the MAC address). Data is stored in CSV format with the following structure:

datetime,voltage,sample length,array of samples

datetime is in YYYY-MM-DD HH24:MI:SS.fff format. For example: 2016-03-04 12:53:30.250, where 250 is the number of milliseconds
voltage is the voltage of the battery at the time the sample was taken. When the voltage drops below 2.2V data might be noisy
Sample length is the time, in milliseconds, that each sample represents (or time between samples). This is typically set to 50ms
Samples array is an array of bytes, each represents one sample. The spacing between samples always equals sample length

Depending on the version of the firmware you are using, there may be duplicates in the data - data are sent in "chunks", with each chunk holding up to 114 bytes. We allow partial chunks to be sent, and therefore the same chunk maybe be sent several times - sometimes as a partial chunk, and later as a full chunk.

Badge Broadcast Data and Communication Protocol

The following specifications use these abbreviations for data type/width:

type	definition
(u)char	(un)signed 8bit
(u)short	(un)signed 16bit
(u)long	(un)signed 32bit
float	32bit float

(Data is little-endian. Brackets indicate an array)

Name and Custom Advertising Data

Within the broadcast packet, the badge advertises with the name "BADGE" or "HDBDG", and includes useful status information in the manufacturer-specific data field.

Earlier revisions of the badge firmware (before scan implementation) sent the following structure as the manufacturer data field, little-endian:

Item	Type	Description
Field length	uchar	length of following data in bytes: 9
Advertising data type	uchar	manufacturer-specific data: 0xFF
Company identifier	ushort	arbitrarily 0xFF00
Battery voltage	float	value is battery voltage
Sync status	uchar	value 1 if badge has received date/time from server, 0 otherwise
Collector status	uchar	value 1 if badge is collecting microphone data, 0 otherwise

Later firmware revisions condensed the existing data, and included additional information, as follows (also little-endian):

Item	Type	Description
Field length	uchar	length of following data in bytes: 14
Advertising data type	uchar	manufacturer-specific data: 0xFF
Company identifier	ushort	arbitrarily 0xFF00
Battery level	uchar	unsigned; scaled so that voltage = 1V + 0.01V*batteryLevel
Status flags	uchar	bit 0 is sync status, bit 1 is collector status, bit 2 is scanner status
Badge ID number	ushort	configurable ID number, set by default to the CRC16 of the badge MAC address
Badge group number	uchar	configurable group identifier, default 0
Badge MAC address	uchar[6]	useful for central devices that do not make peripheral addresses accessible

Badge Communication Protocol

The badges use the NRF UART Service (a custom service to emulate a UART interface) to transfer data to a central device. The central device sends a command along with relevant parameters, and the badge responds appropriately.

Pre-scanning firmware

Earlier firmware revisions support the following commands:

Status request: get badge information (battery level, sync status, etc), and sync badge time
Start recording: start collecting microphone readings
Stop recording: stop collecting microphone readings
Request microphone data: get microphone data since specified time
Identify: light an LED for a specified amount of time

Command	Server sends	Badge responds
Status request	's' (uchar) timestamp:(ulong) milliseconds (ushort)	clock status (uchar) data status (uchar) collector status (uchar) timestamp¹ (ulong) ms¹ (ushort) battery voltage (float)
Start recording	'1' (uchar) timestamp¹ (ulong) milliseconds¹ (ushort) timeout² (ushort)	timestamp (ulong) ms (ushort)
Stop recording	'0' (uchar)	none
Request mic data	'r' (uchar) timestamp (ulong) milliseconds (ushort)	chunks of data (see below)
Identify	'i' (uchar) timeout³ (ushort)	none (lights LED)
¹The badge responds with its previous internal time (0 if unsynced) before syncing itself with the timestamp received from the server.
²The badge will stop collecting microphone data a specified number of minutes after it last received a command from the server. 0 for no timeout.
³Number of seconds to light LED. 0 to turn off LED.

The badge sends the server chunks of microphone data consisting of a header packet:

timestamp (ulong)
ms (ushort)
battery voltage (float)
sample period in ms (ushort)
number of samples in chunk (uchar)

followed by an array of data samples (uchar), in packets of up to 20bytes.

The last chunk of data is followed by a null header (comprised of zeroes) to mark the end of transmission.

Scanning firmware

Later firmware revisions include additional commands related to scanning functionality, and slightly modify the status command response.

Status request: get badge information (battery level, sync status, etc), and sync badge time
Start recording: start collecting microphone readings
Stop recording: stop collecting microphone readings
Start recording: start performing scans
Stop recording: stop performing scans
Request microphone data: get microphone data since specified time
Request scan data: get scan data since specified time
Identify: light an LED for a specified amount of time

Command	Server sends	Badge responds
Status request	's' (uchar) timestamp:(ulong) milliseconds (ushort)	clock status (uchar) collector status (uchar) scanner status (uchar) timestamp¹ (ulong) ms¹ (ushort) battery voltage (float)
Start recording	'1' (uchar) timestamp¹ (ulong) milliseconds¹ (ushort) timeout² (ushort)	timestamp (ulong) ms (ushort)
Stop recording	'0' (uchar)	none
Start scanning	'p' (uchar) timestamp¹ (ulong) milliseconds¹ (ushort) timeout² (ushort) window⁴ (ushort) interval⁴ (ushort) duration⁴ (ushort) period⁴ (ushort)	timestamp (ulong) ms (ushort)
Stop scanning	'q' (uchar)	none
Request mic data	'r' (uchar) timestamp (ulong) milliseconds (ushort)	chunks of mic data (see below)
Request scan data	'b' (uchar) timestamp (ulong)	scan results (see below)
Identify	'i' (uchar) timeout³ (ushort)	none (lights LED)
¹The badge responds with its previous internal time (0 if unsynced) before syncing itself with the timestamp received from the server.
²The badge will stop collecting microphone/scan data a specified number of minutes after it last received a command from the server. 0 for no timeout.
³Number of seconds to light LED. 0 to turn off LED.
⁴Scan timing parameters. 0 for default. "Window" and "Interval" set the duty cycle of the radio during a scan: the radio is active for [window] milliseconds every [interval] milliseconds. "Duration" sets the duration of a scan in seconds (known as "timeout" in the Nordic API) and "Period" sets how often the badge performs a scan, in seconds.