Event-driven architecture for nascoll monitoring services.
This specification documents all events published and consumed across the NAS services monorepo, providing type-safe message definitions and generating Go structs for runtime use.
Production MQTT broker
Power consumption metrics from monitoring devices.
Topic pattern: power/{device}/metrics Example: power/vip130/metrics
Compatible devices:
Receive power monitoring data from devices
Subscribes to power metrics published by monitoring devices. Messages are routed to RRD storage for time-series persistence.
Available only on servers:
Unique device identifier
Accepts the following message:
Power consumption data from monitoring devices
Represents power consumption data from any monitoring device.
Compatible with Shelly Pro PM, IoTaWatt, and other devices that report power/energy/voltage metrics.
Design Philosophy: Device-agnostic by default. The origin field
identifies the vendor/platform while keeping the message structure generic.
See ADR 007 for rationale.
Root message structure for power monitoring data
Example from Shelly Pro PM device
{
"device": "vip130",
"origin": "shelly-pro-pm",
"timestamp": 1731849600000,
"metrics": {
"aenergy": 12345.67,
"apower": 45.2,
"voltage": 230.5
}
}
Example from IoTaWatt device
{
"device": "server-rack-1",
"origin": "iotawatt",
"timestamp": 1731849660000,
"metrics": {
"aenergy": 23456.78,
"apower": 123.4,
"voltage": 231.2
}
}
Temperature and humidity metrics from environmental sensors.
Topic pattern: sensor/{device}/metrics Example: sensor/shelly-ht-001/metrics
Compatible devices:
Note: Location mapping is handled via separate configuration. Sensors can be mobile (battery-powered), so location is not part of the MQTT payload. See configs/device-locations.yaml.
Receive environmental monitoring data from sensors
Subscribes to temperature and humidity metrics published by environmental sensors. Messages are routed to RRD storage for time-series persistence. Device-to-location mapping is handled via external configuration.
Available only on servers:
Unique device identifier
Accepts the following message:
Temperature and humidity data from environmental sensors
Represents temperature, humidity, and optional battery data from environmental sensors.
Compatible with Shelly H&T, Zigbee sensors (Aqara), custom ESP32/Arduino sensors, and web-scraped sensor data.
Design Philosophy: Device-agnostic and location-agnostic. The origin field
identifies the vendor/platform. Location mapping is handled separately via
configuration to support sensor mobility and centralized location management.
Root message structure for sensor monitoring data
Example from Shelly H&T sensor
{
"device": "shelly-ht-001",
"origin": "shelly-ht",
"timestamp": 1731849600000,
"metrics": {
"temperature": 22.5,
"humidity": 45.3,
"battery": 85
}
}
Example from Aqara Zigbee sensor via Zigbee2MQTT
{
"device": "aqara-temp-01",
"origin": "zigbee-aqara",
"timestamp": 1731849660000,
"metrics": {
"temperature": 23.1,
"humidity": 48.7,
"battery": 92
}
}
Example from custom ESP32 sensor (no battery)
{
"device": "esp32-sensor-garage",
"origin": "custom",
"timestamp": 1731849720000,
"metrics": {
"temperature": 18.3,
"humidity": 65.2
}
}
Power consumption data from monitoring devices
Represents power consumption data from any monitoring device.
Compatible with Shelly Pro PM, IoTaWatt, and other devices that report power/energy/voltage metrics.
Design Philosophy: Device-agnostic by default. The origin field
identifies the vendor/platform while keeping the message structure generic.
See ADR 007 for rationale.
Root message structure for power monitoring data
Temperature and humidity data from environmental sensors
Represents temperature, humidity, and optional battery data from environmental sensors.
Compatible with Shelly H&T, Zigbee sensors (Aqara), custom ESP32/Arduino sensors, and web-scraped sensor data.
Design Philosophy: Device-agnostic and location-agnostic. The origin field
identifies the vendor/platform. Location mapping is handled separately via
configuration to support sensor mobility and centralized location management.
Root message structure for sensor monitoring data
Root message structure for power monitoring data
Actual power consumption measurements
Root message structure for sensor monitoring data
Actual sensor measurements