Documentation · For device manufacturers
Connecting devices: MQTT and HTTP API
Contents
This page is for device manufacturers and their programmers. It describes how a device (typically a PLC) sends measured values and events to onlineWatt and how it receives commands. What the manufacturer sets up in the portal is on the page The portal for device manufacturers.
Overview
| MQTT | HTTP | |
|---|---|---|
| Metrics (measured values) | yes | yes |
| Events | yes | yes |
| Commands from the portal to the device | yes | no |
| Format | JSON | form |
| Recommended for new devices | yes | no |
We recommend MQTT: it is encrypted, two-way, and only with it can the customer control the device from the portal (the Customer control field of a device type can be switched on only with MQTT communication). The communication method is chosen for the device type in the portal (field Communication). Each device has its own credentials, which the manufacturer finds in the device detail. A ready-made example for a microcontroller is on the page Your own ESP32 device, for a PLC on Tecomat PLC (Mosaic).
MQTT
Connection
- The device connects encrypted (MQTT over TLS). The manufacturer receives the broker address when the account is set up.
- It logs in with the MQTT user and MQTT password from the device detail in the portal.
- Every connection must have a unique
client_id. When another client connects with the same credentials and the sameclient_id, the previous connection is closed. - So that no messages are lost during an outage, switch off
Clean start(Clean sessionin older versions) and set a non-zeroSession Expiry Interval; we recommend 604800 s, i.e. 7 days. MQTT 3.1.1 withclean sessionswitched off is fine too.
Topics
{device_id} is the device number; the full topics are listed in the device detail in the portal.
| Topic | Direction | Content |
|---|---|---|
onlinewatt/devices/{device_id}/metrics |
device → portal | measured values |
onlinewatt/devices/{device_id}/events |
device → portal | events |
onlinewatt/devices/{device_id}/commands |
portal → device | commands |
onlinewatt/devices/{device_id}/commands_response |
device → portal | command responses |
Metrics
A message is JSON with name–value pairs, without nested objects. Which names the portal processes and where it stores them is determined by the mapping of the device type; other values are ignored.
- Send once a minute, QoS 1, without the retain flag, as the average of the samples since the previous message. The portal does not accept back-filling of older data.
- When metrics do not arrive for about 5 minutes, the portal marks the device as offline. Neither last will nor a heartbeat is used.
- One device is either a PV system or a heat pump.
- Signs: minus means battery discharging and feed-in to the distribution grid; plus means production, charging and consumption from the grid.
{"battery_soc": 64.5, "battery_power": -0.19, "mppt1_power": 2.1, "grid_available": true}Events
{"id": 5, "priority": 1}id is the event number (UID) from the event types of the given device type. The priority is set in the portal; the priority value in the message is not used.
Commands
The portal sends a command as JSON with a unique uid and the command name. Example of a heat pump temperature change:
{"uid": "a1b2c3", "command": "set_temperature", "temperature_offset": 1}The device answers on the commands_response topic with the same uid:
{"uid": "a1b2c3", "response": {"success": true, "message": "OK"}}success says whether the device will carry out the command. message is shown to the user and may contain the reason in case of an error.
Temperature buttons in the portal. The command names the portal sends after the −2 to +2 °C buttons are pressed are set by the temperature_offset_control part of the device type's mapping, for example plus_1c: IndoorTemp+1. After carrying out the command the device sends an event with the special action for that shift and the new state in the following metrics.
HTTP API
The portal can also receive data over HTTP. This is set for the device type in the Communication field with the HTTP option (Types of devices → Add type of device or Edit). The interface is one-way: the device sends metrics and events through it but cannot receive commands from the portal. For new devices we recommend MQTT over TLS. More information about the HTTP interface is available on request at info@onlinewatt.com.
Mapping
The mapping is a YAML text in the device type. It has two parts.
fields describes the values the device sends:
| Key | Meaning |
|---|---|
name |
field name |
type |
str, int, float, bool or enum |
unit |
unit shown in charts |
enum_values |
allowed values; required for the enum type, other values are not stored |
customer_visibility |
whether the end customer sees the value; the default is yes |
filters |
value adjustment: multiply, offset (addition), min and max (range limits). Multiplication is applied before the offset. |
mapping pairs the received values with fields in the portal. Only what is listed in mapping is stored.
For MQTT it is a dictionary portal_field_name: name_in_message. The simplest way is to send the values directly under the portal field names; the mapping is then one to one.
fields:
- name: battery_soc
type: float
unit: "%"
- name: charging_voltage
type: float
unit: "V"
customer_visibility: false
mapping:
battery_soc: SOC
charging_voltage: UchgThe portal field names are fixed for each technology; the full list is in the section List of fields. You set the unit of each field yourself with the unit key.
Event types
Event types of a device type are entered one by one or in bulk in YAML:
device_event_types:
- uid: 5
priority: PRIORITY_1
description_cs: Výpadek čidla teploty
description_en: Temperature sensor failure
customer_visibility: trueThe priorities are PRIORITY_1 (highest) to PRIORITY_5 (informational). customer_visibility determines whether the end customer sees the event as well.
Special action
The optional key special_action marks an event by which the device confirms that it carried out a temperature setting instruction. Values: TEMPERATURE_OFFSET_MINUS_2C, TEMPERATURE_OFFSET_MINUS_1C, TEMPERATURE_OFFSET_ZERO_C, TEMPERATURE_OFFSET_PLUS_1C, TEMPERATURE_OFFSET_PLUS_2C.
- uid: 216
priority: PRIORITY_5
description_cs: Vnitřní teplota upravena o +1 °C
description_en: Temperature offset set to +1 °C
customer_visibility: true
special_action: TEMPERATURE_OFFSET_PLUS_1CList of fields
As of 5 November 2026. You do not have to send all fields, only those the device knows. The enum type is sent as a number.
Heat pump
| Field | Type | Note |
|---|---|---|
mode |
enum | 0 = off, 1 = water heating, 2 = space heating, 3 = cooling |
dhw_temperature |
float | domestic hot water temperature |
dhw_target |
float | |
dhw_hysteresis |
float | |
heating_system_temperature |
float | |
heating_system_target |
float | |
heating_system_hysteresis |
float | |
outdoorunit_target_percentage |
float | |
output_temperature |
float | |
has_boiler |
bool | |
has_inverter |
bool | |
feedback_from_output_temperature |
bool | |
heating_season_active |
bool | |
stop_alarm |
bool | |
bivalent_power_consumption |
float | |
output_power |
float | |
input_power |
float | |
watter_flow |
float | |
heating_factor |
float | |
outdoor_temperature |
float | |
indoor_temperature |
float | |
hw_version |
str | |
sw_version |
str | |
outdoorunit_active |
bool | |
outdoorunit_defrosting |
bool | |
target_indoor_temperature |
float | |
ekviterm_type |
enum | 0 = off, 1 = four-way valve, 2 = power |
ekviterm_power |
float | |
internal_pump_active |
bool | |
evaporator_temperature |
float | |
condenser_temperature |
float | |
compressor_temperature |
float | |
input_power_offer |
float | |
input_energy_offer |
float | |
tuv_boiler_liter |
float | |
heating_boiler_liter |
float |
Photovoltaics and battery
| Field | Type | Note |
|---|---|---|
solar_irradiance |
float | |
internal_temperature |
float | |
battery_voltage |
float | |
battery_current |
float | |
battery_power |
float | |
grid_available |
bool | |
mppt1_voltage |
float | |
mppt1_power |
float | |
mppt2_voltage |
float | |
mppt2_power |
float | |
pv_charger_enable |
bool | |
ac_charger_enable |
bool | |
grid_feed_enable |
bool | |
charging_voltage |
float | |
max_charging_current |
float | |
power_grid_consumption |
float | |
hw_version |
str | |
sw_version |
str | |
do1_state |
bool | |
do2_state |
bool | |
battery_not_charged |
bool | |
battery_temperature |
float | |
battery_soc |
float | |
battery_soc_min |
float | |
battery_soc_max |
float | |
battery_capacity |
float | |
battery_soc_disconnect_actual |
float | |
battery_soc_disconnect_minimum |
float | |
battery_soc_disconnect_nogrid |
float | |
external_pv_power |
float | |
inverter_serial_number |
str | |
grid_l1_power |
float | |
grid_l2_power |
float | |
grid_l3_power |
float | |
load_l1_power |
float | |
load_l2_power |
float | |
load_l3_power |
float | |
mppt1_installed |
int | |
mppt2_installed |
int | |
stop_alarm |
bool | |
grid_feed_power_max |
float | |
battery_serial_number |
str | |
grid_feed_offer |
float | |
grid_consumption_offer |
float | |
grid_consumption_offer_solaroff |
float | |
grid_consumption_offer_solaroff_batteryoff |
float | |
grid_energy_feed_offer |
float | |
grid_energy_consumption_offer |
float | |
grid_consumption_offer_solarexcessoff |
float | |
grid_feed_offer_batteryoff |
float | |
inverter_l1_voltage |
float | |
inverter_l2_voltage |
float | |
inverter_l3_voltage |
float |
Connection for flexibility aggregators
onlineWatt can pass instructions from a flexibility aggregator to connected devices, for example to limit production or change consumption at a given time. The interface for aggregators is not public; terms and a technical description are available on request at info@onlinewatt.com.
Limits
- Commands from the portal to the device work only over MQTT; apart from the heat pump temperature setting there are no other public commands yet.
- Metrics are sent as flat name–value pairs; the portal does not process nested structures.
- Values outside the allowed range are replaced by the limit value; numeric values are limited to ±1,000,000.
- The MQTT broker address is not public; the manufacturer receives it when the account is set up.
← All documentation · Found a mistake or missing something? Write to info@onlinewatt.com.