Get a tag
The OpenBeacon proximity tag is open hardware. Its design is licensed under Creative Commons Attribution-ShareAlike 4.0, which allows commercial use as long as the origin of the design is credited openly. Anyone may manufacture the tags: the repository holds the schematic and PCB layout as PDF, the Gerber files for board production and the Altium Designer sources, and the bill of materials below lists every part with a supplier part number.
If you would rather not run a production yourself, pre-built tags, the tag programmer and custom variants of the design are available from Bitqan on request. Write to us with the quantity and the use case, and we come back with options.
Development environment
Firmware development is supported on Linux and macOS. You need git,
make and the
Arm GNU Toolchain
(the arm-none-eabi-gcc compiler) on your path, plus the
Segger J-Link software
for flashing. The J-Link probe is part of the
Nordic nRF51-DK
development kit, which connects to the tag through the OpenBeacon
Programmer. On macOS, xcode-select --install provides
git and make.
Cloning the repository and building the Physical Web beacon takes
three commands. The makefiles include a flash target that
writes the firmware to the tag in the programmer:
# get the latest source code
git clone https://github.com/meriac/openbeacon-ng
# change into the Physical Web tag firmware
cd openbeacon-ng/firmware/nRF51/tag-physical-web
# compile and flash the tag through the J-Link probe of the nRF51-DK
make clean flash
The same pattern applies to every firmware directory under
firmware/nRF51: tag-proximity for the
logging tag, tag-ble-beacon, tag-mischief,
tag-accel, tag-power,
tag-sound, and the readers reader-prox,
reader-ble and reader-prox-microbit. The
host tools for the other side of the radio link live under
host: openbeacon-sniffer,
openbeacon-rx, tag-dumper and
openbeacon-power.
Hello World firmware
The Physical Web beacon is the shortest complete OpenBeacon firmware
and the one a stock tag ships with. It advertises a UriBeacon packet
carrying the URL http://get.OpenBeacon.org every 995
milliseconds and blinks the blue LED once every five seconds. The
radio runs on the bare nRF51822 without the vendor's SoftDevice, so
the packet bytes are under your control: change the service data
array and the tag broadcasts your own URL.
#include <openbeacon.h>
/* physical web beacon packet */
static const uint8_t g_beacon_pkt[] = {
/* 0x03: Service List */
3,0x03, 0xD8, 0xFE,
/* 0x16: Service Data - 'http://get.OpenBeacon.org' */
21,0x16, 0xD8, 0xFE, 0x00, 0x20,
PROTO_HTTP,'g','e','t','.','O','p','e','n','B','e','a','c','o','n',DOT_ORG
};
void entry(void)
{
/* set advertisment packet */
radio_advertise(&g_beacon_pkt, sizeof(g_beacon_pkt));
/* run advertisement in background every 995ms */
radio_interval_ms(995);
/* infinite foreground loop */
while(TRUE)
{
/* blink once every five seconds */
timer_wait_ms(5000);
pin_set(CONFIG_LED_PIN);
timer_wait_ms(1);
pin_clear(CONFIG_LED_PIN);
}
}
The three calls do all the work: radio_advertise hands
the packet to the radio driver, radio_interval_ms lets
it repeat in the background, and the foreground loop is free for
anything else, here just the LED. The
tag-physical-web
directory holds the current version, and the accelerometer variant
in tag-accel shows how to read the tag's orientation
and transmit only while it faces forward.
Flashing a tag
Tags are programmed through the OpenBeacon Programmer, a 3D-printed cradle with spring contacts and a USB-to-serial bridge, driven by the J-Link debug probe of the nRF51-DK. You do not need the toolchain for this: the firmware releases contain compiled binaries for every tag and reader variant.
- Connect the programmer to the nRF51-DK with the flat ribbon cable. The red stripe of the cable points towards the USB connector of the programmer, and the cable goes into the pins labelled Debug Out next to the USB connector of the development kit.
-
Connect both boards to your computer with a micro USB cable each
and slide the switch next to the USB connector of the nRF51-DK to
ON.
lsusbon Linux orsystem_profiler SPUSBDataTypeon macOS should list an FTDI device (the programmer) and a Segger device (the kit), and a drive named JLINK appears in your file manager. - Remove the battery from the tag, then place the tag on the golden spring pins inside the round frame of the programmer, battery holder facing down, with the small slit in the tag aligned to the embossment of the frame. Hold it down with the black bracket or gently with a finger.
-
Download and unpack the release archive, pick the firmware for the
job, for example the marker tag firmware for fixed locations or
the log tag firmware for people and objects, and copy the
.binfile onto the JLINK drive. Flashing takes less than a second: the blue LED lights up for two seconds and then resumes blinking. - Insert a fresh CR2032 cell only when the tag is handed out. The LED lights up for two seconds and then blinks every five seconds while the tag runs.
Reading tags
Live sniffing with a BBC micro:bit
The cheapest OpenBeacon reader is a
BBC micro:bit,
which uses the same nRF51822 radio as the tag. Copy
reader-prox-microbit.bin from the release archive onto
the MICROBIT drive; the red LED square lights up five times
after the update and then flickers whenever tag traffic is picked
up. The board shows up as a USB serial port at 115200 baud. It
starts in binary mode for the host software; a short press on
button B switches to human-readable text, button A switches back.
In text mode every sighting is printed as one JSON record. Here the tag 0x4A1A13B5 sees three other tags, with the received signal strength of each, its own orientation, battery voltage and the seconds since its battery was inserted; the reader adds the local time in Unix epoch seconds so logs from different tags can be aligned:
{
"uid": "0x4A1A13B5",
"time_local_s": 1535269163,
"time_remote_s": 567,
"rssi": -82,
"angle": 90,
"voltage": 2.8,
"tx_power": 4,
"sighting": [{
"uid": "0x7EA7D3ED",
"rssi": -63
}, {
"uid": "0x3DCFB9B4",
"rssi": -66
}, {
"uid": "0x1AFF5471",
"rssi": -58
}]
}
The openbeacon-sniffer host tool decodes and decrypts
the binary mode on the computer and prints the same records. A tag
placed in the programmer and running the reader-prox
firmware works the same way.
Offline logs with tag-dumper
A tag running the proximity firmware stores days of sightings in
its 8 MB flash. To read them, put the tag into the programmer with
its battery removed, never with the battery inserted, since that can
damage the reader or the tag. Build and run the
tag-dumper host tool against the programmer's serial
port:
# download the sources
git clone https://github.com/meriac/openbeacon-ng
# change into the tag-dumper host software
cd openbeacon-ng/host/tag-dumper/
# compile it
make
# run it: the '*' expands to the device name of your OpenBeacon Programmer,
# for example /dev/tty.usbserial-AK0535TL on macOS or /dev/ttyUSB0 on Linux
./tag-dumper /dev/tty.usbserial-*
# Received Tag ID=0x4A1A13B5
# Received Tag ID=0x4A1A13B5
# press the tag button for one second to dump the stored data;
# '>>' appends to the log file across several runs
./tag-dumper /dev/tty.usbserial-* >>logfile.json
# Received Tag ID=0x4A1A13B5
# Found new log group[0] at page 0The tool prints the ID of the connected tag once a second. A one second press on the tag's button starts the dump; every stored sighting is one JSON record with the tag's own ID, the seen tag, the local and remote tag times, signal strength and angle:
{
"tag_me": "0x4A1A13B5",
"tag_them": "0x1AFF5471",
"time_local_s": 3027,
"time_remote_s": 3033,
"rssi": -58,
"angle": 90,
"group": 1
}
A tag's clock starts at zero at every battery insertion and the
group number increments each time, so earlier data is
kept but marked. Erase a tag before a deployment by holding its
button for more than three seconds until the LED blinks rapidly;
erasing takes tens of seconds and ends with the tag back in idle
mode. Hand out tags with the batteries inserted just before use, and
you will only ever see group 1.
Support and licenses
Questions, bug reports and pull requests go to the issue tracker of the repository, or by email to contact@bitqan.ae. For networked readers with Ethernet or Wi-Fi, bulk orders or custom hardware based on the OpenBeacon designs, get in touch.
The firmware and the host tools are free software under the GNU General Public License version 2, distributed without any warranty. The hardware design files are licensed under CC BY-SA 4.0. Alternative licenses for closed-source products are available on request from contact@bitqan.ae.
