Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Qwiic RF is a packet radio system that's designed for sending short packets of sensor data from one Qwiic bus to another. Messages sent by one Qwiic RF are cached by the receiving Qwiic RF until they can be retrieved over the Qwiic bus.
It may be useful to think of the Qwiic RF less in terms of a phone call and more in terms of a PO Box. Whenever you perform a .send() or .sendReliable() operation, you're sending a letter to another PO Box. The PO Box can only hold one letter, but you can check it as often as you like. The letter stays in your PO Box until you retrieve it using the .read() operation.
Each Qwiic RF has three important Addresses: RF Address, Sync Word, and Paired Address. The RF Address is a unique one byte identifier which functions as the address of your "PO Box". Each radio can send a message directly to another radio's RF Address or to the Broadcast Address of 0xFF. The Sync Word is essentially a Network ID. Radios with different Sync Words cannot communicate with each other. The Paired Address is the RF Address of another radio which the Qwiic RF will use as the destination address of any packet for which a destination is not explicitly provided.
Each packet that is received using the Qwiic RF has the following construction:
- 1 byte Sequential Packet ID
- 1 byte Origin Address
- 1 byte Destination Address
- 1 byte SNR
- 1 byte RSSI
- 1 byte Reliable Send Indicator / Checksum
- 1 byte Reported Payload Length
- 32 byte (maximum) Payload (type String)
.send() vs .sendReliable()
.send() operations are not reliable, which is to say that there is no proof of receipt. This method is acceptable in systems where you have a known strong link or where redundancy is high enough that dropped packets will not affect operation.
During a .sendReliable() operation a simple checksum is generated from the payload and stored by the sending radio. A flag in the packet header alerts the receiving radio that the sender has requested a receipt. The receiving radio then calculates the checksum and returns it to the sender using a simple .send() operation. The sender will repeat the original message until either the Reliable Send Timer expires or a valid checksum is received.
The Qwiic RF implements a primitive pairing function for convenience. Paired radios agree on a random shared Sync Word and exchange randomly generated RF Addresses. Once two radios are paired, messages can be sent between them by calling the .send() function without an address argument.
In order to pair two radios, you must first connect them to the same Qwiic bus. They must be powered but it is important that the bus is not busy to avoid contention. Press the pairing button on either of the boards and a pairing status LED will turn on to indicate that pairing is underway.
During the pairing operation, the Qwiic RF that initiated the pairing operation randomly generates two RF Addresses and a Sync Word, it then assumes control of the Qwiic bus and scans for other Qwiic RF boards by requesting the contents of a known static register. Once the other Qwiic RF board is found, the initiator sets the RF Address, Sync Word and Pairing Address of its new partner. The pairing operation is over when the pairing status LED turns off. The entire process should take less than 3 seconds.