GRC AI Module SDK Developer Guide

Overview

GRC AI module – is a software designed to perform classification and class recognition tasks. Functionality includes:

AI SW on-device learning
parameters configuration
class recognition
classification
saving and loading a pre-trained model GRC_SDK serves as a communication interface for GRC AI module over I2C bus.

GRC_SDK has several abstraction layers:

Transport layer – a platform-dependent interface to work with I2C bus. It provides basic functions: configuring, reading and writing (see drivers);
Protocol layer – a protocol for function remote call on GRC implemented over transport layer (see protocol_layer);
Application layer – high-layer interface for calling GRC function.

Use Cases

The basic GRC AI SW scenario includes parameter configuration, learning, and category classification based on data.

#include "grc/grc.h"

// === 1. Driver’s Initialization ===
struct grc_ll_i2c_dev ll_dev = {
    //constant for selecting communication type
    .type = <PROTOCOL_INTERFACE_I2C>, //PROTOCOL_INTERFACE_I2C_ESP32 or PROTOCOL_INTERFACE_I2C_ARDUINO
    .sda_io_num = <SDA PIN>,
    .scl_io_num = <SCL PIN>,
    .data_ready_io_num = <DATA READY PIN>,
    .i2c_num = <I2C PORT>,
    .clk_speed = 400000,
    .slave_addr = 0x36,
    .timeout_us = 1000
  };
struct grc_device dev = {.ll_dev = &ll_dev, .version = {0, 0, 0}};

// GRC AI SW configuration
const int configuration_bytes_len;
const uint8_t configuration_bytes[];

int result = grc_init(&dev, configuration_bytes, configuration_bytes_len);

// === 2. (Optional) Configuring GRC AI SW Parameters  ===
int ai_params_len = 6;

struct hp_setup ai_params[ai_params_len];
  ai_params[0].type = PREDICT_SIGNAL;
  ai_params[0].value = 1;
  ai_params[1].type = SEPARATE_INACCURACIES;
  ai_params[1].value = 0;
  ai_params[2].type = NOISE;
  ai_params[2].value = 0.001;
  ai_params[3].type = INPUT_SCALING;
  ai_params[3].value = 0.5;
  ai_params[4].type = FEEDBACK_SCALING;
  ai_params[4].value = 0.001;
  ai_params[5].type = THRESHOLD_FACTOR;
  ai_params[5].value = 1;
result = grc_set_params(&dev, ai_params, ai_params_len);

// === 3. Preparing for Classification ===
//--- 3.a Training ---.
struct grc_training_params train_params;
train_params.flags = GRC_PARAMS_ADD_NEW_TAG;
float *train_data;
uint32_t train_data_len;

result = grc_train(&dev, &train_params, train_data, train_data_len);

// === 4. Classification ===
struct grc_inference_params inference_params;
float *inference_data;
unsigned inference_data_len;
int result_category = grc_inference(&dev, &inference_params, train_data, train_data_len);

// === 5. Clearing AI SW State===
result = grc_clear_state(&dev);

// === 6.  Driver’s De-initialization ===
result = grc_release(&dev);

To avoid training every time, a model can be pre-trained, and the result will be saved for further usage.

// === 3b.1. Training and Saving a Model ===
struct grc_training_params train_params;
float *train_data;
uint32_t train_data_len;

result = grc_train(&dev, &train_params, train_data, train_data_len);

// ---------- Save in memory of the Host device ------
struct grc_internal_state *internal_states;
uint32_t internal_states_len;
result = grc_download(&dev, &internal_state, &internal_states_len);

// ---------- or in the GRC internal memory----------
result = grc_store(&dev);
// Afterwards, the model can be loaded to GRC

// === 3b.2 Loading a pre-trained model ===
// ------------- from Host device memory ----------
result = grc_upload(&dev, internal_states, internal_states_len);
// ------------- or from GRC internal memory --------
result = grc_restore(&dev);

Methods

Device Configuration

Initialization of interface dev (grc_device) and configuration of AI SW ( configuration array bytes of len ). In dev->version will be put SDK version of GRC device.

Returns 0 in case of success or an error code (<0)

int grc_init(
     struct grc_device* dev,
     const uint8_t *bytes,
     const int len);

Releasing resources occupied by driver. Returns 0 in case of success or an error code (<0)

int grc_release(struct grc_device* dev);

