File: crcb_weak.h¶

The Reach stack relies on these callback functions being implemented by the device. The gcc supported “weak” keyword allows us to build without having real implementations. The code supporting the various services are included or excluded via configuration in reach-server.h. The corresponding default implementations of these “weak” functions are found in cr_weak.c.

Author: Chuck Peplinski
Date: 2024-02-21
Copyright: (c) Copyright 2023-2024 i3 Product Development. All Rights Reserved. The Cygngus Reach firmware stack is shared under an MIT license.

Defines

INCLUDE_CLI_SERVICE¶: #define in reach-server.h to include the command line interface service.

INCLUDE_PARAMETER_SERVICE¶: #define in reach-server.h to include the parameter repository service.

NUM_SUPPORTED_PARAM_NOTIFY¶: #define in reach-server.h to specify the number of parameter notifications supported.

INCLUDE_COMMAND_SERVICE¶: #define in reach-server.h to include the command service.

INCLUDE_FILE_SERVICE¶: #define in reach-server.h to include the file service.

INCLUDE_TIME_SERVICE¶: #define in reach-server.h to include the time service.

Functions

int crcb_get_coded_prompt(uint8_t *prompt, size_t *len)¶

crcb_get_coded_prompt

The cr_process function calls this function to get any available prompt in coded format. An overriding implementation is responsible to copy the data into the provided buffer and set the size. Alternatively, cr_store_coded_prompt() can be used to push data into the stack. Then this weak implementation can remain, as the data is already where it belongs. crcb_get_coded_prompt() must not block as that would disable any notifications.

Parameters:

prompt – Pointer to raw data (output)
len – Pointer to the number of bytes in the supplied prompt (output)

Returns:

cr_ErrorCodes_NO_ERROR on success. cr_ErrorCodes_NO_DATA if no data is available.

int crcb_send_coded_response(const uint8_t *response, size_t len)¶

crcb_send_coded_response

The cr_process function calls this function to send responses to the client. Must be overridden to send the data to the client.

Parameters:

response – Pointer to coded data to be send (input)
len – Number of bytes to be sent (input)

Returns:

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

int crcb_device_get_info(const cr_DeviceInfoRequest *request, cr_DeviceInfoResponse *pDi)¶

crcb_device_get_info

Called by the stack in response to a device info request. The device must override the weak implementation to provide a valid device info structure to the stack. Response message members like hash and services are computed by the reach stack.

Parameters:

request – Includes challenge key for access control.
pDi – A pointer to memory provided by the stack to be populated with the basic device information.

Returns:

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

bool crcb_challenge_key_is_valid(void)¶

crcb_challenge_key_is_valid

Called by the stack in various places to check whether access is granted by the challenge key. The access grant here is binary. Finer control based on the specific key is determined by the overriding application specific implementation.

Returns:: true if access is granted.

void crcb_invalidate_challenge_key(void)¶

crcb_invalidate_challenge_key

Called by the stack on disconnect or other condition that warrants invalidating access.

bool crcb_access_granted(const cr_ServiceIds service, const int32_t id)¶

crcb_access_granted

A gateway to access control. Called anywhere that access might be blocked.

Parameters:

service – : Which service to check.
id – : Which ID to check. Negative to check any.

Returns:

true if access is granted.

void crcb_configure_access_control(const cr_DeviceInfoRequest *request, cr_DeviceInfoResponse *pDi)¶

crcb_configure_access_control

Configure the device info response based on the challenge key in the device info request.

Returns:: true if access is granted.

int crcb_ping_get_signal_strength(int8_t *rssi)¶

crcb_ping_get_signal_strength

Called by the stack in response to a ping request. The device can override the weak implementation to provide an

estimate of the signal strength.

Parameters:: rssi – A pointer to be populated with a signal strength typically negative in dB.
Returns:: cr_ErrorCodes_NO_ERROR on success or a non-zero error preferably from the cr_ErrorCodes_ enumeration

