Specimen Data Format

The Specimen Data Format developed for the Bosch Sensortec BME688 is used to store data for a specific specimen. BME AI-Studio can be used to import Raw Data Raw Data Format, which then can be sliced into one or multiple specimens. Specimen Data files can be exchanged between different BME AI-Studio projects. If curated correctly they should only contain gas data that belongs to one specific specimen or situation.

File Name

The filename consists of the following parts (each separated by a _):

<specimen_name>
<id>
.bmespecimen

Example: coffee_2.bmespecimen

part	Description
`<specimen_name>`	individual name that can be defined within the BME AI-Studio (strings are converted to lowercase and spaces are replaced with dashes)
`<id>`	project-specific id per specimen
`.bmerawdata`	BME AI-Studio specific ending with JSON syntax

Structure

The file is structured into a metadata part (meta) and data part (data).

The meta part consists of:

appVersion states application version number of BME AI-Studio that created the board configuration
exportedAt states export date and time, according to ISO 8601 in Coordinated Universal Time (UTC)

The data part consists of:

specimenData
measurementSession
boardConfig
boardType
heaterProfiles
dutyCycleProfiles
sensorConfigs
sensors
cycles
dataColumns
specimenDataPoints

The following subsections give a description of each parameter used.

specimenData

Parameter	Description
id	Project-specific Specimen id (automatically defined by BME AI-Studio)
uuid	Universally unique identifier (UUID) per Specimen
comment	Comment that further describes the Specimen
startTime	Start time of time interval that references to `real_time_clock` within specimenDataPoints
endTime	End time of time interval that references to `real_time_clock` within specimenDataPoints
cloneOfUuid	Used for BME AI-Studio internal data handling
measurementSessionId	Reference to `id` of Measurement Session to which this Specimen belongs to
createdAt	Creation date and time of Specimen, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Specimen, according to ISO 8601 in Coordinated Universal Time (UTC)
label	Specimen Label (see Specimen Label)
metaData	List of Meta Data keys and values

measurementSession

Parameter	Description
id	Project-specific Measurement Session id (automatically defined by BME AI-Studio)
uuid	Universally unique identifier (UUID) per Measurement Session
name	Measurement Session label (see Session Name)
startTime	Recording start date and time of Measurement Session, according to ISO 8601 in Coordinated Universal Time (UTC)
endTime	Recording end date and time of Measurement Session, according to ISO 8601 in Coordinated Universal Time (UTC)
boardId	Unique board id for the BME688 Development Kit used for recording
createdAt	Creation date and time of Measurement Session, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Measurement Session, according to ISO 8601 in Coordinated Universal Time (UTC)

boardConfig

Parameter	Description
id	Project-specific Board Configuration id (automatically defined by BME AI-Studio)
boardMode	Identifier for Board Mode. `burn_in` refers to Sensorboard Default HP/RDC, `heater_profile_exploration` refers to Heater Profile Exploration, `duty_cycle_profile_exploration` refers to Duty Cycle Exploration. Other `boardMode` are also accepted, and can be used when data is recorded with specific settings.
measurementSessionId	Reference to `id` of Measurement Session to which this Board Configuration belongs to
boardTypeId	Reference to `id` of Board Type to which this Board Configuration belongs to
createdAt	Creation date and time of Board Configuration, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Board Configuration, according to ISO 8601 in Coordinated Universal Time (UTC)

boardType

Parameter	Description
id	Project-specific Board Type id (automatically defined by BME AI-Studio)
uid	Unique identifier for the type of hardware used. `board_8` refers to the BME688 Development Kit. See Board type. Other `boardType` are also accepted, and can be used when data is recorded with other hardware devices.
name	Individual name of the hardware used (e.g. "BME688 Development Kit")
numSensors	Number of (BME688) sensors on the hardware
createdAt	Creation date and time of Board Type, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Board Type, according to ISO 8601 in Coordinated Universal Time (UTC)

heaterProfiles

Parameter specification per Heater Profile:

