Documentation

MQTT application areas

MQTT is an internet protocol with a central message broker. With this message broker, participants can subscribe to certain "topics" and send messages to topics. The cFos Charging Manager can listen to messages on specific topics and thus be controlled via MQTT. It can also communicate the status of the devices it manages. The cFos Power Brain Wallbox can also be controlled via MQTT and transmit its status. This is useful when connecting to a home automation system, for industrial control (M2M) and for monitoring and recording. All topics start with cfos_mqtt. If you want to connect multiple cFos MQTT devices to one MQTT broker, the topic can optionally start with cfos_mqtt_<serial number>/, adjustable under configuration. In the configuration, you can also set a URL for the default MQTT broker. URLs can optionally start with mqtt:// and mqtts: //. With mqtts://, the cFos Charging Manager or the cFos Power Brain Wallbox establishes a TLS connection. The standard ports 1883 for unencrypted connections and 8883 for TLS connections are used. However, you can also specify a port in the URL. User name and password can be specified in the usual URL notation, e.g. mqtt://user:password@192.168.2.111. If you specify an MQTT broker in the cFos Charging Manager configuration, you can either specify an individual broker or simply write mqtt. In this case, the default broker stored in the configuration is used.

The cFos Charging Manager supports both MQTT 3.1.1 and MQTT 5. If you let the URL start with mqtt3:// or mqtt5:// (mqtts3:// and mqtts5:// for encrypted connection), you determine the protocol version. The default is MQTT 3.1.1. cFos Charging Manager tries to switch back to MQTT 3.1.1 for MQTT 5 if an error message is displayed. This works with older Mosquitto brokers, but not necessarily with other brokers.

Note: Since the setup of MQTT requires the admin password, the Charging Manager handles the data accordingly. Data is therefore deliberately sent that can only be accessed with an admin password.

