Add documentation on using the micro:bit as an OpenBeacon USB reader

meriac · Jan 24, 2020 · bf681c3 · bf681c3
1 parent 132dfdd
commit bf681c3
Show file tree

Hide file tree

Showing 7 changed files with 122 additions and 0 deletions.
diff --git a/docs/images/microbit-reader-binary-small.png b/docs/images/microbit-reader-binary-small.png
diff --git a/docs/images/microbit-reader-binary.png b/docs/images/microbit-reader-binary.png
diff --git a/docs/images/microbit-reader-text.png b/docs/images/microbit-reader-text.png
diff --git a/docs/images/microbit.jpg b/docs/images/microbit.jpg
diff --git a/docs/microbit.md b/docs/microbit.md
@@ -0,0 +1,111 @@
+# Turning the BBC micro:bit into an OpenBeacon Reader
+
+
+## Overview
+
+The [BBC micro:bit](https://microbit.org/guide/features/) is a handheld, programmable micro-computer that can be used for all sorts of cool creations, from robots to musical instruments – the possibilities are endless. You can [buy it at most electronis stores](https://microbit.org/resellers/) and at [Amazon](https://www.amazon.com/s?k=micro%3Abit&ref=bl_dp_s_web_0).
+
+In this tutorial we'll show you how to use the micro:bit as an OpenBeacon reader. You can find the [reader-prox-microbit](../firmware/nRF51/reader-prox-microbit) firmware sources in our github repository. We published a precompiled binary firmware image of reader-prox-microbit to turn your micro:bit into an OpenBeacon USB reader. 
+
+
+## Install Firmware
+
+We provide the [latest precompiled firmware release](../../../releases) in our GitHub repository. Please download the zip file, unpack on your local computer and choose the reader-prox-microbit.bin firmware. Please connect the micro:bit to your computer using a micro USB cable.
+
+Drag & drop the reader-prox-microbit firmware file onto your external device “MICROBIT” within your file manager or finder. The board automatically starts updating the firmware of the main CPU. The process takes less than a second. The red LED square on the board light up five time to indicate a successful boot and resumes fast blinking afterwards in case of picking up traffic by OpenBeacon tags in proximity.
+
+![Image of micro:bit PCB](images/microbit.jpg)
+
+
+## Using the micro:bit OpenBeacon USB Reader
+
+For each blink the received data is sent of over USB serial to the host PC. To see the data you need to connect to the USB serial port created by the micro:bit PCB at 115200 Baud transmission speed (Baudrate). The micro:bit starts in compatibility mode and show the received data in binary mode only:
+
+![Image of micro:bit PCB](images/microbit-reader-binary-small.png)
+
+By pressing "Button B" briefly, the device can be switched to human readable text mode:
+
+![Image of micro:bit PCB](images/microbit-reader-text.png)
+
+By pressing "Button A" briefly, the device can be switched back to binary mode.
+
+For every tag in range of the reader, one line of the data below is printed. You can see below, that the 
+tag with ID 0x4A1A13B5 is in very close proximity to three other tags with the IDs 0x7EA7D3ED, 0x3DCFB9B4
+and 0x1AFF5471. The reader picks up the reporting tag at -82dBm. Additionally  for each of the tags in
+sight of the reporting tag, RSSI-values are reported as well (-63dBm, -66dBm, 58dBm).
+
+The tag also reports its angle, battery voltage and its internal time stamp **time_remote_s**
+(seconds after battery insertion). The key here is the **time_local_s** field - which represents the time
+in seconds receiving this sighting ince starting the micro:bit.
+
+#### Example Output
+```JSON
+{
+	"uid": "0x4A1A13B5",
+	"time_local_s": 1535269163,
+	"time_remote_s": 567,
+	"rssi": -82,
+	"angle": 90,
+	"voltage": 28,
+	"tx_power": 4,
+	"sighting": [{
+		"uid": "0x7EA7D3ED",
+		"rssi": -63
+	}, {
+		"uid": "0x3DCFB9B4",
+		"rssi": -66
+	}, {
+		"uid": "0x1AFF5471",
+		"rssi": -58
+	}]
+}
+```
+
+## Using openbeacon-sniffer host software with the micro:bit
+
+Below you can find a quick example on how to extract live tag data on an Apple MacBook. In case you see errors trying running the commands ```git``` or ```make``` below, you might have to install them first by running ```xcode-select --install```.
+
+> Please note that the software expects the tag to be in its default mode - the binary mode. The packet decryption and decoding is happening in the host software.
+
+For every tag in range of the reader, one line of the data below is printed. You can see below, that the 
+tag with ID 0x4A1A13B5 is in very close proximity to three other tags with the IDs 0x7EA7D3ED, 0x3DCFB9B4
+and 0x1AFF5471. The reader picks up the reporting tag at -82dBm. Additionally  for each of the tags in
+sight of the reporting tag, RSSI-values are reported as well (-63dBm, -66dBm, 58dBm).
+
+The tag also reports its angle, battery voltage and its internal time stamp **time_remote_s**
+(seconds after battery insertion). The key here is the **time_local_s** field - which represents the time
+receiving this sighting at the host in seconds.
+The time unit for the local time is [Unix Epoch Time](https://www.epochconverter.com/) - which is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT).
+By combining the local time and the remote tags time, the log files for each tag can be converted into the common local time.
+
+#### Example Usage
+```bash
+# Download Sources
+git clone https://github.com/meriac/openbeacon-ng
+# Change into the openbeacon-sniffer host software directory
+cd openbeacon-ng/host/openbeacon-sniffer/
+
+# Compile software
+make
+# gcc -O3 -W -Wall -Werror -I.  -D_THREAD_SAFE -D_REENTRANT  -c -o openbeacon_sniffer.o openbeacon_sniffer.c
+# gcc -O3 -W -Wall -Werror -I.  -D_THREAD_SAFE -D_REENTRANT  -c -o crypto.o crypto.c
+# gcc -O3 -W -Wall -Werror -I.  -D_THREAD_SAFE -D_REENTRANT openbeacon_sniffer.o crypto.o -o openbeacon_sniffer
+
+# Run software - note that the '*' is automatically expanded to the device name of your
+# OpenBeacon programmer. Each had a different name - mine is for example /dev/tty.usbserial-AK0535TL
+# The last (and optional) parameter is the optional baud rate setting - in our case 115200 Baud.
+./openbeacon_sniffer /dev/tty.usbserial-* 115200
+#  opening /dev/ttyACM0 @ 115200 Baud
+#  { "uid":"0x4A1A13B5", "time_local_s":1535276483, "time_remote_s":     382, "rssi":-84, "angle": 90, "voltage":2.7, "tx_power":4}
+#  { "uid":"0x1AFF5471", "time_local_s":1535276484, "time_remote_s":    7894, "rssi":-71, "angle": 90, "voltage":2.8, "tx_power":4}
+#  { "uid":"0x7EA7D3ED", "time_local_s":1535276484, "time_remote_s":    7897, "rssi":-78, "angle": 90, "voltage":2.8, "tx_power":4, "sighting": [{"uid":"0x4A1A13B5","rssi":-66},{"uid":"0x1AFF5471","rssi":-57}]}
+#  { "uid":"0x4A1A13B5", "time_local_s":1535276484, "time_remote_s":     383, "rssi":-83, "angle": 90, "voltage":2.8, "tx_power":4}
+#  { "uid":"0x7EA7D3ED", "time_local_s":1535276484, "time_remote_s":    7898, "rssi":-82, "angle": 90, "voltage":2.8, "tx_power":4}
+#  { "uid":"0x1AFF5471", "time_local_s":1535276485, "time_remote_s":    7895, "rssi":-74, "angle": 90, "voltage":2.8, "tx_power":4, "sighting": [{"uid":"0x4A1
+```
+For writing the collected tag data into a file, you simply redirect into a log file:
+```bash
+./openbeacon_sniffer /dev/tty.usbserial-* 115200 >>logfile.json
+```
+Please note that '>>' keeps on appending to **logfile.json** when you run openbeacon_sniffer multiple
+times. This way you can combine data from multiple runs in case you have to replaunch openbeacon_sniffer.
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,5 +1,11 @@
+
 # QuickStart for OpenBeacon Tracking
 
+
+## Turning the BBC micro:bit into an OpenBeacon Reader
+
+See documentation on [Turning the BBC micro:bit into an OpenBeacon Reader](microbit.md) for live sniffing of OpenBeacon sightings. For using the [OpenBeacon Programmer](https://www.openbeacon.org/device.html) instead for offline data data dumping and for live OpenBeacon monotoring, see the documentation below.
+
 ## Offline Logging
 
 When using the [Proximity Tag](../firmware/nRF51/tag-proximity) firmware,
@@ -78,8 +84,11 @@ For erasing the tag, you need to press the button on the tag for more than 3 sec
 starts blinking very quickly. Erasing the tag takes 10's of seconds. Once the erasing stopped,
 the tag will go back into idle mode.
 
+
 ## Live Wireless Sniffing of OpenBeacon Tags
 
+> See latest documentation on [Turning the BBC micro:bit into an OpenBeacon Reader](microbit.md) for live sniffing of OpenBeacon sightings.
+
 The same hardware as used can be used to observe tags in operation. By using the [reader-prox](../firmware/nRF51/reader-prox) firmware and the [openbeacon-sniffer](../host/openbeacon-sniffer) software, a tag sitting
 in the [OpenBeacon Programmer](https://www.openbeacon.org/device.html) sniffs and decodes tag
 transmissions off the air.

diff --git a/readme.md b/readme.md
@@ -10,6 +10,8 @@ The proximity feature additionally allows to resolve human contacts by sending d
 
 On this page you can find the OpenBeacon proximity tag [hardware design](https://github.com/meriac/openbeacon-ng/tree/master/hardware) and the [firmware source code](https://github.com/meriac/openbeacon-ng). You can find more information here:
 
+- See documentation on [Turning the BBC micro:bit into an OpenBeacon Reader](docs/microbit.md) for live sniffing of OpenBeacon sightings.
+
 - [QuickStart for OpenBeacon Tracking](docs/quickstart.md) - this covers serial logging only. For networked live logging, please [contact us](mailto:info@bitmanufactory.com) for more information on our Linux-based network readers (Wifi & Ethernet).
 
 - [Updating your tag firmware](docs/firmware-update.md) - download our latest compiled firmware and update your tags to the latest features.