Type responsible for radio I/O and timing. More...

#include <bluetoe/link_layer/scheduled_radio.hpp>

Inheritance diagram for bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >:

Public Member Functions
	scheduled_radio ()

void	schedule_advertisment (unsigned channel, const bluetoe::link_layer::write_buffer &advertising_data, const bluetoe::link_layer::write_buffer &response_data, bluetoe::link_layer::delta_time when, const bluetoe::link_layer::read_buffer &receive)
	schedules for transmission of advertising data and starts to receive 150µs later

bluetoe::link_layer::delta_time	schedule_connection_event (unsigned channel, bluetoe::link_layer::delta_time start_receive, bluetoe::link_layer::delta_time end_receive, bluetoe::link_layer::delta_time connection_interval)
	schedules a connection event

std::pair< bool, bluetoe::link_layer::delta_time >	disarm_connection_event ()
	tries to stop a scheduled connection event

bool	schedule_synchronized_user_timer (bluetoe::link_layer::delta_time timeout, bluetoe::link_layer::delta_time max_cb_runtime)
	sets up a timer

bool	cancel_synchronized_user_timer ()
	cancel the user timer

void	set_access_address_and_crc_init (std::uint32_t access_address, std::uint32_t crc_init)
	set the access address initial CRC value for transmitted and received PDU

std::uint32_t	static_random_address_seed () const
	function to return a device specific value that is persistent and unique for the device (CPU id or such)

void	run ()
	allocates the CPU to the scheduled_radio

void	wake_up ()
	forces the run() function to return at least once

void	request_event_cancelation ()
	forces the call of CallBack::try_event_cancelation() from the context of the run() function

bool	radio_add_to_white_list (const device_address &addr)
	add the given address to the white list.

bool	radio_remove_from_white_list (const device_address &addr)
	remove the given address from the white list

bool	radio_is_in_white_list (const device_address &addr) const
	returns true, if the given address in within the white list

std::size_t	radio_white_list_free_size () const
	returns the number of addresses that could be added to the white list before add_to_white_list() would return false.

void	radio_clear_white_list ()
	remove all entries from the white list

void	connection_request_filter (bool b)
	Accept connection requests only from devices within the white list.

bool	connection_request_filter () const
	current value of the property.

void	radio_scan_request_filter (bool b)
	Accept scan requests only from devices within the white list.

bool	radio_scan_request_filter () const
	current value of the property.

bool	radio_is_connection_request_in_filter (const device_address &addr) const
	returns true, if a connection request from the given address should be answered.

bool	radio_is_scan_request_in_filter (const device_address &addr) const
	returns true, if a scan request from the given address should be answered.

void	radio_set_phy (details::phy_ll_encoding receiving_encoding, details::phy_ll_encoding transmiting_c_encoding)
	change the used PHY encoding for the transmitting and receiving side

Public Member Functions inherited from bluetoe::link_layer::ll_data_pdu_buffer< TransmitSize, ReceiveSize, scheduled_radio< TransmitSize, ReceiveSize, CallBack > >
	ll_data_pdu_buffer ()

constexpr std::size_t	max_max_rx_size () const
	returns the maximum value that can be used as maximum receive size.

std::size_t	max_rx_size () const
	the current maximum receive size

void	max_rx_size (std::size_t max_size)
	set the maximum receive size

constexpr std::size_t	max_max_tx_size () const
	returns the maximum value that can be used as maximum receive size.

std::size_t	max_tx_size () const
	the current maximum transmit size

void	max_tx_size (std::size_t max_size)
	set the maximum transmit size

std::uint8_t *	raw_pdu_buffer ()
	returns the underlying raw buffer with a size of at least ll_data_pdu_buffer::size

void	stop_pdu_buffer ()
	places the buffer in stopped mode.

void	reset_pdu_buffer ()
	places the buffer in running mode.

read_buffer	allocate_transmit_buffer (std::size_t size)
	allocates a certain amount of memory to place a PDU to be transmitted .

read_buffer	allocate_transmit_buffer ()
	calls allocate_transmit_buffer( max_tx_size() + layout_overhead );

void	commit_transmit_buffer (read_buffer)
	indicates that prior allocated memory is now ready for transmission

bool	pending_outgoing_data_available () const
	returns true, if there is pending, outgoing data

write_buffer	next_received () const
	returns the oldest PDU out of the receive buffer.

void	free_received ()
	removes the oldest PDU from the receive buffer.

Static Public Attributes
static constexpr std::size_t	radio_maximum_white_list_entries = 4
	giving the maximum number of white list entries, the scheduled radio supports by hardware

static constexpr std::size_t	radio_package_overhead = 0
	a number of bytes that are additional required by the hardware to handle an over the air package/PDU.

static constexpr bool	hardware_supports_encryption = false
	indication no support for encryption

