API documentation

Core API documentation

This API uses pointers to raw packet data. TinyCBOR API documentation provides serialization layer over it that uses TinyCBOR.

group nrf_rpc

Module to call procedures on a remote processor.

Defines

NRF_RPC_ID_UNKNOWN

Special value to indicate that ID is unknown or irrelevant.

NRF_RPC_GROUP_DEFINE(_name, _strid, _ack_handler, _ack_data, _err_handler)

Define a group of commands and events.

Parameters

  • _name: Symbol name of the group.

  • _strid: String containing unique identifier of the group. Naming conventions the same as C symbol name. Groups on local and remote must have the same unique identifier.

  • _ack_handler: Handler of type nrf_rpc_ack_handler_t called when ACK was received after event completion. Can be NULL if group does not want to receive ACK notifications.

  • _ack_data: Opaque pointer for the _ack_handler.

  • _err_handler: Handler of type nrf_rpc_err_handler_t called when error occurred in context of this group. Can be NULL if group does not want to receive error notifications.

NRF_RPC_GROUP_DECLARE(_name)

Extern declaration of a group.

Can be used in a header file.

Parameters

  • _name: Symbol name of the group.

NRF_RPC_CMD_DECODER(_group, _name, _cmd, _handler, _data)

Register a command decoder.

Parameters

  • _group: Group that the decoder will belong to, created with a NRF_RPC_GROUP_DEFINE().

  • _name: Name of the decoder.

  • _cmd: Command id. Can be from 0 to 254.

  • _handler: Handler function of type nrf_rpc_handler_t.

  • _data: Opaque pointer for the _handler.

NRF_RPC_EVT_DECODER(_group, _name, _evt, _handler, _data)

Register an event decoder.

Parameters

  • _group: Group that the decoder will belong to, created with a NRF_RPC_GROUP_DEFINE().

  • _name: Name of the decoder.

  • _evt: Event id. Can be from 0 to 254.

  • _handler: Handler function of type nrf_rpc_handler_t.

  • _data: Opaque pointer for the _handler.

NRF_RPC_ALLOC(_packet, _len)

Allocates memory for a packet.

Macro may allocate some variables on stack, so it should be used at top level of a function.

Memory is automatically deallocated when it is passed to any of the send functions. If not NRF_RPC_DISCARD() can be used.

Parameters

  • [out] _packet: Variable of type uint8_t * that will hold pointer to a newly allocated packet buffer.

  • [in] _len: Requested length of the packet.

NRF_RPC_DISCARD(_packet)

Deallocate memory for a packet.

This macro should be used if memory was allocated, but it will not be send with any of the send functions.

Parameters

  • _packet: Packet that was previously allocated.

Typedefs

typedef void (*nrf_rpc_handler_t)(const uint8_t *packet, size_t len, void *handler_data)

Callback that handles decoding of commands, events and responses.

Parameters

  • packet: Packet data.

  • len: Length of the packet.

  • handler_data: Opaque pointer provided by the user.

typedef void (*nrf_rpc_ack_handler_t)(uint8_t id, void *handler_data)

Callback called when ACK was received.

See

NRF_RPC_GROUP_DEFINE

Parameters

  • id: Id of the event that was completed.

  • handler_data: Opaque pointer provided by the user.

typedef void (*nrf_rpc_err_handler_t)(const struct nrf_rpc_err_report *report)

Callback to report error that cannot be returned by the API call.

This callback will be called when received packet cannot be correctly interpreted. Second case is when one of _no_err sending functions failed.

Callback can be assigned to specific group. If group in which error occurred is known associated error handler is called. Later global error handler provided in nrf_rpc_init is called.

See

NRF_RPC_GROUP_DEFINE

See

nrf_rpc_init

Parameters

  • report: Error report.

Enums

enum nrf_rpc_packet_type

Type of packet.

Used by nrf_rpc_err_report to indicate which packet caused the problem.

Values:

enumerator NRF_RPC_PACKET_TYPE_EVT

Event.

enumerator NRF_RPC_PACKET_TYPE_RSP

Response.

enumerator NRF_RPC_PACKET_TYPE_ACK

Event acknowledge.

enumerator NRF_RPC_PACKET_TYPE_ERR

Error report from remote.

enumerator NRF_RPC_PACKET_TYPE_INIT

Initialization packet.

enumerator NRF_RPC_PACKET_TYPE_CMD

Command.

enum nrf_rpc_err_src

Error source.

Used by nrf_rpc_err_report to indicate when the problem occurred.

Values:

enumerator NRF_RPC_ERR_SRC_RECV