Reset grc device(if reset pin is specified)

Returns 0 in case of success or an error code (<0)

int grc_device_reset(struct grc_device* dev);

AI SW parameters tune

AI SW can be tuned with parameters array hp (hp_setup) of len length

Returns 0 in case of success or an error code (<0)

int grc_set_params(
    struct grc_device* dev,
    struct hp_setup* hp,
    int len);

Training GRC on raw data

params – training parameters (grc_training_params )
vals – pointer to training data
len – array length In SYNC mode returns id of the trained class (>=0) in case of success or an error code (<0) In ASYNC returns performance status: 0 in case of success, or <0 in case of error. For getiing trained class use grc_wait and grc_get_train_result (recommended) or pass callback in params

int grc_train(
    struct grc_device* dev,
    struct grc_training_params* params,
    float* vals,
    uint32_t len);

Deletion of a trained class with the tag defined in info (grc_class_info). Returns id of the deleted class (>=0) in case of success or an error code (<0)

 int grc_clear_class_by_tag(
    struct grc_device* dev,
    grc_class_tag_t tag);

Resetting to AI SW default settings. Returns performance status: 0 in case of success, or <0 in case of error

int grc_clear_state(struct grc_device* dev)

Detection / classification

Inference on raw data:

params – inference parameters (grc_inference_params )
vals – pointer to training data
len – array length

In SYNC mode returns id of the trained class (>=0) in case of success or an error code (<0). -1 – failed to determine a class

In ASYNC returns performance status: 0 in case of success, or <0 in case of error. For getting trained class use grc_wait and grc_get_inference_result (recommended) or pass callback in params

int grc_inference(
    struct grc_device* dev,
    struct grc_inference_params* params,
    float* vals,
    uint32_t len);

Async mode

To activate async mode for train or inference GRC_PARAMS_ASYNC flag should be used

params.flag ^= GRC_PARAMS_ASYNC;

There is two options of using async mode: with callback or with wait/get_result

To use async mode with callback it should be specified in params. The callback will be called on get result class idx or error code

params.callback = <callback function>;

If callback was waiting too long or not need anymore it can be canceled

int grc_reset_async();

Wait till inference or training ends or timeout

timeout - time in milliseconds to wait. If time is up ERROR_GRC_ASYNC_TIMEOUT error code will be returned

int grc_wait(struct grc_device* dev, int timeout);

Getting result of async function execution end (grc_wait succeed)

Returns trained class id(>= 0) or error code (<0)

int grc_get_train_result(struct grc_device *dev);
int grc_get_inference_result(struct grc_device *dev);

Information about AI SW

Returns the number of trained classes (>=0) or an error code (<0)

int grc_get_classes_number(struct grc_device* dev);

Forming class information with index in structure info Returns id (>=0) in case of success or an error code (<0)

int grc_get_class_info_by_index(
    struct grc_device * dev,
    uint32_t index,
    struct grc_class_info * info);

Forming class information with tag in structure info Returns id (>=0) in case of success or an error code (<0)

int grc_get_class_info_by_tag(
    struct grc_device* dev,
    grc_class_tag_t tag,
    struct grc_class_info* info);

Saving / Loading AI SW

Placing information (grc_internal_state) about each len class into states array. Returns the number of classes trained on GRC (>= 0) in case of success or an error code (<0).

int grc_download(
    struct grc_device* dev,
    grc_internal_state** states,
    uint32_t* len)

Loading the information (grc_internal_state) about each len class into states array. Returns 0 in case of success or an error code (<0).

int grc_upload(
    struct grc_device* dev,
    grc_internal_state* states,
    uint32_t len);

Saving current state of AI SW into GRC internal memory. Returns 0 in case of success or an error code (<0).

int grc_store(struct grc_device* dev);

Restoring AI SW state from GRC internal memory. Returns 0 in case of success or an error code (<0).

int grc_restore(struct grc_device* dev);

Error Codes

Error codes at protocol layer