Parameter	Description
id	Project-specific Heater Profile id (automatically defined by BME AI-Studio)
uid	Unique identifier for the Heater Profile
name	Individual name of the Heater Profile
useCase	Additional information on specific use cases
timeBase	Defines the base unit of time used for `temperatureTimeVectors` (stated in milliseconds). In order to work properly it should be set to 140.
steps	Temperature-duration steps, where `temperature` is stated in degree Celsius and `duration` is stated as multiples of `timeBase`.
createdAt	Creation date and time of Heater Profile, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Heater Profile, according to ISO 8601 in Coordinated Universal Time (UTC)

dutyCycleProfiles

Parameter specification per Duty Cycle Profile:

Parameter	Description
id	Project-specific Duty Cycle id (automatically defined by BME AI-Studio)
uid	Unique identifier for the Duty Cycle Profile
name	Individual name of the Duty Cycle Profile
description	Additional information
energyConsumption	States the energy consumption of the Duty Cycle Profile in mA
scanningCycles	States the number of Scanning Cycles
sleepingCycles	States the number of Sleeping Cycles
createdAt	Creation date and time of Duty Cycle Profile, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Duty Cycle Profile, according to ISO 8601 in Coordinated Universal Time (UTC)

sensorConfigs

The Sensor Configuration attaches a Board Configuration and individual Heater Profiles and Duty Cycle Profiles to a specific sensor.

Parameter specification per Sensor Configuration:

Parameter	Description
id	Project-specific Sensor Configuration id (automatically defined by BME AI-Studio)
boardConfigId	Reference to `id` of Board Configuration to which this Sensor Configuration belongs to
sensorId	Reference to `id` of Sensors to which this Sensor Configuration belongs to
heaterProfileId	Reference to `id` of Heater Profile to which this Sensor Configuration belongs to
dutyCycleProfileId	Reference to `id` of Duty Cycle Profile to which this Sensor Configuration belongs to
createdAt	Creation date and time of Sensor Configuration, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of Sensor Configuration, according to ISO 8601 in Coordinated Universal Time (UTC)

sensors

The list of sensors connects their Id (used within BME AI-Studio) to their index (used in raw data logging).

Parameter specification per sensor:

Parameter	Description
id	Project-specific sensor id (automatically defined by BME AI-Studio)
index	Sensor index which is used within Raw Data Format
createdAt	Creation date and time of sensor, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of sensor, according to ISO 8601 in Coordinated Universal Time (UTC)

cycles

The list of curated Scanning Cycles.

Parameter specification per cycle:

Parameter	Description
id	Project-specific cycle id (automatically defined by BME AI-Studio)
uuid	Universally unique identifier (UUID) per cycle that references to `cycle_id` within specimenDataPoints
startTime	Start time of cycle that references to `real_time_clock` within specimenDataPoints
endTime	End time of cycle that references to `real_time_clock` within specimenDataPoints
dropped	Decision (encoded as boolean), whether cycle was selected as "dropped" within import process (see Cycles Dropped)
measurementSessionId	Reference to `id` of Measurement Session to which this cycle belongs to
sensorId	Reference to `id` of Sensors to which this cycle belongs to
createdAt	Creation date and time of cycle, according to ISO 8601 in Coordinated Universal Time (UTC)
updatedAt	Update date and time of cycle, according to ISO 8601 in Coordinated Universal Time (UTC)

dataColumns

Every block within dataColumns describes one of the 12 data columns within specimenDataPoints.

Here are some additional remarks concerning the column descriptions:

data_point_id is a unique id per data point, that can be used to trace back data to an individual sensor element
error_code states errors that happened during recording with the follwing encoding:
1 for invalid Heater Profiles (affects all data points that follow)
2for time stamp mismatch or data loss (affects only a single data point, dropping the whole cycle is recommended)
3 for communication errors (affects only a single data point, dropping the whole cycle is recommended).
cycle_step_index is a counter for 10 heater steps that will be cycled continously (see Heater Profile ). Counting starts at 0 up to 9.

specimenDataPoints

The part carries the sensor data in a condensed form according to dataColumns.

Example

