Modem API Reference

The Blecon Device SDK provides a developer interface to the Blecon modem.

The Blecon SDK is available on GitHub. This document refers to SDK Version 4.1.0+t2510241335.c94.g427010e.gh86.

Overview

Macros

Name	Description

Enumerations

Name	Description
enum blecon_scan_type_t
enum blecon_advertising_mode_t	Controls the advertising performance and power consumption trade-off.

Data Structures

Name	Description
struct blecon_callbacks_t	Callbacks structure to populate by user.
struct blecon_request_callbacks_t	Callbacks structure to populate by user for requests.
struct blecon_request_parameters_t	A structure used to build a request based on its attributes.

Functions

Name	Description
blecon_int_modem_create()	Create new internal modem instance.
blecon_int_modem_destroy()	Destroy internal modem instance.
blecon_ext_modem_create()	Create new external modem instance.
blecon_ext_modem_destroy()	Destroy external modem instance.
blecon_init()	Initialise Blecon.
blecon_setup()	Set-up Blecon.
blecon_set_callbacks()	Set callbacks.
blecon_get_info()	Get information about the modem.
blecon_set_application_data()	Set application-related data.
blecon_set_advertising_mode()	Set advertising mode.
blecon_announce()	Announce the device ID to surrounding hotspots.
blecon_connection_initiate()	Initiate a connection to the Blecon infrastructure.
blecon_connection_terminate()	Terminate the current connection, or cancel the connection attempt.
blecon_is_connected()	Check if a connection is established.
blecon_get_url()	Get the device's ID in URL form.
blecon_get_identity()	Get the device's ID in UUID form.
blecon_get_time()	Get the current global synchronized time.
blecon_ping_perform()	Perform a ping to the Blecon infrastructure.
blecon_ping_cancel()	Cancel a ping to the Blecon infrastructure.
blecon_ping_get_latency()	Get latency information from the last ping.
blecon_scan_start()	Start a peer scanning session.
blecon_scan_stop()	Stop the current peer scanning session.
blecon_scan_get_data()	Get the data from the last peer scan.
blecon_submit_request()	Submit a request for processing.
blecon_get_request_processor()	Get a request processor.
blecon_get_user_data()	Get the user data associated with the blecon instance.
blecon_request_init()	Initialise a request.
blecon_request_get_parameters()	Retrieve a request's parameters.
blecon_request_get_status()	Get the status of a request.
blecon_request_send_data()	Send data for a request.
blecon_request_send_data_op_get_user_data()	Get the user data associated with a send data operation.
blecon_request_receive_data()	Start a receiving operation.
blecon_request_receive_data_op_get_user_data()	Get the user data associated with a receive data operation.
blecon_request_cleanup()	Clean-up a request.

Macros

Enumerations

enum blecon_scan_type_t

Values

Value	Description
blecon_scan_type_passive	Passive scanning - listen only
blecon_scan_type_active	Active scanning - send scan requests

enum blecon_advertising_mode_t

Controls the advertising performance and power consumption trade-off.

Values

Value	Description
blecon_advertising_mode_high_performance	High performance - 100ms period, higher power consumption
blecon_advertising_mode_balanced	Balanced - alternate between 100ms and 1s advertising period when requesting connection, otherwise 1s period, balances power consumption with performance
blecon_advertising_mode_ultra_low_power	Ultra low power - only advertise (100ms/1s alternating) when requesting connection, lowest power consumption

Data Structures

struct blecon_callbacks_t

Callbacks structure to populate by user.

Members

Type	Name	Description
void(*)(struct blecon_t *blecon)	on_connection	Called when a blecon connection is open.
void(*)(struct blecon_t *blecon)	on_disconnection	Called when a blecon connection is closed.
void(*)(struct blecon_t *blecon)	on_time_update	Called when time is updated from the Blecon infrastructure.
void(*)(struct blecon_t *blecon)	on_ping_result	Called when a ping is completed.
void(*)(struct blecon_t *blecon)	on_scan_report	Called when a scan report is available.
void(*)(struct blecon_t *blecon)	on_scan_complete	Called when a scan completed.

struct blecon_request_callbacks_t

Callbacks structure to populate by user for requests.

Members

