Protocols

1. Introduction

This document describes the communication protocol designed in the framework of the Multipurpose InerTial CHamaleon (MITCH) project. This protocol can be used with the wireless (Bluetooth Low Energy, BLE) interface to retrieve parameters from the system or to apply changes to the system, as well as to control the data acquisition and device calibration.

To control the device using the wired interface (i.e., USB), each message must be wrapped with a unique header and trailer, as described in Section 2.2.

2. Communication protocol

2.1 Overview

The system designed in the framework of this project complies with a bidirectional communication protocol based on the Type-Length-Value (TLV) format. As summarized in Table 1, each packet contains one byte indicating the type (e.g., command), one byte indicating the number of bytes in the value (e.g., the length of the payload), and the value (e.g., the payload itself).

TABLE 1: TLV FORMAT.

Each TLV packet shall be acknowledge by the receiver with an ACK response, either positive (success) or negative (error), carrying information about the outcome using the same TLV format. As summarized in Table 2, the ACK response contains the ACK_CODE which identifies that the message is actually an ACK, the length of the value, and the value. The length of the value is at least equal to 2, for it carries information about which message the ACK refers to and the error code. In case the command sent previously needs some information back, the bytes following the error code byte contain the actual information.

TABLE 2: STRUCTURE OF THE ACKNOWLEDGE MESSAGE.

Each command byte has a SET/GET bit, which can be used either to change the parameter / behavior related to the command or to retrieve it, respectively. The bit used for such purpose is the Most Significant bit (MSb), as summarized in Table 3.

TABLE 3: COMMAND TYPE ARRANGEMENT.

The Mitch Generic ATTribute Profile (GATT) defines how data are transferred back and forth with respect to an external device (i.e., typically mobile or desktop applications), using Services and Characteristics. Standard services and characteristics of the BLE profile are highlighted in light grey. A custom service, named Mitch Custom Service, allows to control and access data. By means of the two characteristics provided by the latter service, Command and Data, it is possible to send and receive a command to the system and to retrieve data, respectively. All information is exchanged by means of a bidirectional protocol.

FIGURE 1: GATT PROFILE OF MITCH.

2.2 USB: Header and Trailer

All commands and messages described in this document are available through both wireless (i.e., Bluetooth Low Energy) and wired (i.e., serial / USB) interfaces. It is sufficient to wrap the default messages, provided in this document for BLE interface, with a custom header (“?!”) and trailer (“!?”) ASCII patterns to be used with wired interface.

3. Device Information Service

The Mitch Custom Service exposes the commands and functionalities necessary to control the device and access data. It is declared as a Primary Service. It is not dependent upon any other services. The service UUID is c8c0a708-e361-4b5e-a365-98fa6b0a836f. The Mitch Custom Service exposes 2 characteristics: Command and Data.

3.1 Command Characteristic

3.2 Data Characteristic

4. Commands

Table 4 provides a list of commands supported by the Muse v3 device.

TABLE 4: COMMAND SUPPORTED BY MITCH DEVICE.

4.1 General

4.1.1 Restart Device

The restart command can be executed in write mode only. The HEX code is: 0x03. To perform a restart operation, the following command must be composed.

TRANSMISSION

RESPONSE

RESTART MODE
It must be one of the following:

• 0x00      APPLICATION      Restart device in application mode
• 0x01      BOOT      Restart device in boot loader mode

4.1.2 Application Firmware Information

The application information command can be executed in read mode only. The HEX code is: 0x84. To access the application information, the following command must be composed.

TRANSMISSION

RESPONSE

• APP CRC
  It represents the Circular Redundancy Check (CRC) as 32-bit unsigned integer.

Example:

• APP CRC: “73 E4 FC FC” which corresponds to 4244431987.

4.1.3 Device Check-up

The device check-up command can be executed in read mode only. The HEX code is: 0x89. To get the current check-up register value, the following command must be composed.

TRANSMISSION

RESPONSE

