Metainformationen zur Seite
|Min. LB Version||3.0.0|
|Beschreibung||LoxBerry plugin to enable communication between the Loxone Miniserver and MQTT|
LoxBerry plugin to enable communication between the Loxone Miniserver and MQTT. This plugin connects to the Loxone Miniserver websocket and the LoxBerry MQTT Widget and publishes Miniserver control state changes over MQTT. In addition, control commands can be send over MQTT to control the Miniserver directly.
NOTE: The current version is not production ready. Use it at your own risk.
The latest version of the plugin can be found in Github: https://github.com/nufke/LoxBerry-Plugin-Lox2MQTT
Use the LoxBerry plugin installation procedure.
The plugin detects and lists the available Miniservers. For each Miniserver, the following configuration options are available:
- Miniserver topic name: MQTT topic name used when publishing control state changes and subscribing to Miniserver control commands (default: loxone)
- Use other Miniserver login credentials: Connect to the Miniserver as a different user (default: false)
- Publish structure: the Miniserver structure is published over MQTT (default: false)
- Publish control state changes: the Miniserver control state changes are published over MQTT (default: false)
- Retain published MQTT messages: Published MQTT messages will be retained by the MQTT server (default: false)
- Subscribe to MQTT to control the Miniserver: Control commands sent over MQTT will control the Miniserver (default: false)
- Miniserver username: Miniserver username (if enabled, default: empty)
- Miniserver password: Miniserver password (if enabled, default: empty)
When saving the configuration, the Lox2MQTT plugin will be restarted automatically. Updates to the general Miniserver settings or plugin logging level will also restart this plugin. The process status of the Lox2MQTT plugin is shown at the bottom of the configuration page. When the status is colored green, the process is running as expected. In case of issues, the text color is red and check the log file for more details.
WARNING! Publishing and subscribing to control state changes will increase the load on your Loxone Miniserver(s) and MQTT server.
Broadcasting Miniserver state changes over MQTT
Each Miniserver state change is broadcasted over MQTT, using the following topic structure:
Each MQTT message uses a topic name
<mqtt_topic_ms> as is defined in the configuration, to identify messages send to or from a Loxone Miniserver. The next topic level specifies the serial number
serialnr of the Miniserver, followed by a unique identifier
uuid representing a control state, which can be found in the Loxone structure file
LoxAPP3.json on your Miniserver.
If enabled, each last Miniserver control state broadcast is retained by the MQTT server. This enables MQTT clients to receive the latest state values immediately after subscribing to the topic.
loxone is the MQTT topic indicating a Miniserver message,
0123456789AB is the Miniserver serial nr., and
01234567-abcd-0123-ffffeeeeddddcccc the uuid of the control state, and the value is
Broadcasting Miniserver structure over MQTT
Broadcasting the Miniserver structure might be relevant for MQTT subscribers such as mobile apps to receive information on the available controls, their properties, capabilties and states. If enabled, the Miniserver structure (
LoxAPP3.json) is broadcasted over MQTT, but only once, at plugin startup. It uses the following topic structure:
If enabled, the Miniserver structure is retained by the MQTT server. This enables MQTT clients to receive the latest structure immediately after subscribing to the topic.
Controling the Loxone Miniserver over MQTT
To control a Loxone Miniserver, a messages should be send using the following topic structure:
Note that Loxone subcontrols share the same
uuid inherited from the parent control, and therefore define an additional string
subcontrol. The name for the
subcontrol can be found in the Loxone Miniserver structure file
LoxAPP3.json listed under the
uuid of the parent control.
In this example, a switch on Miniserver
0123456789AB with uuid
01234567-abcd-0123-ffffeeeeddddcccc is switched
Q: What is the difference between the LoxBerry MQTT Gateway and Lox2MQTT?
A: LoxBerry MQTT Gateway communicates to the Miniserver via HTTP Virtual Inputs or UDP messages, which require additional infrastructure in your Loxone Config program. The Lox2MQTT plugin connects to the Miniserver websocket and has direct access to the Miniserver controls and states. Therefore there are no changes required in your Loxone Config program.
Q: I receive state information from my Miniserver over MQTT, but I do not recognize the format and identifiers
A: A received MQTT message has the following format:
<mqtt_topic_ms>/<serialnr>/<uuid> <value>. Each MQTT message uses the Miniserver topic name (
mqtt_topic_ms) as defined in the configuration to identify messages coming from a Loxone Miniserver. The next topic level specifies the serial number (
serialnr) of your Miniserver, followed by the unique identifier (
uuid) representing a control state as defined in the Loxone structure file
LoxAPP3.json on your Miniserver.
Q: Can I change the Miniserver control states via MQTT?
A: Yes, you can send MQTT messages which are converted to commands for the Loxone Miniserver. A transmited MQTT message should have the following format:
<mqtt_topic_ms>/<serialnr>/<uuid>/cmd <command>. Note the command extension (
/cmd) in this message, which has been added to the unique identifier of a control or subcontrol. The allowed values for
command are defined in the Loxone Structure File.
Q: Where can I find my Loxone Miniserver structure file
A: You can download your structure file via URL
http://miniserver_ip_address/data/LoxAPP3.json or access it via FTP in directory
web/data/LoxAPP3.json. In both cases, login credentials are required.
Issues and questions
Please submit your issues and questions via the GitHub issue tracker: https://github.com/nufke/LoxBerry-Plugin-Lox2MQTT/issues or use https://www.loxforum.com Lox2MQTT thread