{
  "meta": {
    "appVersion": "2.2.0",
    "exportedAt": "2023-10-05T13:04:14.888Z"
  },
  "data": {
    "specimenData": {
      "id": 18,
      "uuid": "a4c9403f-7275-43b9-ad2e-59183a01324b",
      "comment": " ",
      "startTime": 220894,
      "endTime": 921935,
      "cloneOfUuid": null,
      "measurementSessionId": 3,
      "createdAt": "2023-09-08T11:46:12.000Z",
      "updatedAt": "2023-10-02T15:44:59.000Z",
      "label": "100g Water + 1g Desinfectant",
      "metaData": [
        {
          "key": "Caffeine [mg]",
          "value": null
        }
      ]
    },
    "measurementSession": {
      "id": 3,
      "uuid": "58660f88-e1ce-4c0d-8ee8-77c151ee37e5",
      "name": null,
      "startTime": "2023-07-28T07:57:36.000Z",
      "endTime": "2023-07-28T08:32:28.000Z",
      "boardId": "E0E2E69BA804",
      "createdAt": "2023-09-08T11:46:12.000Z",
      "updatedAt": "2023-09-08T11:46:12.000Z"
    },
    "boardConfig": {
      "id": 3,
      "boardMode": "heater_profile_exploration",
      "measurementSessionId": 3,
      "boardTypeId": 1,
      "createdAt": "2023-09-08T11:46:12.000Z",
      "updatedAt": "2023-09-08T11:46:12.000Z"
    },
    "boardType": {
      "id": 1,
      "uid": "board_8",
      "name": "BME688 Development Kit",
      "numSensors": 8,
      "createdAt": "2022-12-05T16:33:29.339Z",
      "updatedAt": "2022-12-05T16:33:29.339Z"
    },
    "heaterProfiles": [
      {
        "id": 1,
        "uid": "heater_301",
        "name": "HP-301",
        "useCase": "",
        "timeBase": 140,
        "steps": [
          {
            "temperature": 100,
            "duration": 2
          },
          {
            "temperature": 100,
            "duration": 41
          },
          {
            "temperature": 200,
            "duration": 2
          },
          {
            "temperature": 200,
            "duration": 14
          },
          {
            "temperature": 200,
            "duration": 14
          },
          {
            "temperature": 200,
            "duration": 14
          },
          {
            "temperature": 320,
            "duration": 2
          },
          {
            "temperature": 320,
            "duration": 14
          },
          {
            "temperature": 320,
            "duration": 14
          },
          {
            "temperature": 320,
            "duration": 14
          }
        ],
        "createdAt": "2022-12-05T16:33:29.332Z",
        "updatedAt": "2022-12-05T16:33:29.332Z"
      }
    ],
    "dutyCycleProfiles": [
      {
        "id": 3,
        "uid": "duty_1",
        "name": "RDC-1-0 Continuous",
        "description": "This is a continous duty cycle profile, which is best suited for maximum data acquisition, but with maximum power consumption. Please not that the sensor will significantly warm up in continous duty cycle profile.",
        "energyConsumption": 12,
        "scanningCycles": 1,
        "sleepingCycles": 0,
        "createdAt": "2022-12-05T16:33:29.337Z",
        "updatedAt": "2022-12-05T16:33:29.337Z"
      },
      {
        "id": 12,
        "uid": "duty_5_10",
        "name": "RDC-5-10",
        "description": "",
        "energyConsumption": 4,
        "scanningCycles": 5,
        "sleepingCycles": 10,
        "createdAt": "2021-05-19T12:29:24.267Z",
        "updatedAt": "2021-05-19T12:29:24.267Z"
      }
    ],
    "sensorConfigs": [
      {
        "id": 17,
        "boardConfigId": 3,
        "sensorId": 17,
        "heaterProfileId": 1,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 18,
        "boardConfigId": 3,
        "sensorId": 18,
        "heaterProfileId": 1,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 19,
        "boardConfigId": 3,
        "sensorId": 19,
        "heaterProfileId": 7,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 20,
        "boardConfigId": 3,
        "sensorId": 20,
        "heaterProfileId": 7,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 21,
        "boardConfigId": 3,
        "sensorId": 21,
        "heaterProfileId": 9,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 22,
        "boardConfigId": 3,
        "sensorId": 22,
        "heaterProfileId": 9,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 23,
        "boardConfigId": 3,
        "sensorId": 23,
        "heaterProfileId": 12,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 24,
        "boardConfigId": 3,
        "sensorId": 24,
        "heaterProfileId": 12,
        "dutyCycleProfileId": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      }
    ],
    "sensors": [
      {
        "id": 17,
        "index": 0,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 18,
        "index": 1,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 19,
        "index": 2,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 20,
        "index": 3,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 21,
        "index": 4,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 22,
        "index": 5,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 23,
        "index": 6,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 24,
        "index": 7,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      }
    ],
    "cycles": [
      {
        "id": 4352,
        "uuid": "a6153bb3-2217-4494-9dfd-2c4635c6ce43",
        "startTime": 221518,
        "endTime": 239542,
        "dropped": false,
        "measurementSessionId": 3,
        "sensorId": 17,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 4360,
        "uuid": "f9eeb8fc-f089-4a5b-80f4-7b9ac6591220",
        "startTime": 239998,
        "endTime": 258049,
        "dropped": false,
        "measurementSessionId": 3,
        "sensorId": 17,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 4370,
        "uuid": "4ddb91d7-67cc-43f6-9bcd-55f2733e9f9a",
        "startTime": 258482,
        "endTime": 276541,
        "dropped": false,
        "measurementSessionId": 3,
        "sensorId": 17,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      },
      {
        "id": 4377,
        "uuid": "d1122e71-97c1-4e52-ab49-a7a3e4bdb4db",
        "startTime": 276968,
        "endTime": 294970,
        "dropped": false,
        "measurementSessionId": 3,
        "sensorId": 17,
        "createdAt": "2023-09-08T11:46:12.000Z",
        "updatedAt": "2023-09-08T11:46:12.000Z"
      }
    ],
    "dataColumns": [
      {
        "name": "Data Point ID",
        "unit": "",
        "format": "integer",
        "key": "data_point_id"
      },
      {
        "name": "Resistance Gassensor",
        "unit": "Ohms",
        "format": "float",
        "key": "resistance_gassensor"
      },
      {
        "name": "Temperature",
        "unit": "DegreesCelsius",
        "format": "float",
        "key": "temperature"
      },
      {
        "name": "Pressure",
        "unit": "Hectopascals",
        "format": "float",
        "key": "pressure"
      },
      {
        "name": "Relative Humidity",
        "unit": "Percent",
        "format": "float",
        "key": "relative_humidity"
      },
      {
        "name": "Time Since PowerOn",
        "unit": "Milliseconds",
        "format": "integer",
        "key": "timestamp_since_poweron"
      },
      {
        "name": "Real time clock",
        "unit": "Unix Timestamp: seconds since Jan 01 1970. (UTC); 0 = missing",
        "format": "integer",
        "key": "real_time_clock"
      },
      {
        "name": "Error Code",
        "unit": "",
        "format": "integer",
        "key": "error_code"
      },
      {
        "name": "Cycle Step Index",
        "unit": "",
        "format": "integer",
        "key": "cycle_step_index"
      },
      {
        "name": "Cycle ID",
        "unit": "",
        "format": "integer",
        "key": "cycle_id"
      }
    ],
    "specimenDataPoints": [
      [
        43440,
        102400000,
        38.939491,
        979.661133,
        27.739399,
        221518,
        1690531277,
        0,
        0,
        4352
      ],
      [
        43441,
        102400000,
        38.043331,
        979.61792,
        28.48719,
        227161,
        1690531283,
        0,
        1,
        4352
      ],
      [
        43442,
        7994145,
        38.353733,
        979.60968,
        28.582357,
        227446,
        1690531283,
        0,
        2,
        4352
      ],
      [
        43443,
        6618461,
        39.024601,
        979.644348,
        28.885283,
        229422,
        1690531285,
        0,
        3,
        4352
      ],
      [
        43444,
        5645761.5,
        39.112213,
        979.663635,
        28.904493,
        231382,
        1690531287,
        0,
        4,
        4352
      ]
    ]
  }
}

# Specimen Data Format

# File Name

# Structure

# specimenData

# measurementSession

# boardConfig

# boardType

# heaterProfiles

# dutyCycleProfiles

# sensorConfigs

# sensors

# cycles

# dataColumns

# specimenDataPoints

# Example