WomoNET Protocol

The WomoNET network uses MQTT as the primary protocol for communication between various devices. This setup enables efficient and flexible data exchange within the network.

Version History

Structure

The MQTT topics in the WomoNET network are systematically organized into the following main categories:

c (config)

conf (configuration)

This topic stores configuration settings, including user interface preferences, device parameters, and other important configurations. The key feature of this topic is that settings are persistent, meaning they remain intact even after a system reboot.

• ui: Contains UI layout from the WomoNET.app. Layouts are written as JSON for every available layout
• driver: Can be used to store configurations for drivers

dev (virtual devices, auto-discovery)

This topic is reserved for drivers to publish their auto-discovery configuration. The configuration data for device discovery is defined here, as described in detail below.

s (state)

Each MQTT client within the WomoNET network has a dedicated state topic where it publishes messages reflecting its current state or data. All data has to be human-readable UTF-8 data. Numeric values have to be sent as UTF-8 string. Decimal point is . (dot). We parse with Dart’s double.tryParse.

State updates and commands should use QoS 1.

Message Semantics

State messages should be retained by default, ensuring new subscribers immediately receive the current state. Implementations should:

• Publish state only when the value changes (change detection)
• Use retain=true for state topics so the MQTT broker caches the latest value
• Avoid periodic republishing of unchanged values to reduce bandwidth

Structure

The state tree is structured as follows: s/<client_id>/<device_id>/<object_id>/[set/]<state/value/command>, whereas:

• client_id is the MQTT client ID
• device_id is the identifier of the virtual device
• object_id is the object unit of a type’s value
• set (optional) is a constant which is only provided if this is a command
• state/value/command is the actual state, value or command

Topic Validity

State topics are only valid while the corresponding auto-discovery configuration exists. When an auto-discovery topic is removed (empty retained message), all associated state topics should be considered invalid.

Client Availability

Each client publishes its availability status to c/dev/<client_id>/alive:

• online: Published (retained) when the client connects to the broker
• offline: Published automatically by the broker via Last Will and Testament (LWT) when the client disconnects unexpectedly

Subscribers should monitor the alive topic to determine if a client’s auto-discovery topics and state values are current. When a client goes offline, its retained state values may be stale.

Error Feedback

Drivers report device faults on well-known, retained topics — one topic per active fault — so the app can surface them without any additional auto-discovery configuration. This mirrors the Client Availability convention: the topics are implicit for every virtual device and do not appear in the auto-discovery tree.

Topic: s/<client_id>/<device_id>/error/<id>/state (retained)

