Ir para o conteúdo

MQTT Topics and CDDL Messages Documentation

This document details all MQTT topics used in the SESI Ergotech project, as well as the structure of the messages exchanged via the CDDL (Context Data Distribution Layer) middleware.


1. CDDL Middleware (Context Data Distribution Layer)

CDDL is a middleware developed to facilitate the development of ubiquitous computing applications, focusing on the collection, processing, and distribution of context data. In the SESI Ergotech project, it acts as the abstraction layer between the sensors (Smartphone and Wearables) and the data consumers.

1.1. Technical Architecture

The CDDL architecture in the project is based on a local Micro-Broker model: - Microbroker: An embedded MQTT broker that runs inside the Android app itself. This allows communication between internal sensors and the app's logic to happen locally, even without internet access. - Pub/Sub Abstraction: CDDL uses the Publisher and Subscriber concepts to isolate the complexity of the MQTT protocol and connectivity. - Hybrid Connectivity: Supports publishing data both to the local broker and forwarding it to an External Broker (remote server), ensuring cloud persistence.

1.2. Main Features

  • Context Management: Automates the discovery of new sensors (mobile objects) and their disconnection through dedicated event topics.
  • Query Processing: Supports SQL-based filters (e.g.: SELECT * FROM Message WHERE confidence >= 70) so that subscribers receive only relevant data.
  • Security: Implements authentication and encryption via TLS/SSL, using KeyStore to manage certificates and granular per-topic access permissions through the SecurityService.
  • Interoperability: Transparently integrates different communication technologies (Bluetooth LE for wearables and internal Android sensors) for the developer.

2. MQTT Topics

CDDL uses a hierarchical topic pattern to distribute context data and object lifecycle events.

2.1. Service Topics (Sensors)

Sensor data is published and subscribed to on topics based on the service (sensor) name and scoped to the publishing client, so that each subscriber can isolate exactly one client's traffic by topic alone, without inspecting message content.

Format: mhub/{clientId}/service_topic/<serviceName>

Example subscriptions (from a real client session):

MQTT_Client -> Broker: Subscribe("mhub/{clientId}/service_topic/PolarSense_HR")
MQTT_Client -> Broker: Subscribe("mhub/{clientId}/service_topic/PolarH10_HR")
MQTT_Client -> Broker: Subscribe("mhub/{clientId}/service_topic/BHBHT008010_HeartRateSensor")
MQTT_Client -> Broker: Subscribe("mhub/{clientId}/service_topic/BHBHT008010_RespirationRateSensor")
MQTT_Client -> Broker: Subscribe("mhub/{clientId}/service_topic/ActivityDetectionSensor")
MQTT_Client -> Broker: Subscribe("mhub/{clientId}/service_topic/BloodGlucose")

HDT-AF integration note (BL-237): earlier revisions of this document, and of the HDT-AF reference platform's IotTopics class, incorrectly used a global format for this topic family (microbroker/cddl/service/<serviceName>, with no clientId segment), scoping the publisher by the envelope's senderId instead of by the topic path. That was reconciled against this document's own example subscriptions above, which are what the real CDDL/SESI Ergotech client actually uses. IotTopics.cddlService(clientId, serviceName) now emits the mhub/… format described here; see docs/components/07-data-component.md and docs/components/14-iot-replay-simulator.md.

List of Identified Services and Attributes:

