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 2.0.1.

Overview

Macros

Enumerations

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_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 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_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

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_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
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_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 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, uint32_t duration_ms)

Start a peer scanning session.

Parameters

Parameter	Description
blecon	the blecon instance
peer_scan	true to report peer devices
raw_scan	true to report raw advertising data
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_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