Type	Name	Description
void(*)(struct blecon_request_t *request)	on_closed	Called when a request has completed and all data has been sent and received by the modem, or when the request terminated with an error.
void(*)(struct blecon_request_send_data_op_t *send_data_op, bool data_sent)	on_data_sent	Called when the data set in blecon_request_send_data() has been sent.
uint8_t *(*)(struct blecon_request_receive_data_op_t *receive_data_op, size_t sz)	alloc_incoming_data_buffer	Allocate memory for incoming data.
void(*)(struct blecon_request_receive_data_op_t *receive_data_op, bool data_received, const uint8_t *data, size_t sz, bool finished)	on_data_received	Called when new data is received for a request.

struct blecon_request_parameters_t

A structure used to build a request based on its attributes.

Members

Type	Name	Description
bool	oneway	If true, the request is one-way (no response expected)
const char *	method	< The namespace of this request's event type (maximum BLECON_NAMESPACE_MAX_SZ characters, including null terminator) or NULL
const char *	request_content_type	The content type of the request (e.g. application/cbor, maximum BLECON_CONTENT_TYPE_MAX_SZ characters, including null terminator) or NULL.
const char *	response_content_type	The expected content type of the response (e.g. application/cbor, maximum BLECON_CONTENT_TYPE_MAX_SZ characters, including null terminator) or NULL.
size_t	response_mtu	The maximum size of a response data frame (for a single data operation, maximum BLECON_MTU)
const struct blecon_request_callbacks_t *	callbacks	The callbacks to use for this request.
void *	user_data	User data to pass to the callbacks.

Functions

blecon_int_modem_create()

struct blecon_modem_t * blecon_int_modem_create(struct blecon_event_loop_t * event_loop, struct blecon_timer_t * timer, struct blecon_bluetooth_t * bluetooth, struct blecon_crypto_t * crypto, struct blecon_nvm_t * nvm, struct blecon_nfc_t * nfc, size_t scan_buffer_size, void *(*)(size_t) allocator)

Create new internal modem instance.

Parameters

Parameter	Description
event_loop	a platform-specific event loop instance
timer	a platform-specific timer instance
bluetooth	a platform-specific bluetooth instance
crypto	a platform-specific crypto instance
nvm	a platform-specific nvm instance
nfc	a platform-specific nfc instance
scan_buffer_size	the size of the scan buffer
allocator	a function to allocate memory

Returns

a pointer to a struct blecon_modem_t instance

blecon_int_modem_destroy()

void blecon_int_modem_destroy(struct blecon_modem_t * modem, void(*)(void *) deallocator)

Destroy internal modem instance.

Parameters

Parameter	Description
modem	a pointer to a struct blecon_modem_t instance created by blecon_int_modem_create()
deallocator	a function to deallocate memory or NULL

blecon_ext_modem_create()

struct blecon_modem_t * blecon_ext_modem_create(struct blecon_event_loop_t * event_loop, struct blecon_ext_modem_transport_t * transport, void *(*)(size_t) allocator)

Create new external modem instance.

Parameters

Parameter	Description
event_loop	a platform-specific event loop instance
transport	a platform-specific transport instance
allocator	a function to allocate memory

Returns

a pointer to a struct blecon_modem_t instance

blecon_ext_modem_destroy()

void blecon_ext_modem_destroy(struct blecon_modem_t * modem, void(*)(void *) deallocator)

Destroy external modem instance.

Parameters

Parameter	Description
modem	a pointer to a struct blecon_modem_t instance created by blecon_ext_modem_create()
deallocator	a function to deallocate memory or NULL

blecon_init()

void blecon_init(struct blecon_t * blecon, struct blecon_modem_t * modem)

Initialise Blecon.

Parameters

Parameter	Description
blecon	the blecon instance to initialise
modem	the modem instance to use

blecon_setup()

bool blecon_setup(struct blecon_t * blecon)

Set-up Blecon.

Parameters

Parameter	Description
blecon	the blecon instance to set-up

Returns

true on success, or false on failure

blecon_set_callbacks()

void blecon_set_callbacks(struct blecon_t * blecon, const struct blecon_callbacks_t * callbacks, void * user_data)

Set callbacks.

Parameters

Parameter	Description
blecon	the blecon instance
callbacks	a struct blecon_modem_callbacks_t structure containing the user's callbacks
user_data	user data to pass to the callbacks

blecon_get_info()

void blecon_get_info(struct blecon_t * blecon, struct blecon_modem_info_t * info)

Get information about the modem.

Parameters

Parameter	Description
blecon	the blecon instance
info	a pointer to a struct blecon_modem_info_t structure which is populated on success