• CHECK-UP REGISTER
  It represents the health status of the device in relation to its peripheral configuration. The 32-bit unsigned integer must be decoded performing a bitwise operation using the following mask:

TABLE 5: BIT-MASK FOR CHECK-UP REGISTER DECODING.

Each bit-field can be 0 (normal condition) or 1 (error condition).

The meaning of the fields is as follows:

• BLE, consistency of Bluetooth module firmware,
• BATT, battery charger,
• MEM, memory,
• PRX1, proximity sensor #1 (i.e., also called distance sensor in this document),
• PRX2, proximity sensor #2 (i.e., also called distance sensor in this document),
• MAG, magnetometer,
• AXL, accelerometer,
• GAS, gas gauge status.

4.1.4 Firmware Version

The firmware version command can be executed in read mode only. The HEX code is: 0x8A. To access the device firmware version, the following command must be composed.

TRANSMISSION

RESPONSE

• APPLICATION FW VERSION
  It is provided in HEX format and must be converted into the corresponding ASCII Text String. If no application firmware is installed, the APPLICATION FW VERSION field is “0.0.0”.

Example:

• APPLICATION FW VERSION: “31 2E 33 2E 30” which corresponds to “1.3.0”.

4.1.5 Hardware Version

The hardware version command can be executed in read mode only. The HEX code is: 0x8D. To access the hardware version, the following command must be composed.

TRANSMISSION

RESPONSE

• HW VERSION
  It is provided in HEX format and must be converted into the corresponding ASCII Text String.

Example:

• HW VERSION: “33 2E 31 2E 30” which corresponds to “3.1.0”.

4.1.6 Date/Time

The date/time command can be executed in read mode only. The HEX code is 0x8B (read).

To GET the current date/time, the following command must be composed.

TRANSMISSION

RESPONSE

• TIMESTAMP
  It is the 32-bit unsigned integer value that represents the current date/time as retrieved from the device, in Unix epoch format.

Example:

Using this tool https://www.epochconverter.com the user can convert the time in a specific number, and vice versa.

• TIMESTAMP: “00 FA BF 63” which corresponds to “1/12/2023 12:16:00”.

4.2 Device

A set of dedicated commands allow to access the Bluetooth Low Energy (BLE) device name, the unique identifier (ID) alphanumeric code and the hardware and software features exposed by the system itself.

4.2.1 Device Name

The BLE name command can be executed in both write and read mode. The HEX code is 0x0C (write), and 0x8C (read).

To SET a custom name, the following command must be composed.

TRANSMISSION

RESPONSE

• PAYLOAD LENGTH
  The overall payload length, as 8-bit unsigned integer. It corresponds to the length (i.e., number of characters, including the end-of-string character) of the device name to be set.
• DEVICE NAME TO BE SET
  The HEX representation of the device name to be set, converted from the corresponding ASCII Text String. It must also include the end-of-string character “\0”.

To GET the current device name, the following command must be composed.

TRANSMISSION

RESPONSE

• PAYLOAD LENGTH
  It is equal to the length of the current device name plus 2 (i.e., due to the command and error code fields, in the response buffer).
• DEVICE NAME
  The HEX representation of the current device name. It must be converted into the corresponding ASCII Text String. It also includes the end-of-string character “\0”.

Example:

• DEVICE NAME: “6D 75 73 65 5F 72 6F 62 65 72 74 6F” which corresponds to “muse_roberto”.

4.2.2 Device ID

The Device ID command can be executed in read mode only. The HEX code is 0x8E. The perform a get device ID operation, the following command must be composed.

TRANSMISSION

RESPONSE

• DEVICE ID
  It represents the unique identifier of the device, as a 32-bit unsigned integer that can be converted into the corresponding hex string representation.

Example:

• DEVICE ID: “03 46 B5 83” which corresponds to “83B54603”. Bytes in reverse order to keep endianness w.r.t. the corresponding 32-bit unsigned integer numeric value.

4.2.3 Battery Charge and Voltage

