Developer
Ask a QuestionBlecon WebsiteBlecon Console
  • Learn Blecon
    • Introduction
    • Blecon Modems
      • Device Identity and Network Security
      • Modem Firmware vs Modem Library
      • Using the Modem
      • Communicating with the cloud
      • Sending data from the cloud to a device
    • Blecon Hotspots
    • Blecon Networks
      • Blecon Accounts
      • Registering devices
        • The Blecon Scanner
        • Blecon Scanner Developer Guide
      • Blecon Events
      • Cloud Integrations
  • Cloud Integrations
    • Webhook
    • AWS S3
    • AWS SQS
    • AWS EventBridge
    • Memfault
  • Getting Started Guides
    • Getting started index
    • Install the Blecon Modem Firmware
    • Set up a Blecon Hotspot
    • Use Blecon from your computer with the Blecon CLI
    • Create a Network and register a device
    • Send device requests and events to your web service
    • Use Blecon from a Development Board
    • Use the Blecon Modem from an MCU
  • Device Guides
    • KKM S5-BCN
  • Development Board Guides
    • Supported Development Boards
    • Ezurio DVK-BL54L15
    • Fanstel EV-BM15C
    • InsightSiP ISP2454-LX-EB
    • Nordic nRF52840DK
    • Nordic nRF54L15DK
    • Minew ME54BE01
    • Panasonic PAN-B511 EVB
    • Raytac AN54L15Q-DB
    • u-Blox EVK-NORA-B20
  • Modem Reference
    • Modem Firmware Releases
      • nRF54L15 DK
      • nRF52840 Dongle
      • nRF52840 DK
    • CLI Releases
    • SDK Releases
    • Modem API Reference
    • Modem Protocol Reference
      • Request Frames
      • Command Protocol
      • UART Transport
    • Guides and best practices
      • Retrieve a device's identity
  • Cloud Reference
    • Configuration API
    • Advanced event routing
  • Hotspot Reference
    • Blecon Hub
Powered by GitBook

Get Support

  • Ask a question
On this page
  • Overview
  • Macros
  • Enumerations
  • Data Structures
  • Functions
  • Macros
  • Enumerations
  • Data Structures
  • struct blecon_callbacks_t
  • struct blecon_request_callbacks_t
  • struct blecon_request_parameters_t
  • Functions
  • blecon_int_modem_create()
  • blecon_int_modem_destroy()
  • blecon_ext_modem_create()
  • blecon_ext_modem_destroy()
  • blecon_init()
  • blecon_setup()
  • blecon_set_callbacks()
  • blecon_get_info()
  • blecon_set_application_data()
  • blecon_announce()
  • blecon_connection_initiate()
  • blecon_connection_terminate()
  • blecon_is_connected()
  • blecon_get_url()
  • blecon_get_identity()
  • blecon_get_time()
  • blecon_ping_perform()
  • blecon_ping_cancel()
  • blecon_ping_get_latency()
  • blecon_scan_start()
  • blecon_scan_stop()
  • blecon_scan_get_data()
  • blecon_submit_request()
  • blecon_get_request_processor()
  • blecon_request_init()
  • blecon_request_get_parameters()
  • blecon_request_get_status()
  • blecon_request_send_data()
  • blecon_request_send_data_op_get_user_data()
  • blecon_request_receive_data()
  • blecon_request_receive_data_op_get_user_data()
  • blecon_request_cleanup()
  1. Modem Reference

Modem API Reference

The Blecon Device SDK provides a developer interface to the Blecon modem.

PreviousCLI ReleasesNextModem Protocol Reference

Last updated 28 days ago

The Blecon SDK is available . This document refers to SDK Version 2.2.0.

Overview

Macros

Enumerations

Data Structures

Name
Description

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

Name
Description

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 global synchronized time.

Perform a ping to the Blecon infrastructure.

Cancel a ping to the Blecon infrastructure.

Get latency information from the last ping.

Start a peer scanning session.

Stop the current peer scanning session.

Get the data from the last peer scan.

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

Type
Name
Description

on_connection

Called when a blecon connection is open.

on_disconnection

Called when a blecon connection is closed.

on_time_update

Called when time is updated from the Blecon infrastructure.

on_ping_result

Called when a ping is completed.

on_scan_report

Called when a scan report is available.

on_scan_complete

Called when a scan completed.

struct blecon_request_callbacks_t

Callbacks structure to populate by user for requests.

Members

Type
Name
Description

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.

on_data_sent

alloc_incoming_data_buffer

Allocate memory for incoming data.

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

oneway

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

method

< The namespace of this request's event type (maximum BLECON_NAMESPACE_MAX_SZ characters, including null terminator) or NULL

