Reality AI Data Collector (rm_rai_data_collector)

Functions
fsp_err_t	RM_RAI_DATA_COLLECTOR_Open (rai_data_collector_ctrl_t *const p_api_ctrl, rai_data_collector_cfg_t const *const p_cfg)
fsp_err_t	RM_RAI_DATA_COLLECTOR_SnapshotChannelRegister (rai_data_collector_ctrl_t *const p_api_ctrl, uint8_t channel, void const *p_src)
fsp_err_t	RM_RAI_DATA_COLLECTOR_BufferReset (rai_data_collector_ctrl_t *const p_api_ctrl)
fsp_err_t	RM_RAI_DATA_COLLECTOR_BufferRelease (rai_data_collector_ctrl_t *const p_api_ctrl)
fsp_err_t	RM_RAI_DATA_COLLECTOR_ChannelBufferGet (rai_data_collector_ctrl_t *const p_api_ctrl, uint8_t channel, void **pp_buf)
fsp_err_t	RM_RAI_DATA_COLLECTOR_ChannelWrite (rai_data_collector_ctrl_t *const p_api_ctrl, uint8_t channel, const void *p_buf, uint32_t len)
fsp_err_t	RM_RAI_DATA_COLLECTOR_SnapshotStart (rai_data_collector_ctrl_t *const p_api_ctrl)
fsp_err_t	RM_RAI_DATA_COLLECTOR_SnapshotStop (rai_data_collector_ctrl_t *const p_api_ctrl)
fsp_err_t	RM_RAI_DATA_COLLECTOR_Close (rai_data_collector_ctrl_t *const p_api_ctrl)

Detailed Description

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

Overview

Data Collector is to abstract the collection of data from sensors so that data samples are accumulated into fixed length frames before being made available to application. Support of "snapshot" mode and "data feed" mode are required to accommodate for background and cooperative data collection. Each mode supports 8 sensor channels maximally. Each sensor channel will be captured into a separate frame buffer. Frame buffers shall have the same amount of data samples, however, data type can be different(int32_t, float, uint8_t etc). Users have to make sure that frame buffers will be filled up at the same rate.

When all frame buffers are filled up, they will be provided to the application via data ready callback. After they are consumed, application has to release them by calling RM_RAI_DATA_COLLECTOR_BufferRelease(). For seamless operation, PING-PONG buffer will be used. Ideally buffers will be released before the other set of buffers are filled up. However, it is possible that frame buffers will overrun due to the fact that application may take longer time to process the data in some cases. If it happens, application will be notified with a buffer-overrun event via the error callback. No intervention is required from user side in this case. Buffer overrun will disappear when frame buffers are released. However, if not all sensor channels are configured to work at the same pace, application will get a buffer-out-of-sync error. Users have to reconfigure sensor channels and ensure all of them will work at the same pace. If sensor channels can't work at the same rate, then multiple data collector instances are required.

Features

• Snapshot mode and data feed mode are supported
• Maximally 8 sensors are supported for each mode
• Mix mode is supported(both snapshot mode and data feed mode are enabled)

Snapshot Mode

Snapshot mode will periodically pull data from the user-specified places and save to designated frame buffers. It requires a DTC module and a timer module. DTC will work in chain mode, which enables data collection from various, potentially non-linear and different-sized sources. Timer, either General PWM Timer (GPT) or Asynchronous General Purpose Timer, provides activation source for DTC to work periodically. To select this activation source, relevant interrupt has to be configured in the timer module. Application has to start the timer to enable DTC after sensor source addresses are registered.

Data Feed Mode

Data feed mode will require data producer to push data directly to the designated frame buffer whenever data is ready. Data can be pushed synchronously or asynchronously. Synchronous mode is for use cases that the data producer has a short amount of data to be copied to the frame buffer. Asynchronous mode is to use DTC/DMAC for data transfer. Application has to add DTC/DMAC modules and initialize transfer descriptors for asynchronous transfer.

Usage Notes

1. Do not use the DTC stack and timer stack of the data collector instance for data feed mode.
2. Users must take care to make sure all channels of a data collector instance will work at the same pace.
3. Priority Interrupt level of Timer stack in a Data collector instance must be higher (numerically lower) than that of RM COMMS USB PCDC GPT Overflow interrupt.

Configuration

Build Time Configurations for rm_rai_data_collector

The following build time configurations are defined in fsp_cfg/rm_rai_data_collector_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 Channels	Value must be a positive integer less than or equal to 16	16	Max number of channels.

