Open Badge V3.0
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.
- 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
First, you will need to setup the tool-chain for nRF51:
- Install the following packages:
- 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.
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.
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.
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
- 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.
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.
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 | Length | Description |
|---|---|---|
| Field length | 8bit | length of following data in bytes: 9 |
| Advertising data type | 8bit | manufacturer-specific data: 0xFF |
| Company identifier | 16bit | arbitrarily 0xFF00 |
| Battery voltage | 32bit float | value is battery voltage |
| Sync status | 8bit | value 1 if badge has received date/time from server, 0 otherwise |
| Collector status | 8bit | 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 | 8bit | length of following data in bytes: 14 |
| Advertising data type | 8bit | manufacturer-specific data: 0xFF |
| Company identifier | 16bit | arbitrarily 0xFF00 |
| Battery level | 8bit | unsigned; scaled so that voltage = 1V + 0.01V*batteryLevel |
| Status flags | 8bit | bit 0 is sync status, bit 1 is collector status, bit 2 is scanner status |
| Badge ID number | 16bit | configurable ID number, set by default to the CRC16 of the badge MAC address |
| Badge group number | 8bit | configurable group identifier, default 0 |
| Badge MAC address | 6bytes | useful for central devices that do not make peripheral addresses accessible |
The badges use the NRF UART Service (a custom service meant 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. Earlier firmware revisions (pre-scanning) support the following commands: