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

Enumerations

NameDescription

Request status codes.

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.

Initialise a request.

Retrieve a request's parameters.

Submit a request for processing.

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

#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

ValueDescription

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

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.

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.

struct blecon_request_receive_data_op_t

Members

TypeNameDescription
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

TypeNameDescription
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

TypeNameDescription
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

TypeNameDescription
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

TypeNameDescription
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

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

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