Configurations for AI > Data Collector (rm_rai_data_collector)

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

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_rai_data_collector0	Module name.
ID	Value must be a positive integer.	0	Instance ID
Frame Buffer Length	Value must be a positive integer greater than 0	100	Length of frame buffers in data samples.
Data Ready Callback	Name must be a valid C symbol	rai_data_collector0_callback	Callback function on data ready.
Error Callback	Name must be a valid C symbol	rai_data_collector0_error_callback	Callback function for error events.
Data Feed Mode
Data Feed Mode > Channel 0
Name	Must be valid C variable name	dc0_data_feed_ch0	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 1
Name	Must be valid C variable name	dc0_data_feed_ch1	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 2
Name	Must be valid C variable name	dc0_data_feed_ch2	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 3
Name	Must be valid C variable name	dc0_data_feed_ch3	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 4
Name	Must be valid C variable name	dc0_data_feed_ch4	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 5
Name	Must be valid C variable name	dc0_data_feed_ch5	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 6
Name	Must be valid C variable name	dc0_data_feed_ch6	Channel name
Data Type	MCU Specific Options		Channel Data Type
Data Feed Mode > Channel 7
Name	Must be valid C variable name	dc0_data_feed_ch7	Channel name
Data Type	MCU Specific Options		Channel Data Type
Channels	Value must be an integer between 0 and 8	0	Number of Data Feed Mode channels.
Snapshot Mode
Snapshot Mode > Channel 0
Name	Must be valid C variable name	dc0_snapshot_ch0	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 1
Name	Must be valid C variable name	dc0_snapshot_ch1	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 2
Name	Must be valid C variable name	dc0_snapshot_ch2	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 3
Name	Must be valid C variable name	dc0_snapshot_ch3	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 4
Name	Must be valid C variable name	dc0_snapshot_ch4	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 5
Name	Must be valid C variable name	dc0_snapshot_ch5	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 6
Name	Must be valid C variable name	dc0_snapshot_ch6	Channel name
Data Type	MCU Specific Options		Channel Data Type
Snapshot Mode > Channel 7
Name	Must be valid C variable name	dc0_snapshot_ch7	Channel name
Data Type	MCU Specific Options		Channel Data Type
Channels	Value must be an integer between 0 and 8	0	Number of snapshot mode channels.
DTC Transfer Count	Value must be a positive integer greater than 0	1	DTC transfer count on each activation

Clock Configuration

This module has no required clock configurations.

Pin Configuration

This module does not use I/O pins.

Examples

Snapshot Mode Example

void rm_rai_data_collector_snapshot_mode_example ()
{
    fsp_err_t err;

    err = RM_RAI_DATA_COLLECTOR_Open(&g_dc_ctrl, &g_dc_cfg);

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

    for (uint8_t i = 0; i < DC_TEST_CHAN_COUNT; i++)
    {
        RM_RAI_DATA_COLLECTOR_SnapshotChannelRegister(&g_dc_ctrl, i, g_sensor_buf[i]);
        assert(FSP_SUCCESS == err);
    }

    err = RM_RAI_DATA_COLLECTOR_SnapshotStart(&g_dc_ctrl);
    assert(FSP_SUCCESS == err);

    do
    {
        /* Process error event */
        if (RAI_DATA_COLLECTOR_ERROR_TYPE_BUF_OUT_OF_SYNC & g_dc_error_event)
        {
            /* Error! Please reconfigure sensors to make sure they all work at the same pace.*/

            g_dc_error_event = RAI_DATA_COLLECTOR_ERROR_TYPE_NONE;
        }

        if (g_data_ready)
        {
            /* Process collected data saved in g_frame_buf. */
            do_data_process(g_data_ready_callback_arg.instance_id,
                            g_data_ready_callback_arg.frames,
                            g_data_ready_callback_arg.frame_buf_len,
                            g_data_ready_callback_arg.p_frame_buf);

            g_data_ready = false;

            /* Release buffer when done */

            RM_RAI_DATA_COLLECTOR_BufferRelease(&g_dc_ctrl);
        }
    } while (!g_exit);

    err = RM_RAI_DATA_COLLECTOR_SnapshotStop(&g_dc_ctrl);
    assert(FSP_SUCCESS == err);

    err = RM_RAI_DATA_COLLECTOR_Close(&g_dc_ctrl);
    assert(FSP_SUCCESS == err);
}