Service Name Category Description Attributes (availableAttributesList)
ActivityDetectionSensor Smartphone Physical activity detection activity, confidence
PolarSense_PPG Wearable Photoplethysmography (Polar Sense) ppg0, ppg1, ppg2, ambient
PolarSense_PPI Wearable Peak-to-Peak Interval (Polar Sense) ppi, hr, errorEstimate, blockerBit, skinContactStatus, skinContactSupported
PolarSense_HR Wearable Heart Rate (Polar Sense) hr, rr
PolarSense_ACC Wearable Accelerometer (Polar Sense) x, y, z
PolarSense_MAGNETOMETER Wearable Magnetometer (Polar Sense) x, y, z
PolarSense_GYRO Wearable Gyroscope (Polar Sense) x, y, z
PolarH10_ECG Wearable Electrocardiogram (Polar H10) ecg
PolarH10_HR Wearable Heart Rate (Polar H10) hr, rr
PolarH10_ACC Wearable Accelerometer (Polar H10) x, y, z
Polar360_HR Wearable Heart Rate (Polar 360) hr, rr
Polar360_SKIN_TEMPERATURE Wearable Skin Temperature (Polar 360) temperature
HXM030655_HeartRateSensor Wearable Zephyr HXM Heart Rate Sensor hr, rr
BHBHT_HeartRateSensor Wearable Heart Rate (BioHarness) hr
BHBHT_RespirationRateSensor Wearable Respiration Rate (BioHarness) respirationRate
BHBHT_PostureSensor Wearable Posture (BioHarness) posture
BHBHT_ECGSamplesSensor Wearable ECG Samples (BioHarness) ecg
Location Smartphone Location (GPS/Network) latitude, longitude, altitude, accuracy
Battery Smartphone Battery charge level level, status, health
ActivityTransitionSensor Smartphone Transitions between activities activity, transitionType
Goldfish 3-axis Accelerometer Smartphone 3-axis accelerometer x, y, z
Goldfish 3-axis Gyroscope Smartphone 3-axis gyroscope x, y, z
Goldfish 3-axis Magnetic field sensor Smartphone Magnetometer x, y, z
Goldfish Orientation sensor Smartphone Orientation azimuth, pitch, roll
Goldfish Ambient Temperature sensor Smartphone Ambient temperature temperature
Goldfish Proximity sensor Smartphone Proximity to objects distance
Goldfish Light sensor Smartphone Light level light
Goldfish Pressure sensor Smartphone Barometer/Pressure pressure
Goldfish Humidity sensor Smartphone Relative humidity humidity
Goldfish 3-axis Magnetic field sensor (uncalibrated) Smartphone Uncalibrated magnetometer x_uncalib, y_uncalib, z_uncalib, x_bias, y_bias, z_bias
Goldfish 3-axis Gyroscope (uncalibrated) Smartphone Uncalibrated gyroscope x_uncalib, y_uncalib, z_uncalib, x_bias, y_bias, z_bias
Goldfish 3-axis Accelerometer Uncalibrated Smartphone Uncalibrated accelerometer x_uncalib, y_uncalib, z_uncalib, x_bias, y_bias, z_bias
Game Rotation Vector Sensor Smartphone Rotation (Game-optimized) x, y, z, cos, estimated_accuracy
GeoMag Rotation Vector Sensor Smartphone Rotation (Magnetic field) x, y, z, cos, estimated_accuracy
Gravity Sensor Smartphone Gravity x, y, z
Linear Acceleration Sensor Smartphone Linear acceleration x, y, z
Rotation Vector Sensor Smartphone Estimated orientation (Fusion) x, y, z, cos, estimated_accuracy
Orientation Sensor Smartphone Orientation (Legacy/Deprecated) azimuth, pitch, roll
BloodPressure Manual Blood Pressure (Manual entry) systolic, diastolic
Oximeter Manual Oxygen Saturation (Manual entry) Spo2
BloodGlucose Manual Blood Glucose (Manual entry) BloodGlucose
Internal Sensors Smartphone Native Android sensors Depends on the sensor (e.g.: x, y, z for Accelerometer)

2.2. Event Topics

Used to monitor the discovery and disconnection of devices in the CDDL ecosystem.

Topic Description
microbroker/cddl/event/object/discovered Published when a new object (smartphone or wearable) is discovered.
microbroker/cddl/event/object/disconnected Published when an object disconnects.

3. Message Structure

Messages sent follow the Message and SensorDataMessage specification of CDDL.

3.1. Base JSON Format

{
  "uuid": "string",
  "serviceName": "string",
  "serviceValue": [object],
  "mouuid": "string",
  "timeStamp": long,
  "availableAttributes": int,
  "availableAttributesList": ["string"],
  "publisherID": "string",
  "accuracy": double
}

3.2. Field Description

  • uuid: Globally unique message identifier.
  • serviceName: Name of the sensor or service that generated the data (per the table above).
  • serviceValue: Vector containing the values collected by the sensor. The meaning of each index depends on availableAttributesList.
  • mouuid: Unique identifier of the originating mobile object (device).
  • timeStamp: Timestamp in milliseconds since the epoch when the data was generated.
  • availableAttributes: Number of attributes present in serviceValue.
  • availableAttributesList: List of attribute names (e.g.: ["x", "y", "z"] for an accelerometer).
  • publisherID: Identification of the entity that published the message.
  • accuracy: (Optional) Precision level of the collected data.

4. Message Examples per Sensor

4.1. Heart Rate (PolarH10_HR, PolarSense_HR, Polar360_HR, HXM030655_HeartRateSensor)

{
  "serviceName": "PolarH10_HR",
  "serviceValue": [75.0, 800.0],
  "availableAttributesList": ["hr", "rr"],
  "timeStamp": 1716825600000
}

4.2. Accelerometer, Gyroscope, and Magnetometer (..._ACC, ..._GYRO, ..._MAGNETOMETER)