int crcb_cli_enter(const char *cli)¶

crcb_cli_enter

When the CLI service is active, the stack can provide the device with remotely entered CLI input by calling crcb_cli_enter(). The device must override the weak implementation to support remote access to the command line.

Parameters:: cli – A string being commanded to the CLI.
Returns:: cr_ErrorCodes_NO_ERROR on success or a non-zero error preferably from the cr_ErrorCodes_ enumeration

void crcb_set_command_line(const char *ins)¶

crcb_set_command_line

store the command line to be parsed elsewhere. When there are both the remote and local command lines, this set and get pair allows one set of functions to handle commands from either source.

Parameters:: ins – A string pointer to be retrieved by crcb_get_command_line
Returns:: none

const char *crcb_get_command_line()¶

crcb_get_command_line

Retrieve the command line stored with crcb_set_command_line(). When there are both the remote and local command lines, this set and get pair allow one set of functions to handle commands from either source.

Returns:: A string pointer stored by crcb_set_command_line().

int crcb_parameter_get_count()¶

crcb_parameter_get_count

returns the number of parameters exposed by this device.

Returns:: Total number of parameter descriptions

int crcb_parameter_discover_reset(const uint32_t pid)¶

crcb_parameter_discover_reset

The overriding implementation must reset a pointer into the parameter table such that the next call to crcb_parameter_discover_next() will return the description of this parameter.

Parameters:: pid – The parameter ID to which the parameter table pointer should be reset. Use 0 for the first entry.
Returns:: cr_ErrorCodes_NO_ERROR on success or a non-zero error like cr_ErrorCodes_INVALID_PARAMETER.

int crcb_parameter_discover_next(cr_ParameterInfo *pDesc)¶

crcb_parameter_discover_next

Gets the parameter description for the next parameter. Allows the stack to iterate through the parameter list. Implies an order in the parameter list that is known by the application, but not directly by the stack. The overriding implementation must post-increment its pointer into the parameter table. Parameter ID’s need not be continuous or in order.

Parameters:: pDesc – Stack provided memory into which the description must be copied.
Returns:: cr_ErrorCodes_NO_ERROR on success or cr_ErrorCodes_INVALID_PARAMETER if the last parameter has already been returned.

int crcb_parameter_ex_get_count(const int32_t pid)¶

crcb_parameter_ex_get_count

returns the number of parameter extension exposed by this device.

Returns:: Total number of parameter extensions

int crcb_parameter_ex_discover_reset(const int32_t pid)¶

crcb_parameter_ex_discover_reset

The overriding implementation must reset a pointer into the parameter extension table such that the next call to crcb_parameter_ex_discover_next() will return the description of this parameter extension.

Parameters:: pid – The parameter ID to which the parameter extension table pointer should be reset. Use 0 for the first entry.
Returns:: cr_ErrorCodes_NO_ERROR on success or a non-zero error like cr_ErrorCodes_INVALID_PARAMETER.

int crcb_parameter_ex_discover_next(cr_ParamExInfoResponse *pDesc)¶

crcb_parameter_ex_discover_next

Gets the parameter extension for the next parameter. Parameter extensions allow more data to be provided about enumerations and bitfields. The overriding implementation must post-increment its pointer into the parameter extension table.

Parameters:: pDesc – Pointer to stack provided memory into which the extension is to be copied.
Returns:: cr_ErrorCodes_NO_ERROR on success or cr_ErrorCodes_INVALID_PARAMETER if the last parameter extension has already been returned.

int crcb_parameter_read(const uint32_t pid, cr_ParameterValue *data)¶

crcb_parameter_read

The overriding implementation allows the stack to access the parameter repository of the device. The parameter descripion of this pid specifying the size and type of the data is known both by the app and the stack.

Parameters:

pid – (input) parameter ID
data – Pointer to stack provided memory into which the parameter data must be copied.

Returns:

cr_ErrorCodes_NO_ERROR on success or an error like