Error during receiving.

enumerator NRF_RPC_ERR_SRC_SEND

Error during sending.

enumerator NRF_RPC_ERR_SRC_REMOTE

Error reported be the remote.

Functions

int nrf_rpc_init(nrf_rpc_err_handler_t err_handler)

Initialize the nRF RPC.

Return

0 on success or negative error code.

Parameters

  • err_handler: Error handler that will be called to report error in nRF RPC.

static inline int nrf_rpc_cmd(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet, size_t len, nrf_rpc_handler_t handler, void *handler_data)

Send a command and provide callback to handle response.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • group: Group that command belongs to.

  • cmd: Command id.

  • packet: Packet allocated by NRF_RPC_ALLOC and filled with an encoded data.

  • len: Length of the packet. Can be smaller than allocated.

  • handler: Callback that handles the response. In case of error (e.g. malformed response packet was received) it is undefined if the handler will be called.

  • handler_data: Opaque pointer that will be passed to handler.

static inline int nrf_rpc_cmd_rsp(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet, size_t len, const uint8_t **rsp_packet, size_t *rsp_len)

Send a command and get response as an output parameter.

This variant of command send function outputs response as an output parameter. Caller is responsible to call nrf_rpc_decoding_done with a response packet just after response packet was decoded and can be deallocated.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • [in] group: Group that command belongs to.

  • [in] cmd: Command id.

  • [in] packet: Packet allocated by NRF_RPC_ALLOC and filled with an encoded data.

  • [in] len: Length of the packet. Can be smaller than allocated.

  • [out] rsp_packet: Packet containing the response or NULL on error.

  • [out] rsp_len: Length of rsp_packet.

static inline void nrf_rpc_cmd_no_err(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet, size_t len, nrf_rpc_handler_t handler, void *handler_data)

Send a command, provide callback to handle response and pass any error to an error handler.

This variant of command send function returns void, so sending error returned from the transport layer is passed to the error handler. Source of error is NRF_RPC_ERR_SRC_SEND.

Parameters

  • group: Group that command belongs to.

  • cmd: Command id.

  • packet: Packet allocated by NRF_RPC_ALLOC and filled with an encoded data.

  • len: Length of the packet. Can be smaller than allocated.

  • handler: Callback that handles the response. In case of error (e.g. malformed response packet was received) it is undefined if the handler will be called.

  • handler_data: Opaque pointer that will be passed to handler.

static inline void nrf_rpc_cmd_rsp_no_err(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet, size_t len, const uint8_t **rsp_packet, size_t *rsp_len)

Send a command, get response as an output parameter and pass any error to an error handler.

See both nrf_rpc_cmd_rsp and nrf_rpc_cmd_no_err for more details on this variant of command send function.

Parameters

  • [in] group: Group that command belongs to.

  • [in] cmd: Command id.

  • [in] packet: Packet allocated by NRF_RPC_ALLOC and filled with an encoded data.

  • [in] len: Length of the packet. Can be smaller than allocated.

  • [out] rsp_packet: Packet containing the response or NULL on error.

  • [out] rsp_len: Length of rsp_packet.

int nrf_rpc_evt(const struct nrf_rpc_group *group, uint8_t evt, uint8_t *packet, size_t len)

Send an event.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • group: Group that event belongs to.

  • evt: Event id.

  • packet: Packet allocated by NRF_RPC_ALLOC and filled with an encoded data.

  • len: Length of the packet. Can be smaller than allocated.

void nrf_rpc_evt_no_err(const struct nrf_rpc_group *group, uint8_t evt, uint8_t *packet, size_t len)

Send an event and pass any error to an error handler.

This variant of event send function returns void, so sending error returned from the transport layer is passed to the error handler. Source of error is NRF_RPC_ERR_SRC_SEND.

Parameters

  • group: Group that event belongs to.

  • evt: Event id.

  • packet: Packet allocated by NRF_RPC_ALLOC and filled with an encoded data.

  • len: Length of the packet. Can be smaller than allocated.

int nrf_rpc_rsp(uint8_t *packet, size_t len)

Send a response.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • packet: Packet allocated by NRF_RPC_ALLOC and filled with encoded data.

  • len: Length of the packet. Can be smaller than allocated.

void nrf_rpc_rsp_no_err(uint8_t *packet, size_t len)

Send a response and pass any error to an error handler.

This variant of response send function returns void, so sending error returned from the transport layer is passed to the error handler. Source of error is NRF_RPC_ERR_SRC_SEND.

