wms_beacon_tx.h File Reference

Detailed Description

Wirepas Mesh stack is capable of using the idle time between network protocol radio transmissions to transmit Bluetooth LE compatible beacons. The Beacon TX library provides an API for configuring each node to transmit beacons. It is recommended to read document WP-RM-103 - Wirepas Mesh Beacon API Reference Manual for an introduction of beacon support in the Wirepas Mesh stack. The Beacon TX library is not available on all radio architectures, only supported in 2.4GHz radio architectures.

Library services are accessed via lib_beacon_tx handle.

For examples on how to use these services, check out example application ble_beacon.

Definition in file wms_beacon_tx.h.

Go to the source code of this file.

Typedefs
typedef app_res_e(*	app_lib_beacon_tx_clear_beacons_f) (void)
typedef app_res_e(*	app_lib_beacon_tx_enable_beacons_f) (bool enabled)
typedef app_res_e(*	app_lib_beacon_tx_set_beacon_interval_f) (uint32_t interval)
typedef app_res_e(*	app_lib_beacon_tx_set_beacon_power_f) (uint8_t index, int8_t *power_p)
typedef app_res_e(*	app_lib_beacon_tx_set_beacon_channels_f) (uint8_t index, app_lib_beacon_tx_channels_mask_e mask)
typedef app_res_e(*	app_lib_beacon_tx_set_beacon_contents_f) (uint_fast8_t index, const uint8_t *bytes, size_t num_bytes)

Data Structures
struct	app_lib_beacon_tx_t

Enumerations
enum	app_lib_beacon_tx_channels_mask_e {   APP_LIB_BEACON_TX_CHANNELS_37 = 0, APP_LIB_BEACON_TX_CHANNELS_38, APP_LIB_BEACON_TX_CHANNELS_39, APP_LIB_BEACON_TX_CHANNELS_37_38,   APP_LIB_BEACON_TX_CHANNELS_37_39, APP_LIB_BEACON_TX_CHANNELS_38_39, APP_LIB_BEACON_TX_CHANNELS_37_38_39, APP_LIB_BEACON_TX_CHANNELS_ALL = APP_LIB_BEACON_TX_CHANNELS_37_38_39 }

Macros
#define	APP_LIB_BEACON_TX_NAME   0x0cb930b8
	"BCONTX" More...
#define	APP_LIB_BEACON_TX_VERSION   0x200
#define	APP_LIB_BEACON_TX_MIN_INTERVAL   100
#define	APP_LIB_BEACON_TX_MAX_INTERVAL   60000
#define	APP_LIB_BEACON_TX_DEFAULT_INTERVAL   1000
#define	APP_LIB_BEACON_TX_MAX_INDEX   7
#define	APP_LIB_BEACON_TX_MAX_NUM_BYTES   (38)

Typedef Documentation

app_lib_beacon_tx_clear_beacons_f

typedef app_res_e(* app_lib_beacon_tx_clear_beacons_f) (void)

Clear all beacon contents and set all values to defaults:

• Beacon transmission disabled
• Interval: 1 s
• Power: maximum
• Channels: all
• Contents: cleared

  Note

  Default is not enabled, maximum power, APP_LIB_BEACON_TX_DEFAULT_INTERVAL, APP_LIB_BEACON_TX_CHANNELS_ALL and no payload set for any index

  Returns

  always returns APP_RES_OK

Definition at line 126 of file wms_beacon_tx.h.

app_lib_beacon_tx_enable_beacons_f

typedef app_res_e(* app_lib_beacon_tx_enable_beacons_f) (bool enabled)

Enable or disable beacon transmissions. A true value enables transmissions, false value disables beacon transmissions. Usually the beacon parameters are set up first and the transmission is enabled after that.

Parameters

enabled

New state, true for enabled, false otherwise

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is not running

Note

Stack must be running (i.e. lib_state->startStack() must have been called) in order for enabling being possible.

Definition at line 142 of file wms_beacon_tx.h.

app_lib_beacon_tx_set_beacon_channels_f

typedef app_res_e(* app_lib_beacon_tx_set_beacon_channels_f) (uint8_t index, app_lib_beacon_tx_channels_mask_e mask)

Set the channels to use for a beacon. The index parameter is the beacon number to change, from 0 to APP_LIB_BEACON_TX_MAX_INDEX. mask is the channel mask, app_lib_beacon_tx_channels_mask_e.