blecon_set_application_data()

bool blecon_set_application_data(struct blecon_t * blecon, const uint8_t * application_model_id, uint32_t application_schema_version)

Set application-related data.

Parameters

Parameter	Description
blecon	the blecon instance
application_model_id	the device's specific model id encoded as a UUID (16 bytes long)
application_schema_version	the device's schema version

Returns

true on success, or false on failure

blecon_set_advertising_mode()

bool blecon_set_advertising_mode(struct blecon_t * blecon, enum blecon_advertising_mode_t mode)

This function configures the advertising mode, which affects the power consumption and connection latency when advertising or attempting to connect.

Parameters

Parameter	Description
blecon	the blecon instance
mode	the advertising mode (high_performance, balanced, or ultra_low_power)

Returns

true on success, or false on failure

blecon_announce()

bool blecon_announce(struct blecon_t * blecon)

Announce the device ID to surrounding hotspots.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

true on success, or false on failure

blecon_connection_initiate()

bool blecon_connection_initiate(struct blecon_t * blecon)

Initiate a connection to the Blecon infrastructure.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

true on success, or false on failure

blecon_connection_terminate()

bool blecon_connection_terminate(struct blecon_t * blecon)

Terminate the current connection, or cancel the connection attempt.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

true on success, or false on failure

blecon_is_connected()

bool blecon_is_connected(struct blecon_t * blecon)

Check if a connection is established.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

true if connected, or false if not

blecon_get_url()

bool blecon_get_url(struct blecon_t * blecon, char * url, size_t max_sz)

Get the device's ID in URL form.

Parameters

Parameter	Description
blecon	the blecon instance
url	a char array where to store the url (0-terminated)
max_sz	the maximum size of the array (including space for 0 terminator)

Returns

true on success, or false on failure

blecon_get_identity()

bool blecon_get_identity(struct blecon_t * blecon, uint8_t * uuid)

Get the device's ID in UUID form.

Parameters

Parameter	Description
blecon	the blecon instance
uuid	a 16-byte array where to store the uuid

Returns

true on success, or false on failure

blecon_get_time()

bool blecon_get_time(struct blecon_t * blecon, bool * time_valid, uint64_t * utc_time_ms_now, uint64_t * utc_time_ms_last_updated)

Get the current global synchronized time.

Parameters

Parameter	Description
blecon	the blecon instance
time_valid	a pointer to a bool which is set to true if the time is valid
utc_time_ms_now	a pointer to a uint64_t where the current time is stored
utc_time_ms_last_updated	a pointer to a uint64_t where the time of last update is stored

Returns

true on success, or false on failure

blecon_ping_perform()

bool blecon_ping_perform(struct blecon_t * blecon, uint32_t timeout_ms)

Perform a ping to the Blecon infrastructure.

Parameters

Parameter	Description
blecon	the blecon instance
timeout_ms	the timeout in milliseconds

Returns

true on success, or false on failure

blecon_ping_cancel()

bool blecon_ping_cancel(struct blecon_t * blecon)

Cancel a ping to the Blecon infrastructure.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

true on success, or false on failure

blecon_ping_get_latency()

bool blecon_ping_get_latency(struct blecon_t * blecon, bool * latency_available, uint32_t * connection_latency_ms, uint32_t * round_trip_latency_ms)

Get latency information from the last ping.

Parameters

Parameter	Description
blecon	the blecon instance
latency_available	a pointer to a bool which is set to true if the latency is available
connection_latency_ms	a pointer to a uint32_t where the connection latency is stored (milliseconds)
round_trip_latency_ms	a pointer to a uint32_t where the round trip latency is stored (milliseconds)

Returns

true on success, or false on failure

blecon_scan_start()

bool blecon_scan_start(struct blecon_t * blecon, bool peer_scan, bool raw_scan, enum blecon_scan_type_t scan_type, uint32_t duration_ms)

This function starts a scanning session to discover nearby Blecon and Bluetooth devices. The scan can be configured to report other Blecon devices (peers), raw advertising data from all devices, or both.When peer_scan is enabled, the function will report devices that are identified as Blecon peers through the on_scan_report callback.When raw_scan is enabled, the function will report raw advertising data from other Bluetooth devices. The scan_type parameter controls whether to send scan requests to advertisers (active scanning) or just listen passively.The scan will run for the specified duration and results will be available through the blecon_scan_get_data() function after completion.

Parameters