Note on MQTT brokers: Thanks to Stefan G. (#diebestenuserderwelt) we were able to test the MQTT broker built into ioBroker. This MQTT 3.1.1 broker behaves (as of Feb. 2023) in several ways not standard-compliant: Connect attempts are silently terminated without an error message, the payload is sometimes missing in PUBLISH packets, PUBLISH packets are apparently sent twice (can this be turned off by a config setting?). This means that this broker is not suitable for controlling the Charging Manager API, as API requests may be executed more than once. Even though we are interested in our MQTT implementation being compatible with as many brokers as possible, we currently recommend using Mosquitto for ioBroker.

Integration of meters and wallboxes via device type "HTTP Input".

Instead of supplying these devices via HTTP (see HTTP API -> HTTP meters and wallboxes), these devices can also listen to MQTT. Enter mqtt or an MQTT broker URL as the device address. Then the corresponding meter or wallbox listens to the topic cfos_mqtt/set/<device ID>, e.g. for a meter with the device ID M1 to cfos_mqtt/set/M1. The HTTP input meter then expects a JSON string as a message, as described in the HTTP API under "HTTP meters and wallboxes". Your MQTT source must therefore deliver the data in this format. This allows you to integrate devices that are not supported by the cFos Charging Manager by obtaining the data from another source (e.g. a home automation system) and then feeding it into the Charging Manager.
Note: If the data from the source is in a different format than the HTTP counter expects, you can also create a custom counter. For MQTT, this is described below.

Example:
You have created an HTTP input counter and it has M3 as the device ID. You have entered the address of the Mosquitto broker as the address, e.g. mqtt://192.168.2.30. If you enter the following command on the command line on the computer on which Mosquitto is running:
mosquitto_pub -h localhost -t cfos_mqtt/set/M3 -m '{ "model": "TestModell", "import_wh": 12345, "export_wh": 23456, "voltage": [231, 232, 233], "current": [10001, 10002, 10003] }'
the counter should then contain the above values.

Transfer the status of the Charging Manager devices

In the Charging Manager configuration, you can specify an MQTT broker URL (or mqtt for standard broker), under which the Charging Manager then publishes the status of all devices under the topic cfos_mqtt/get/dev_info. It transmits this in the format known from HTTP get_dev_info. This gives you all the values of the devices as they are also visible in the UI, e.g. power values of the meters or the status of the wallboxes. If you only want to subscribe to individual devices, you can deactivate the checkbox "Publish info via MQTT" and instead check the option "Publish info via MQTT" in the settings of the individual devices under "Display". Then a corresponding JSON string about the respective device is published under the topic cfos_mqtt/get/<device-ID>. In addition, you can subscribe to all global values under the topic cfos_mqtt/get/params, as they are output in the format known from HTTP get_dev_info under "params".

control cFos Charging Manager API via MQTT

In the cFos Charging Manager configuration, you can specify an MQTT broker URL (or mqtt for standard brokers) under "Broker for API access via MQTT". If this value is not empty, the cFos Charging Manager subscribes to all topics that start with cfos_mqtt/api/. It then interprets messages under such topics as if the topic name were an HTTP URL beginning with /cnf? and forwards them to the HTTP API. The Charging Manager then publishes the response of the HTTP API as JSON under the topic cfos_mqtt/api_res. This way, you have almost the entire HTTP API under your control via MQTT. Exceptions are API calls that deliver long JSON responses. Example: cfos_mqtt/api/cmd=set_cm_vars&name=x&val=1 sets the Charging Manager variable x to 1 with the API function set_cm_var. A message under cfos_mqtt/api/cmd=enter_rfid&rfid=5678&dev_id=E1 enters the RFID 5678 for the wallbox with the device ID E1 (see also our extended RFID functions).
Data transmitted via HTTP POST can be placed in the message under the topic.

Example: Periodically change the maximum total current available to the Charging Manager:
Enter your broker under the general Charging Manager settings under "Brokers for API access via MQTT" (or simply mqtt if the default broker stored under "Configuration" is to be used). Then, using MQTT, publish to the topic
cfos_mqtt/api/cmd=set_params
a JSON object with the following content:
{"max_total_cur_prc": p}
where p is an indication in percent of what portion of the preset maximum total stream should be taken.
Note: Some of the HTTP API calls cause the Charging Manager to save the configuration. If you execute them too often, the flash (in the cFos Power Brain or cFos Wallbox Booster) or the SD card in the Raspberry will wear out. The API call "set_params" with the single parameter "max_total_cur_prc" therefore does not save the parameters.

Control wallboxes via MQTT

If the cFos Charging Manager is not in "Load management" mode, but in "Observe" mode, you can use MQTT to take control of all wallboxes yourself. This applies in particular to cFos Power Brain wallboxes that are operated as slaves in "Observe" mode. To do this, you must tick the "Activate control of wallboxes" option under MQTT in the Charging Manager settings. The cFos Charging Manager then listens to the MQTT topic cfos_mqtt/ctl and expects messages with a JSON object. This object has sub-objects with the device ID as the name as properties. The sub-objects look like this: {"cur": c, "ena": b, "wke": b, "phs": p}, where c is the charging current in mA, and b can each be true or false. "ena": false deactivates charging at the wallbox, "wke": true attempts to send a "wake up car" command to the wallbox (currently only possible with cFos Power Brain wallboxes). p can be 1 or 3 to switch between 1-phase and 3-phase charging. You can also omit "cur", "ena", "wke" and "phs" and thus only execute certain control functions. Example:
{"E1":
{cur: 8000, ena: true, wke: true},
"E2":
{cur: 10000, phs: 3}}

Sets the charging current of the wallbox with the device ID to 8A, activates charging and attempts to wake up the car. Furthermore, the charging current for wallbox E2 is set to 10A and switched to 3-phase charging.

Send logging and transaction log via MQTT

You can specify an MQTT broker URL for the transmission of log entries in the system log under "Configuration". The cFos Charging Manager then publishes all log entries under the topic cfos_mqtt/log. This allows you to monitor the Charging Manager logs remotely. You can also specify an MQTT broker URL for transaction log entries under "Configuration". Then all charging transactions are sent under the topic cfos_mqtt/ta_log. This allows remote evaluation of charging transaction accounting data and the creation of charging transaction backups on another system. A charging transaction begins when the charging plug is plugged in and ends when it is unplugged.

User-defined counters with MQTT

You can create custom counters using rtype = 2 for MQTT. These counters are defined similarly to HTTP counters (rtype = 1). However, the addresses here are not HTTP URLs, but MQTT topics. Example:
"power_w": {
"address": "/test_topic3",
"type": "float",
"query": "power_w"
}

Here the user-defined counter subscribes to the topic /test_topic3 and expects a JSON object with property "power_w", e.g. {"power_w": 1234}. Different counter variables can have different topics and are updated as soon as a message is published under the corresponding topic.