MQTT Integration Guide

Overview

Just Sensors can publish sensor data to any MQTT broker, enabling integration with home automation systems, data visualization platforms, and custom applications. MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol ideal for IoT and sensor data.

Topic Structure

Sensor data is published to hierarchical topics that make it easy to subscribe to specific sensors or all data from a device.

Example Topics

justsensors/a1b2c3d4/accelerometer
justsensors/a1b2c3d4/battery
justsensors/a1b2c3d4/location
justsensors/a1b2c3d4/sound_level
justsensors/a1b2c3d4/session  # Session metadata

Wildcard Subscriptions

Use MQTT wildcards to subscribe to multiple topics:

# All sensors from a specific device
justsensors/a1b2c3d4/#

# Specific sensor from all devices
justsensors/+/battery

# All data
justsensors/#

Payload Format

All payloads are JSON-formatted with an ISO8601 timestamp and sensor-specific fields.

Accelerometer Example

{
  "timestamp": "2025-02-05T10:30:00Z",
  "sensor_type": "accelerometer",
  "x": 0.012,
  "y": -0.984,
  "z": 0.021
}

Battery Example

{
  "timestamp": "2025-02-05T10:30:00Z",
  "sensor_type": "battery",
  "level": 0.85,
  "state": "charging"
}

Location Example

{
  "timestamp": "2025-02-05T10:30:00Z",
  "sensor_type": "location",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "altitude": 10.5,
  "speed": 2.3,
  "horizontalAccuracy": 5.0
}

Quality of Service (QoS)

MQTT supports three levels of delivery guarantee. Choose based on your reliability needs and network conditions.

Recommended QoS by Sensor Type

Home Assistant Setup

Home Assistant has native MQTT integration that makes it easy to receive sensor data from Just Sensors.

# In Home Assistant, go to:
Settings → Add-ons → Add-on Store → Mosquitto broker → Install

# In Home Assistant, go to:
Settings → Devices & Services → Add Integration → MQTT

mqtt:
  sensor:
    # iPhone Battery Level
    - name: "iPhone Battery"
      state_topic: "justsensors/+/battery"
      value_template: "{{ (value_json.level * 100) | round(0) }}"
      unit_of_measurement: "%"
      device_class: battery
      icon: mdi:cellphone

    # Sound Level
    - name: "iPhone Sound Level"
      state_topic: "justsensors/+/sound_level"
      value_template: "{{ value_json.decibels | round(1) }}"
      unit_of_measurement: "dB"
      icon: mdi:microphone

    # Brightness
    - name: "iPhone Brightness"
      state_topic: "justsensors/+/brightness"
      value_template: "{{ (value_json.level * 100) | round(0) }}"
      unit_of_measurement: "%"
      icon: mdi:brightness-6

    # Barometer (Pressure)
    - name: "iPhone Pressure"
      state_topic: "justsensors/+/barometer"
      value_template: "{{ value_json.pressure | round(2) }}"
      unit_of_measurement: "kPa"
      device_class: pressure

  device_tracker:
    # Location Tracking
    - name: "iPhone Location"
      state_topic: "justsensors/+/location"
      json_attributes_topic: "justsensors/+/location"
      source_type: gps

automation:
  - alias: "Low iPhone Battery Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.iphone_battery
        below: 20
    action:
      - service: notify.notify
        data:
          message: "iPhone battery is low!"

Grafana Setup

Visualize sensor data over time with Grafana, using Telegraf to collect MQTT data and InfluxDB for storage.

# docker-compose.yml
version: '3'
services:
  influxdb:
    image: influxdb:2.7
    ports:
      - "8086:8086"
    volumes:
      - influxdb-data:/var/lib/influxdb2
  
  telegraf:
    image: telegraf:latest
    volumes:
      - ./telegraf.conf:/etc/telegraf/telegraf.conf:ro
    depends_on:
      - influxdb
  
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    depends_on:
      - influxdb

volumes:
  influxdb-data:

# telegraf.conf

# MQTT Consumer Input
[[inputs.mqtt_consumer]]
  servers = ["tcp://your-broker:1883"]
  topics = ["justsensors/#"]
  data_format = "json"
  topic_tag = "topic"
  
  # Parse device_id and sensor from topic
  [[inputs.mqtt_consumer.topic_parsing]]
    topic = "justsensors/+/+"
    tags = "_/device_id/sensor"

# InfluxDB Output
[[outputs.influxdb_v2]]
  urls = ["http://influxdb:8086"]
  token = "your-token"
  organization = "your-org"
  bucket = "sensors"

// Battery level over time
from(bucket: "sensors")
  |> range(start: -24h)
  |> filter(fn: (r) => r.sensor == "battery")
  |> filter(fn: (r) => r._field == "level")
  |> map(fn: (r) => ({ r with _value: r._value * 100.0 }))

// Accelerometer magnitude
from(bucket: "sensors")
  |> range(start: -1h)
  |> filter(fn: (r) => r.sensor == "accelerometer")
  |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")
  |> map(fn: (r) => ({
      r with magnitude: math.sqrt(r.x*r.x + r.y*r.y + r.z*r.z)
    }))

Available Sensors

Just Sensors can publish data from the following sensors via MQTT:

Troubleshooting