Error	Error code	Meaning
GRC_OK	0	Function works correctly
NOT_CLASSIFIED	-1	Data belong to none of the classes
ERROR_I2C	-2	Transport layer error
ERROR_SDK_WRONG_ARGUMENTS	-3	Argument layer error. E.g., negative values in configuration of GRC AI SW architecture, incorrect flags, an attempt to set up a non-existenthp (hp_setup) parameter, an attempt to classify data as a non-existent class
ERROR_GRC_WRONG_ANSWER	-4	Fails to interpret GRC response
ERROR_GRC_IS_BUSY	-5	GRC cannot start performing a new function while the previous one is still running
ERROR_SDK_DATA_NOT_DELIVERED	-6	Data have not been delivered to GRC
ERROR_SDK_NOT_IMPLEMENTED	-7	The functionality is yet to be implemented
ERROR_SDK_VERSION_MISMATCH	-8	The GRC_SDK version does not match the GRC firmware version
ERROR_GPIO	-9
ERROR_ISR_INSTALL	-10	Failed to setup ISR handler for DATA_READY_PIN
ERROR_SDK_WRONG_API_USAGE	-11	GRC_SDK was not init or grc is busy executing async function
ERROR_GRC_ASYNC_TIMEOUT	-12	waiting result of async function too long

Error code, which are returned by remote functions

Error	Error code	Meaning
ERROR_REMOTE_FUNCTION_CALL	-20
ERROR_REMOTE_FUNCTION_CALL_INVAL_STATE	-21	grc was not initialized
ERROR_REMOTE_FUNCTION_CALL_INVAL_PARAM	-22	wrong class idx or tag, or unknown parameter to setup
ERROR_REMOTE_FUNCTION_CALL_INVAL_DATA_LEN	-23	len of train or inference data does not match to configuration
ERROR_REMOTE_FUNCTION_CALL_NOT_CALLED	-24	something went wrong during prepare function arguments
ERROR_REMOTE_FUNCTION_CALL_NOT_IMPLEMENTED	-25	function not implemented on grc. maybe sdk version mismatch
ERROR_REMOTE_FUNCTION_CALL_STORAGE_ERROR	-26	grc could not read from or write to local storage

Structures

grc_device

Description of the remote GRC AI SW device.

Field	Description
void* ll_dev	Information about used driver (grc_ll_i2c_dev_esp32 or grc_ll_i2c_dev_arduino)
struct grc_sdk_version version	GRC firmware version. It is set up during interface initialization call

The latest sdk version is 0.4.*

grc_sdk_version

structure to store sdk major, minor and patch version.

Field	Description
uint32_t version_maj	major version
uint32_t version_min	minor version
uint32_t version_patch	patch version

grc_ll_i2c_dev_esp32

GRC AI SW driver parameters

Field	Description
uint32_t type	Remote connection type (I2C/SPI/UART). For I2C PROTOCOL_INTERFACE_I2C value is used
int sda_io_num	SDA pin
int scl_io_num	SCL pin
int data_ready_io_num	Date readiness interrupt pin
int reset_io_num	pin to reset GRC device
int i2c_num	I2C port
uint32_t clk_speed	Clock frequency for I2C master (not greater than 400KHz)
uint16_t slave_addr	GRC device address
uint32_t timeout_us	GRC response waiting time in milliseconds

hp_setup

Structure for configuring classification parameters

Field	Description
hyperparam_types type	Parameter configuration
float value	Value of the configured parameter

hyperparam_types

Field	Description
PREDICT_SIGNAL	Takes value 1 or 0
SEPARATE_INACCURACIES	Takes value 1 or 0
NOISE
INPUT_SCALING
FEEDBACK_SCALING
THRESHOLD_FACTOR

GRC_PARAMS

PArams to configure train and inference functions

Filed	Description
GRC_PARAMS_ASYNC	if set then run function in asynchronous mode
GRC_PARAMS_OVERWRITE	(train only) allows to train the tag again
GRC_PARAMS_SINGLE_CLASS	(inference only) if set then run inference in anomaly detection mode (defines belonging to a specific class)
GRC_PARAMS_ADD_NEW_TAG	(train only) allows not specify tag for train and just create new one. Allows to use only class idx-s and ignore tags

grc_training_params

Field	Description
uint32_t flags	Allow/Forbid overwriting the existing class with this tag (GRC_PARAMS_OVERWRITE). Perform synchronously or asynchronously (GRC_PARAMS_ASYNC). Train a class with the tag or create a new tag(GRC_PARAMS_ADD_NEW_TAG)
grc_class_tag_t tag	Class name
grc_callback_t callback	Performance processing for asynchronous variant
void* user_data	Callback arguments

