API documentation

Core API documentation

This API uses pointers to raw packet data. CBOR API documentation provides serialization layer over it using zcbor.

group nrf_rpc

Module to call procedures on a remote processor.

Defines

NRF_RPC_PROTOCOL_VERSION

nRF RPC protocol version.

NRF_RPC_ID_UNKNOWN

Special value to indicate that ID is unknown or irrelevant.

NRF_RPC_GROUP_DEFINE(_name, _strid, _transport, _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.

  • _transport – Group transport. It is used by group to communicate with a remote processor.

  • _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_GROUP_STATUS(_group)

Check group status.

Macro checks whether the group and the transport assigned to it have been initialized.

Parameters:

  • _group – Name of the group.

Typedefs

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

Callback that handles decoding of commands, events and responses.

Param group:

Group that decoder belongs to.

Param packet:

Packet data.

Param len:

Length of the packet.

Param 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 also

NRF_RPC_GROUP_DEFINE

Param id:

Id of the event that was completed.

Param 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 also

NRF_RPC_GROUP_DEFINE

See also

nrf_rpc_init

Param 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.

Parameters:

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

Returns:

0 on success or negative error code.

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.

Parameters:

  • group – Group that command belongs to.

  • cmd – Command id.

  • packet – Packet allocated by nrf_rpc_alloc_tx_buf 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.

Returns:

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

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.

Parameters:

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

  • cmd – [in] Command id.

  • packet – [in] Packet allocated by nrf_rpc_alloc_tx_buf and filled with an encoded data.

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

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

  • rsp_len – [out] Length of rsp_packet.

Returns:

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

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_tx_buf 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:

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

  • cmd – [in] Command id.

  • packet – [in] Packet allocated by nrf_rpc_alloc_tx_buf and filled with an encoded data.

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

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

  • rsp_len – [out] 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.

Parameters:

  • group – Group that event belongs to.

  • evt – Event id.

  • packet – Packet allocated by nrf_rpc_alloc_tx_buf and filled with an encoded data.

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

Returns:

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

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_tx_buf and filled with encoded data.

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

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

Send a response.

Parameters:

  • group – Group that response belongs to.

  • packet – Packet allocated by nrf_rpc_alloc_tx_buf and filled with encoded data.

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

Returns:

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

void nrf_rpc_rsp_no_err(const struct nrf_rpc_group *group, 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:

  • group – Group that response belongs to.

  • packet – Packet allocated by nrf_rpc_alloc_tx_buf and filled with encoded data.

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

void nrf_rpc_decoding_done(const struct nrf_rpc_group *group, 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 completion of the response handler function, so this nrf_rpc_decoding_done is not needed in response handler.

Parameters:

  • group – Group that decoder belongs to.

  • packet – Packet where 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 nRF RPC error handler.

This function allows the serialization layer (such as zcbor) to report errors to the same error handler as nRF RPC.

Parameters:

  • code – Negative error code.

  • src – Source of error.

  • group – Group where error happens 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.

void nrf_rpc_alloc_tx_buf(const struct nrf_rpc_group *group, uint8_t **buf, size_t len)

Allocates buffer for a packet.

Memory is automatically deallocated after packet sending. If not, nrf_rpc_free_tx_buf can be used.

Parameters:

  • group – [in] nRF RPC group

  • buf – [inout] Pointer to allocated packet buffer.

  • len – [in] Requested length of the buffer.

void nrf_rpc_free_tx_buf(const struct nrf_rpc_group *group, uint8_t *buf)

Deallocates Tx buffer.

It should be used only if packet was allocated but it is not sent by any transport.

Parameters:

  • group – [in] nRF RPC group.

  • buf – [in] Previously allocated buffer for Tx packet.

struct nrf_rpc_group_data
#include <nrf_rpc.h>

Group data structure. It contains no constant group data.

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.

CBOR 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 zcbor.

group nrf_rpc_cbor

A module that simplifies the usage of zcbor for serializing nRF RPC.

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(_group, _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:

  • _group – [in] nRF RPC group.

  • _ctx – [out] 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.

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

NRF_RPC_CBOR_DISCARD(_group, _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:

  • _group – nRF RPC group, used for allocation.

  • _ctx – Packet that was previously allocated.

Typedefs

typedef void (*nrf_rpc_cbor_handler_t)(const struct nrf_rpc_group *group, struct nrf_rpc_cbor_ctx *ctx, void *handler_data)

Callback that handles decoding of commands, events and responses.

Param group:

nRF RPC group.

Param ctx:

CBOR decoding context

Param handler_data:

Custom handler data.

Functions

bool nrf_rpc_cbor_is_alloc(struct nrf_rpc_cbor_ctx *ctx)

Check that the memory for a packet has been allocated.

Parameters:
Returns:

true if memory is valid otherwise false.

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.

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.

Returns:

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

int nrf_rpc_cbor_cmd_rsp(const struct nrf_rpc_group *group, uint8_t cmd, struct nrf_rpc_cbor_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.

Parameters:

  • group – Group that command belongs to.

  • cmd – Command id.

  • ctx – Context allocated by NRF_RPC_CBOR_ALLOC.

Returns:

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

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_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.

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.

Parameters:

  • group – Group that event belongs to.

  • evt – Event id.

  • ctx – Context allocated by NRF_RPC_CBOR_ALLOC.

Returns:

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

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(const struct nrf_rpc_group *group, struct nrf_rpc_cbor_ctx *ctx)

Send a response.

Parameters:

  • group – Group that response belongs to.

  • ctx – Context allocated by NRF_RPC_CBOR_ALLOC.

Returns:

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

void nrf_rpc_cbor_rsp_no_err(const struct nrf_rpc_group *group, 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:

  • group – Group that response belongs to.

  • ctx – Context allocated by NRF_RPC_CBOR_ALLOC.

void nrf_rpc_cbor_decoding_done(const struct nrf_rpc_group *group, struct nrf_rpc_cbor_ctx *ctx)

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 completion of the response handler function, so this nrf_rpc_cbor_decoding_done is not needed in response handler.

Parameters:

  • group – Group that response belongs to.

  • ctx – Context allocated by NRF_RPC_CBOR_ALLOC.

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.