static constexpr bool	hardware_supports_2mbit = true
	indicates support for 2Mbit

static constexpr bool	hardware_supports_synchronized_user_timer = true
	indicates support for schedule_synchronized_user_timer()

Static Public Attributes inherited from bluetoe::link_layer::ll_data_pdu_buffer< TransmitSize, ReceiveSize, scheduled_radio< TransmitSize, ReceiveSize, CallBack > >
static constexpr std::size_t	size
	the size of memory in bytes that are return by raw()

static constexpr std::size_t	min_buffer_size
	the minimum size an element in the buffer can have (header size + payload size).

static constexpr std::size_t	max_buffer_size
	the maximum size an element in the buffer can have (header size + payload size).

static constexpr std::size_t	header_size
	16 bit header size of a link layer PDU

static constexpr std::size_t	layout_overhead
	addition layout overhead introduced by the applied layout

Additional Inherited Members
Public Types inherited from bluetoe::link_layer::ll_data_pdu_buffer< TransmitSize, ReceiveSize, scheduled_radio< TransmitSize, ReceiveSize, CallBack > >
using	layout = typename pdu_layout_by_radio< scheduled_radio< TransmitSize, ReceiveSize, CallBack > >::pdu_layout
	layout to be applied to each PDU.

Protected Member Functions inherited from bluetoe::link_layer::ll_data_pdu_buffer< TransmitSize, ReceiveSize, scheduled_radio< TransmitSize, ReceiveSize, CallBack > >
read_buffer	allocate_receive_buffer () const
	allocates a buffer for the next PDU to be received.

write_buffer	received (read_buffer)
	This function will be called by the scheduled radio when a PDU was received without error.

write_buffer	acknowledge (read_buffer)
	This function will be called, instead of received(), when the CRC of a received PDU is ok, but the MIC is not ok.

write_buffer	next_transmit ()
	returns the next PDU to be transmitted

Detailed Description

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack>
class bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >

Type responsible for radio I/O and timing.

The API provides a set of scheduling functions, to schedule advertising or to schedule connection events. All scheduling functions take a point in time to switch on the receiver / transmitter and to transmit and to receive. This points are defined as relative offsets to a previous point in time T0. The first T0 is defined by the return of the constructor. After that, every scheduling function have to define what the next T0 is, that the next functions relative point in time, is based on.

TransmitSize and ReceiveSize is the size of buffer used for receiving and transmitting. This might not make sense for all implementations.

Constructor & Destructor Documentation

◆ scheduled_radio()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::scheduled_radio ( )

initializes the hardware and defines the first time point as anker for the next call to a scheduling function.

Member Function Documentation

◆ connection_request_filter()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::connection_request_filter ( bool b )

Accept connection requests only from devices within the white list.

If the property is set to true, only connection requests from from devices that are in the white list, should be answered. If the property is set to false, all connection requests should be answered.

The default value of the is property is false.

Postcondition: connection_request_filter() == b

See also: connection_request_filter()

◆ disarm_connection_event()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

std::pair< bool, bluetoe::link_layer::delta_time > bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::disarm_connection_event ( )

tries to stop a scheduled connection event

The function tries to stop the scheduled connection event if it is not already running, already in the past or too close to happen to be canceled.

If the function was able to stop the connection event, it will return true and the current time from the last anchor plus some margin that is used by schedule_connection_event() to make sure, that the connection event can be setup before reaching the start time.

The support for this function is optional. If a scheduled_radio implementation does not implement this function, there will be no support for the peripheral latency option: peripheral_latency::listen_if_pending_transmit_data

◆ radio_add_to_white_list()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

bool bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::radio_add_to_white_list ( const device_address & addr )

add the given address to the white list.

Function will return true, if it was possible to add the address to the white list or if the address was already in the white list. If there was not enough room to add the address to the white list, the function returns false.

◆ radio_remove_from_white_list()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

bool bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::radio_remove_from_white_list ( const device_address & addr )

remove the given address from the white list

The function returns true, if the address was in the list.

Postcondition: addr is not in the white list.

◆ radio_scan_request_filter()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::radio_scan_request_filter ( bool b )

Accept scan requests only from devices within the white list.

If the property is set to true, only scan requests from from devices that are in the white list, should be answered. If the property is set to false, all scan requests should be answered.

Postcondition: radio_scan_request_filter() == b

See also: radio_scan_request_filter()

◆ request_event_cancelation()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::request_event_cancelation ( )

forces the call of CallBack::try_event_cancelation() from the context of the run() function

The function queues the request until control is passed back to run().

The function is intended to be used from interrupt handler to synchronize with the main thread.

◆ run()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::run ( )

allocates the CPU to the scheduled_radio

All callbacks given by the CallBack parameter are called from within this CPU context. The function will return from time to time, when an external event happed. It's up to concrete implementations to identify and to define situations where the CPU should be released back to the calling application.