grc_inference_params

Field	Description
uint32_t flags	Switch on/off class classification (GRC_PARAMS_SINGLE_CLASS). Perform synchronously or asynchronously (GRC_PARAMS_ASYNC)
grc_class_tag_t tag	Name of the class for which classification is done. (In case flag GRC_PARAMS_SINGLE_CLASS is set)
grc_callback_t callback	Performance processing for asynchronous variant
void* user_data	Callback arguments

grc_class_info

Field	Description
grc_class_tag_t tag	Class name
uint32_t responce_len	Length of response array (should be equal to CLASS_INFO_FIELDS_CNT)
float* responce	Class parameters. Can be interpreted with enum class_info_fields

class_info_fields

enum with meanings of grc_class_info responce values by index

Field	Value
InputQty	0
UsedQty	1
SignalMean	2
SignalStDev	3
InaccAbsMean	4
InaccStDevs	5

Count of mening fields specified in CLASS_INFO_FIELDS_CNT

grc_internal_state

Structure that contains the internal AI SW device for a particular tag

Field	Description
grc_class_tag_t tag	Class name
uint32_t len	Length of values array
double* values	Internal model value for recognizing tag

Data Types

typedef uint32_t grc_class_tag_t;

typedef void(*grc_callback_t)(int status, void* user_data);

GRC_SDK Structure

examples

Contains examples of work with sdk

async_exchange.c – file includes examples on synchronous and asynchronous classification function call (grc_inference)

grc

SDK Code:

drivers - [Transport Layer] – grc remote protocols. Includes interaction interface over I2C grc_ll_i2c.h and implementation for different platforms (MCU Specific code):
- arduino
  - grc_arduino_impl.h - MCU specific implementation of grc_ll_i2c.h
  - grc_arduino.h - driver id and ll_dev structure for arduino
- esp32
  - grc_esp32_impl.h - MCU specific implementation of grc_ll_i2c.h
  - grc_esp32.h - driver id and ll_dev structure for esp32
i2c – [Protocol Layer] – i2c protocol of remote function calls on GRC
- crc_calculation.h/crc_calculation.c – calculation of checksum to check integrity of the sent and received data
- grc_i2c.с - [Application Layer] –interface implementation grc.h for I2C protocol
- grc_ll_api.h/grc_ll_api.c – functions presented on grc devise
- grc_ll_protocol_commands.h/grc_ll_protocol_commands.c – protocol layers which implements various function call steps: GRC status check, argument transfer, function call, waiting till function is over, receiving finished function code, receiving returned values
- protocol_structures.h – data structures required for remote call of deleted functions (grc_ll_api)
grc_error_codes.h - definition of errors returned by functions in grs.h
Grc.hpp/Grc.cpp - [Application Layer] – cpp interface implemented over grc.h
grc.h – [Application Layer] – API for communicating with GRC (High Level API)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GRC_AI_module_SDK_Developer_Guide.md

GRC_AI_module_SDK_Developer_Guide.md

GRC AI Module SDK Developer Guide

Overview

Use Cases

Methods

Device Configuration

AI SW parameters tune

Training GRC on raw data

Detection / classification

Async mode

Information about AI SW

Saving / Loading AI SW

Error Codes

Error codes at protocol layer

Error code, which are returned by remote functions

Structures

grc_device

grc_sdk_version

grc_ll_i2c_dev_esp32

hp_setup

hyperparam_types

GRC_PARAMS

grc_training_params

grc_inference_params

grc_class_info

class_info_fields

grc_internal_state

Data Types

GRC_SDK Structure

examples

grc

Files

GRC_AI_module_SDK_Developer_Guide.md

Latest commit

History

GRC_AI_module_SDK_Developer_Guide.md

File metadata and controls

GRC AI Module SDK Developer Guide

Overview

Use Cases

Methods

Device Configuration

AI SW parameters tune

Training GRC on raw data

Detection / classification

Async mode

Information about AI SW

Saving / Loading AI SW

Error Codes

Error codes at protocol layer

Error code, which are returned by remote functions

Structures

grc_device

grc_sdk_version

grc_ll_i2c_dev_esp32

hp_setup

hyperparam_types

GRC_PARAMS

grc_training_params

grc_inference_params

grc_class_info

class_info_fields

grc_internal_state

Data Types

GRC_SDK Structure

examples

grc