Adding Custom Device Firmware
The Data Capture Lab supports data collection from any third-party hardware.
Note
If you have your own means of collecting sensor data from your embedded device, the Data Capture Lab can import CSV/WAV datasets from any source. See more on the various import formats described in the Importing External Sensor Data Documentation.
Interfacing with Data Collection Firmware
Follow the steps below to use your embedded device to capture sensor data in the Data Capture Lab.
Implement the SensiML Simple Streaming Interface in your embedded device firmware. The Simple Streaming Interface specification can be found in the Simple Streaming Interface Documentation.
Create a Device Plugin. A Device Plugin is created by implementing an .SSF (SensiML Sensor Format) file. We will go over how to define the .SSF file below.
Device Plugins
Device Plugins are a list of properties that describe how the DCL will collect data from your device. For example, the device plugin may contain a list of sample rates that your device supports. This allows the DCL to collect data from any device that has been built to accept the supported parameters below.
How to Import a Device Plugin
The Data Capture Lab allows you to import Device Plugins via .SSF files. We will define the SSF file format in the next section below. For now, just note that you can import your SSF file through the menu item Edit → Import Device Plugin…
Example SSF File
Note
Device Plugins require that you set your own uuid property in the SSF file. The uuid is how the DCL identifies your Device Plugin.
SSF File Format
The Data Capture Lab allows you to import Device Plugins via .SSF files. Let’s go over the SSF file format and how this file will be used in the DCL. The SSF file format is a JSON based format with JSON properties that the DCL will use when configuring your Device Plugin.
Open the
Example SSF Filein any text editor and look at the properties. We will define these properties in the next section.
When you import your Device Plugin the DCL will use the plugin to dynamically build out a screen for a user to configure sensor properties during data collection. See a screenshot below for a better understanding of how these parameters will be displayed in the DCL:
Notice that there are options for selecting your Device Plugin sample rate and sensors in the screenshot. Now, let’s look at how this screen will map to the SSF file format.
JSON Object Definitions
Device Plugin
uuid |
(GUID) A unique ID to identify a plugin |
device_name |
(String) Name of your device |
device_manufacturer |
(String) Name of the developer or company that manufacturers the device |
plugin_developer |
(String) Name of the developer or company that developed the Device Plugin |
firmware_download_links |
(List<Object>) A list of links that a user can use to find information on updating the device firmware for data collection. See how to define a firmware_download_link in the Plugin Link section |
documentation_links |
(List<Object>) A list of links that a user can use to find information on general tutorials or useful documentation about the device. See how to define a documentation_link in the Plugin Link section |
capture_sources |
(List<Object>) Defines each of the sensors in your device. See how to define the capture_source JSON property in the Capture Source section |
device_connections |
(List<Object>) Defines the connection protocols your board supports. See how to how to define the device_connection JSON property in the Device Connection section |
is_little_endian |
(Boolean) Defines if your embedded device is little endian (true) or big endian (false) |
Example Device Plugin:
{
"uuid": "00000000-0000-0000-0000-000000000000",
"device_name": "Your Device Name",
"device_manufacturer": "You Device Manufacturer",
"plugin_developer": "Your Device Plugin Developer",
"firmware_download_links": [
],
"documentation_links": [
],
"capture_sources": [
],
"device_connections": [
],
"is_little_endian": true
}
Plugin Link
title |
(String) A user-friendly title for the link. Example: Data Collection Tutorial |
description |
(String) An optional field used to describe the contents of the link |
link |
(String) Hyperlink URL location. Example: https://sensiml.com/documentation/data-capture-lab/flashing-data-collection-firmware.html |
Example Plugin Link:
{
"title": "Data Collection Firmware",
"description": "",
"link": "https://sensiml.com/documentation/data-capture-lab/flashing-data-collection-firmware.html"
}
Capture Source
name |
(String) Display name for your source. Example: Motion is used to describe a source that can supply both an Accelerometer and a Gyroscope sensor. Audio is used to describe a source that is a Microphone sensor. |
part |
(String) Name of the device hardware part. Set to “Default” if a device only has one |
sample_rates |
(List<Integer>) A list of all available sample rates your device can support |
sensors |
(List<Object>) Defines the sensors your board supports. See how to how to define the sensor JSON property in the Sensor section |
Example Capture Source:
{
"name": "Motion",
"part": "Default",
"sample_rates": [
400,
200,
100,
50
],
"sensors": [
]
}
Sensor
type |
(String) Class/name of the sensor. Example: Accelerometer |
is_default |
(Boolean) Defines if this sensor is selected as a default option in the Data Capture Lab user interface |
column_count |
(Integer) Defines how many columns of data this sensor sends |
column_suffixes |
(List<String>) A list of strings used to describe sensors axes or channels. During data collection the Data Capture Lab will append the column_suffix to the sensor name to create the sensor column names. For example: X | Y | Z on Accelerometer would save as AccelerometerX | AccelerometerY | AccelerometerZ |
parameters |
(List<Object>) Defines a list of sensor specific parameters such as Accelerometer range or Microphone gain. See how to how to define the sensor_parameter JSON property in the Sensor Parameter section |
Example Sensor:
{
"type": "Accelerometer",
"is_default": true,
"column_count": 3,
"column_suffixes": [
"X",
"Y",
"Z"
],
}
Sensor Parameter
Sensor Parameters are used to define properties you wish to send to the sensor during data collection or recognition. For example setting the Range in an Accelerometer sensor.
We do not support Sensor Parameters out-of-the-box, but if you contact the SensiML integration team, we can work with you.
name |
(String) Name of the parameter sent as an unsigned integer value to the device. It must match the definition used on your device. This is used for both data collection and for a Knowledge Pack to configure your sensors. |
values |
(List<Object>) Defines a list of available parameter values for the user to select. See how to how to define the value JSON property in the Sensor Parameter Value section |
Sensor Parameter Value
display_value |
(String) Value to be displayed to the user |
actual_value |
(Integer) Value to be used when configuring the device (saved as an unsigned 64-bit value). This can be turned into a byte array with the num_bytes property |
num_bytes |
(Integer) The number of bytes that the actual_value property needs to be converted. This is typically one byte. |
Sensor Paramater/Parameter Value Example:
{
"name": "Accelerometer Range",
"values": [
{
"actual_value": 20,
"num_bytes": 1,
"display_value": "+/- 2G"
},
{
"actual_value": 40,
"num_bytes": 1,
"display_value": "+/- 4G"
},
{
"actual_value": 80,
"num_bytes": 1,
"display_value": "+/- 8G"
},
{
"actual_value": 160,
"num_bytes": 1,
"display_value": "+/- 16G"
}
],
}
Device Connection
Device connections define the protocol for how you will connect to your device (Bluetooth-Low Energy, Serial/Wired UART Port, or Wi-Fi).
display_name |
(String) Name to be displayed to the user |
value |
(Integer) Value to define the connection type. There are three available options: |
is_default |
(Boolean) Defines if this connection is the default option in the Data Capture Lab user interface |
bluetooth_le_configuration |
(Object) Defines Bluetooth-Low Energy specific configuration options. See how to how to define the bluetooth_le_configuration JSON property in the Bluetooth-LE Configuration section |
serial_port_configuration |
(Object) Defines Serial/Wired UART Port specific configuration options. See how to how to define the serial_port_configuration JSON property in the Serial Port Configuration section |
Device Connection Example:
{
"display_name": "Serial Port",
"value": 1,
"is_default": true,
"serial_port_configuration": {
}
}
Bluetooth-LE Configuration
uuid_service |
(GUID) The service UUID of your device GATT service for data collection |
uuid_sensor_data_out |
(GUID) The characteristic UUID that transmits your sensor data output |
uuid_device_configuration |
(GUID) The characteristic UUID that transmits your device json configuration information |
Example Bluetooth-LE Configuration:
{
"bluetooth_le_configuration": {
"uuid_service": "00000000-0000-0000-0000-000000000000",
"uuid_sensor_data_out": "00000000-0000-0000-0000-000000000000",
"uuid_device_configuration": "00000000-0000-0000-0000-000000000000"
}
}
Serial Port Configuration
baud_rate |
(Integer) Speed at which you communicate. Default value is 115200. Refer to Microsoft BaudRate Documentation for more details |
stop_bits |
(Integer) Number of stop bits. Default value is 1. Refer to Microsoft StopBits Documentation for more details |
parity |
(Integer) Parity scheme. Default value is 0. Refer to Microsoft Parity Documentation for more details |
handshake |
(Integer) Handshake scheme. Default value is 0. Refer to Microsoft Handshake Documentation for more details |
Example Serial Configuration:
{
"serial_port_configuration": {
"baud": 921600,
"stop_bits": 1,
"parity": 0,
"handshake": 0
}
}