Comment on page

Device SDK API Reference

SDK Version 0.1.5

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

Name	Description
#define BLECON_REQUEST_LOCAL_ERROR_CODE_NS
#define BLECON_REQUEST_REMOTE_ERROR_CODE_NS

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

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

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.

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)

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

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.

Value	Description
blecon_modem_info_type_internal
blecon_modem_info_type_external

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.

Type	Name	Description
enum blecon_modem_info_type_t	type
uint32_t	firmware_version

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

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

Parameter	Description
modem	the modem instance to set-up

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

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

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

Parameter	Description
modem	the modem instance

Parameter	Description
modem	the modem instance

Parameter	Description
modem	the modem instance

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

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

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

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)

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

Getting Started Guides - Previous

Hardware Hotspot

Next - Modem Reference

Modem Commands

Last modified 2mo ago