API v0.1.0 How To

The MetaWear C++ library is intended to be imported as a shared library by higher level languages such as C# and Python. Because of this use case, the library has been designed to minimize dynamic memory allocation and the amount of wrapper code needed to communicate with the shared library, and only uses basic types.

As mentioned in the README, the library only constructs the bytes for communicating with the MetaWear board and processes the responses received from the board. It does not implement any Bluetooth LE functionality so the user will need to hook in the appropriate BLE calls for their target platform

Calling Functions

Most of the functions in the library require the caller to allocate memory for the function's use. You can allocate buffers of varying lengths on a case by case basis or simply allocate 20 bytes to ensure there is always enough memory for all functions to work with. The function definitions explicitly list how many bytes they require for a buffer.

///< function requires a 3 byte buffer
uint8_t command[3];

///< function will fill the command parameter with the bytes needed to play an LED pattern
mbl_mw_led_play(command);

///< Call appropriate Bluetooth LE function to send the bytes to the MetaWear board

Sensors

The board's sensors are represented by the DataSource struct and configured with the functions in the respective header files. Currently, only data streaming is supported.

Configuration

To configure a sensor, first make a call to the appropriate create_config function for your sensor. The memory for the struct is dynamically allocated so you will need to free the memory when you are done with the struct.

For this example, we will configure the MMA8452Q accelerometer by calling mbl_mw_acc_mma8452q_create_config.

MblMwAccMma8452qConfig *config= mbl_mw_acc_mma8452q_create_config();

With a pointer to the configuration struct, you can then call various setter functions to modify the default settings.

///< Change the acceleration range to +/- 8g
mbl_mw_acc_mma8452q_set_range(config, MBL_MW_ACC_MMA8452Q_FSR_8G);

When you are ready to write the configuration to the board, call the appropriate write config function.

uint8_t command[7];
mbl_mw_acc_mma8452q_write_acceleration_config(command, config);

Finally, don't forget to free the memory when you are done using the struct.

mbl_mw_acc_mma8452q_free_config(config);

Streaming Data

To enabling data streaming, you will need first retrieve a pointer to the senor's DataSource struct, then call the mbl_mw_sensor_subscribe function.

DataSource *mma8452q_accel_src= mbl_mw_acc_mma8452q_get_acceleration_data_source();
uint8_t command[3];
mbl_mw_sensor_subscribe(command, mma8452q_accel_src);

Processing Data

Sensor data is sent back to the user as raw bytes. The library provides helper functions to convert the bytes into meaningful data. Users will need to allocate memory for the appropriate data type for the function to write the data to.

If the function was provided an inappropriate response, it will return a non-zero status.

///< assume fn is called when a response is received from the board
void received_response(uint8_t *response) {
    CartesianFloat accel_g;

    int status= mbl_mw_acc_mma8452q_get_acceleration_data_g(&accel_g, response);
    if (!status) {
        cerr << "Invalid response provided for MMA8452Q acceleration data" << endl;
    } else {
        cout << "(" << accel_g.x << ", " << accel_g.y << ", " << accel_g.z << ")" << endl;
    }
}