Device Plugins

Device Plugins are an optional feature in the Data Studio to ensure consistent data collection protocols are followed in a project. They contain list of properties that describe how the Data Studio 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 Data Studio to collect data from any device that has been built to accept the supported parameters below.

Device plugins force validation on connection so that a user always connects using the same sensors and sample rate.

How to Import a Device Plugin

The Data Studio 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…

../_images/menu-import-device-plugin.png

Example SSF File

Example SSF File

Note

Device Plugins require that you set your own uuid property in the SSF file. The uuid is how the Data Studio identifies your Device Plugin.

SSF File Format

The Data Studio 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 Data Studio. The SSF file format is a JSON based format with JSON properties that the Data Studio will use when configuring your Device Plugin.

Open the Example SSF File in any text editor and look at the properties. We will define these properties in the next section.

When you import your Device Plugin the Data Studio 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 Data Studio:

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-studio/flashing-data-collection-firmware.html

Example Plugin Link:

{
    "title": "Data Collection Firmware",
    "description": "",
    "link": "https://sensiml.com/documentation/data-studio/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 Studio 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 Studio 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

Example Sensor:

{
    "type": "Accelerometer",
    "is_default": true,
    "column_count": 3,
    "column_suffixes": [
        "X",
        "Y",
        "Z"
    ],
}

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: 0 : Bluetooth-Low Energy 1 : Serial/Wired UART Port 2 : Wi-Fi
is_default	(Boolean) Defines if this connection is the default option in the Data Studio 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
    }
}