Parameters

  • packet: Packet allocated by NRF_RPC_ALLOC and filled with encoded data.

  • len: Length of the packet. Can be smaller than allocated.

void nrf_rpc_decoding_done(const uint8_t *packet)

Indicate that decoding of the input packet is done.

This function must be called as soon as the input packet was parsed and can be deallocated. It must be called in command decoder, event decoder and after nrf_rpc_cmd_rsp or nrf_rpc_cmd_rsp_no_err. Packet is automatically deallocated after completetion of the response handler function, so this nrf_rpc_decoding_done is not needed in response handler.

Parameters

  • packet: Packet which parsing has completed.

void nrf_rpc_err(int code, enum nrf_rpc_err_src src, const struct nrf_rpc_group *group, uint8_t id, uint8_t packet_type)

Report an error to nRP PRC error handler.

Main intention for exposing this function is to allow serialization layer (e.g. TinyCBOR) report error to the same error handler as entire nRF RPC.

Parameters

  • code: Negative error code.

  • src: Source of error.

  • group: Group where error happent or NULL if unknown.

  • id: Command or event id which caused the error or NRF_RPC_ID_UNKNOWN if unknown.

  • packet_type: Type of packet related to this error.

struct nrf_rpc_group
#include <nrf_rpc.h>

Defines a group of commands and events.

Created by NRF_RPC_GROUP_DEFINE.

Fields of this structure are used internally by nRF RPC and not intended to be used by the user.

struct nrf_rpc_err_report
#include <nrf_rpc.h>

Error report.

Public Members

int code

Error code.

const struct nrf_rpc_group *group

Group where the error occurred or NULL if it is unknown.

enum nrf_rpc_err_src src

Source of the error.

uint8_t id

Command or event id or NRF_RPC_ID_UNKNOWN.

enum nrf_rpc_packet_type packet_type

Type of packet. Value may be outside defined enum values if packet is malformed.

TinyCBOR API documentation

This API is built on top of the core nRF RPC API and it is not independent. See Core API documentation for more information on how to use nRF RPC together with TinyCBOR.

group nrf_rpc_cbor

Module simplifying usage of TinyCBOR as a serialization for nRF RPC module.

Defines

NRF_RPC_CBOR_CMD_DECODER(_group, _name, _cmd, _handler, _data)

Register a command decoder.

Parameters

  • _group: Group that the decoder will belong to, created with a NRF_RPC_GROUP_DEFINE().

  • _name: Name of the decoder.

  • _cmd: Command id. Can be from 0 to 254.

  • _handler: Handler function of type nrf_rpc_cbor_handler_t.

  • _data: Opaque pointer for the _handler.

NRF_RPC_CBOR_EVT_DECODER(_group, _name, _evt, _handler, _data)

Register an event decoder.

Parameters

  • _group: Group that the decoder will belong to, created with a NRF_RPC_GROUP_DEFINE().

  • _name: Name of the decoder.

  • _evt: Event id. Can be from 0 to 254.

  • _handler: Handler function of type nrf_rpc_cbor_handler_t.

  • _data: Opaque pointer for the _handler.

NRF_RPC_CBOR_ALLOC(_ctx, _len)

Allocates memory for a packet.

Macro may allocate some variables on stack, so it should be used at top level of a function.

Memory is automatically deallocated when it is passed to any of the send functions. If not NRF_RPC_CBOR_DISCARD() can be used.

Parameters

  • [out] _ctx: Variable of type nrf_rpc_cbor_ctx or nrf_rpc_cbor_rsp_ctx that will hold newly allocated resources to encode and send a packet.

  • [in] _len: Requested length of the packet.

NRF_RPC_CBOR_DISCARD(_ctx)

Deallocate memory for a packet.

This macro should be used if memory was allocated, but it will not be sent with any of the send functions.

Parameters

  • _ctx: Packet that was previously allocated.

Typedefs

typedef void (*nrf_rpc_cbor_handler_t)(CborValue *value, void *handler_data)

Callback that handles decoding of commands, events and responses.

Parameters

  • value: TinyCBOR value to decode.

  • handler_data: Custom handler data.

Functions

int nrf_rpc_cbor_cmd(const struct nrf_rpc_group *group, uint8_t cmd, struct nrf_rpc_cbor_ctx *ctx, nrf_rpc_cbor_handler_t handler, void *handler_data)

Send a command and provide callback to handle response.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • group: Group that command belongs to.

  • cmd: Command id.

  • ctx: Context allocated by NRF_RPC_CBOR_ALLOC.

  • handler: Callback that handles the response. In case of error (e.g. malformed response packet was received) it is undefined if the handler will be called.

  • handler_data: Opaque pointer that will be passed to handler.

