openJII MQTT API (AWS IoT Core)

v1.0.0MQTT

API Information: This AsyncAPI specification defines the MQTT topics and message schemas for AWS IoT Core. It details channels for device status updates and sensor data, allowing devices to publish their state and sensor readings securely.

Servers

production

URL	`a123456789.iot.us-east-1.amazonaws.com`
Protocol	MQTT
Description	AWS IoT Core production endpoint

Security

sigv4

Type: apiKey

Location: user

AWS Signature Version 4 is used to sign the MQTT connection requests to AWS IoT Core.

Operations

SUBSCRIBEexperiment/data_ingest/v1/{experimentId}/{sensorType}/{sensorVersion}/{sensorId}/{protocolId}

Channel for ingesting experiment sensor data. The path parameters represent:

experimentId: Unique identifier of the experiment (e.g., exp123).
sensorType: The type or family of sensor (e.g., MutlispeQ, Ambit...).
sensorVersion: Sensor firmware/hardware revision (without the 'v' prefix, e.g., 1, 2.1).
sensorId: Unique sensor identifier (UUID format recommended).
protocolId: Unique identifier for the sampling or measurement protocol (e.g., protoA).

Parameters

Name	Type	Description
`experimentId`	string	Unique identifier of the experiment (e.g., exp123).
`sensorType`	string	The type or family of sensor (e.g., MutlispeQ, Ambit...).
`sensorVersion`	string	Sensor firmware/hardware revision (e.g., v1, v2.1).
`sensorId`	string	Unique sensor identifier (UUID format recommended).
`protocolId`	string	Unique identifier for the sampling or measurement protocol (e.g., protoA).

Subscribe Operation

Operation ID: ingestExperimentData

Summary: Ingest experiment sensor data.

PUBLISHdevice/scripts/v1/{sensorType}/{sensorVersion}/{thingName}

Channel for delivering behaviour scripts to a device. The cloud publishes and the device subscribes, then applies the script to its attached sensor. Messages are published retained at QoS 1 so a device that reconnects immediately receives the current script for its topic. The path parameters represent:

sensorType: The target sensor family (e.g., MultispeQ, Ambit...).
sensorVersion: Target firmware/hardware revision (without the 'v' prefix, e.g., 1, 2.1).
thingName: AWS IoT Thing name of the target device. The IoT policy binds this segment to ${iot:Connection.Thing.ThingName}, so a device (authenticated by its X.509 certificate) can only subscribe to and receive its own scripts.

Parameters

Name	Type	Description
`sensorType`	string	The target sensor family (e.g., MultispeQ, Ambit...).
`sensorVersion`	string	Target firmware/hardware revision (without the 'v' prefix, e.g., 1, 2.1).
`thingName`	string	AWS IoT Thing name of the target device (e.g., dom_ludo_prototype_ambyte_thing_v2).

Publish Operation

Operation ID: deliverDeviceScript

Summary: Deliver a behaviour script to a device.

Messages

Experiment Data Ingestion Message

A message containing sensor data for an experiment.

Name	`ExperimentDataMessage`
Content Type	`application/json`

Payload Schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Sensor data payload.",
      "additionalProperties": true,
      "properties": {
        "sample": {
          "type": "string",
          "description": "Sensor sample data. May be a raw JSON string (legacy) or a gzip+base64 encoded string when _sample_encoding is set.\n"
        },
        "_sample_encoding": {
          "type": "string",
          "enum": [
            "gzip+base64"
          ],
          "description": "When present, indicates that the `sample` field has been compressed (gzip) and base64-encoded to reduce payload size. Absent on legacy (uncompressed) payloads.\n"
        },
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 timestamp with UTC offset captured at measurement time using the synced clock (e.g. \"2026-03-09T10:30:00.000-05:00\").\n"
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone identifier resolved from GPS at measurement time (e.g. \"America/Chicago\"). Preserved across retries so the original measurement-time timezone is never lost.\n"
        }
      }
    }
  },
  "required": [
    "data"
  ]
}

Example

Example 1

{
  "data": {
    "moisture": 30.5,
    "temperature": 22.1
  }
}

Device Script Update Message

A protocol measurement script delivered from the cloud to a device.

Name	`DeviceScriptMessage`
Content Type	`application/json`

Payload Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "script_update"
      ],
      "description": "Command discriminator, so the same topic can carry future command types."
    },
    "id": {
      "type": "string",
      "description": "Unique update identifier (e.g. upd-2026-06-08-001). Lets a device skip an update it has already applied."
    },
    "payload": {
      "type": "string",
      "description": "The protocol measurement script body (Lua source), sent inline. May be a raw string or a gzip+base64 encoded string when _payload_encoding is set.\n"
    },
    "_payload_encoding": {
      "type": "string",
      "enum": [
        "gzip+base64"
      ],
      "description": "When present, indicates that the `payload` field has been compressed (gzip) and base64-encoded. Absent on raw (uncompressed) payloads.\n"
    },
    "checksum": {
      "type": "string",
      "description": "SHA-256 hex digest of the decoded script body, for integrity verification before applying."
    }
  },
  "required": [
    "type",
    "id",
    "payload"
  ]
}

Example

Example 1

{
  "type": "script_update",
  "id": "upd-2026-06-08-001",
  "payload": "-- Lua protocol script\nreturn { pulses = 100, interval_ms = 500 }",
  "checksum": "adaeff5386f5e9dcaef58c0cc39f69f2d62a98bedae07195d02bdc82595a90ad"
}

Contact & License

Organization: openJII

Contact: ji-institute@info.nl

License: GNU General Public License