Parameter	Description
blecon	the blecon instance
peer_scan	true to report peer devices
raw_scan	true to report raw advertising data
scan_type	the type of scan to perform (only valid when performing a raw scan)
duration_ms	the duration of the scan in milliseconds

Returns

true on success, or false on failure

blecon_scan_stop()

bool blecon_scan_stop(struct blecon_t * blecon)

Stop the current peer scanning session.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

true on success, or false on failure

blecon_scan_get_data()

bool blecon_scan_get_data(struct blecon_t * blecon, void(*)(const struct blecon_modem_peer_scan_report_t *report, void *user_data) peer_scan_report_iterator, void(*)(const struct blecon_modem_raw_scan_report_t *report, void *user_data) raw_scan_report_iterator, bool * overflow, void * user_data)

Get the data from the last peer scan.

Parameters

Parameter	Description
blecon	the blecon instance
peer_scan_report_iterator	a function to call for each peer device report; if NULL, no peer device reports are returned
raw_scan_report_iterator	a function to call for each raw advertising data report; if NULL, no raw advertising data reports are returned
overflow	a pointer to a bool which is set to true if the scan data buffer overflowed
user_data	user data to pass to the report iterator callbacks

Returns

true on success, or false on failure

blecon_submit_request()

void blecon_submit_request(struct blecon_t * blecon, struct blecon_request_t * request)

Submit a request for processing.

Parameters

Parameter	Description
blecon	the blecon instance
request	the request to submit

blecon_get_request_processor()

struct blecon_request_processor_t * blecon_get_request_processor(struct blecon_t * blecon)

Get a request processor.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

a pointer to a struct blecon_request_processor_t instance

blecon_get_user_data()

void * blecon_get_user_data(struct blecon_t * blecon)

Get the user data associated with the blecon instance.

Parameters

Parameter	Description
blecon	the blecon instance

Returns

a pointer to the user data

blecon_request_init()

void blecon_request_init(struct blecon_request_t * request, const struct blecon_request_parameters_t * parameters)

Initialise a request.

Parameters

Parameter	Description
request	the request instance to initialise
parameters	a struct blecon_request_parameters_t structure containing the request's parameters

blecon_request_get_parameters()

const struct blecon_request_parameters_t * blecon_request_get_parameters(struct blecon_request_t * request)

Retrieve a request's parameters.

Parameters

Parameter	Description
request	the request instance

Returns

a pointer to the request's parameters

blecon_request_get_status()

enum blecon_request_status_code_t blecon_request_get_status(struct blecon_request_t * request)

Get the status of a request.

Parameters

Parameter	Description
request	the request instance

Returns

the status code of the request

blecon_request_send_data()

bool blecon_request_send_data(struct blecon_request_send_data_op_t * op, struct blecon_request_t * request, const uint8_t * data, size_t sz, bool finished, void * user_data)

Send data for a request.

Parameters

Parameter	Description
op	a pointer to a struct blecon_request_send_data_op_t structure which is populated on success
request	a pointer to the relevant request structure
data	the data to send
sz	the size of the data buffer (maximum BLECON_MTU)
finished	a flag indicating if this is the end of the data
user_data	a pointer to user-defined data which will be associated with the operation

Returns

true if the operation was queued successfully, or false on failure

blecon_request_send_data_op_get_user_data()

void * blecon_request_send_data_op_get_user_data(struct blecon_request_send_data_op_t * op)

Get the user data associated with a send data operation.

Parameters

Parameter	Description
op	the send data operation instance

Returns

a pointer to the user data

blecon_request_receive_data()

bool blecon_request_receive_data(struct blecon_request_receive_data_op_t * op, struct blecon_request_t * request, void * user_data)

Start a receiving operation.

Parameters

Parameter	Description
op	a pointer to a struct blecon_request_receive_data_op_t structure which is populated on success
request	a pointer to the relevant request structure
user_data	a pointer to user-defined data which will be associated with the operation

Returns

true if the operation was queued successfully, or false on failure

blecon_request_receive_data_op_get_user_data()

void * blecon_request_receive_data_op_get_user_data(struct blecon_request_receive_data_op_t * op)

Get the user data associated with a receive data operation.

Parameters

Parameter	Description
op	the receive data operation instance

Returns

a pointer to the user data

blecon_request_cleanup()

void blecon_request_cleanup(struct blecon_request_t * request)

Clean-up a request.

Parameters

Parameter	Description
request	the request to clean-up