Reality AI Data Shipper (rm_rai_data_shipper)

Functions
fsp_err_t	RM_RAI_DATA_SHIPPER_Open (rai_data_shipper_ctrl_t *const p_api_ctrl, rai_data_shipper_cfg_t const *const p_cfg)
fsp_err_t	RM_RAI_DATA_SHIPPER_Read (rai_data_shipper_ctrl_t *const p_api_ctrl, void *const p_buf, uint32_t *const buf_len)
fsp_err_t	RM_RAI_DATA_SHIPPER_Write (rai_data_shipper_ctrl_t *const p_api_ctrl, rai_data_shipper_write_params_t const *p_write_params)
fsp_err_t	RM_RAI_DATA_SHIPPER_Close (rai_data_shipper_ctrl_t *const p_api_ctrl)

Detailed Description

Middleware to implement the Data Shipper for Reality AI applications. This module implements the Data Shipper Interface.

Overview

RAI Data Shipper is mainly for sending data collected by RAI Data Collector to PC so that they can be used for Reality AI model training. It utilizes the Communicatons Middleware Interface and all communications are fully asynchronous. The data being transported may be any combination of the following:

• Sensor data
• System events/errors
• Debug data and diagnostic information, including RAI runtime output

Sensor data is provided by Data Collector instance via the data ready callback. System events and debug data are prepared by application. A callback is used to notify application that communcation is finished. Sensor data buffers must be released if they are not used. Error flag will be set if there is any error during data transmission.

Note

Debug data, diagnostic information, and associated events are provided for debug purposes only and are not tracked by upstream Reality AI tools.

Features

1. The RAI Data Shipper module supports up to 8 Data Collector instances.
2. The RAI Data Shipper module supports the following interface:
   • RM_COMMS_UART with/without CRC-8
   • RM_COMMS_USB_PCDC with/without CRC-8

Configuration

Build Time Configurations for rm_rai_data_shipper

The following build time configurations are defined in fsp_cfg/rm_rai_data_shipper_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Max Number Of DC Instances	Value must be a positive integer that less than or equal to 8	8	Max number of DC instances to be sent.

Configurations for AI > Data Shipper (rm_rai_data_shipper)

This module can be added to the Stacks tab via New Stack > AI > Data Shipper (rm_rai_data_shipper).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rai_data_shipper0	Module name
Frame Rate Divider	Value must be non-negative	0	Skip write requests
Callback	Name must be a valid C symbol	rai_data_shipper0_callback	A user callback function on data sent or error.

Clock Configuration

This module has no required clock configurations.

Pin Configuration

This module does not use I/O pins.

Limitations

1. 2-way communication hasn't been supported yet - data is always sent from device to host.
2. Users shall take care to avoid race condition in the case of multiple data collector instances.
3. To use RM COMMS USB PCDC with Full Speed mode and DMA, frame buffer length needs to be multiple of 2 when 8-bit channel is used.
4. To use RM COMMS USB PCDC with High Speed mode and DMA, frame buffer length needs to be multiple of 2 when 16-bit channel is used. If 8-bit channel is used, its frame buffer length needs to be a multiple of 4.

Examples

Basic Example

This is a basic example of minimal use of the Data Shipper implementation in an application.

void RM_RAI_DATA_SHIPPER_example();
void data_shipper_callback(rai_data_shipper_callback_args_t * p_args); 

extern rai_data_shipper_cfg_t g_ds_cfg;

extern rai_data_shipper_instance_t g_ds_ctrl;

static bool g_exit = false;                                          

extern bool g_data_ready;                                            
extern rai_data_collector_callback_args_t g_data_ready_callback_arg; 

void RM_RAI_DATA_SHIPPER_example ()
{
    fsp_err_t err;

    err = RM_RAI_DATA_SHIPPER_Open(&g_ds_ctrl, &g_ds_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    while (!g_exit)
    {
        if (g_data_ready)
        {
            rai_data_shipper_write_params_t g_write_params;
            g_write_params.p_sensor_data = &g_data_ready_callback_arg;

            /* Application is responsible to initialize diagnostic information and events.- */
            /* Application has no diagnostic information/events to report. */
            g_write_params.diagnostic_data_len = 0;
            g_write_params.events              = 0;
            g_write_params.p_diagnostic_data   = NULL;
            err = RM_RAI_DATA_SHIPPER_Write(&g_ds_ctrl, &g_write_params);
            assert(FSP_SUCCESS == err);

            g_data_ready = false;
        }
    }

    err = RM_RAI_DATA_SHIPPER_Close(&g_ds_ctrl);
    assert(FSP_SUCCESS == err);
}

/* Called when all sensor data are sent or there is an error */
void data_shipper_callback (rai_data_shipper_callback_args_t * p_args)
{
    if (RM_COMMS_EVENT_ERROR == p_args->result)
    {
        /* Communication error */
    }

    /* Release sensor buffers if they are not being used by any other modules. */
    /* RM_RAI_DATA_COLLECTOR_BufferRelease(g_dc_ctrl); */
}

Data Structures
struct	rai_data_shipper_instance_ctrl_t

---

Data Structure Documentation

rai_data_shipper_instance_ctrl_t

struct rai_data_shipper_instance_ctrl_t

RAI_DATA_SHIPPER instance control block. Initialization occurs when RM_RAI_DATA_SHIPPER_Open() is called.

Function Documentation

RM_RAI_DATA_SHIPPER_Open()

fsp_err_t RM_RAI_DATA_SHIPPER_Open	(	rai_data_shipper_ctrl_t *const	p_api_ctrl,
		rai_data_shipper_cfg_t const *const	p_cfg
	)

Opens and configures the Data Shipper module.

Implements rai_data_shipper_api_t::open().

Return values

FSP_SUCCESS	Data Shipper successfully configured.
FSP_ERR_ALREADY_OPEN	Module already open.
FSP_ERR_ASSERTION	One or more pointers point to NULL or callback is NULL.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

RM_RAI_DATA_SHIPPER_Read()

fsp_err_t RM_RAI_DATA_SHIPPER_Read	(	rai_data_shipper_ctrl_t *const	p_api_ctrl,
		void *const	p_buf,
		uint32_t *const	buf_len
	)

Read data.

Implements rai_data_shipper_api_t::read().

Return values

FSP_ERR_UNSUPPORTED

Data Shipper module read not supported

RM_RAI_DATA_SHIPPER_Write()

fsp_err_t RM_RAI_DATA_SHIPPER_Write	(	rai_data_shipper_ctrl_t *const	p_api_ctrl,
		rai_data_shipper_write_params_t const *	p_write_params
	)

Write data. Note this function may be called in ISR.

Implements rai_data_shipper_api_t::write().

Return values

FSP_SUCCESS	Tx buf list created and transmission starts, or write request skipped.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

RM_RAI_DATA_SHIPPER_Close()

fsp_err_t RM_RAI_DATA_SHIPPER_Close

(

rai_data_shipper_ctrl_t *const

p_api_ctrl

)

Closes Data Shipper module instance.

Implements rai_data_shipper_api_t::close().

Return values

FSP_SUCCESS	Data Shipper module closed.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

Returns

See Common Error Codes or functions called by this function for other possible return codes.