# IoT Sensor Platform

> IoT platform with EMQX MQTT broker, TimescaleDB for time-series, Telegraf collection, and Grafana

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: emqx, timescaledb, telegraf, grafana
- Tags: iot, mqtt, emqx, timescaledb, telegraf, sensors, grafana
- Source: https://docker.recipes/homelab/iot-sensor-platform

## Overview

EMQX is a massively scalable, open-source MQTT broker built on Erlang/OTP that can handle millions of concurrent IoT device connections with sub-millisecond latency. As a distributed message broker implementing MQTT 3.1.1 and 5.0 protocols, EMQX excels at ingesting high-velocity sensor data from IoT devices, industrial equipment, and smart home systems. Originally developed by EMQ Technologies, it has become the backbone for IoT platforms requiring enterprise-grade reliability and horizontal scaling capabilities.

This IoT sensor platform combines EMQX's high-performance MQTT brokering with TimescaleDB's PostgreSQL-based time-series storage, creating a powerful data pipeline for sensor telemetry. Telegraf acts as the bridge, subscribing to MQTT topics from EMQX and writing structured time-series data into TimescaleDB's hypertables with automatic time-based partitioning. Grafana completes the stack by providing rich visualizations and alerting capabilities, connecting directly to TimescaleDB using standard PostgreSQL drivers for complex analytical queries across your sensor data.

This combination is ideal for IoT developers and system integrators who need PostgreSQL compatibility alongside time-series optimization, allowing them to join sensor data with relational information like device metadata, user accounts, or inventory systems. Unlike pure time-series databases, TimescaleDB's full SQL support enables complex analytics while EMQX handles the massive concurrent connection loads that industrial IoT deployments demand, making this stack perfect for smart building management, industrial monitoring, or large-scale sensor networks.

## Features

- EMQX clustering support for horizontal scaling to millions of concurrent MQTT connections
- TimescaleDB hypertables with automatic time-based partitioning for optimal sensor data storage
- Built-in EMQX rule engine for real-time data processing and routing based on MQTT topics
- TimescaleDB continuous aggregates for pre-computed sensor data rollups and statistics
- EMQX WebSocket and MQTT-over-SSL support for browser-based IoT applications
- PostgreSQL compatibility allowing complex JOINs between sensor data and device metadata
- Telegraf's extensive input plugins supporting 200+ data sources beyond MQTT
- TimescaleDB compression achieving 90%+ storage reduction for historical sensor data

## Use cases

- Smart building management systems collecting temperature, humidity, and occupancy data from hundreds of sensors
- Industrial IoT monitoring for manufacturing equipment with predictive maintenance analytics
- Environmental monitoring networks tracking air quality, weather, and pollution across multiple locations
- Smart agriculture platforms monitoring soil moisture, temperature, and crop health sensors
- Fleet management systems tracking vehicle telemetry, GPS coordinates, and engine diagnostics
- Home automation platforms managing smart thermostats, security sensors, and energy monitors
- Retail analytics collecting foot traffic, temperature, and inventory sensor data across store chains

## Prerequisites

- Minimum 4GB RAM recommended (2GB for TimescaleDB, 1GB for EMQX, 512MB for Grafana)
- Available ports: 1883 (MQTT), 5432 (PostgreSQL), 3000 (Grafana), 18083 (EMQX Dashboard)
- Basic understanding of MQTT protocol and topic structure for IoT device communication
- Familiarity with PostgreSQL and SQL queries for TimescaleDB data analysis
- Telegraf configuration knowledge for setting up MQTT consumer and PostgreSQL output plugins
- Understanding of time-series data concepts like retention policies and data aggregation

## docker-compose.yml

```yaml
services:
  emqx:
    image: emqx/emqx:latest
    container_name: emqx
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "8083:8083"
      - "8084:8084"
      - "${EMQX_DASHBOARD:-18083}:18083"
    environment:
      - EMQX_NAME=emqx
      - EMQX_HOST=127.0.0.1
    volumes:
      - emqx_data:/opt/emqx/data
      - emqx_log:/opt/emqx/log

  timescaledb:
    image: timescale/timescaledb:latest-pg15
    container_name: timescaledb
    restart: unless-stopped
    ports:
      - "${TIMESCALE_PORT:-5432}:5432"
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=iot
    volumes:
      - timescaledb_data:/var/lib/postgresql/data

  telegraf:
    image: telegraf:latest
    container_name: telegraf
    restart: unless-stopped
    volumes:
      - ./telegraf/telegraf.conf:/etc/telegraf/telegraf.conf:ro
    depends_on:
      - emqx
      - timescaledb

  grafana:
    image: grafana/grafana:latest
    container_name: iot-grafana
    restart: unless-stopped
    ports:
      - "${GRAFANA_PORT:-3000}:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - timescaledb

volumes:
  emqx_data:
  emqx_log:
  timescaledb_data:
  grafana_data:
```

## .env

```bash
# IoT Sensor Platform
EMQX_DASHBOARD=18083
TIMESCALE_PORT=5432
GRAFANA_PORT=3000

# Database
DB_USER=iot
DB_PASSWORD=iot_password

# Grafana
GRAFANA_PASSWORD=admin
```

## Usage notes

- EMQX Dashboard at http://localhost:18083 (admin/public)
- MQTT broker at localhost:1883
- Grafana at http://localhost:3000
- Configure telegraf.conf for MQTT input and PostgreSQL output
- TimescaleDB optimized for time-series IoT data
- EMQX supports millions of concurrent connections

## Troubleshooting

- EMQX connection refused on port 1883: Check if EMQX container started properly and verify firewall rules allow MQTT traffic
- Telegraf failing to connect to EMQX: Ensure MQTT input plugin configuration uses correct broker URL 'emqx:1883' for container networking
- TimescaleDB connection errors from Grafana: Verify PostgreSQL service is running and use 'timescaledb:5432' as data source URL
- High memory usage in TimescaleDB: Enable TimescaleDB compression on older chunks and configure appropriate retention policies for sensor data
- EMQX dashboard shows authentication failures: Default credentials are admin/public, check client certificates if using SSL/TLS connections
- Missing data in Grafana dashboards: Verify Telegraf is successfully writing to TimescaleDB by checking PostgreSQL logs and table row counts