• One topic per active fault. <id> identifies this occurrence of the fault: it is assigned by the driver, unique within the device, and must be a valid MQTT topic segment (no /, +, #). Subscribers discover the active faults of a device by subscribing to the wildcard s/<client_id>/<device_id>/error/+/state.
• Scoped to the virtual device (device_id), matching how the app groups components into WidgetGroups.
• Clearing a fault = empty retained message on its topic (the same mechanism used to invalidate auto-discovery topics). A device with no error/<id>/state topics — or all of them cleared — is healthy.
• When a client goes offline, its retained error state — like all its state — may be stale. Subscribers should weigh the alive topic accordingly.

Payload: a JSON object describing the fault. The identifier is not repeated in the payload — it is the last path segment (<id>). Fields:

Severity follows the automotive warning-lamp model:

• error — the device cannot be used in this state (analogous to a red stop lamp), e.g. gas supply interrupted, electronics locked.
• warning — the device remains usable, but the user should take care (analogous to an amber warning lamp), e.g. imminent undervoltage.

Only currently active faults have a topic. A continuously-present fault keeps the same <id> (topic) across updates, so the app does not re-notify.

Example — an example heater reporting two concurrent faults publishes two retained topics:

s/womonet-core-123.../heater-a1b2/error/1/state:

{"severity": "error", "code": "E12", "message": "Overtemperature shutdown"}

s/womonet-core-123.../heater-a1b2/error/2/state:

{"severity": "warning", "code": "W07", "message": "Supply voltage low"}

Reset

Users reset faults — one by one — by publishing to the fault’s own command topic:

Topic: s/<client_id>/<device_id>/error/<id>/set/state (command, not retained)

Any payload triggers the reset (e.g. reset). To reset every fault of a device, publish to each active fault’s command topic.

On a reset request the driver always clears the fault (empty retained message on its error/<id>/state topic). It then attempts to resolve the underlying condition on the device:

• If the condition is already gone, the fault stays cleared.
• If the condition persists (the fault cannot be resolved), the driver raises it again under a new <id> (new topic). This re-notifies the user instead of leaving a silently-stuck entry, and it distinguishes “still broken after I acknowledged it” from the original report.

Faults whose condition resolves on the device on their own clear without any reset.

Open Questions

• History: This mechanism reports current state only. A fault log/history, if needed, would be a separate concern.

Auto-discovery

The configuration data needs to be published as MQTT messages in a specific JSON format. Each component requires a unique topic name and a JSON configuration. The topic format is c/dev/<client_id>/<device_id>/<type>/<component>, where:

• <client_id> is the MQTT client id (globally unique)
• <device_id> is an identifier for the virtual device (driver level). This id has to be unique for the client to avoid collisions
• <type> is the type of component. See below for available types
• <component> is the name of the component. It has to be unique across all components for the given type of this virtual device

When publishing auto discovery configs, the retain flag has to be set for the MQTT message.

Auto discovery is organized different to Home Assistant: We use dev_id and then type instead the other way around. This enables us to use WidgetGroups in the app for each dev_id.

Naming Convention

device_id and component use different casing so the device level and the component level stay visually distinct within a topic:

• device_id uses kebab-case with dashes:
  • Examples: inverter-d929, solar-mppt-1a2b, heater-a1b2
• component uses snake_case with underscores:
  • Examples: battery_voltage, inverter_enabled, zone1_temp

Available Types

toggle

A switchable unit which can be turned on or off.

actuator

An actuator which can be switched in two directions e.g. push/pull, forward/reverse and also has a neutral stop state. Important: The driver has to make sure to automatically stop the motion, when no more valid messages are received.

binary

A boolean sensor with states on and off.

sensor

A sensor publishing a value.

mode

Selectable options for a dropdown.

slider

A controllable level value (slider in UI), which can be changed between a min and max value with a specified step size, e.g. for controlling heater/cooler temperatures, light dimmers, power consumption, charger output, …

button

A stateless command trigger. Unlike the other types it has no state_t: triggering it simply publishes a fixed payload to its command topic, e.g. to reset a counter, acknowledge an error, or start a calibration.

Example Structure

c/
├── conf/
│   ├── ui/
│   │   ├── 1 = "{ layout JSON }"
│   │   ├── main = "{ layout JSON }"
│   │   └── heater_only = "{ layout JSON }"
│   └── driver/
│       ├── core-gpio = "{ driver configuration JSON }"
│       └── core-adc = "{ driver configuration JSON }"
└── dev/
    ├── womonet-core-123.../
    │   ├── adc/
    │   │   └── sensor/
    │   │       ├── vin0 = "{'unit_of_measurement': 'V', 'state_t': 's/womonet-core-123.../adc/0/state'}"
    │   │       ├── vin1 = "{'unit_of_measurement': 'V', 'state_t': 's/womonet-core-123.../adc/1/state'}"
    │   │       └── ...
    │   ├── extrelay/
    │   │   └── toggle/
    │   │       ├── relay0 = "{'state_t': 's/womonet-core-123.../extrelay/0/state', 'cmd_t': 's/womonet-core-123.../extrelay/0/set/state', 'allow_timed': true}"
    │   │       ├── relay1 = "{'state_t': 's/womonet-core-123.../extrelay/1/state', 'cmd_t': 's/womonet-core-123.../extrelay/1/set/state', 'allow_timed': true}"
    │   │       └── ...
    │   ├── heater-a1b2/
    │   │   ├── mode/
    │   │   │   └── heat = "{'state_t': 's/womonet-core-123.../heater-a1b2/heat/state', 'cmd_t': 's/womonet-core-123.../heater-a1b2/heat/set/state', 'option_t': 's/womonet-core-123.../heater-a1b2/heat/options'}"
    │   │   ├── sensor/
    │   │   │   ├── current_temp = "{'state_t': 's/womonet-core-123.../heater-a1b2/current_temp/state'}"
    │   │   │   └── boiler_temp = "{'state_t': 's/womonet-core-123.../heater-a1b2/boiler_temp/state'}"
    │   │   └── slider/
    │   │       └── target_temp = "{'state_t': 's/womonet-core-123.../heater-a1b2/target_temp/state', 'cmd_t': 's/womonet-core-123.../heater-a1b2/target_temp/set/state', 'min_value': 16, 'max_value': 36, 'step_size': 0.5}"
    │   └── ...
    └── womonet-power-524.../
        ├── toggle/
        │   └── pump = "{'state_t': 's/womonet-power-524.../pump/state', 'cmd_t': 's/womonet-power-524.../pump/set/state'}"
        ├── actuator/
        │   ├── step = "{'state_t': 's/womonet-power-524.../step/state', 'cmd_t': 's/womonet-power-524.../step/set/state', 'allow_timed': true}"
        │   ├── awning = "{'state_t': 's/womonet-power-524.../awning/state', 'cmd_t': 's/womonet-power-524.../awning/set/state'}"
        │   ├── valve0 = "{'state_t': 's/womonet-power-524.../valve0/state', 'cmd_t': 's/womonet-power-524.../valve0/set/state', 'allow_timed': true}"
        │   └── valve1 = "{'state_t': 's/womonet-power-524.../valve1/state', 'cmd_t': 's/womonet-power-524.../valve1/set/state', 'allow_timed': true}"
        └── ...

s/
├── womonet-core-123.../
│   ├── adc/
│   │   ├── 0/
│   │   │   └── state = "1.33"
│   │   ├── 1/
│   │   │   └── state = "0.452"
│   │   └── ...
│   ├── extrelay/
│   │   ├── 0/
│   │   │   ├── state = "ON"
│   │   │   └── set/
│   │   │       └── state (writable only, no retain)
│   │   ├── 1/
│   │   │   ├── state = "OFF"
│   │   │   └── set/
│   │   │       └── state (writable only, no retain)
│   │   └── ...
│   ├── heater-a1b2/
│   │   ├── heat/
│   │   │   ├── state = "heating"
│   │   │   ├── options = "[\"off\", \"heating\", \"venting\"]"
│   │   │   └── set/
│   │   │       └── state (writable only, no retain)
│   │   ├── current_temp/
│   │   │   └── state = "18.62"
│   │   ├── target_temp/
│   │   │   ├── state = "22.0"
│   │   │   └── set/
│   │   │       └── state (writable only, no retain)
│   │   └── error/
│   │       ├── 1/
│   │       │   ├── state = "{\"severity\": \"error\", \"code\": \"E12\", \"message\": \"Overtemperature shutdown\"}"
│   │       │   └── set/
│   │       │       └── state (writable only, no retain)
│   │       └── 2/
│   │           ├── state = "{\"severity\": \"warning\", \"code\": \"W07\", \"message\": \"Supply voltage low\"}"
│   │           └── set/
│   │               └── state (writable only, no retain)
│   └── ...
└── womonet-power-524.../
    ├── pump/
    │   ├── state = "ON"
    │   └── set/
    │       └── state (writable only, no retain)
    ├── step/
    │   ├── state = "0"
    │   └── set/
    │       └── state (writable only, no retain)
    └── ...