esb

This is an unofficial implementation of Nordic's Enhanced ShockBurst communication protocol.

Documentation

Usage examples can be found at the demos repository.

Enhanced ShockBurst is a trademark of Nordic Semiconductor ASA.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

lib.rs:

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.

Timing Requirements

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 timeout plus a constant offset of 62 microseconds.

• 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.

Supported devices and crate features

Other devices might be compatible with this implementation, however, at this point, the only tested devices are the ones in the table above.

Ramp-up

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 into account.

In-queue packet representation

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.

The maximum in-queue packet size is 258 bytes (with a 252 bytes payload).

Compatibility with nRF24L01+

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.

Examples

Usage examples can be found at the demos repository.