Skip to main content

MQTT Topics Reference

Complete guide to MQTT topic structure, naming conventions, and access control rules.

Topic Structure Overview​

WAYSCloud IoT Platform uses a hierarchical topic structure based on device identity:

devices/{device_id}/{category}/{subcategory}

Device to Platform Topics​

Topics that devices can publish to send data to the platform.

Telemetry​

Send time-series sensor data and metrics.

Topic: devices/{device_id}/telemetry

Purpose: Real-time sensor readings, measurements, and continuous data streams

Example:

{
  "temperature": 22.5,
  "humidity": 65.3,
  "pressure": 1013.25,
  "timestamp": 1699189234
}

Payload format: JSON (recommended) or any custom format

QoS recommendation: 1

Use cases:

  • Temperature/humidity readings
  • GPS coordinates
  • Energy consumption
  • Vibration data
  • Any time-series measurements

Events​

Send discrete event notifications and alerts.

Topic: devices/{device_id}/events

Purpose: Significant events, alerts, and state changes

Example:

{
  "event_type": "door_opened",
  "timestamp": 1699189234,
  "metadata": {
    "sensor_id": "door-01",
    "location": "entrance"
  }
}

QoS recommendation: 1 or 2 (depending on criticality)

Use cases:

  • Motion detected
  • Alarm triggered
  • Door opened/closed
  • Button pressed
  • Error conditions
  • Maintenance required

Attributes​

Send or update device metadata and properties.

Topic: devices/{device_id}/attributes

Purpose: Device configuration, capabilities, and metadata

Example:

{
  "firmware_version": "2.1.0",
  "model": "DHT22",
  "manufacturer": "Sensors Inc",
  "location": "warehouse-a",
  "capabilities": ["temperature", "humidity"]
}

QoS recommendation: 1

Retain: true (recommended)

Use cases:

  • Firmware version
  • Device model/serial
  • Capabilities
  • Configuration snapshot
  • Location updates

Status​

Send device health and connectivity status.

Topic: devices/{device_id}/status

Purpose: Device online/offline status and health indicators

Example:

{
  "status": "online",
  "uptime": 86400,
  "memory_free": 45120,
  "battery_level": 85,
  "signal_strength": -65,
  "timestamp": 1699189234
}

QoS recommendation: 1

Retain: true (recommended for online/offline status)

Use cases:

  • Online/offline heartbeat
  • Battery level
  • Memory usage
  • Network signal strength
  • System health

Platform to Device Topics​

Topics that devices can subscribe to receive commands and updates.

Commands - Reboot​

Trigger device reboot.

Topic: devices/{device_id}/commands/reboot

Payload:

{
  "delay_seconds": 10,
  "reason": "firmware_update"
}

Device action: Perform graceful shutdown and restart

Commands - Configuration​

Update device configuration.

Topic: devices/{device_id}/commands/config

Payload:

{
  "telemetry_interval": 60,
  "temperature_threshold": 25.0,
  "enable_debug": false
}

Device action: Apply new configuration and acknowledge

Commands - Firmware Update​

Initiate firmware update.

Topic: devices/{device_id}/commands/firmware

Payload:

{
  "version": "2.1.0",
  "url": "https://firmware.wayscloud.services/device-fw-2.1.0.bin",
  "checksum": "sha256:abc123...",
  "size_bytes": 524288
}

Device action: Download, verify, and install firmware

Commands - Custom​

Send custom application-specific commands.

Topic: devices/{device_id}/commands/custom

Payload: Application-specific JSON

Example:

{
  "command": "calibrate_sensor",
  "parameters": {
    "sensor": "temperature",
    "offset": 0.5
  }
}

Wildcard Subscriptions​

Devices can use MQTT wildcards to subscribe to multiple topics:

Single Level Wildcard (+)​

Subscribe to all commands:

devices/sensor-001/commands/+

Receives:

  • devices/sensor-001/commands/reboot
  • devices/sensor-001/commands/config
  • devices/sensor-001/commands/firmware
  • devices/sensor-001/commands/custom