The Battery Charge and Battery Voltage commands can be executed in read mode only. The HEX codes are: 0x87 (charge level), and 0x88 (voltage).

The access the current battery charge level, the following command must be composed.

TRANSMISSION

RESPONSE

• BATTERY CHARGE
  It represents the battery charge level in percentage format, as an 8-bit unsigned integer.

The access the current battery voltage level, the following command must be composed.

TRANSMISSION

RESPONSE

• BATTERY VOLTAGE
  It represents the battery voltage as a 16-bit unsigned integer value.

4.2.4 System State

The Mitch device behavior is controlled through a state machine (Figure 2) implemented at a firmware level. It depends on a set of pre-defined user scenarios or operating modes, as well as the functions supported by the device itself. The available states, that can be (directly and indirectly) controlled by the end-user are summarized in Table 6.

FIGURE 2: STATE MACHINE REPRESENTATION.

TABLE 6: SYSTEM STATES.

The system state command can be executed in both write and read mode. The HEX code is 0x02 (write), and 0x82 (read).

To SET a new system state, the following command must be composed.

TRANSMISSION

RESPONSE

• STATE TO BE SET
  It must be filled with the HEX code of the state to be set.

To GET the current system state, the following command must be composed.

TRANSMISSION

RESPONSE

• SYSTEM STATE
  It provides the HEX code corresponding to the current state of the system.

4.3 Settings

4.3.1 Full Scales

The full scales command can be executed in both write and read mode. The HEX code is 0x40 (write), and 0xC0 (read).

To SET a new full scales configuration, the following command must be composed.

TRANSMISSION

RESPONSE

• SENSORS FULL SCALE
  The first byte represents the accelerometer full scale code (byte index: 2), while the second is the gyroscope full scale code (byte index: 3). It must be encoded in HEX format as summarized in Table 7

TABLE 7: FULL SCALE CONFIGURATIONS.

*1 The sensitivity coefficients have the following unit of measure, in order: dps/LSB (Gyroscope), mg/LSB (Accelerometer), mGauss/LSB (Magnetometer).

To GET the current full scales configuration, the following command must be composed.

TRANSMISSION

RESPONSE

• SENSORS FULL SCALE
  The first byte represents the accelerometer full-scale code (byte index: 4), while the second is the gyroscope full scale code (byte index: 5). It must be encoded in HEX format as summarized in Table 7.

Example:

• SENSORS FULL SCALE: the first byte is the code corresponding to the accelerometer full-scale (i.e., 4 g), while the second byte refers to the gyroscope sensor (i.e., 1000 dps).

4.3.2 Distance Sensors Full Scale and Offset

The distance sensors full-scale command can be executed in both write and read mode. The HEX code is 0x44 (write), and 0xC4 (read) for sensor number 1, and 0x45 (write), 0xC5 (read) for sensor number 2.

To SET a new full-scale configuration, the following command must be composed.

TRANSMISSION

RESPONSE

• DS FULL SCALE
  It represents the code to be set to select the desired full-scale for distance sensor. The available codes and correspondig full scales are shown in Table 8.

TABLE 8: FULL SCALE CONFIGURATIONS FOR DISTANCE SENSORS.

To GET current full-scale configuration, the following command must be composed.

TRANSMISSION

RESPONSE

• DS FULL SCALE
  It represents the code to be set to select the desired full-scale for distance sensor. The available codes and correspondig full scales are shown in Table 8.

4.3.3 Calibration

Calibration of IMU must be performed offline and then uploaded into the device as described in this section.

To SET a new calibration matrix, the following command must be composed.

TRANSMISSION (REQUIRES ONE ITERATION FOR EACH LINE OF THE MATRIX THAT MUST BE UPLOADED)

RESPONSE

• TYPE
  Describes the sensor to which the matrix is referred:
  • Accelerometer 0x00
  • Gyroscope 0x01
  • Magnetometer 0x02

• LINE
  Defines the line to which the current values are referred.