cr_ErrorCodes_INVALID_PARAMETER if the parameter ID is not valid. Also can return cr_ErrorCodes_READ_FAILED or cr_ErrorCodes_PERMISSION_DENIED

int crcb_parameter_write(const uint32_t pid, const cr_ParameterValue *data)¶

crcb_parameter_write

The overriding implementation allows the stack to access the parameter repository of the device. The parameter descripion of this pid specifying the size and type of the data is known both by the app and the stack.

Parameters:

pid – (input) parameter ID
data – Pointer to stack provided memory containing data to be written into the devices parameter repository.

Returns:

cr_ErrorCodes_NO_ERROR on success or an error like

cr_ErrorCodes_INVALID_PARAMETER if the parameter ID is not valid. Also can return cr_ErrorCodes_WRITE_FAILED or cr_ErrorCodes_PERMISSION_DENIED

uint32_t crcb_compute_parameter_hash(void)¶

crcb_compute_parameter_hash

The overriding implementation is to compute a number that will change if the table of parmeter descriptions is changed. This allows the client to cache a large table of parameter descriptions. into the devices parameter repository.

Returns:: cr_ErrorCodes_NO_ERROR on success or an error from the cr_ErrorCodes_ enumeration.

int crcb_parameter_notification_init(const cr_ParameterNotifyConfig **pNoteArray, size_t *pNum)¶

crcb_parameter_notification_init

Called in cr_init() to enable any notifications that the device wishes to be active.

Parameters:

pNoteArray – pointer to an array of cr_ParameterNotifyConfig structures describing the desired notifications.
pNum – How many are in the array.

Returns:

cr_ErrorCodes_NO_ERROR on success or a non-zero error like cr_ErrorCodes_INVALID_PARAMETER.

int crcb_get_command_count()¶

NUM_SUPPORTED_PARAM_NOTIFY >= 0.

INCLUDE_PARAMETER_SERVICE

crcb_get_command_count

The overriding implementation must returns the number of commands implemented by the device.

Returns:: the number of commands implemented by the device.

int crcb_command_discover_reset(const uint32_t cid)¶

crcb_command_discover_reset

The overriding implementation must reset a pointer into the command table such that the next call to crcb_command_discover_next() will return the description of this command.

Parameters:: cid – The ID to which the command table pointer should be reset. 0 for the first command.
Returns:: cr_ErrorCodes_NO_ERROR on success or a non-zero error like cr_ErrorCodes_INVALID_PARAMETER.

int crcb_command_discover_next(cr_CommandInfo *cmd_desc)¶

crcb_command_discover_next

Gets the command description for the next command. The overriding implementation must post-increment its pointer into the command table.

Parameters:: cmd_desc – Pointer to stack provided memory into which the command description is to be copied.
Returns:: cr_ErrorCodes_NO_ERROR on success or cr_ErrorCodes_INVALID_PARAMETER if the last command has already been returned.

int crcb_command_execute(const uint8_t cid)¶

crcb_command_execute

Execute the command associated with this command ID.

Parameters:: cid – command ID.
Returns:: cr_ErrorCodes_NO_ERROR on success or an error from the cr_ErrorCodes_ enumeration if the command fails.

int crcb_file_get_file_count()¶

crcb_file_get_file_count

The overriding implementation must returns the number of files implemented by the device.

Returns:: the number of files implemented by the device.

int crcb_file_discover_reset(const uint8_t fid)¶

crcb_file_discover_reset

The overriding implementation must reset a pointer into the file table such that the next call to crcb_file_discover_next() will return the description of this file.

Parameters:: fid – The ID to which the file table pointer should be reset. use 0 for the first command.
Returns:: cr_ErrorCodes_NO_ERROR on success or a non-zero error like cr_ErrorCodes_INVALID_PARAMETER.

int crcb_file_discover_next(cr_FileInfo *file_desc)¶

crcb_file_discover_next

