Device SDK API Reference

SDK Version 0.1.6

The Blecon SDK is available on GitHub

Overview

Macros

Name	Description
#define BLECON_REQUEST_LOCAL_ERROR_CODE_NS
#define BLECON_REQUEST_REMOTE_ERROR_CODE_NS

Enumerations

Name	Description
enum blecon_ret_t	Return codes.
enum blecon_mode_t	Modem modes.
enum blecon_request_error_t	Request errors.
enum blecon_modem_info_type_t

Data Structures

Name	Description
struct blecon_modem_callbacks_t	Callbacks structure to populate by user.
struct blecon_modem_info_t

Functions

Name	Description
blecon_int_modem_new()	Create new internal modem instance.
blecon_ext_modem_new()	Create new external modem instance.
blecon_setup()	Set-up modem.
blecon_set_callbacks()	Set callbacks.
blecon_get_info()	Set callbacks.
blecon_set_application_data()	Set application-related data.
blecon_identify()	Identify the device to surrounding hotspots.
blecon_request_connection()	Request a connection to the Blecon infrastructure.
blecon_close_connection()	Cancel or close the current connection.
blecon_send_request()	Send a request to the integration.
blecon_get_error()	Get the error regarding the last request.
blecon_get_response()	Get the response to the sent request.
blecon_get_url()	Get the device's URL.
blecon_get_identity()	Get the device's ID in UUID form.

Macros

#define BLECON_REQUEST_LOCAL_ERROR_CODE_NS

Value

0x100

#define BLECON_REQUEST_REMOTE_ERROR_CODE_NS

Value

0x200

Enumerations

enum blecon_ret_t

Return codes.

Values

Value	Description
blecon_ok	OK.
blecon_error_exceeds_mtu	Message exceeds MTU.
blecon_error_invalid_state	This method cannot be called in the current state.
blecon_error_buffer_too_small	Data doesn't fit in the buffer.
blecon_error_serialization	Serialization error (external modem)
blecon_error_transport_error	Transport error (external modem)

enum blecon_mode_t

Modem modes.

Values

Value	Description
blecon_mode_high_performance	High Performance mode.
blecon_mode_balanced	Balanced mode.
blecon_mode_ultra_low_power	Low Power mode.

enum blecon_request_error_t

Request errors.

Values

Value	Description
blecon_request_ok	OK.
blecon_request_error_timeout	Request timed out.
blecon_request_error_security_error	The connection failed due to a security error.
blecon_request_error_disconnected	The link was disconnected before the request completed.
blecon_request_error_handler_not_set	The network's handler is not set.
blecon_request_error_handler_timeout	The network's handler timed out.
blecon_request_error_handler_failed	The network's handler failed.
blecon_request_error_network_not_set	The device is attached to a Blecon network.

enum blecon_modem_info_type_t

Values

Value	Description
blecon_modem_info_type_internal
blecon_modem_info_type_external

Data Structures

struct blecon_modem_callbacks_t

Callbacks structure to populate by user.

Members

Type	Name	Description
void(*)(struct blecon_modem_t *modem, void *user_data)	on_connection	Called when a connection has been established.
void(*)(struct blecon_modem_t *modem, void *user_data)	on_response	Called when a response is available.
void(*)(struct blecon_modem_t *modem, void *user_data)	on_error	Called when a request didn't complete successfully.

struct blecon_modem_info_t

Members

Type	Name	Description
enum blecon_modem_info_type_t	type
uint32_t	firmware_version

Functions

blecon_int_modem_new()

struct blecon_modem_t * blecon_int_modem_new(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)

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

Returns

a pointer to a struct blecon_modem_t instance

blecon_ext_modem_new()

struct blecon_modem_t * blecon_ext_modem_new(struct blecon_event_loop_t * event_loop, struct blecon_ext_modem_transport_t * transport)

Create new external modem instance.

Parameters

Parameter	Description
event_loop	a platform-specific event loop instance
transport	a platform-specific transport instance

Returns

a pointer to a struct blecon_modem_t instance

blecon_setup()

enum blecon_ret_t blecon_setup(struct blecon_modem_t * modem)

Set-up modem.

Parameters

Parameter	Description
modem	the modem instance to set-up

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_set_callbacks()

void blecon_set_callbacks(struct blecon_modem_t * modem, const struct blecon_modem_callbacks_t * callbacks, void * user_data)

Set callbacks.

Parameters

Parameter	Description
modem	the modem instance
callbacks	a struct blecon_modem_callbacks_t structure containing the user's callbacks

blecon_get_info()

enum blecon_ret_t blecon_get_info(struct blecon_modem_t * modem, struct blecon_modem_info_t * info)

Set callbacks.

Parameters

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

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_set_application_data()

enum blecon_ret_t blecon_set_application_data(struct blecon_modem_t * blecon_modem, const uint8_t * application_model_id, uint32_t application_schema_version)

Set application-related data.

Parameters

Parameter	Description
modem	the modem 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

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_identify()

enum blecon_ret_t blecon_identify(struct blecon_modem_t * blecon_modem)

Identify the device to surrounding hotspots.

Parameters

Parameter	Description
modem	the modem instance

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_request_connection()

enum blecon_ret_t blecon_request_connection(struct blecon_modem_t * blecon_modem)

Request a connection to the Blecon infrastructure.

Parameters

Parameter	Description
modem	the modem instance

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_close_connection()

enum blecon_ret_t blecon_close_connection(struct blecon_modem_t * blecon_modem)

Cancel or close the current connection.

Parameters

Parameter	Description
modem	the modem instance

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_send_request()

enum blecon_ret_t blecon_send_request(struct blecon_modem_t * blecon_modem, const uint8_t * data, size_t sz)

Send a request to the integration.

Parameters

Parameter	Description
modem	the modem instance
data	the data to send to the integration
sz	the size of the data buffer

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_get_error()

enum blecon_ret_t blecon_get_error(struct blecon_modem_t * blecon_modem, enum blecon_request_error_t * request_error)

Get the error regarding the last request.

Parameters

Parameter	Description
modem	the modem instance
error	a pointer where the error code can be stored

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_get_response()

enum blecon_ret_t blecon_get_response(struct blecon_modem_t * blecon_modem, uint8_t * data, size_t * sz)

Get the response to the sent request.

Parameters

Parameter	Description
modem	the modem instance
data	where to store the data sent by the integration
sz	pointer to the maximum size that can be stored in data, updated to the actual stored size on success

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_get_url()

enum blecon_ret_t blecon_get_url(struct blecon_modem_t * blecon_modem, char * url, size_t max_sz)

Get the device's URL.

Parameters

Parameter	Description
modem	the modem 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

enum blecon_ret_t blecon_ok on success, or an error code on failure

blecon_get_identity()

enum blecon_ret_t blecon_get_identity(struct blecon_modem_t * blecon_modem, uint8_t * uuid)

Get the device's ID in UUID form.

Parameters

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

Returns

enum blecon_ret_t blecon_ok on success, or an error code on failure