{
  "serviceName": "PolarSense_MAGNETOMETER",
  "serviceValue": [12.5, -45.2, 30.1],
  "availableAttributesList": ["x", "y", "z"],
  "timeStamp": 1716825600100
}

4.3. PPG - Photoplethysmography (PolarSense_PPG)

{
  "serviceName": "PolarSense_PPG",
  "serviceValue": [45231, 39822, 41203, 120],
  "availableAttributesList": ["ppg0", "ppg1", "ppg2", "ambient"],
  "timeStamp": 1716825600200
}

4.4. PPI - Peak-to-Peak Interval (PolarSense_PPI)

{
  "serviceName": "PolarSense_PPI",
  "serviceValue": [800, 75, 10, 0, 1, 1],
  "availableAttributesList": ["ppi", "hr", "errorEstimate", "blockerBit", "skinContactStatus", "skinContactSupported"],
  "timeStamp": 1716825600300
}

4.5. ECG - Electrocardiogram (PolarH10_ECG, BHBHT_ECGSamplesSensor)

{
  "serviceName": "PolarH10_ECG",
  "serviceValue": [240],
  "availableAttributesList": ["ecg"],
  "timeStamp": 1716825600400
}

4.6. Skin Temperature (Polar360_SKIN_TEMPERATURE)

{
  "serviceName": "Polar360_SKIN_TEMPERATURE",
  "serviceValue": [36.5],
  "availableAttributesList": ["temperature"],
  "timeStamp": 1716825600500
}

4.7. BioHarness Sensors (BHBHT_HeartRateSensor, BHBHT_RespirationRateSensor, BHBHT_PostureSensor)

{
  "serviceName": "BHBHT_RespirationRateSensor",
  "serviceValue": [16.0],
  "availableAttributesList": ["respirationRate"],
  "timeStamp": 1716825600600
}

4.8. Activity Detection (ActivityDetectionSensor)

{
  "serviceName": "ActivityDetectionSensor",
  "serviceValue": ["WALKING", 95.0],
  "availableAttributesList": ["activity", "confidence"],
  "timeStamp": 1716825605000
}

4.9. Location and Battery (Location, Battery)

{
  "serviceName": "Location",
  "serviceValue": [-2.5, -44.3, 15.0, 10.0],
  "availableAttributesList": ["latitude", "longitude", "altitude", "accuracy"],
  "timeStamp": 1716825612000
}

4.10. Motion and Environmental Sensors (Inertial and other)

The phone's native sensors (e.g.: Goldfish...) follow the inertial or single-reading pattern.

{
  "serviceName": "Goldfish 3-axis Accelerometer",
  "serviceValue": [0.0, 9.81, 0.0],
  "availableAttributesList": ["x", "y", "z"],
  "timeStamp": 1716825613000
}

4.11. Uncalibrated Sensors

{
  "serviceName": "Goldfish 3-axis Gyroscope (uncalibrated)",
  "serviceValue": [0.0, 0.0, 0.0, 0.01, 0.01, 0.01],
  "availableAttributesList": ["x_uncalib", "y_uncalib", "z_uncalib", "x_bias", "y_bias", "z_bias"],
  "timeStamp": 1716825614000
}

4.12. Data Fusion and Rotation (Rotation Vector Sensor, etc.)

{
  "serviceName": "Rotation Vector Sensor",
  "serviceValue": [0.1, 0.2, 0.3, 0.9, 0.05],
  "availableAttributesList": ["x", "y", "z", "cos", "estimated_accuracy"],
  "timeStamp": 1716825615000
}

4.13. Manual Entries (BloodPressure, Oximeter, BloodGlucose)

{
  "serviceName": "BloodPressure",
  "serviceValue": [120.0, 80.0],
  "availableAttributesList": ["systolic", "diastolic"],
  "timeStamp": 1716825610000
}
Oximeter example: serviceValue: [98.0], availableAttributesList: ["Spo2"] Blood glucose example: serviceValue: [105.0], availableAttributesList: ["BloodGlucose"]

5. QoS (Quality of Service) Policies

The project specifically configures message delivery behavior through CDDL:

  • Reliability: Supports BEST_EFFORT, RELIABLE, and EXACTLY_ONCE. Manual data is sent with EXACTLY_ONCE.
  • Time-based filter: Some sensors use TimeBasedFilterQoS with a minimum interval of 1000ms to avoid overload.
  • History: Configured to keep the last N seconds of data (KEEP_LAST) to support temporary disconnections.
  • Compression: Optional support for data compression before publishing to the external broker.