• VALUE #1, VALUE #2, VALUE #3, VALUE #4
  Values to be uploaded into the selected line.

To GET a specific calibration matrix, the following command must be composed.

TRANSMISSION

RESPONSE

• TYPE
  Describes the sensor to which the matrix is referred:
  • Accelerometer 0x00
  • Gyroscope 0x01
  • Magnetometer 0x02

• LINE
  Defines the line to which the current values are referred.

TABLE 9: DEFAULT STRUCTURE OF A CALIBRATION MATRIX.

MAGNETOMETER
The magnetometer calibration entails performing as many different system rotations as possible during the procedure.

4.4 Data Acquisition

Data acquisition is controlled by using the set state command performed on Command Characteristic. Based on the selected acquisition channel (i.e., STREAM or LOG), the device starts to stream the data through notification on Data Characteristic or save the data on the flash memory, respectively. The general format of the command is as follows, independently from the sensor configuration, state, and selected acquisition mode or frequency.

To START data acquisition, the following command must be composed.

TRANSMISSION

RESPONSE (LOG ACQUISITION)

RESPONSE (STREAM ACQUISITION)

TABLE 10: ACQUISITION MODES DEFINITION (LOG).

TABLE 11: ACQUISITION FREQUENCIES (LOG).

TABLE 12: ACQUISITION MODES DEFINITION (STREAM).

TABLE 13: ACQUISITION FREQUENCIES (STREAM).

To STOP data acquisition, the following command must be composed to put the system in IDLE (0x02) state.

TRANSMISSION

RESPONSE

4.4.1 Button Log Configuration

The button log configuration command can be executed in both write and read mode. The HEX code is 0x50 (write), and 0xD0 (read).

To SET a new button log configuration, the following command must be composed.

TRANSMISSION

RESPONSE

To GET the current button log configuration, the following command must be composed.

TRANSMISSION

RESPONSE

• ACQUISITION MODE
  It is the 8-bit unsigned integer representing the acquisition mode currently set.
• ACQUISITION FREQUENCY
  It is the 8-bit enumerative representing the desired acquisition frequency to be set (write) or currently set (read) for log operations.

4.5 Data Decoding

4.5.1 Pressure

The pressures measured by the Force Sensitive Resistor (FSR) insole must be decoded considering the resolution due to numeric representation as described in the following code snippet.

byte[] buffer = new byte[packetDimension + 8];
int k = 0;
for (int j = 0; j < 16; j += 2)
{
    //First pressure
    temp_pressure = buffer[i * packet_dimension + 26 + k];
    temp_pressure = (UInt16)(temp_pressure << 4); temp_pressure |= (UInt16)(buffer[i * packet_dimension + 26 + k + 1] >> 4);
    tempData.Pressure[j] = temp_pressure;
    tempData.Pressure[j] *= 255;
    tempData.Pressure[j] /= 4096;

    //Second pressure
    temp_pressure = (UInt16)(buffer[i * packet_dimension + 26 + k + 1]);
    temp_pressure &= 0x0F;
    temp_pressure = (UInt16)(temp_pressure << 8);
    temp_pressure |= (UInt16)(buffer[i * packet_dimension + 26 + k + 2]);

    tempData.Pressure[j + 1] = temp_pressure;
    tempData.Pressure[j + 1] *= 255;
    tempData.Pressure[j + 1] /= 4096;
    k += 3;
}

4.5.2 Gyroscope: 3D Angular Rate

The 3D angular rate is provided as a raw value read out from the sensor registers, represented as a two’s complement, Little Endian encoded, 16-bit signed integer value. The conversion from raw value to actual measurement must be performed on the master side considering the actual full-scale set and the corresponding sensitivity coefficient (see Table 7).

The output measure is provided in Degrees Per Second, dps.

Each channel (i.e., x, y, z) must be converted from raw 2-bytes array to the corresponding 16-bit signed integer representation (i.e., Int16) and then scaled to the actual metric representation multiplying it by the appropriate sensitivity coefficient.

