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

Overview

Macros

Enumerations

Data Structures

NameDescription

Callbacks structure to populate by user.

Callbacks structure to populate by user for requests.

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

Functions

NameDescription

Create new internal modem instance.

Destroy internal modem instance.

Create new external modem instance.

Destroy external modem instance.

Initialise Blecon.

Set-up Blecon.

Set callbacks.

Get information about the modem.

Set application-related data.

Announce the device ID to surrounding hotspots.

Initiate a connection to the Blecon infrastructure.

Terminate the current connection, or cancel the connection attempt.

Check if a connection is established.

Get the device's ID in URL form.

Get the device's ID in UUID form.

Get the current time.

Perform a ping to the Blecon infrastructure.

Cancel a ping to the Blecon infrastructure.

Get latency information from the last ping.

Submit a request for processing.

Get a request processor.

Initialise a request.

Retrieve a request's parameters.

Get the status of a request.

Send data for a request.

Get the user data associated with a send data operation.

Start a receiving operation.

Get the user data associated with a receive data operation.

Clean-up a request.

Macros

Enumerations

Data Structures

struct blecon_callbacks_t

Callbacks structure to populate by user.

Members

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

struct blecon_request_callbacks_t

Callbacks structure to populate by user for requests.

Members

TypeNameDescription
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

TypeNameDescription
bool

oneway

If true, the request is one-way (no response expected)

const char *

method

< The namespace of this request's event type

const char *

request_content_type

The content type of the request (e.g. application/cbor)

const char *

response_content_type

The expected content type of the response (e.g. application/cbor)

size_t

response_mtu

The maximum size of a response data frame (for a single data operation)

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, void *(*)(size_t) allocator)

Create new internal modem instance.

Parameters

ParameterDescription

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

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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_submit_request()

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

Submit a request for processing.

Parameters

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

request

the request to clean-up

Last updated