Home
The main purpose of this project is to create a standard interface that all the various official and unofficial badges can communicate over at large events. This interface is aimed to be accessible by all classes of processors and is intentionally kept on the low feature side. Due to the short runway for the 2018 conferences I am mainly concentrating on the wired interface option. I do want to expand this spec to include one or more wireless interfaces in the future.
Send any feedback via tweet or direct message to https://twitter.com/wireengineer
The good folks over at QueerCon found a excellent Hermaphroditic Board to Board connector for their 2017 badge.
Decided to pick up the same one for the badge bus wired hardware interface. The reason I like this is the exact same connector can be on each side of the link and it has some miss plug prevention built right in. The connector is a FCI SSL RCPT & BLADE 4POS 3MM PN 10120045-401LF. Digikey stocks them in small quantities under PN 609-5015-1-ND here:
https://www.digikey.com/product-detail/en/amphenol-fci/10120045-401LF/609-5015-1-ND/5731726
There is also a version without the mounting pegs and instead 2 extra solder pads available under FCI PN 10120045-400LF / Digikey PN 609-4673-1-ND here:
https://www.digikey.com/product-detail/en/amphenol-fci/10120045-400LF/609-4673-1-ND/4128733
(Note picture above is of the non peg version 10120045-400LF. Also the non peg version is a slightly more expensive than the peg version of the same connector.)
I have included KiCad physical libraries (under KiCad/pretty/FCI.pretty) for both peg, non peg, and a universal symbol that will take either. For a logical symbol use any standard 4 pin (pins numbered 1 to 4) for the peg version. For the non peg versions use a 6 pin symbol (numbered 1 to 6). Note in this case pins 5 and 6 are the 2 mounting tabs and can be left disconnected. Typically I connect the mounting pads to the ground fill for better mechanical stability and to reduce the chance the pads are ripped off the card. If you are drawing your own symbol I arbitrary set pin one to the left most pin when looking into the connector contacts when mounted on top side of the PCB surface. When 2 connectors are plugged into each other the signals twist as shown:
| Connector 1 | Connector 2 |
|---|---|
| 1 | 4 |
| 2 | 3 |
| 3 | 2 |
| 4 | 1 |
This twist removes the need to have a inbound and outbound port on the badge as TX and RX will be swapped properly when plugged in.
- Pin 1 is the transmit line OUT of the badge. This pin must be driven by a open collector (can drive low or tristate only, never able to drive a high) driver that is 5v tolerant. No other pull up or pull down resistors should be connected to this net.
- Pin 2 is signal ground.
- Pin 3 is signal ground.
- Pin 4 is the receive line IN to the badge. This pin must have a 1k Ohm to 10k Ohm pull up resistor to the IO bank voltage of the receiving buffer. (Most folks this will be the IO voltage of their micro controller.)
The theory of operation here is by using a 5V tolerant open collector driver and a pull up resistor on the receiving end the bus should automatically convert From any IO voltage under 5V to any other IO voltage under 5V. This will allow 1.8V badges to talk to 5V badges and 5V badges to talk to 3.3V badge and so on without having to add a bunch of voltage translators.
The "idle" state of the bus should be set up to be logical high (physical tristate if no other badge is plugged in) at the badge connector.
The default baud rate and connection options are 9600bps 8N1. I am planning on supporting commands to allow badges to negotiate to higher rates. But in the case of a new connection or errors the link should go back to 9600pbs.
If this is not clear or you need help translating from your particular micro drop me a line on twitter.
I am currently looking for opinions on wireless options but they will not be ready for the 2018 season. My current thoughts on requirements is low cost / power device that is available in mass quantity. Some good options out there like the ESP series but at this time we cannot get them in large enough quantities (30k+) reliably to use them in a design. As for protocol open to just about anything. WiFi, BT, LoRa others?
Feel free to toss thoughts out on twitter.
- Master = Badge initiating the transaction. Any badge can be the master it is just used as an identifier of which badge started the transaction by sending the request packet.
- Slave = Badge responding to the transaction request. Any badge can be the slave it is just used as an identifier of which badge received, processed, and responded to a request packet.
Note the LSB(least significant bit, right most) of the left most byte is transmitted first.
These 2 bytes of "U"(0x55) are for synchronizing receivers on micros that support auto baud detection. These must be transmitted but the receiver must NOT check for them. Some devices consume the bytes as part of the baud detection. As such they should be ignored by the start of packet detection code.
These 2 bytes of "B"(0x42) are for start of packet detection. The receiver needs to sit and wait in the idle state until two bytes of "B" are received. At this point it will transition to receiving the packet. NOTE see comments about packet length error handling in the next section about requirements on counting packet bytes before transitioning back to idle.
This byte is a bit field used to communicate status about the packet:
| Bit | Meaning if sent by master | Meaning if sent by the slave |
|---|---|---|
| 0 | Reserved set to 0 | 1 = Packet length too long for slave's buffer (will never work), 0 = ok |
| 1 | Reserved set to 0 | 1 = Packet length too long for current free space in slave's buffer (try again later), 0 = ok |
| 2 | Reserved set to 0 | 1 = checksum was invalid, 0 = ok |
| 3 | Reserved set to 0 | 1 = command not supported, 0 = ok |
| 4 | Reserved set to 0 | 1 = invalid data, 0 = ok |
| 5 | Reserved set to 0 | Reserved set to 0 |
| 6 | Set to 0 to indicate request | Set to 1 to indicate response |
| 7 | 1 = Transmitted checksum is valid, 0 = checksum set to 0x0000 | 1 = Transmitted checksum is valid, 0 = checksum set to 0x0000 |
This is the command requested to be run in the transaction. The response packet must have the same value for the command field as the request packet it is responding to. Note there is NO requirements to support any of these commands the badge maker is free to pick and choose which commands to support. Note any command the slave does not support must be responded to with the "command not supported" bit (3) in the status byte set. See the recommended transaction flows section below for more details.
| Command byte | abbreviation | Meaning |
|---|---|---|
| 0x00 | MID | Makers ID this is a 2 byte packet indicating who the badge was made by. See the Makers IDs page for a list of Makers IDs. => master packet payload of 0 bytes. => slave packet payload of 2 bytes. |
| 0x01 | BID | Badge ID this is a 2 byte packet indicating the model number of the badge. See the Makers IDs page for links to the various makers badge IDs. => master packet payload of 0 bytes. => slave packet payload of 2 bytes. |
| 0x03 | MIDH | Makers ID human readable. This returns a string of up to 255 bytes that is the human readable name of the badge maker. => master packet payload of 0 bytes. => slave packet payload from 0 up to 255 bytes. |
| 0x04 | BIDH | Badge ID human readable. This returns a string of up to 255 bytes that is the human readable name of the badge. => master packet payload of 0 bytes. => slave packet payload from 0 up to 255 bytes. |
| 0x05 | BSN | Badge serial number. This returns a binary value or string of up to 255 bytes that is the unique serial number of the badge. => master packet payload of 0 bytes. => slave packet payload from 0 up to 255 bytes. |
| 0x06 | GCN | Generic control. This command has a single byte of data with undefined meaning. The main use for this command is to allow a badge to control arbitrary functions on another. For example if someone attaches flair to a badge this command can be used by the badge to change the LED mode on the flair. But if that same badge is attached to another badge this command may allow control over a synthesizer. The master badge does not need to know what the bits do it just needs to allow the user to manipulate the bits and send the command. Note if your badge does not have a user interface on it this command does not apply to send. => master packet payload of 1 bytes. => slave packet payload of 0 bytes. |
| 0x07 | GSTS | Generic status. This command should get back a packet with a single byte of data with undefined meaning. The main use for this command is to allow a badge to query a functions status on another. For example if someone attaches flair to a badge this command can be used to read the value of a light sensor. But if that same badge is attached to another badge this command may read back the score out of that badge. The master badge does not need to know what the bits do it just needs to display them to the user. Note if your badge does not have a user interface on it this command does not apply to send. => master packet payload of 1 bytes. => slave packet payload of 0 bytes. |
| 0x08 | GCNH | Generic control human readable description. This command retrieves a string up to 255 bytes that describes what the GCN bits do. => master packet payload of 0 bytes. => slave packet payload from 0 to 255 bytes. |
| 0x09 | GSTSH | Generic status human readable description. This command retrieves a string up to 255 bytes that describes what the GSTS bits mean. => master packet payload of 0 bytes. => slave packet payload from 0 to 255 bytes. |
| 0x0A | ABR | Available baud rates. This command returns a 1 byte packet that is a bit field of supported baud rates of the slave. The bit values MSB to LSB are: N/A, 256000, 128000, 115200, 57600, 38400, 19200, 14400. The master badge uses this list to find the highest common denominator to for baud rate switching. If all bits are clear only 9600 baud is supported. => master packet payload of 0 bytes. => slave packet payload of 1 bytes. |
| 0x0B | SBR | Set baud rate. This command instructs the slave badge to change it's baud rate from the current value (default 9600) to the selected speed. The packet has a single byte of data where the bit values MSB to LSB are: N/A, 256000, 128000, 115200, 57600, 38400, 19200, 14400. If the requested speed is not supported or more than one speed is requested the slave should return a response with "invalid data" bit (4) set. If the requested speed is supported the good response packet with 0 data bytes should be sent back at the original speed and immediately afterwards the baud rate on both ends should change to the new rate. !!NOTE!! if the master does not get back a good response from the slave it MUST not change it's speed. Also both the master and slave MUST monitor the bus for errors (both checksum and serial port) and automatically switch back to the default speed (9600 baud) when they are detected. Overall is is NOT recommended to change bus speeds due to all the possible error conditions when users move from badge to badge. Command was added to maximize flexibility when moving large files like firmware images between badges. Most general communicative should have plenty of bandwidth at 9600 baud. => master packet payload of 1 bytes. => slave packet payload of 0 bytes. |
| 0x0C to 0x7F | Reserved | These command IDs are reserved for future expansion and should not be used for any purpose. |
| 0x80 to 0xFF | BUCs | Badge unique commands. Badge maker are free to use these command IDs for anything they want as long as they conform to the overall packet format. Note since these are free for all commands it is best practice to verify the badge your communicating to is the one you expect via badge (BID) and Makers IDs (MID) before sending and BUCs |
This is the number of data bytes in this packet. Valid values are 0 (no data bytes) to 255 (255 bytes of data). Note if the slave badge is unable to accept the requested data length it MUST keep count of the bytes (but toss them vs store for processing) and then return a response packet with the "Packet length too long for slave's buffer" bit (0) set. If the master badge gets a response packet that is too long it MUST keep count of the bytes (but toss them vs store for processing) but, unlike the slave it does NOT return a status packet.
This is the actual data bytes of the packet. The number of bytes included are dependent on the command sent (see the Command byte above) and MUST match the number specified in the Length byte above.
This is a optional 16 bit CRC checksum using CCITT (0x1D0F seed) CRC 16 poly (X^16+X^12+X^5+1) over the entire frame minus the sync bytes and checksum bytes. If the transmitter does not support calculating CRCs it MUST set the valid checksum bit (7) to 0 in the status byte and transmit 0x0000 for the checksum bytes. If the transmitter can calculate CRCs it must set the valid checksum bit (7) in the status byte and transmit the calculated CRCs for the checksum bytes.
If the receiver cannot calculate CRCs and the valid checksum bit is set it MUST receive the checksum bytes but can assume they are correct and process the packet. If the receiver can calculate CRCs and the valid checksum bit is set it MUST calculate the packet CRCs and toss the packet and send back a response with the "checksum was invalid" bit (2) set if the calculated value does not match the transmitted value. In either case if the valid checksum bit is NOT set the receiver must check the checksum bytes are 0x0000 and toss the packet and send back a response with the "checksum was invalid" bit (2) set if they are any other value.
Sample packets with proper checksums
| packet type | from | packet data |
|---|---|---|
| MID | master | 0x555542428000001C8B |
| MID | slave | TBT |
| BID | master | 0x555542428001002FBA |
| BID | slave | TBT |
| BSN | master | 0x55554242800500E37E |
| BSN | slave | TBT |
The master badge needs to have a mechanism to deal with unresponsive slaves (busy, not connected, or removed mid transmission). This can be accomplished via many methods. For my implementation I am using a simple timeout. My current timeout value is set to 2s as a fully loaded packet with 255 byte payload should only take 1/4 second to transmit at 9600 baud. This timer gets reset on every byte received to cover cases where the connection was broken mid response. When the timer times out the message is purged since it is incomplete and the badge bus engine goes back to idle.
NOTE save image or open it in a new window to zoom in on the detail.
NOTE every outstanding command should have a internal timer. Every time a new valid byte is received all outstanding timers should reset to the max timeout value. If any timer hits 0 that command should be aborted and any partial buffer discarded. This indicates that the slave is not connected, stopped responding, or was disconnected mid transmission. Note any received bytes while in the "Receiver idle" state (before the first "B" is received) do NOT reset the timeouts.