4.5.3 Accelerometer: 3D Linear Acceleration

The 3D acceleration is provided as a raw value read out from the sensor registers, represented as a two’s complement, Little Endian encoded, 16-bit signed integer value. The conversion from raw value to actual measurement must be performed on the master side considering the actual full-scale set and the corresponding sensitivity coefficient (see Table 7).

The output measure is provided in millig, mg.

Each channel (i.e., x, y, z) must be converted from raw 2-bytes array to the corresponding 16-bit signed integer representation (i.e., Int16) and then scaled to the actual metric representation multiplying it by the appropriate sensitivity coefficient.

4.5.4 Magnetometer: 3D Magnetic Field Intensity

The 3D magnetic field intensity provided as a raw value read out from the sensor registers, represented as a two’s complement, Little Endian encoded, 16-bit signed integer value. The conversion from raw value to actual measurement must be performed on the master side considering the actual full-scale set and the corresponding sensitivity coefficient (see Table 7). Magnetometer full scale cannot be changed by the user.

The output measure is provided in milli-Gauss, mGauss.

Each channel (i.e., x, y, z) must be converted from raw 2-bytes array to the corresponding 16-bit signed integer representation (i.e., Int16) and then scaled to the actual metric representation multiplying it by the appropriate sensitivity coefficient. It is worth noting that the sensitivity of the magnetometer is fixed to 1.5 mGauss/LSB.

4.5.5 Orientation Quaternion (MPE required)

The orientation is presented as a normalized quaternion, but only the three imaginary components are reported in the data, 2 bytes each. Each reported component is transmitted as a signed integer, mapped inside the range [-1,1], meaning that the LSB value is

From this, the user should read the 2 bytes corresponding to the quaternion component as a signed 16-bit integer, then divide it by 32767 to obtain the float equivalent (with the approximations intrinsic to the method). The user can then use the knowledge that the quaternion is normalized, and recalculate the real component as

Since this method drops the real part of the quaternion, given a quaternion q:

Imaginary components of quaternion q are transmitted as −𝑞1, −𝑞2 and −𝑞3, so that the reconstructed quaternion is

Example of decoding implementation:

private static float[] DataTypeOrientation(byte[] currentPayload)
{
    // Define 4-elements array of float (i.e., qw, qi, qj, qk channels)
    float[] currentData = new float[4];

    // Define temporary internal variable used for data conversion
    byte[] tmp = new byte[2];

    // Orientation Quaternion (i.e., UNIT QUATERNION)
    float[] tempFloat = new float[3];
    for (int i = 0; i < 3; i++)
    {
        // Extract channel raw value (i.e., 2-bytes each) and convert to Int16
        tempFloat[i] = BitConverter.ToInt16(currentPayload, 2*i);

        // Keep into account the data resolution
        tempFloat[i] /= 32767;
                
        // Assign imaginary parts of quaternion
        currentData[i + 1] = tempFloat[i];
    }

    // Compute real component of quaternion given immaginary parts
    currentData[0] = (float)Math.Sqrt(1 - (currentData[1] * currentData[1] +
            currentData[2] * currentData[2] + currentData[3] * currentData[3]));

    // Return decoded Unit Quaternion
    return currentData;
}

4.5.6 Temperature

The temperature is sampled at a fixed rate of 25 Hz. The user can reconstruct the values by converting the provided byte array into a 16-bit signed integer and using the following equations:

𝑇=𝐷𝑎𝑡𝑎_𝑎𝑟𝑟𝑎𝑦_𝑇 ⋅ 0.004

Finally, the reference ambient temperature must be added to the estimated variation to obtain the current temperature value.

4.6 Memory

4.6.1 Control

The memory control command can be executed in both write and read mode. The HEX code is 0x20 (write), and 0xA0 (read).

To perform an ERASE MEMORY operation, the command must be executed in WRITE mode. The following command must be composed.

