Skip to content
Quick start Product guide

Protocol reference

This page records the interface to follow when you write firmware yourself. A generated sketch already follows it. In most cases you can start from that sketch and skip writing the connection code yourself.

WizDash and ESP32 two-way JSON communication and BLE, local WiFi WebSocket, and custom MQTT transport protocol overview diagram
Two-way JSON message flow between the WizDash phone app and ESP32 firmware across BLE, local WiFi WebSocket, and MQTT.

The board sends the app one JSON object, such as {"temp": 25.4, "hum": 61, "msg": "OK"}. Sending every reading in that one message is more efficient than sending them separately.

The app sends the board one {"key": value} at a time. The value may be a number, text, or an array, such as the [x, y] sent by a joystick.

WizDash maker dashboard and Serial Terminal widget showing live incoming and outgoing JSON payloads
In the app: the Serial Terminal and control widgets display live incoming JSON objects and outgoing command payloads.
WizDash full Arduino sketch viewer showing sendData() and onCommand() JSON handling
In firmware: sendData() and onCommand() assemble and parse JSON keys matching your dashboard widgets.
ItemValue
Service UUID6E400001-B5A3-F393-E0A9-E50E24DCCA9E
Written by the app6E400002-B5A3-F393-E0A9-E50E24DCCA9E
Notified by the board6E400003-B5A3-F393-E0A9-E50E24DCCA9E
MTU512 is recommended. The default packet is 20 bytes and can cut a JSON message short.

The board serves a WebSocket on port 81. The app looks for it on the local network with mDNS and UDP, and can also connect by IP address.

DirectionTopic
Board to appwizdash/{username}/{deviceId}/data
App to boardwizdash/{username}/{deviceId}/cmd

When no username is set, that segment is omitted, as in wizdash/{deviceId}/data.

{
"ota": {
"url": "https://example.com/firmware.bin",
"version": "1.0.0",
"size": 123456,
"checksum": "sha256:<64 hexadecimal digits>"
}
}

The address must be HTTPS and must not contain a username or password. The size is in bytes. The app sends the checksum in lowercase. The board reports progress and the result with ota_status.