request_content_type

The content type of the request (e.g. application/cbor, maximum BLECON_CONTENT_TYPE_MAX_SZ characters, including null terminator) or NULL.

response_content_type

The expected content type of the response (e.g. application/cbor, maximum BLECON_CONTENT_TYPE_MAX_SZ characters, including null terminator) or NULL.

response_mtu

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

callbacks

The callbacks to use for this request.

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_timer_t * timer, struct blecon_bluetooth_t * bluetooth, struct blecon_crypto_t * crypto, struct blecon_nvm_t * nvm, struct blecon_nfc_t * nfc, size_t scan_buffer_size, void *(*)(size_t) allocator)

Create new internal modem instance.

Parameters

Parameter
Description

event_loop

a platform-specific event loop instance

timer

a platform-specific timer 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

scan_buffer_size

the size of the scan buffer

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

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

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_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 global synchronized time.

Parameters

Parameter
Description

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

Parameter
Description

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

Parameter
Description

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

Parameter
Description

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

bool blecon_scan_start(struct blecon_t * blecon, bool peer_scan, bool raw_scan, uint32_t duration_ms)

Start a peer scanning session.

Parameters

Parameter
Description

blecon

the blecon instance

peer_scan

true to report peer devices

raw_scan

true to report raw advertising data

duration_ms

the duration of the scan in milliseconds

Returns

true on success, or false on failure

blecon_scan_stop()

bool blecon_scan_stop(struct blecon_t * blecon)

Stop the current peer scanning session.

Parameters

Parameter
Description

blecon

the blecon instance

Returns

true on success, or false on failure

blecon_scan_get_data()

bool blecon_scan_get_data(struct blecon_t * blecon, void(*)(const struct blecon_modem_peer_scan_report_t *report, void *user_data) peer_scan_report_iterator, void(*)(const struct blecon_modem_raw_scan_report_t *report, void *user_data) raw_scan_report_iterator, bool * overflow, void * user_data)

Get the data from the last peer scan.

Parameters

Parameter
Description

blecon

the blecon instance

peer_scan_report_iterator

a function to call for each peer device report; if NULL, no peer device reports are returned

raw_scan_report_iterator

a function to call for each raw advertising data report; if NULL, no raw advertising data reports are returned

overflow

a pointer to a bool which is set to true if the scan data buffer overflowed

user_data

user data to pass to the report iterator callbacks

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

Parameter
Description

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

Parameter
Description

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

Parameter
Description

request

the request instance to initialise

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_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 (maximum BLECON_MTU)

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

Called when the data set in has been sent.

a pointer to a struct blecon_modem_t instance created by

a pointer to a struct blecon_modem_t instance created by

a struct structure containing the request's parameters

void(*)(struct blecon_t *blecon)
void(*)(struct blecon_t *blecon)
void(*)(struct blecon_t *blecon)
void(*)(struct blecon_t *blecon)
void(*)(struct blecon_t *blecon)
void(*)(struct blecon_t *blecon)
void(*)(struct blecon_request_t *request)
void(*)(struct blecon_request_send_data_op_t *send_data_op, bool data_sent)
uint8_t *(*)(struct blecon_request_receive_data_op_t *receive_data_op, size_t sz)
void(*)(struct blecon_request_receive_data_op_t *receive_data_op, bool data_received, const uint8_t *data, size_t sz, bool finished)
bool
const char *
const char *
const char *
size_t
const struct blecon_request_callbacks_t *
void *
on GitHub
struct blecon_callbacks_t
struct blecon_request_callbacks_t
struct blecon_request_parameters_t
blecon_int_modem_create()
blecon_int_modem_destroy()
blecon_ext_modem_create()
blecon_ext_modem_destroy()
blecon_init()
blecon_setup()
blecon_set_callbacks()
blecon_get_info()
blecon_set_application_data()
blecon_announce()
blecon_connection_initiate()
blecon_connection_terminate()
blecon_is_connected()
blecon_get_url()
blecon_get_identity()
blecon_get_time()
blecon_ping_perform()
blecon_ping_cancel()
blecon_ping_get_latency()
blecon_scan_start()
blecon_scan_stop()
blecon_scan_get_data()
blecon_submit_request()
blecon_get_request_processor()
blecon_request_init()
blecon_request_get_parameters()
blecon_request_get_status()
blecon_request_send_data()
blecon_request_send_data_op_get_user_data()
blecon_request_receive_data()
blecon_request_receive_data_op_get_user_data()
blecon_request_cleanup()
blecon_request_send_data()
blecon_int_modem_create()
blecon_ext_modem_create()
blecon_request_parameters_t