TRANSMISSION

RESPONSE

To GET the current memory status in terms of available space (i.e., in percentage format) and number of files currently saved in memory, the following command must be composed.

TRANSMISSION

RESPONSE

• AVAILABLE SPACE
  Available space, provided in percentage format (i.e., 8-bit unsigned integer value).
• NUMBER OF FILES
  It is the 16-bit unsigned integer representing the number of files saved in memory.

4.6.2 File Information

The file information command can be executed in read-only mode. The HEX code is 0xA1.

To GET the file info about a specific file identifier, the following command must be composed.

TRANSMISSION

RESPONSE

• FILE ID
  The files are retrieved passing an index (i.e., between 0 and N-1, where N is the number of files currently stored in the system) as the command argument. If the requested file is present, the command will respond with the following information, in order:
  • TIMESTAMP (bytes index 4 to 7)
    Start timestamp of the file (i.e., 4 bytes).
    It must be decoded by converting the raw values into a 64-bit unsigned integer, and adding the REFERENCE_EPOCH = 1554105600², multiplied by 1000 to keep into account the milliseconds resolution.
  • SENSORS FULL SCALES (bytes 10 and 11, respectively)
    The sensors full scale code (i.e., 1 byte each). The first is the accelerometer full scale, the second is the gyroscope full scale.
  • DATA ACQUISITION MODE
    The data mode (i.e., 1 bytes).
    It must be decoded based on Table 10.
  • DATA ACQUISITION FREQUENCY
    The log frequency for the file (i.e., 1 byte, the hex code representing the selected frequency).
  • FILE DIMENSION (bytes 12 to 15)
    The dimension of the file in bytes.

Otherwise, an acknowledge message with ERROR CODE = 0x01 is returned.

² It corresponds to Sunday 1 April 2019 08:00:00 GMT.

4.6.3 File Download

The file download command can be executed in write-only mode. The HEX code is 0x22.

To start the file download procedure given a specific file identifier, the following command must be composed.

TRANSMISSION

RESPONSE

• FILE ID
  The files are retrieved passing an index (i.e., between 0 and N-1, where N is the number of files currently stored in the system) as the command argument.
• FILE SIZE
  It is a 32-bit unsigned integer value that represents the file size in bytes.

The user must send an ack message, at the end of each page, with the same ack format of every other command: the first byte of the payload is used to indicate the command that triggered the ack (0x22 in this case), and the second byte is used to signify an ACK (0x00) or NACK (any other number).

4.7 Time Synchronization

One or more Mitch can be synchronized with respect to a master device that controls the data acquisition. Such a procedure allows us to estimate the clock offset between each client (i.e., Mitch) and the master to synchronize the acquired data in time. The following commands allow us to manage the time synchronization (i.e., time sync) procedure.

4.7.1 Clock Offset

The clock offset command can be executed in both write and read mode. The HEX code is 0x31 (write), and 0xB1 (read).

To SET a new clock offset, the following command must be composed.

TRANSMISSION

RESPONSE

• CLOCK OFFSET
  The 64-bit unsigned integer value representing the clock offset value to be set.

To GET the current clock offset, the following command must be composed.

TRANSMISSION

RESPONSE

• CLOCK OFFSET
  The 64-bit unsigned integer value representing the clock offset currently set.

4.7.2 Time Sync

The time sync command can be executed in both write and read mode. The HEX code is 0x32 (write), and 0xB2 (read).

To ENABLE time sync procedure, the following command must be composed.

TRANSMISSION

RESPONSE

To GET the current drift value necessary for clock offset computation, the following command must be composed.

TRANSMISSION

RESPONSE

• TIME DRIFT
  The 64-bit unsigned integer value represents the clock drift, necessary for clock offset computation.

4.7.3 Exit Time Sync

The exit time sync command can be executed in write-only mode. The HEX code is 0x33 (write).

To DISABLE time sync mode, the following command must be composed.

TRANSMISSION

RESPONSE