Waveshare

At a glance

• Product: Waveshare
• Manufacturer: Waveshare

Getting started

This provider type supports controlling relay channels via Switchable actions by publishing Modbus RTU binary frames over MQTT.

Provisioning (VirCom + mqtt.txt)

OpenApp can provision supported Waveshare/ZLAN relay boards by speaking the vendor ZLAN UDP management protocol (the same protocol used by the VirCom tool).

• VirCom download: VirCom_en.rar (Waveshare)

Hardware device ID (required)

Each OpenApp Waveshare device requires a hardware device ID (hw_device_id). This is a stable, IP-independent identifier read from the board’s ZLAN status. OpenApp derives MQTT client ID and topics from it.

To obtain the HW device ID for your board:

1. From the dashboard: Open the device page and use Fetch HW device ID. This sends a ZLAN query to the board (requires the board to be reachable from the backend).
2. From VirCom: Open the VirCom Device Management UI and connect to your board. In the Device Info section (top left of the device settings dialog), find the Dev ID field. Copy that value (e.g. 2880F28D589E or F28D589E) into the device’s HW device ID field in OpenApp.

Steps

In the current model:

• Broker host/port are not stored on the integration. The API uses OPENAPP_WAVESHARE_API_MQTT_BROKER_* for relay commands; ZLAN provisioning uses OPENAPP_WAVESHARE_DEVICE_MQTT_BROKER_* for the address written to the board. The integration may store optional MQTT username/password when the broker requires them.
• Each device holds board-specific identity: board host/IP and hardware device ID (required). MQTT client ID and topics are derived from the HW device ID.
• The 30 relays are modeled as switch entities under the device, with metadata.channel_index (0..29).

Manual fallback (VirCom)

If the device is not reachable from OpenApp (or UDP management is blocked), you can provision manually:

1. Obtain the HW device ID from VirCom (see Dev ID in the Device Info section of the device settings dialog).
2. Generate a mqtt.txt payload (VirCom format) containing per-device topics and credentials.
3. In VirCom, configure the MQTT server IP/port and upload/flash mqtt.txt to the device.

Note: OpenApp cannot perform the manual VirCom step for you; it requires the vendor UI.

Setup reference

Field	Type	Required	Description	Default	Example
OPENAPP_WAVESHARE_API_MQTT_BROKER_HOST / OPENAPP_WAVESHARE_API_MQTT_BROKER_PORT	string	required	Required deployment environment variables: hostname and port the **OpenApp API** uses to publish Modbus-over-MQTT. No defaults — the process fails fast if unset.	—	your-broker.internal
OPENAPP_WAVESHARE_DEVICE_MQTT_BROKER_HOST / OPENAPP_WAVESHARE_DEVICE_MQTT_BROKER_PORT	string	required	Required deployment environment: broker address **programmed onto boards** via ZLAN provisioning (often a LAN IP reachable from devices). No defaults.	—	192.168.1.11:1883
mqtt_username	string	optional	Optional MQTT credentials stored on the integration (for the deployment broker).	—	openapp-device
mqtt_password	string	optional	Optional MQTT password stored on the integration.	—	********

Secrets

Waveshare does not use integration secrets.

Troubleshooting: relay toggle does nothing

Relay commands are MQTT publishes from the API to the board’s subscribe topic. The board must be connected to the broker using OPENAPP_WAVESHARE_DEVICE_MQTT_BROKER_* (ZLAN programs that address). It must be an IP/hostname the board can route to on the LAN—often the same host that exposes EMQX on port 1883, not an address only reachable from inside a container network.

API traffic uses OPENAPP_WAVESHARE_API_MQTT_BROKER_*. Device programming uses OPENAPP_WAVESHARE_DEVICE_MQTT_BROKER_*.

Verify: EMQX Dashboard → Clients (board should appear), or subscribe with an MQTT client to the Modbus topic while toggling.