Multi-Level Wildcard (#)​

Subscribe to all commands and subcommands:

devices/sensor-001/commands/#

Receives everything under commands/

Access Control Rules (ACL)​

The IoT Gateway enforces strict ACL rules for security:

Device Permissions​

Each device has restricted access based on its device_id:

ALLOWED to Publish:

devices/{device_id}/*

ALLOWED to Subscribe:

devices/{device_id}/commands/*

NOT ALLOWED:

  • Publishing to other device topics
  • Subscribing to other device topics
  • Publishing to system topics
  • Administrative operations

Example ACL Enforcement​

Device sensor-001:

ActionTopicResult
Publishdevices/sensor-001/telemetryAllowed
Publishdevices/sensor-002/telemetryDenied
Subscribedevices/sensor-001/commands/#Allowed
Subscribedevices/sensor-002/commands/#Denied
Subscribe$SYS/#Denied

Best Practices​

Topic Design​

Do:

  • Use consistent naming conventions
  • Keep topics hierarchical and logical
  • Use lowercase with hyphens or underscores
  • Include timestamp in payload

Don't:

  • Use special characters in topic names
  • Create overly deep hierarchies
  • Include sensitive data in topic names
  • Use spaces in topics

Retained Messages​

Use retained messages for:

  • Device status (online/offline)
  • Device attributes
  • Last known configuration

Example:

client.publish(
    "devices/sensor-001/status",
    '{"status": "online"}',
    qos=1,
    retain=True
)

Message Size​

  • Recommended: < 256 KB per message
  • Maximum: 1 MB per message
  • For large data, consider splitting or using object storage

Publish Frequency​

Respect rate limits:

  • Maximum: 100 messages/second per device
  • Recommended: Adjust based on use case

Telemetry examples:

  • Temperature: Every 60 seconds
  • GPS: Every 10 seconds
  • Vibration: Every 1 second (high-frequency monitoring)

Topic Examples by Use Case​

Smart Home Sensor​

Publish:
  devices/livingroom-sensor-01/telemetry
  devices/livingroom-sensor-01/events
  devices/livingroom-sensor-01/status

Subscribe:
  devices/livingroom-sensor-01/commands/config

Industrial Gateway​

Publish:
  devices/gateway-factory-a/telemetry
  devices/gateway-factory-a/events
  devices/gateway-factory-a/attributes

Subscribe:
  devices/gateway-factory-a/commands/#

Fleet Tracking Device​

Publish:
  devices/vehicle-truck-042/telemetry      (GPS, speed, fuel)
  devices/vehicle-truck-042/events         (harsh braking, geofence)
  devices/vehicle-truck-042/status         (engine, battery)

Subscribe:
  devices/vehicle-truck-042/commands/config
  devices/vehicle-truck-042/commands/custom

Command Response Pattern​

Devices should acknowledge commands by publishing responses:

Command received:

Topic: devices/sensor-001/commands/config
Payload: {"interval": 30}

Device publishes acknowledgment:

Topic: devices/sensor-001/events
Payload: {
  "event_type": "command_ack",
  "command_topic": "config",
  "status": "success",
  "message": "Interval updated to 30 seconds",
  "timestamp": 1699189234
}

Testing Topics​

Using mosquitto_sub​

Subscribe to all device messages:

mosquitto_sub \
  -h mqtt.wayscloud.services \
  -p 1883 \
  -u sensor-001 \
  -P mqtt_password \
  -t "devices/sensor-001/#" \
  -v

Using mosquitto_pub​

Publish telemetry:

mosquitto_pub \
  -h mqtt.wayscloud.services \
  -p 1883 \
  -u sensor-001 \
  -P mqtt_password \
  -t "devices/sensor-001/telemetry" \
  -m '{"temperature": 22.5, "timestamp": 1699189234}'

Publish with QoS 1:

mosquitto_pub \
  -h mqtt.wayscloud.services \
  -p 1883 \
  -u sensor-001 \
  -P mqtt_password \
  -t "devices/sensor-001/telemetry" \
  -m '{"temperature": 22.5}' \
  -q 1

Platform System Topics​

Read-only system topics (subscription only, not for devices):

Statistics​

Topic: $SYS/broker/clients/connected

Purpose: Number of connected clients (admin access only)

Logs​

Topic: $SYS/broker/log/#

Purpose: Broker logs (admin access only)

info

System topics ($SYS/*) are restricted to administrative access only.

Next Steps​