Documentation · For device manufacturers

Connecting devices: MQTT and HTTP API

Last change: Text version 1.4 of 17 November 2026Česká verze

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 same client_id, the previous connection is closed.
  • So that no messages are lost during an outage, switch off Clean start (Clean session in older versions) and set a non-zero Session Expiry Interval; we recommend 604800 s, i.e. 7 days. MQTT 3.1.1 with clean session switched 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: Uchg

The 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: true

The 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_1C

List 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.