API v0.2.0 How To

Version 0.2.0 of the C++ API has undergone a major overhaul with regards to how the MetaWear commands are passed to the user and utilizes more C++ features to make the library more closely resemble the Android API:

• MblMwMetaWearBoard struct that represents a board
• Route all commands to a function pointer instead of dumping the data into a buffer
• Central function that processes responses from the board
• Rudimentary data routing system based on the Android API data routes

Setting up Bluetooth LE Communication

Before we use any functionality in the library, users first need to add the Bluetooth LE code that writes to and receives notifications from the MetaWear Gatt service for their respective platform:

#include <cstdint>
#include <cstring>
#include <iostream>

#include "metawear/connection.h"
#include "metawear/types.h"

using namespace std;

static void write_to_mw_service(const MblMwMetaWearBoard* board, 
        const uint8_t* command, uint8_t len) {
    // put code that writes to the MetaWear Gatt service here
}

static void received_data_from_mw_sensor(const MblMwDataSignal* signal, 
        const MblMwData* data) {
    // Make sure you copy the bytes from the value field
    // The memory allocated for "data" will be freed after this fn executes

    switch(data->type_id) {
    case MBL_MW_DT_ID_UINT32:
        uint32_t value= *((uint32_t*) data->value);
        // Dispatch to appropriate consumer
        break;
    case MBL_MW_DT_ID_FLOAT:
        float value= *((float*) data->value);
        // Dispatch to appropriate consumer
        break;
    case MBL_MW_DT_ID_CARTESIAN_FLOAT:
        MblMwCartesianFloat value;
        memcpy(&value, data->value, sizeof(MblMwCartesianFloat));
        // Dispatch to appropriate consumer
        break;
    default:
        cout << "Unknown ID type: " << data->type_id << endl;
        break;
    }
}

Then pass those function to the library by calling mbl_mw_connection_init:

static MblMwConnection connection= {write_to_mw_service, 
        received_data_from_mw_sensor};

void init_connection() {
    mbl_mw_connection_init(&connection);
}

MblMwMetaWearBoard Type

Like the MetaWearBoard (Android) and MBLMetaWear (iOS) classes, the MblMwMetaWearBoard type is the starting point for the C++ API. To instantiate a MblMwMetaWearBoard variable, call the mbl_mw_create_metawear_board method:

MblMwMetaWearBoard *my_mw_board= mbl_mw_create_metawear_board();

With the newly created "my_mw_board" variable, we can begin interacting with the board. An easy way to check if everything is working so far, try turning on the LED using the functions in the led.h header file.

#include "metawear/led.h"

MblMwLedPattern pattern;
mbl_mw_led_load_preset_pattern(&pattern, MBL_MW_LED_PRESET_SOLID);
mbl_mw_led_write_pattern(my_mw_board, &pattern, MBL_MW_LED_COLOR_BLUE);

Handling Responses

The MetaWear board will send responses back to your device which will need to be processed. When a response is received from the MetaWear notification characteristic, pass it to the mbl_mw_metawearboard_handle_response function. This must be done for all responses received from the MetaWear notification characteristic.

// Assume this callback function is executed when there is a change in the 
// the MetaWear notification characteristic
static void mw_gatt_char_notify_callback(uint8_t *response, uint8_t len) {
    mbl_mw_metawearboard_handle_response(my_mw_board, response, len);
}

Data Stream

To stream data to your mobile device, we need to switch the desired sensor to active mode and subscribe to its data stream. Lets see this in action by setting up a data stream from the accelerometer.

First, we will configure the accelerometer to stream at 50Hz and set the acceleration range to 8g.

mbl_mw_acc_mma8452q_set_odr(my_mw_board, MBL_MW_ACC_MMA8452Q_ODR_50HZ);
mbl_mw_acc_mma8452q_set_range(my_mw_board, MBL_MW_ACC_MMA8452Q_FSR_8G);
mbl_mw_acc_mma8452q_write_acceleration_config(my_mw_board);

Next, we will acquire a reference to the acceleration data signal and indicate that we wish to subscribe to it. Data from the senor will be received in the function pointed by the MblMwConnection.received_sensor_data variable.

#include <string.h>

#include "metawear/datasignal.h"
#include "metawear/types.h"

MblMwDataSignal *mma8452q_accel_signal= mbl_mw_acc_mma8452q_get_acceleration_data_signal(my_mw_board);
mbl_mw_datasignal_subscribe(mma8452q_accel_signal);

// in this example code, data from the accelerometer is directed to the 
// received_data_from_mw_sensor callback function with the "signal" parameter 
// equal to mma8452q_accel_signal

Finally, we enable the sensor to begin the data stream.

mbl_mw_acc_mma8452q_enable_acceleration_sampling(my_mw_board);
mbl_mw_acc_mma8452q_start(my_mw_board);