====== Overview ======

openbeacon readers dump one RF channel/MAC and send them via UDP packets to a central server.

===== Original =====
Original OpenBeacon Readers are nice little black boxes created by milosch with two nRF24L01 and two antenna. (i.e. two receivers in nearly the same position). Problem is: they are expensive, and we currently don't have any.

===== Replacement =====

We sometimes use r0kets as readers. Their sensitivity is worse and they are very directional, but it's good enough to play around with it.

==== Current version ====
bridge firmware flashed on r0ket, packet dump read via USB serial and sent on with a small script.
  * e.g. [[https://github.com/r0ket/r0ket/blob/master/tools/reader/beacon-udp.pl|beacon-udp.pl]]
  * or a compiled version of [[https://github.com/r0ket/r0ket/blob/master/tools/reader/obreader.c|obreader.c]] if perl is too slow

====== packet format ======

The OpenBeacon packets are 16 byte long.
The reader prepends a 16-Byte header before it sends it off to the central server.

**NOTE**: all fields are in "network order" i.e. big endian.

The header looks like this:
| **byte** | **name** | **description** |
| 0x00 | icrc | ccitt16(bytes[0x2:end]) XORd with 0xffff |
| 0x01 | ::: | ::: |
| 0x02 | proto | BEACONLOG_SIGHTING == 1 |
| 0x03 | interface | 0 or 1 on official reader, 0 always in our code |
| 0x04 | readerid | needs to be added to src/bmReaderPositions.h |
| 0x05 | ::: | ::: |
| 0x06 | size | size of the whole packet (usually 32) |
| 0x07 | ::: | ::: |
| 0x08 | ctr | sequence number over all packets |
| 0x09 | ::: | ::: |
| 0x0a | ::: | ::: |
| 0x0b | ::: | ::: |
| 0x0c | time | timestamp in seconds (milosch: since bootup, we: unix time_t) |
| 0x0d | ::: | ::: |
| 0x0e | ::: | ::: |
| 0x0f | ::: | ::: |

this is followed by the raw packet as captured by the rf interface.

For the reference, the openbeacon packet format looks like this:

**NOTE**: we use what milosch calls RFBPROTO_BEACONTRACKER_OLD2 because that's what sputnik and HOPE/AMD used.

| **byte** | **name** | **description** |
| 0x00 | len | length of the packet (usually 16) |
| 0x01 | type | openbeacon (0x17) |
| 0x02 | button | sputnik "button" press. R0ket=0xff which makes openbeacon-tracker output "button=true" |
| 0x03 | strength | 0x00 / 0x55 / 0xaa / 0xff (low to high) rf sending strength used |
| 0x04 | idx | monotonically increading sequence. Original sputnik dies after 0xffffffff |
| 0x05 | ::: | ::: |
| 0x06 | ::: | ::: |
| 0x07 | ::: | ::: |
| 0x08 | beacon | openbeacon id |
| 0x09 | ::: | ::: |
| 0x0a | ::: | ::: |
| 0x0b | ::: | ::: |
| 0x0c | unused | unused fields. r0ket = 0xff 0xff |
| 0x0d | ::: | ::: |
| 0x0e | crc | ccitt16(bytes[0x0-0xd]) |
| 0x0f | ::: | ::: |

We added a new packet types to transmit the nickname:

| **byte** | **name** | **description** |
| 0x00 | len | length of the packet (usually 16) |
| 0x01 | type | 0x23 / 0x24 / 0x25 |
| 0x02 | beacon | openbeacon id |
| 0x03 | ::: | ::: |
| 0x04 | ::: | ::: |
| 0x05 | ::: | ::: |
| 0x06 | string | up to 8 ascii characters, 0-terminated if less |
| ...  | ::: | ::: |
| 0x0d | ::: | ::: |
| 0x0e | crc | ccitt16(bytes[0x0-0xd]) |
| 0x0f | ::: | ::: |
<code>
if (length(nickname)<=8):
  Packet 0x23 is sent with the nickname
else
  Packet 0x24 is sent with nickname[0:7]
  Packet 0x25 is sent with nickname[8:15]
  # longer nicknames get truncated.
fi
</code>

Our reader implementation also send a heartbeat packet every second. This packet has the standard reader header, but the last 16 bytes are just:

| **byte** | **name** | **description** |
| 0x00 | type | RFBPROTO_READER_ANNOUNCE (22)  |
| 0x01 | unused | 0x0 |
| ...  | ::: | ::: |
| 0x0d | ::: | ::: |
| 0x0e | crc | ccitt16(bytes[0x0-0xd]) |
| 0x0f | ::: | ::: |