netdev BLE mode

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

• This interface works for memory mapped radios only (no support for bus-connected devices). This is mainly for timing reasons.
• No support for LE Data Length Extension (bigger packet size), yet

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.
static int	netdev_ble_recv (netdev_t *dev, netdev_ble_pkt_t *pkt)
	Start listening for an incoming packet and write it into pkt.
static void	netdev_ble_set_ctx (netdev_t *dev, netdev_ble_ctx_t *ctx)
	Set the radio context for the given radio device.
static void	netdev_ble_stop (netdev_t *dev)
	Stop the ongoing RX/TX sequence.

Macro Definition Documentation

NETDEV_BLE_CRC_MASK

#define NETDEV_BLE_CRC_MASK   (0x00ffffff)

Mask for the actual (3 byte) CRC data in the context's CRC field.

Definition at line 94 of file ble.h.

NETDEV_BLE_CRC_OK

#define NETDEV_BLE_CRC_OK   (0x80000000)

Flag for marking a correct CRC on packet reception.

Definition at line 99 of file ble.h.

NETDEV_BLE_PDU_MAXLEN

#define NETDEV_BLE_PDU_MAXLEN   (37U)

Maximum payload length of a standard BLE packet.

Definition at line 89 of file ble.h.

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]	dev	radio to use for receiving
[out]	pkt	buffer 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]	dev	radio to use for sending
[in]	pkt	data 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]	dev	target radio device
[in]	ctx	new 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]

dev

target radio device

Definition at line 190 of file ble.h.