BLE adaption of netdev. More...

Detailed Description

BLE adaption of netdev.

Warning
This API is experimental and in an early state - expect significant changes!

About

BLE defines a very specific environment for the used radio, both in terms of communication sequences and in terms of timings. BLE communication is structured in so called events, where each event is a sequence of request and reply packets send between two peers. A radio context (frequency, CRC initializer, and access address) is used throughout such an event and typically changed for the next one. In addition, the timing of the packets sent in a sequence is fixed to an inter-frame-spacing of exactly 150us.

To cater with these specific attributes of BLE, this interface tailors the generic netdev interface to be used for BLE radios.

Interface Adaption / Netdev Interpretation

Transmission Sequence Based Approach

To be able to handle the exact inter-packet-spacing if 150us seconds, this interface expects the device driver to stay in a continuous alternating RX-TX sequence, until it is manually aborted. While in this sequence, the radio driver needs to take care of switching to RX mode 150us after sending the last packet, and to send the next packet 150us after the last packet was received.

Such a transmission sequence is started by calling either the radio's send or receive function while the radio is in idle/standby mode.

Once a transmission sequence is in progress, the next packet to be send, or the next reception buffer to be used is specified also using the send/recv functions. They should be called in the event_callback right after the last transmission (RX or TX) was finished.

The transmission sequence is aborted by calling netdev_ble_stop(dev) (netdev->set(dev, NETOPT_BLE_CTX, NULL, 0)). This will put the radio back into idle/standby mode.

Radio Context

As BLE uses time sliced channel hopping, the used channel needs to be set regularly. Additionally, also the used access address and the CRC initializer need to be set regularly, as they differ for different BLE connections. To make setting these values more efficient, this interface combines these three values in to a so called radio context and adds a netopt option to set all three values at once using netdev_ble_set_ctx(dev, ctx) (netdev->set(dev, NETOPT_BLE_CTX, ctx, sizeof(netdev_ble_ctx_t))).

Implementation Status and Limitations

Files

file  ble.h
 BLE specific adaption for the Netdev API.
 

Data Structures

struct  netdev_ble_pkt_t
 BLE packet structure (as defined by the BLE standard) More...
 
struct  netdev_ble_ctx_t
 Radio context. More...
 

Macros

#define NETDEV_BLE_PDU_MAXLEN   (37U)
 Maximum payload length of a standard BLE packet.
 
#define NETDEV_BLE_CRC_MASK   (0x00ffffff)
 Mask for the actual (3 byte) CRC data in the context's CRC field.
 
#define NETDEV_BLE_CRC_OK   (0x80000000)
 Flag for marking a correct CRC on packet reception.
 

Functions

static int netdev_ble_send (netdev_t *dev, netdev_ble_pkt_t *pkt)
 Send the given packet on the next occasion. More...
 
static int netdev_ble_recv (netdev_t *dev, netdev_ble_pkt_t *pkt)
 Start listening for an incoming packet and write it into pkt. More...
 
static void netdev_ble_set_ctx (netdev_t *dev, netdev_ble_ctx_t *ctx)
 Set the radio context for the given radio device. More...
 
static void netdev_ble_stop (netdev_t *dev)
 Stop the ongoing RX/TX sequence. More...
 

Function Documentation

◆ netdev_ble_recv()

static int netdev_ble_recv ( netdev_t dev,
netdev_ble_pkt_t pkt 
)
inlinestatic

Start listening for an incoming packet and write it into pkt.

If a transmission sequence is in progress, the radio will use the given buffer for reception when it goes in to RX mode 150us after sending the last packet. If no sequence is in progress, the radio will go into RX mode immediately (using the given RX buffer), and a new transmission sequence is started.

Note
Call this function only to start a new transmission sequence (radio is currently idle), or right after a packet was sent. If called at any other point in time, the behavior is undefined.
Parameters
[in]devradio to use for receiving
[out]pktbuffer to write new packet to
Returns
0 on success
< 0 on error

Definition at line 166 of file ble.h.

◆ netdev_ble_send()

static int netdev_ble_send ( netdev_t dev,
netdev_ble_pkt_t pkt 
)
inlinestatic

Send the given packet on the next occasion.

If a transmission sequence is in progress, the given packet will be send after 150us after receptions of the last packet. If no sequence is currently active, the packet will be send immediately and a new transmission sequence is started.

Note
Call this function only to start a new transmission sequence (radio is currently idle), or right after a packet was received. If called at any other point in time, the behavior is undefined.
Parameters
[in]devradio to use for sending
[in]pktdata to send
Returns
0 on success
< 0 on error

Definition at line 141 of file ble.h.

◆ netdev_ble_set_ctx()

static void netdev_ble_set_ctx ( netdev_t dev,
netdev_ble_ctx_t ctx 
)
inlinestatic

Set the radio context for the given radio device.

Parameters
[in]devtarget radio device
[in]ctxnew radio context (CRC, channel, access address)

Definition at line 177 of file ble.h.

◆ netdev_ble_stop()

static void netdev_ble_stop ( netdev_t dev)
inlinestatic

Stop the ongoing RX/TX sequence.

Note
This function has not effect if the radio is in the middle of a data transfer
Parameters
[in]devtarget radio device

Definition at line 190 of file ble.h.