1. Introduction
This document describes the communication protocol designed in the framework of the Muse v3 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).
Type | Length | Value (payload) | ||
---|---|---|---|---|
8-bit unsigned int | 8-bit unsigned int | Byte-0 | ... | Byte-N |
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.
Type | Length | Value (payload) | ||
---|---|---|---|---|
ACKNOWLEDGE CODE | 8-bit unsigned int | COMMAND CODE | ERROR CODE | ... |
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.
Command type | |||
---|---|---|---|
b7 – R/W Read (R) = 1 Write (W) = 0 |
b6 | ... | b0 |
TABLE 3: COMMAND TYPE ARRANGEMENT.
The Muse 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 standard Device Information Service provides access to generic manufacturing and system information. Finally, a custom service, named Muse_v3 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 MUSE V3.
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.
Header | Message Body | Trailer | |||
---|---|---|---|---|---|
Index | 0 | 1 | Byte array variable length | N-1 | N |
ASCII | '?' | '!' | Byte array representing the command to be sent to the device or the message received from the device itself. | '!' | '?' |
HEX | 0x3f | 0x21 | 0x21 | 0x3f |
3. Device Information Service
The Device Information Service exposes the manufacturer information. It is declared as a Primary Service. It is not dependent upon any other services. The service UUID is 0x180A. The Device Information Service exposes 5 characteristics: Manufacturer Name, Firmware Revision, Hardware Revision, Serial Number, System ID.
3.1 Manufacturer Name
UUID: | 00002a29-0000-1000-8000-00805f9b34fb |
Byte: | 4 |
Property: | READ |
Value: | 221e |
Description: | UTF-8 string representing the name of the manufacturer of the device. |
3.2 Firmware Revision
UUID: | 00002a26-0000-1000-8000-00805f9b34fb |
Byte: | 6 |
Property: | READ |
Value: | Firmware version described with the format [Major].[Minor].[Patch]. Example: 1.5.06. |
Description: | UTF-8 string representing the firmware revision currently installed on device. |
3.3 Hardware Revision
UUID: | 00002a27-0000-1000-8000-00805f9b34fb |
Byte: | 4 |
Property: | READ |
Value: | 3.0 |
Description: | UTF-8 string representing the hardware revision of device. |
3.4 Serial Number
UUID: | 00002a25-0000-1000-8000-00805f9b34fb |
Byte: | 8 |
Property: | READ |
Value: | [8-bytes alphanumeric code]. Example: 0346b583. |
Description: | UTF-8 string representing a unique system identifier. It allows us to uniquely identify each board. |
3.5 System ID
UUID: | 00002a23-0000-1000-8000-00805f9b34fb |
Byte: | 4 |
Property: | READ |
Value: | 03b1 |
Description: | UTF-8 string representing the system identifier using the device model, as encoded by the manufacturer. |
4. Muse Custom Service
The Muse 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 Muse Custom Service exposes 2 characteristics: Command and Data.
4.1 Command Characteristic
UUID: | d5913036-2d8a-41ee-85b9-4e361aa5c8a7 |
Byte: | 20 |
Property: | READ, WRITE, NOTIFY |
Description: | It allows to control the device behaviors. |
4.2 Data Characteristic
UUID: | 09bf2c52-d1d9-c0b7-4145-475964544307 |
Byte: | 128 |
Property: | READ, NOTIFY, WRITE_NO_RESPONSE |
Description: | It allows to manage streaming of data from device. |
5. Commands
Table 4 provides a list of commands supported by the Muse v3 device.
Name | R/W | Code (hex) | Code (dec) | Description |
---|---|---|---|---|
CMD_ACK | W | 0x00 | 0 | Acknowledge |
CMD_STATE | W | 0x02 | 2 | Set system state |
R | 0x82 | 130 | Get system state | |
CMD_RESTART | W | 0x03 | 3 | Restart device |
CMD_APP_INFO | R | 0x84 | 132 | Get application firmware information (i.e., CRC and length) |
CMD_BATTERY_CHARGE | R | 0x87 | 135 | Get battery charge level |
CMD_BATTERY_VOLTAGE | R | 0x88 | 136 | Get battery voltage |
CMD_CHECK_UP | R | 0x89 | 137 | Read value of check-up register |
CMD_FW_VERSION | R | 0x8A | 138 | Get bootloader and application firmware versions |
CMD_TIME | W | 0x0B | 11 | Set date / time |
R | 0x8B | 139 | Get date / time | |
CMD_BLE_NAME | W | 0x0C | 12 | Set BLE device name |
R | 0x8C | 140 | Get BLE device name | |
CMD_DEVICE_ID | R | 0x8E | 142 | Get device unique identifier |
CMD_DEVICE_SKILLS | R | 0x8F | 143 | Get device skills in terms of hardware and software features |
CMD_MEM_CONTROL | W | 0x20 | 32 | Erase memory |
R | 0xA0 | 160 | Get memory status | |
CMD_MEM_FILE_INFO | R | 0xA1 | 161 | Get file information |
CMD_MEM_FILE_DOWNLOAD | W | 0x22 | 34 | Manage file download |
CMD_CLK_OFFSET | W | 0x31 | 49 | Set a new clock offset |
R | 0xB1 | 177 | Retrieve current clock offset | |
CMD_TIME_SYNC | W | 0x32 | 50 | Enter time sync procedure |
R | 0xB2 | 178 | Update time sync variables | |
CMD_EXIT_TIME_SYNC | W | 0x33 | 51 | Exit time sync procedure |
CMD_SENSORS_FS | W | 0x40 | 64 | Set device full scales |
R | 0xC0 | 192 | Get device full scales | |
CMD_MATRIX_CALIBRATION | W | 0x48 | 72 | Set calibration matrix |
R | 0xC8 | 200 | Get calibration matrix | |
CMD_BTN_LOG | W | 0x50 | 80 | Set button log configuration |
R | 0xD0 | 208 | Get button log configuration | |
CMD_USER_CFG | W | 0x51 | 81 | Set user configuration |
R | 0xD1 | 209 | Get user configuration |
TABLE 4: COMMAND SUPPORTED BY MUSE V3 DEVICE.
5.1 General
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 03 | 01 | RESTART MODE | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 02 | 03 | ERROR CODE | 0 … 0 |
RESTART MODE
It must be one of the following:
- 0x00 APPLICATION Restart device in application mode
- 0x01 BOOT Restart device in boot loader mode
- 0x02 RESET Restart device in application mode after performing a factory reset
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 84 | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 0A | 84 | ERROR CODE | APP CRC | APP LENGTH | 0 … 0 |
-
APP CRC
It represents the Circular Redundancy Check (CRC) as 32-bit unsigned integer.
-
APP LENGTH
It represents the length of the application firmware (i.e., number of bytes), as a 32-bit unsigned integer.
Example:
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
APP CRC | APP LENGTH | |||||||||||||||||||
Value | 00 | 0A | 84 | 00 | 53 | E9 | 63 | CA | 48 | 90 | 02 | 00 | 0 … 0 |
- APP CRC: “53 E9 63 CA” which corresponds to 3395545427.
- APP LENGTH: “48 90 02 00” which corresponds to 168008 bytes.
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 89 | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 04 | 89 | ERROR CODE | CHECK-UP REGISTER | 0 … 0 |
-
CHECK-UP REGISTER
It represents the health status of the device in relation to its peripheral configuration. The 16-bit unsigned integer must be decoded performing a bitwise operation using the following mask:
Byte Order | 0 (index 4 in RESPONSE) | 1 (index 5 in RESPONSE) | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Bit Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
Field | LSE | HSE | BTN | IMU | MAG | HDR | MEM | BAR | PRX | HUM | BAT | MIC | RFU |
TABLE 5: BIT-MASK FOR CHECK-UP REGISTER DECODING.
Each bit-field can be 0 (normal condition) or 1 (error condition).
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 8A | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 12 | 8A | ERROR CODE | BOOT LOADER FW VERSION | APPLICATION FW VERSION | BLE MAJOR | BLE MINOR |
-
BOOT LOADER FW VERSION and APPLICATION FW VERSION
They are provided in HEX format and must be converted into the corresponding ASCII Text String. They come with the termination “\0” character and represent the boot loader and application firmware versions currently installed on device. If no application firmware is installed, the APPLICATION FW VERSION field is “0.0.00”. - BLE MAJOR and BLE MINOR They are provided in HEX format and correspond to the major and minor version numbers of the flashed BLE stack.
Example:
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
BOOT LOADER FW VERSION | APPLICATION FW VERSION | BLE MAJ | BLE MIN | |||||||||||||||||
Value | 00 | 10 | 8A | 00 | 31 | 2E | 33 | 2E | 30 | 31 | 00 | 31 | 2E | 35 | 2E | 32 | 32 | 00 | 01 | 0B |
- BOOT LOADER FW VERSION: “31 2E 33 2E 30 31” which corresponds to “1.3.01”.
- APPLICATION FW VERSION: “31 2E 35 2E 32 32” which corresponds to “1.5.22”.
- BLE STACK VERSION “01 0B” which corresponds to “1.11″
The end-of-string character “\0” has been removed from both values before conversion to ASCII.
5.1.5 Date/Time
The date/time command can be executed in both write and read mode. The HEX code is 0x0B (write), and 0x8B (read).
To SET a new date/time, the following command must be composed.
TRANSMISSION
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 0B | 04 | TIMESTAMP TO BE SET | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 02 | 0B | ERROR CODE | 0 … 0 |
-
TIMESTAMP TO BE SET
It is the 32-bit unsinged integer value that represents the timestamp to be set, in Unix epoch format.
To GET the current date/time, the following command must be composed.
TRANSMISSION
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | ||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||||
Value | 8B | 00 | 0B | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 06 | 8B | ERROR CODE | TIMESTAMP | 0 … 0 |
-
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:
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
TIMESTAMP | 0 … 0 | |||||||||||||||||||
Value | 00 | 06 | 8B | 00 | 00 | FA | BF | 63 |
- TIMESTAMP: “00 FA BF 63” which corresponds to “1/12/2023 12:16:00 PM”.
5.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.
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 0C | PAYLOAD LENGTH | DEVICE NAME TO BE SET | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 02 | 0C | ERROR CODE | 0 … 0 |
-
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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 8C | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | PAYLOAD LENGTH | 8C | ERROR CODE | DEVICE NAME |
-
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:
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
DEVICE NAME | ||||||||||||||||||||
Value | 00 | 0E | 8C | 00 | 6D | 75 | 73 | 65 | 5F | 72 | 6F | 62 | 65 | 72 | 74 | 6F | 0 … 0 |
- DEVICE NAME: “6D 75 73 65 5F 72 6F 62 65 72 74 6F” which corresponds to “muse_roberto”.
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 8E | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 06 | 8E | ERROR CODE | DEVICE ID | 0 … 0 |
-
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:
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
DEVICE ID | ||||||||||||||||||||
Value | 00 | 06 | 8E | 00 | 03 | 46 | B5 | 83 | 0 ... 0 |
- 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.
5.2.3 Device Skills
The Device Skills command can be executed in read mode only. The HEX code is 0x8F. The perform a get device skills operation, the following command must be composed.
TRANSMISSION
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 8F | 01 | SKILLS CODE | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 06 | 8F | ERROR CODE | SKILLS | 0 … 0 |
-
SKILLS CODE
It identifies the skill set of interest among:- HARDWARE SKILLS 0x00
- SOFTWARE SKILLS 0x01
-
SKILLS
It is a 32-bit unsigned integer value that represents the required skill set in response buffer. While Software skills depends on the firmware and algorithm licenses installed, the numeric value corresponding to hardware skills must be decoded performing a bitwise operation using the following mask (Table 6).
HARDWARE | |
---|---|
Skill | Code |
Gyroscope | 0x0001 |
Accelerometer | 0x0002 |
Magnetometer | 0x0004 |
Accelerometer (HDR) | 0x0008 |
Temperature | 0x0010 |
Relative Humidity | 0x0020 |
Ambient Barometric Pressure | 0x0040 |
Light intensity (Visible Spectrum) | 0x0080 |
Light intensity (IR) | 0x0100 |
Range / distance | 0x0200 |
Microphone | 0x0400 |
TABLE 6: BIT-MASK FOR HARDWARE SKILLS DECODING.
5.2.4 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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 87 | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 03 | 87 | ERROR CODE | BATTERY CHARGE | 0 … 0 |
-
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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 88 | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 04 | 88 | ERROR CODE | BATTERY VOLTAGE | 0 … 0 |
-
BATTERY VOLTAGE
It represents the battery voltage as a 16-bit unsigned integer value.
5.2.5 System State
The Muse v3 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 7.
FIGURE 2: STATE MACHINE REPRESENTATION.
Name | Coding | Description |
---|---|---|
IDLE | 0x02 | System in IDLE state |
STANDBY | 0x03 | System in STANDY state |
LOG | 0x04 | System in LOG state |
READOUT | 0x05 | System in the READOUT state |
CALIBRATION | 0x07 | System in CALIBRATION state |
TX | 0x06 | System in TX state – BUFFERED MODE |
0x08 | System in TX state – DIRECT MODE |
TABLE 7: 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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 02 | 01 | STATE TO BE SET | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 02 | 02 | ERROR CODE | 0 … 0 |
-
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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 82 | 02 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 03 | 82 | ERROR CODE | SYSTEM STATE | 0 … 0 |
-
SYSTEM STATE
It provides the HEX code corresponding to the current state of the system.
5.3 Settings
5.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
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 40 | 03 | SENSORS FULL SCALE | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 02 | 40 | ERROR CODE | 0 … 0 |
-
SENSORS FULL SCALE
It is a 24-bit unsigned integer representation of the full scales to be set. It must be encoded in HEX format.
Each sensor has 2-bits reserved for its full scale, in order: Gyroscope, Accelerometer, High Dynamic Range (HDR) Accelerometer, and Magnetometer.
/** * Structure containing the sensors full scale */ typedef struct { uint8_t gyro_fs :2; uint8_t axl_fs :2; uint8_t hdr_axl_fs :2; uint8_t magn_fs :2; uint16_t rfu; } __attribute__((packed)) System_sensorsFS;
To generate the 24-bit unsigned integer value to be used as FULL-SCALE CODE, sensor configurations (Table 8) must be combined with a bitwise OR.
Sensor | FS value | Sensitivity¹ | HEX code |
---|---|---|---|
GYROSCOPE [dps] | 245 | 0.00875 | 0x00 |
500 | 0.0175 | 0x01 | |
1000 | 0.035 | 0x02 | |
2000 | 0.070 | 0x03 | |
ACCELEROMETER [g] | 4 | 0.122 | 0x00 |
32 | 0.976 | 0x04 | |
8 | 0.244 | 0x08 | |
16 | 0.488 | 0x0C | |
HDR ACCELEROMETER [g] | 100 | 49 | 0x00 |
200 | 98 | 0x10 | |
400 | 195 | 0x30 | |
MAGNETOMETER [Gauss] | 4 | 1000/6842 | 0x00 |
8 | 1000/3421 | 0x40 | |
12 | 1000/2281 | 0x80 | |
16 | 1000/1711 | 0xC0 |
TABLE 8: FULL SCALE CONFIGURATIONS.
*1 The sensitivity coefficients have the following unit of measure, in order: dps/LSB (Gyroscope), mg/LSB (Accelerometer), mg/LSB (HDR Accelerometer), mGauss/LSB (Magnetometer).
To GET the current full scales configuration, the following command must be composed.
TRANSMISSION
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | C0 | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 05 | C0 | ERROR CODE | SENSORS FULL SCALE | 0 … 0 |
-
SENSORS FULL SCALE
It is a 24-bit unsigned integer representation of the current full scales configuration that must be decoded performing a bitwise AND using the following bit mask (Table 9), one for each sensor.
Sensor | Mask Value |
---|---|
Gyroscope | 0x03 |
Accelerometer | 0x0C |
Magnetometer | 0xC0 |
Accelerometer (HDR) | 0x30 |
TABLE 9: BIT-MASK DEFINITION FOR FULL SCALE DECODING OPERATIONS.
Example:
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
SENSORS FULL SCALE | ||||||||||||||||||||
Value | 00 | 05 | C0 | 00 | 0A | 00 | 00 | 0 ... 0 |
- SENSORS FULL SCALE: “0A0000” from which the sensors configuration can be extracting as follows:
- Perform a bitwise AND using the masks provided in Table 8. With the code retrieved in this example, we obtained:
- Gyroscope code: 0x02
- Accelerometer code: 0x08
- Magnetometer code: 0x00
- HDR Accelerometer code: 0x00
- Retrieve the full scale and corresponding sensitivity coefficient from the configuration dictionary:
- Gyroscope: 1000 / 0.035
- Accelerometer: 8 / 0.244
- Magnetometer 4 / 0.146156088
- HDR Accelerometer: 100 / 49
- Perform a bitwise AND using the masks provided in Table 8. With the code retrieved in this example, we obtained:
5.3.2 User Configuration
The user can customize the Muse behaviors operating on a set of configuration flags, including:
-
STANDBY
It allows to enable (value: 1) or disable (value: 0) automatic standby. If enabled, the device will move to standby condition after 120 seconds of inactivity.
The default value is ENABLED (value: 1). The system can also be forced into standby by using the button when the automatic standby is disabled.
If the device is connected, the system is prevented from going into standby condition.
-
CIRCULAR MEMORY
It allows to enable (value: 1) or disable (value: 0) memory management using a circular buffer instead of a linear one. The default value is DISABLED (value: 0). If enabled, the memory is treated as a circular buffer, which means that when the memory runs out, the oldest data is deleted to make space for new. This means that a log can never be interrupted by an end-of-memory condition.
-
STREAMING CHANNEL
It allows to enable (value: 1) or disable (value: 0) the streaming over USB operating mode. The default value is DISABLED (value: 0). If enabled, it indicates that the streaming is performed via USB instead of BLE.
The user configuration command can be executed in both write and read mode. The HEX code is 0x51 (write), and 0xd1 (read).
To SET a new user configuration, the following command must be composed.
TRANSMISSION
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 51 | 04 | BIT MASK | USER CONFIGURATION | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 02 | 51 | ERROR CODE | 0 … 0 |
-
BIT MASK
It is a 16-bit unsigned integer value representing the configuration channels to be set. See Table 10. -
USER CONFIGURATION
It is a 16-bit unsigned integer value representing the configuration to be set.
Configuration | Mask Value |
---|---|
Standby (1 bit) | 0x01 |
Circular Memory (1 bit) | 0x02 |
Streaming Channel (3 bits) | 0x1c |
TABLE 10: BIT-MASK DEFINITION FOR USER CONFIGURATION MANAGEMENT.
To properly encode all the accepted configuration, the following tables summarize the bit order and hex/decimal codes to be used.
LSB Byte | MSB Byte | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Bit Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
Field | STANDBY | CIRCULAR MEMORY | STREAMING CHANNEL | RFU (0xff) |
TABLE 11: USER CONFIGURATION REGISTER.
STANDBY | CIRCULAR MEMORY | STREAMING CHANNEL | USER CONFIGURATION | |||
---|---|---|---|---|---|---|
Status | Value | Status | Value | Status | Value | |
False | 0 | False | 0 | False | 0 | 0 |
True | 1 | False | 0 | False | 0 | 1 |
False | 0 | True | 2 | False | 0 | 2 |
True | 1 | True | 2 | False | 0 | 3 |
False | 0 | False | 0 | True | 4 | 4 |
True | 1 | False | 0 | True | 4 | 5 |
False | 0 | True | 2 | True | 4 | 6 |
True | 1 | True | 2 | True | 4 | 7 |
TABLE 12: CODES TO BE SET AS USER CONFIGURATION BASED ON ENABLED / DISABLED FLAGS.
To GET current user configuration, the following command must be composed.
TRANSMISSION
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | D1 | 00 | 0 … 0 |
RESPONSE
Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | TYPE | LENGTH | VALUE (Payload) | |||||||||||||||||
Value | 00 | 04 | D1 | ERROR CODE | USER CONFIGURATION | 0 … 0 |
-
USER CONFIGURATION
It is a 16-bit unsigned integer value representing the current configuration. To decode the value of each configuration flag, a bitwise AND operation using the masks provided in Table 10 must be performed.