Gets the description for the next file. The overriding implementation must post-increment its pointer into the file table.

Parameters:: file_desc – Pointer to stack provided memory into which the file description is to be copied.
Returns:: cr_ErrorCodes_NO_ERROR on success or cr_ErrorCodes_INVALID_PARAMETER if the last file has already been returned.

int crcb_file_get_description(uint32_t fid, cr_FileInfo *file_desc)¶

crcb_file_get_description

Get the description matching the file ID.

Parameters:

fid – The ID of the desired file.
file_desc – Pointer to stack provided memory into which the file description is to be copied

Returns:

cr_ErrorCodes_NO_ERROR on success or a non-zero error like cr_ErrorCodes_INVALID_PARAMETER.

int crcb_file_get_preferred_ack_rate(uint32_t fid, uint32_t requested_rate, bool is_write)¶

crcb_file_get_preferred_ack_rate

If the device has a preferred acknowledge rate it can implement this function to advise the file transfer code of the rate. Higher ack rates mean less acknowlegements and faster file trasnfer.

Parameters:

fid – : File ID, in case this affects the decision
requested_rate – might factor into the decison.
is_write – true if enquiring about write.

Returns:

A return value of zero means that there is no preferred rate and the client can specify it.

int crcb_read_file(const uint32_t fid, const int offset, const size_t bytes_requested, uint8_t *pData, int *pBytes_read)¶

crcb_read_file

The device overrides this method to provide data read from the specified file.

Parameters:

fid – (input) which file
offset – (input) offset, negative value specifies current location.
bytes_requested – (input) how many bytes to read
pData – where the (output) data goes
pBytes_read – (output) bytes actually read, negative for errors.

Returns:

returns zero or an error code

int crcb_write_file(const uint32_t fid, const int offset, const size_t bytes, const uint8_t *pData)¶

crcb_write_file

The device overrides this method to accept data for the specified file.

Parameters:

fid – (input) which file
offset – (input) offset, negative value specifies current location.
bytes – (input) how many bytes to write
pData – data from the stack.

Returns:

returns zero or an error code

int crcb_erase_file(const uint32_t fid)¶

crcb_erase_file

The device overrides this method to accept a command to set the length of a file to zero, erasing it. The erase process may take some time the implementation can choose to return cr_ErrorCodes_INCOMPLETE to indicate that the erase command needs to be issued again until it succeeds. Other errors are reported via the result field and its message.

Parameters:: fid – (input) which file
Returns:: returns cr_ErrorCodes_NO_ERROR or cr_ErrorCodes_INCOMPLETE.

int crcb_file_transfer_complete(const uint32_t fid)¶

crcb_file_transfer_complete

Called when the last bytes have been received and a file write is complete.

Parameters:: fid – (input) which file
Returns:: returns zero or an error code

int crcb_file_prepare_to_write(const uint32_t fid, const size_t offset, const size_t bytes_to_write)¶

crcb_file_prepare_to_write

Called when a file write has been requested. Designed to give the app the chance to erase flash memory and setup before receiving the first bytes.

Parameters:

fid – (input) which file
offset – start address of write
bytes_to_write –

Returns:

returns zero or an error code. The stack reacts to an error code.

int crcb_time_get(cr_TimeGetResponse *response)¶

crcb_time_get

Retrieve the device’s idea of the current time. Time is specified in UTC Epoch format, seconds since 1970. More than 32 bits are required to remain valid past 2030.

Parameters:: response – (output) with utc_seconds current time and zone
Returns:: returns zero or an error code

int crcb_time_set(const cr_TimeSetRequest *request)¶

crcb_time_set

Inform the device of the current time to support setting an internal time clock. Time is specified in UTC Epoch format, seconds since 1970. More than 32 bits are required to remain valid past 2030.

Parameters:: request – (input) structure with utc_seconds current time and zone
Returns:: returns zero or an error code

File: crcb_weak.h¶

Cygnus Reach Embedded Stack

Navigation

Related Topics