File: cr_stack.h

This file exposes the core of the public Reach stack API. It depends on reach-server.h which defines what parts of the stack are being used by an applicaiton. crcb_weak.h is incluced. That is the part of the API that must be implemented by a server application.

Author

Chuck Peplinski

Date

2024-01-24

Copyright

(c) Copyright 2023 i3 Product Development. All Rights Reserved. The Cygngus Reach firmware stack is shared under an MIT license.

Defines

MAX_NUM_PARAM_ID

The largest acceptable parameter ID is 16 bits.

CR_STACK_VERSION_LEN

The length of the version string.

Functions

int cr_init()

cr_init

To be called before starting the stack.

Returns:

cr_ErrorCodes_NO_ERROR or a non-zero error like cr_ErrorCodes_.

int cr_set_advertised_name(char *name, int length)

cr_set_advertised_name

Sets the name of the device that should be advertised before connecting. Used in BLE. The length of the string is set by APP_ADVERTISED_NAME_LENGTH which can be define in the application. See reach-server.h. Uses REACH_SHORT_STRING_LEN when APP_ADVERTISED_NAME_LENGTH is not defined. The code setting up the communication link can retrieve this using cr_get_advertised_name().

Returns:

cr_ErrorCodes_NO_ERROR or a non-zero error code.

const char *cr_get_advertised_name()

cr_get_advertised_name

Retrieves the name stored by cr_set_advertised_name().

Returns:

pointer to a string of length REACH_SHORT_STRING_LEN.

int cr_process(uint32_t ticks)

cr_process

The application must call cr_process() regularly as it does most of the work required of Reach. The ticks parameter is expected to be a monotonically increasing value representing the time since the system started. This allows it to perform timing related tasks such as notifications. cr_process() returns immediately if the device is not connected to BLE.

Parameters:

ticks – A measure of time passed, typically milliseconds, but the units are not specified.

Returns:

cr_ErrorCodes_NO_ERROR or a non-zero error code, however these are indicative only. The non-zero returns indicate normal conditions.

int cr_store_coded_prompt(uint8_t *data, size_t len)

cr_store_coded_prompt

Allows the application to store the prompt where the Reach stack can see it. The byte data and length are copied into private storage. This data is retrieved using crcb_get_coded_prompt().

Parameters:

• data – The coded prompt to be stored.

• len – : number of bytes to be stored.

Returns:

cr_ErrorCodes_NO_ERROR or a non-zero error code.

int cr_get_coded_response_buffer(uint8_t **pResponse, size_t *len)

cr_get_coded_response_buffer

Retrieve the adress of the “coded response buffer”. This buffer contains the response to a prompt, coded according to protobuf specs, to be transmitted to the client. The stored coded length is zeroed by this call.

Parameters:

• ppResponse – Pointer to pointer to bytes.

• pLen – : pointer to the number of bytes for transmission.

Returns:

cr_ErrorCodes_NO_ERROR or a non-zero error code.

void cr_report_error(int error_code, const char *fmt, ...)

cr_report_error

Report an error condition to the client. This can be called at any point as the report to the client is asynchronous and immediate. The stack can be configured to use only the error code, but the printf-like string describing the error condition is encouraged. This is intended to make it easier to find and eliminate errors during development.

Parameters:

• error_code – : Use of the cr_ErrorCodes_ enum is encouraged but not required.

• fmt – : A printf-like string with variables.

int cr_notify_stream(cr_StreamData *data)

cr_notify_stream

Called by crcb_stream_read().

Parameters:

data – Pointer to a stream notification structure.

Returns:

cr_ErrorCodes_NO_ERROR on success or a non-zero error preferably from the cr_ErrorCodes_ enumeration

void cr_set_comm_link_connected(bool connected)

cr_set_comm_link_connected

The communication stack must inform the Reach stack of the status of the communication link. The integration must inform Reach when the connection status changes. The Reach loop only runs when the connection is valid. All parameter notifications are cleared when a connection is established. The client must reenable notifications on each connection.

Parameters:

connected – true if connected.

bool cr_get_comm_link_connected(void)

cr_get_comm_link_connected

Returns what was set using cr_set_comm_link_connected().

Returns:

true if the communication link is connected.

void cr_clear_param_notifications(void)

cr_clear_param_notifications

Disable all parameter notifications.

void cr_init_param_notifications(void)

cr_init_param_notifications

Enable all locally specified parameter notifications via crcb_parameter_notification_init().

void cr_get_notification_statistics(uint32_t *numActive, uint32_t *numSent)

cr_get_notification_statistics

numSent is zeroed by each call.

Parameters:

• numActive –

  is populated with the number of

  notifications currently enabled.a

• numSent – is populated with the number of notifications sent since last called.

uint32_t cr_get_current_ticks()

cr_get_current_ticks

The tick count is passed in to cr_process(). This function gives other Reach functions access to that value.

Returns:

The same tick count passed into cr_process().

void cr_test_sizes()

Verify that buffer structures fit into limited size memory

const char *cr_get_reach_version()

cr_get_reach_version

The version is in semantic version format: MAJOR.MINOR.PATCH with an optional string appended.

Returns:

Returns a pointer to a null terminated string containing the C stack version.

const char *cr_get_proto_version()

cr_get_proto_version

The version is in semantic version format: MAJOR.MINOR.PATCH with an optional string appended.

Returns:

Returns a pointer to a null terminated string containing the C protobuf version.

struct reach_sizes_t

#include <cr_stack.h>

The reach_sizes_t is used to communicate the sizes of device structures to clients. These sizes can vary from one server to another and the client is required to respect these sizes. Many of them are determined by the chosen communication link, such as BLE. reach_sizes_t uses smaller member sizes that the uint32 favored by protobufs. Hence it communicates these sizes without blowing up the size of the device info packet. Refer also to enum SizesOffsets reach.proto and sCr_populate_device_info_sizes() which populates the structure.

Public Members

uint16_t max_message_size

The largest message that can be communicated

uint16_t big_data_buffer_size

The size of the buffer most of the packet is one string.

uint8_t parameter_buffer_count

The number of parameter buffers kept by the device. This determines the number of parameters that can be handled in a single message.

uint8_t num_params_in_response

The number of parameter values that fit in one message.

uint8_t description_len

The length of the device and command description fields.

uint8_t max_param_bytes

The number of bytes in the largest parameter types eg, strings and byte array.

uint8_t param_info_description_len

Length of the text string for parameter info description.

uint8_t medium_string_len

The length of longer strings.

uint8_t short_string_len

The number of bytes in short strings like the units label.

uint8_t param_notify_config_count

The max number of parameter notification configurations that a client can provide in a message.

uint8_t num_descriptors_in_response

number of descriptors (stream, file) that fit in one message.

uint8_t num_param_notifications

Number of parameter notifications supported.

uint8_t num_commands_in_response

number of commands that can be in one info packet

uint8_t num_param_desc_in_response

number of parameter descriptions that can be in one info packet.