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

Overview

Macros

Name	Description
#define BLECON_REQUEST_LOCAL_STATUS_CODE_NS
#define BLECON_REQUEST_REMOTE_STATUS_CODE_NS

Enumerations

Name	Description
enum blecon_request_status_code_t	Request status codes.

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.
struct blecon_request_receive_data_op_t
struct blecon_request_send_data_op_t
struct blecon_request_t.status
struct blecon_request_t
struct blecon_t

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_request_init()	Initialise a request.
blecon_request_get_parameters()	Retrieve a request's parameters.
blecon_request_submit()	Submit a request for processing.
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

#define BLECON_REQUEST_LOCAL_STATUS_CODE_NS

Value

0x100

#define BLECON_REQUEST_REMOTE_STATUS_CODE_NS

Value

0x200

Enumerations

enum blecon_request_status_code_t

Request status codes.

Values

Value	Description
blecon_request_status_ok	OK.
blecon_request_status_pending	The request is pending.
blecon_request_status_timeout	Request timed out.
blecon_request_status_transport_error	A transport error occurred.
blecon_request_status_handler_not_set	The network's handler is not set.
blecon_request_status_handler_timeout	The network's handler timed out.
blecon_request_status_handler_failed	The network's handler failed.
blecon_request_status_network_not_set	The device is not attached to a Blecon network.

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.

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

struct blecon_request_receive_data_op_t

Members

Type	Name	Description
struct blecon_request_t *	request
void *	user_data
struct blecon_list_node_t	receive_data_ops_list_node

struct blecon_request_send_data_op_t

Members

Type	Name	Description
struct blecon_request_t *	request
const uint8_t *	data
size_t	sz
bool	finished
void *	user_data
struct blecon_list_node_t	send_data_ops_list_node

struct blecon_request_t.status

Members

Type	Name	Description
bool	submitted
bool	open_sent
bool	headers_sent
bool	headers_received
bool	data_sent
bool	data_received
bool	reset_sent
bool	reset_received
bool	error

struct blecon_request_t

Members

Type	Name	Description
const struct blecon_request_parameters_t *	parameters
struct blecon_t *	blecon
blecon_request_id_t	id
enum blecon_request_status_code_t	status_code
struct blecon_request_t::@0	status
size_t	pending_receive_credits
struct blecon_list_t	send_data_ops_list
struct blecon_list_t	receive_data_ops_list
struct blecon_list_node_t	requests_list_node

struct blecon_t

Members

Type	Name	Description
struct blecon_modem_t *	modem
const struct blecon_callbacks_t *	callbacks
void *	user_data
bool	is_setup
bool	is_connected
struct blecon_modem_info_t	modem_info
struct blecon_list_t	requests_list
blecon_request_id_t	next_request_id
size_t	outgoing_stream_frame_queue_space_count

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

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
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_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_submit()

void blecon_request_submit(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_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
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