Parameters

index	Number of beacon (0 .. APP_LIB_BEACON_TX_MAX_INDEX)
mask	Channels to use for transmission

Returns

Result code, APP_RES_OK if successful, APP_RES_RESOURCE_UNAVAILABLE if index is too large, APP_RES_INVALID_VALUE if mask is invalid APP_RES_INVALID_STACK_STATE if stack is not running

Note

Stack must be running (i.e. lib_state->startStack() must have been called) in order for set being possible.

Definition at line 203 of file wms_beacon_tx.h.

app_lib_beacon_tx_set_beacon_contents_f

typedef app_res_e(* app_lib_beacon_tx_set_beacon_contents_f) (uint_fast8_t index, const uint8_t *bytes, size_t num_bytes)

Set beacon contents. The index parameter is the beacon number to change, from 0 to APP_LIB_BEACON_TX_MAX_INDEX. bytes is the beacon contents to set and num_bytes is the number of bytes, or size, of the beacon. Anatomy of a beacon is shown in WP-RM-103 - Wirepas Mesh Beacon API Reference Manual.

If more than one beacon index is set up, the beacons are transmitted one after another, starting from index 0, separated by a gap set by the lib_beacon_tx->setBeaconInterval() function. Setting bytes to NULL or num_bytes to 0 disables the beacon for that index.

Parameters

index	Number of beacon (0 .. APP_LIB_BEACON_TX_MAX_INDEX)
bytes	Beacon payload, or NULL to disable payload for this index
num_bytes	Payload size in bytes, or 0 to disable payload for this index

Returns

Result code, APP_RES_OK if successful, APP_RES_RESOURCE_UNAVAILABLE if index is too large, APP_RES_INVALID_VALUE if num_bytes is invalid APP_RES_INVALID_STACK_STATE if stack is not running

Note

Stack must be running (i.e. lib_state->startStack() must have been called) in order for set being possible.

Definition at line 234 of file wms_beacon_tx.h.

app_lib_beacon_tx_set_beacon_interval_f

typedef app_res_e(* app_lib_beacon_tx_set_beacon_interval_f) (uint32_t interval)

Set the interval of beacon transmissions. If more than one beacon is set up, different beacon is transmitted after each interval.

Parameters

interval

Sending interval in milliseconds

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if interval is invalid, APP_RES_INVALID_STACK_STATE if stack is not running

Note

Stack must be running (i.e. lib_state->startStack() must have been called) in order for set being possible.

Beacons are sent on all enabled channels right after each other, for every interval, i.e. the more channels are enabled, the longer a transmission takes

Different beacon payloads are sent on succeeding transmissions, interval milliseconds apart

Definition at line 162 of file wms_beacon_tx.h.

app_lib_beacon_tx_set_beacon_power_f

typedef app_res_e(* app_lib_beacon_tx_set_beacon_power_f) (uint8_t index, int8_t *power_p)

Set the output power of a beacon. The index parameter is the beacon number to change, from 0 to APP_LIB_BEACON_TX_MAX_INDEX. power_p parameter is a pointer to the power value. The value is rounded to the nearest available power and the new value is stored in the address pointed by power_p.

Parameters

index	Number of beacon (0 .. APP_LIB_BEACON_TX_MAX_INDEX)
power_p	Pointer to radio transmission power, in dBm

Returns

Result code, APP_RES_OK if successful, APP_RES_RESOURCE_UNAVAILABLE if index is too large APP_RES_INVALID_STACK_STATE if stack is not running

Note

Stack must be running (i.e. lib_state->startStack() must have been called) in order for set being possible.

Power is rounded to the closest possible value and the value pointed by power_p is modified to the used value

Definition at line 184 of file wms_beacon_tx.h.

---

Data Structure Documentation

app_lib_beacon_tx_t

struct app_lib_beacon_tx_t

The function table returned from app_open_library_f

Definition at line 241 of file wms_beacon_tx.h.

Data Fields
app_lib_beacon_tx_clear_beacons_f	clearBeacons
app_lib_beacon_tx_enable_beacons_f	enableBeacons
app_lib_beacon_tx_set_beacon_channels_f	setBeaconChannels
app_lib_beacon_tx_set_beacon_contents_f	setBeaconContents
app_lib_beacon_tx_set_beacon_interval_f	setBeaconInterval
app_lib_beacon_tx_set_beacon_power_f	setBeaconPower