Data Structures
struct	rai_data_collector_instance_ctrl_t

---

Data Structure Documentation

rai_data_collector_instance_ctrl_t

struct rai_data_collector_instance_ctrl_t

RAI_DATA_COLLECTOR instance control block. Initialization occurs when RM_RAI_DATA_COLLECTOR_Open() is called.

Function Documentation

RM_RAI_DATA_COLLECTOR_Open()

fsp_err_t RM_RAI_DATA_COLLECTOR_Open	(	rai_data_collector_ctrl_t *const	p_api_ctrl,
		rai_data_collector_cfg_t const *const	p_cfg
	)

Opens and configures the Data Collector module.

Implements rai_data_collector_api_t::open().

Return values

FSP_SUCCESS	Data Collector 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_COLLECTOR_SnapshotChannelRegister()

fsp_err_t RM_RAI_DATA_COLLECTOR_SnapshotChannelRegister	(	rai_data_collector_ctrl_t *const	p_api_ctrl,
		uint8_t	channel,
		void const *	p_src
	)

Config transfer src address for snapshot mode channel

Implements rai_data_collector_api_t::snapshotChannelRegister().

Return values

FSP_SUCCESS	Src addresses are set.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

RM_RAI_DATA_COLLECTOR_BufferReset()

fsp_err_t RM_RAI_DATA_COLLECTOR_BufferReset

(

rai_data_collector_ctrl_t *const

p_api_ctrl

)

Reset to discard accumulated data and start with PING buffer.

Note

Application must stop data transfer on all channels first.

Implements rai_data_collector_api_t::bufferReset().

Return values

FSP_SUCCESS	Data Collector module internal buffers reset.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

RM_RAI_DATA_COLLECTOR_BufferRelease()

fsp_err_t RM_RAI_DATA_COLLECTOR_BufferRelease

(

rai_data_collector_ctrl_t *const

p_api_ctrl

)

Release frame buffer

Implements rai_data_collector_api_t::bufferRelease().

Return values

FSP_SUCCESS	Buffer released.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

RM_RAI_DATA_COLLECTOR_ChannelBufferGet()

fsp_err_t RM_RAI_DATA_COLLECTOR_ChannelBufferGet	(	rai_data_collector_ctrl_t *const	p_api_ctrl,
		uint8_t	channel,
		void **	pp_buf
	)

Get channel destination buffer address for asynchronous data transfer.

Implements rai_data_collector_api_t::channelBufferGet().

Return values

FSP_SUCCESS	Buffer avaialble.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

RM_RAI_DATA_COLLECTOR_ChannelWrite()

fsp_err_t RM_RAI_DATA_COLLECTOR_ChannelWrite	(	rai_data_collector_ctrl_t *const	p_api_ctrl,
		uint8_t	channel,
		const void *	p_buf,
		uint32_t	len
	)

Synchronouse data transfer using CPU copy.

Implements rai_data_collector_api_t::channelWrite().

Return values

FSP_SUCCESS	Data copy completed.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.

RM_RAI_DATA_COLLECTOR_SnapshotStart()

fsp_err_t RM_RAI_DATA_COLLECTOR_SnapshotStart

(

rai_data_collector_ctrl_t *const

p_api_ctrl

)

Starts snapshot mode channels

Implements rai_data_collector_api_t::snapshotStart().

Return values

FSP_SUCCESS	Snapshot mode started.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.
FSP_ERR_UNSUPPORTED	No snapshot mode channel

Returns

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

RM_RAI_DATA_COLLECTOR_SnapshotStop()

fsp_err_t RM_RAI_DATA_COLLECTOR_SnapshotStop

(

rai_data_collector_ctrl_t *const

p_api_ctrl

)

Stops snapshot mode channels

Implements rai_data_collector_api_t::snapshotStop().

Return values

FSP_SUCCESS	Snapshot mode stopped.
FSP_ERR_ASSERTION	An input parameter was invalid.
FSP_ERR_NOT_OPEN	Module not open.
FSP_ERR_UNSUPPORTED	No snapshot mode channel

Returns

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

RM_RAI_DATA_COLLECTOR_Close()

fsp_err_t RM_RAI_DATA_COLLECTOR_Close

(

rai_data_collector_ctrl_t *const

p_api_ctrl

)

Closes Data Collector module instance.

Implements rai_data_collector_api_t::close().

Return values

FSP_SUCCESS	Data Collector 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.