◆ schedule_advertisment()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::schedule_advertisment	(	unsigned	channel,
		const bluetoe::link_layer::write_buffer &	advertising_data,
		const bluetoe::link_layer::write_buffer &	response_data,
		bluetoe::link_layer::delta_time	when,
		const bluetoe::link_layer::read_buffer &	receive
	)

schedules for transmission of advertising data and starts to receive 150µs later

The function will return immediately. Depending on whether a response is received or the receiving times out, CallBack::adv_received() or CallBack::adv_timeout() is called. In both cases, every following call to a scheduling function is based on the time, the transmission was scheduled. So the new T0 = T0 + when. In case of a CRC error, CallBack::adv_timeout() will be called immediately.

White list filtering is applied by calling CallBack::is_scan_request_in_filter().

This function is intended to be used for sending advertising PDUs.

Parameters

channel	channel to transmit and to receive on
advertising_data	the advertising data to be send out.
response_data	the response data used to reply to a scan request, in case the request was in the white list.
when	point in time, when the first bit of data should be started to be transmitted
receive	buffer where the radio will copy the received data, before calling Callback::adv_receive(). This buffer have to have at least room for two bytes.

◆ schedule_connection_event()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

bluetoe::link_layer::delta_time bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::schedule_connection_event	(	unsigned	channel,
		bluetoe::link_layer::delta_time	start_receive,
		bluetoe::link_layer::delta_time	end_receive,
		bluetoe::link_layer::delta_time	connection_interval
	)

schedules a connection event

The function will return immediately and schedule the receiver to start at start_receive.

CallBack::timeout() is called when between start_receive and end_receive no valid pdu is received. The new T0 is then the old T0.

CallBack::end_event(connection_event_event evts) is called when the connection event is over. The evts object passed to the end_event() callback will give some details about what happend in that connection event. The new T0 is the time point where the first PDU was received from the central.

In any case is one (and only one) of the callbacks called (timeout(), end_event()), unless the connection event is disarmed prior, by a call to disarm_connection_event(). The context of the callback call is run().

Data to be transmitted and received is passed by the inherited ll_data_pdu_buffer.

Returns: the distance from now to start_receive. If the scheduled event is already in the past, the function will return delta_time() and the timeout() callback will be called.

◆ schedule_synchronized_user_timer()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

bool bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::schedule_synchronized_user_timer	(	bluetoe::link_layer::delta_time	timeout,
		bluetoe::link_layer::delta_time	max_cb_runtime
	)

sets up a timer

The timeout is based on the connects last anchor. Which then means, that there has to be a connection and that the anchor will not move, if there was a timeout while waiting for the next connection event.

Calls CallBack::user_timer( bool anchor_moved ) from an unspecified CPU context. anchor_moved is set to true, if the anchor moved inbetween setting up the timer and the timer callback beeing called.

◆ set_access_address_and_crc_init()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::set_access_address_and_crc_init	(	std::uint32_t	access_address,
		std::uint32_t	crc_init
	)

set the access address initial CRC value for transmitted and received PDU

The values should be changed, when there is no outstanding scheduled transmission or receiving. The values will be applied with the next call to schedule_advertisment() or schedule_connection_event().

◆ wake_up()

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

void bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::wake_up ( )

forces the run() function to return at least once

The function is intended to be used from interrupt handler to synchronize with the main thread.

Member Data Documentation

◆ radio_maximum_white_list_entries

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

constexpr std::size_t bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::radio_maximum_white_list_entries = 4

staticconstexpr

giving the maximum number of white list entries, the scheduled radio supports by hardware

Only if this value is not zero, the radio have to implement the white list related functions.

◆ radio_package_overhead

template<std::size_t TransmitSize, std::size_t ReceiveSize, typename CallBack >

constexpr std::size_t bluetoe::link_layer::scheduled_radio< TransmitSize, ReceiveSize, CallBack >::radio_package_overhead = 0

staticconstexpr

a number of bytes that are additional required by the hardware to handle an over the air package/PDU.

This number includes every byte that have to stored in a package to meet the requirments of the hardware, that is not part of the received / transmitted PDU (CRC, preamble etc.).

The documentation for this class was generated from the following file:

bluetoe/link_layer/scheduled_radio.hpp

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ scheduled_radio()

Member Function Documentation

◆ connection_request_filter()

◆ disarm_connection_event()

◆ radio_add_to_white_list()

◆ radio_remove_from_white_list()

◆ radio_scan_request_filter()

◆ request_event_cancelation()

◆ run()

◆ schedule_advertisment()

◆ schedule_connection_event()

◆ schedule_synchronized_user_timer()

◆ set_access_address_and_crc_init()

◆ wake_up()

Member Data Documentation

◆ radio_maximum_white_list_entries

◆ radio_package_overhead