Enumeration Type Documentation

app_lib_beacon_tx_channels_mask_e

enum app_lib_beacon_tx_channels_mask_e

The type is used as a parameter to lib_beacon_tx->setBeaconChannels(), to select which advertising channels are used for sending the beacon payload.

Enumerator
APP_LIB_BEACON_TX_CHANNELS_37	Use advertising channel 37
APP_LIB_BEACON_TX_CHANNELS_38	Use advertising channel 38
APP_LIB_BEACON_TX_CHANNELS_39	Use advertising channel 39
APP_LIB_BEACON_TX_CHANNELS_37_38	Use advertising channels 37 and 38
APP_LIB_BEACON_TX_CHANNELS_37_39	Use advertising channels 37 and 39
APP_LIB_BEACON_TX_CHANNELS_38_39	Use advertising channels 38 and 39
APP_LIB_BEACON_TX_CHANNELS_37_38_39	Use advertising channels 37, 38 and 39
APP_LIB_BEACON_TX_CHANNELS_ALL	Use advertising channels 37, 38 and 39

Definition at line 92 of file wms_beacon_tx.h.

{
    APP_LIB_BEACON_TX_CHANNELS_37 = 0,
    APP_LIB_BEACON_TX_CHANNELS_38,
    APP_LIB_BEACON_TX_CHANNELS_39,
    APP_LIB_BEACON_TX_CHANNELS_37_38,
    APP_LIB_BEACON_TX_CHANNELS_37_39,
    APP_LIB_BEACON_TX_CHANNELS_38_39,
    APP_LIB_BEACON_TX_CHANNELS_37_38_39,
    APP_LIB_BEACON_TX_CHANNELS_ALL = APP_LIB_BEACON_TX_CHANNELS_37_38_39
} app_lib_beacon_tx_channels_mask_e;

Macro Definition Documentation

APP_LIB_BEACON_TX_DEFAULT_INTERVAL

#define APP_LIB_BEACON_TX_DEFAULT_INTERVAL   1000

The default interval of beacon transmissions, in milliseconds, to use if lib_beacon_tx->setBeaconInterval() is not called.

Definition at line 64 of file wms_beacon_tx.h.

APP_LIB_BEACON_TX_MAX_INDEX

#define APP_LIB_BEACON_TX_MAX_INDEX   7

Maximum beacon index for lib_beacon_tx->setBeaconPower(), lib_beacon_tx->setBeaconChannels() and lib_beacon_tx->setBeaconContents(). Each index is transmitted in a round-robin fashion, separated by the interval, set by lib_beacon_tx->setBeaconInterval() .

Definition at line 75 of file wms_beacon_tx.h.

APP_LIB_BEACON_TX_MAX_INTERVAL

#define APP_LIB_BEACON_TX_MAX_INTERVAL   60000

The maximum amount of time, in milliseconds, between beacon transmissions. Used as a parameter to to lib_beacon_tx->setBeaconInterval().

Definition at line 57 of file wms_beacon_tx.h.

APP_LIB_BEACON_TX_MAX_NUM_BYTES

#define APP_LIB_BEACON_TX_MAX_NUM_BYTES   (38)

Maximum number of bytes per beacon, for lib_beacon_tx->setBeaconContents().

Note

Bluetooth advertising PDU has a maximum length of 39 bytes, but the radio driver inserts the length byte automatically, instead of having it as part of the buffer

Examples

ble_tx/app.c.

Definition at line 85 of file wms_beacon_tx.h.

APP_LIB_BEACON_TX_MIN_INTERVAL

#define APP_LIB_BEACON_TX_MIN_INTERVAL   100

The minimum amount of time, in milliseconds, between beacon transmissions. Used as a parameter to lib_beacon_tx->setBeaconInterval().

Definition at line 50 of file wms_beacon_tx.h.

APP_LIB_BEACON_TX_NAME

#define APP_LIB_BEACON_TX_NAME   0x0cb930b8

"BCONTX"

This is the library name for use with app_global_functions_t::openLibrary

Definition at line 38 of file wms_beacon_tx.h.

APP_LIB_BEACON_TX_VERSION

#define APP_LIB_BEACON_TX_VERSION   0x200

This is the library version for use with app_global_functions_t::openLibrary

Definition at line 43 of file wms_beacon_tx.h.