int nrf_rpc_cbor_cmd_rsp(const struct nrf_rpc_group *group, uint8_t cmd, struct nrf_rpc_cbor_rsp_ctx *ctx)

Send a command and get response as an output parameter.

This variant of command send function outputs response as an output parameter. Caller is responsible to call nrf_rpc_cbor_decoding_done just after response packet was decoded and can be deallocated. ctx->value can be used to decode the response.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • group: Group that command belongs to.

  • cmd: Command id.

  • ctx: Context allocated by NRF_RPC_CBOR_ALLOC.

void nrf_rpc_cbor_cmd_no_err(const struct nrf_rpc_group *group, uint8_t cmd, struct nrf_rpc_cbor_ctx *ctx, nrf_rpc_cbor_handler_t handler, void *handler_data)

Send a command, provide callback to handle response and pass any error to an error handler.

This variant of command send function returns void, so sending error returned from the transport layer is passed to the error handler. Source of error is NRF_RPC_ERR_SRC_SEND.

Parameters

  • group: Group that command belongs to.

  • cmd: Command id.

  • ctx: Context allocated by NRF_RPC_CBOR_ALLOC.

  • handler: Callback that handles the response. In case of error (e.g. malformed response packet was received) it is undefined if the handler will be called.

  • handler_data: Opaque pointer that will be passed to handler.

void nrf_rpc_cbor_cmd_rsp_no_err(const struct nrf_rpc_group *group, uint8_t cmd, struct nrf_rpc_cbor_rsp_ctx *ctx)

Send a command, get response as an output parameter and pass any error to an error handler.

See both nrf_rpc_cbor_cmd_rsp and nrf_rpc_cbor_cmd_no_err for more details on this variant of command send function.

TinyCBOR value will be initialized and invalid if function failed, so cbor_value_is_valid can be used to check failure.

Parameters

  • group: Group that command belongs to.

  • cmd: Command id.

  • ctx: Context allocated by NRF_RPC_CBOR_ALLOC.

int nrf_rpc_cbor_evt(const struct nrf_rpc_group *group, uint8_t evt, struct nrf_rpc_cbor_ctx *ctx)

Send an event.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

  • group: Group that event belongs to.

  • evt: Event id.

  • ctx: Context allocated by NRF_RPC_CBOR_ALLOC.

void nrf_rpc_cbor_evt_no_err(const struct nrf_rpc_group *group, uint8_t evt, struct nrf_rpc_cbor_ctx *ctx)

Send an event and pass any error to an error handler.

This variant of event send function returns void, so sending error returned from the transport layer is passed to the error handler. Source of error is NRF_RPC_ERR_SRC_SEND.

Parameters

  • group: Group that event belongs to.

  • evt: Event id.

  • ctx: Context allocated by NRF_RPC_CBOR_ALLOC.

int nrf_rpc_cbor_rsp(struct nrf_rpc_cbor_ctx *ctx)

Send a response.

Return

0 on success or negative error code if a transport layer reported a sendig error.

Parameters

void nrf_rpc_cbor_rsp_no_err(struct nrf_rpc_cbor_ctx *ctx)

Send a response and pass any error to an error handler.

This variant of response send function returns void, so sending error returned from the transport layer is passed to the error handler. Source of error is NRF_RPC_ERR_SRC_SEND.

Parameters

void nrf_rpc_cbor_decoding_done(CborValue *value)

Indicate that decoding of the input packet is done.

This function must be called as soon as the input packet was parsed and can be deallocated. It must be called in command decoder, event decoder and after nrf_rpc_cbor_cmd_rsp or nrf_rpc_cbor_cmd_rsp_no_err. Packet is automatically deallocated after completetion of the response handler function, so this nrf_rpc_cbor_decoding_done is not needed in response handler.

struct nrf_rpc_cbor_ctx
#include <nrf_rpc_cbor.h>

Context for encoding and sending commands, events and responses.

Initialize it with NRF_RPC_CBOR_ALLOC macro. Only encoder field is significant for the API, other fields are internal.

Public Members

CborEncoder encoder

TinyCBOR encoder.

struct nrf_rpc_cbor_rsp_ctx
#include <nrf_rpc_cbor.h>

Context for encoding commands, sending commands, receiving responses and parsing them.

Initialize it with NRF_RPC_CBOR_ALLOC macro. Only encoder and value fields are significant for the API, other fields are internal.

Public Members

CborEncoder encoder

TinyCBOR encoder for encoding command.

CborValue value

TinyCBOR value for parsing response.