Rust implementation of Nordic's Enhanced ShockBurst communication protocol
This crate implements the Enhanced ShockBurst protocol with dynamic payload size up to 252 bytes and acknowledgement support.
The communication is performed by two devices in different roles, one acting as the Primary Transmitter (PTX) and a second one acting as the Primary Receiver (PRX). The transaction is always started by the PTX, and bi-directional communication is achieved via acknowledgement packets, where the PRX can embed a payload.
This crate makes use of
bbqueue to handle buffering of packets and
to be able to achieve a zero-copy implementation. For timing requirements, the payload that must
be sent together with an acknowledgement must be pre-buffered. When a packet that demands an
acknowledgement is received in PRX mode the driver will try to dequeue a payload from the
transmit queue to be sent, an acknowledgement with a zero sized payload will be sent if the
transmit queue is empty.
For better communication stability, both the radio and timer interrupts must be top priority, and the driver's methods should be called at the beginning of the interrupt handler. In the current implementation, the data rate is fixed at 2Mbps.
There are three configurable options that directly affect the timing of the communication:
Wait for acknowledgement timeout (us) - Default: 120 microseconds.
- It is used in PTX mode while sending a packet that requested for an acknowledgement. It must be bigger than the Ramp-up time.
Retransmit delay offset (us) - Default: 500 microseconds.
- The delay between the end of a transmission and the start of a retransmission when an
acknowledgement was expected but not received. It must be bigger than the
acknowledgement timeoutplus a constant offset of 62 microseconds.
- The delay between the end of a transmission and the start of a retransmission when an acknowledgement was expected but not received. It must be bigger than the
Number of retransmit attempts - Default: 3 attempts.
- The number of times the driver will retransmit a packet that requires an acknowledgement. After all the attempts are carried out, the driver will drop the packet and proceed to transmit the next one in the queue.
Other devices might be compatible with this implementation, however, at this point, the only tested devices are the ones in the table above.
The radio's hardware requires a time before the start or reception of a transmission. This time
is 140 microseconds in the nRF5 devices. However, nRF52 devices have a Fast Ramp-up feature,
where this time is reduced to 40 microseconds. This feature can be enabled by using the
fast-ru feature of this crate. Care must be taken when using the Fast Ramp-up while
communicating with devices that do not support it, the timing configuration must take this case
This crate uses some bytes of queue space to pass information between the user and the driver. The user must take this into account when choosing the size of the EsbBuffer. Moreover, the characteristics of the underlying BipBuffer must be considered, for more information refer to bbqueue docs.
|Used by bbqueue framed||SW USE||ACTUAL DMA PART|
|frame_size - 1 to 2 bytes||rssi - 1 byte | pipe - 1 byte||length - 1 byte | pid_no_ack - 1 byte | payload - 1 to 252 bytes|
The maximum in-queue packet size is 258 bytes (with a 252 bytes payload).
This implementation is only compatible with nRF24L01+ devices when using a configuration with a maximum packet size no bigger than 32 bytes (inclusive). That is required because the nRF24L01+ only supports payloads up to that size and uses a 6-bits effective payload length that must be configured in the nRF5 radio.
Usage examples can be found at the demos repository.
Type aliases for many constants.
A backing structure for a BBQueue. Can be used to create either a BBQueue or a split Producer/Consumer pair
A builder for an
Crate-wide error type