ESP32 NDJSON HMI – UART-Controlled LVGL Display Firmware

The ESP32 NDJSON HMI is a lightweight and deterministic Human Machine Interface firmware for ESP32-based RGB displays. It is controlled entirely via a UART connection using NDJSON (Newline Delimited JSON) and is designed as a transparent alternative to Nextion-style HMIs.

Instead of using a proprietary editor, precompiled screen files, or closed design tools, the complete user interface is created and modified at runtime by sending plain text JSON commands from a host MCU or a PC. Each command represents exactly one UI action and is easy to debug, log, and reproduce.

Design Goals

• Full control over the UI from the host system
• Simple and robust serial protocol
• No proprietary file formats or editors
• Easy debugging with standard serial tools
• Predictable behavior suitable for embedded systems

Technical Overview

• Target platform: ESP32-S3
• Graphics engine: LVGL 9.x
• Display type: RGB TFT (parallel RGB interface)
• Resolution tested: 800 × 480
• Communication interface: UART (115200 baud, 8N1)
• Protocol format: NDJSON (one JSON object per line)
• Text encoding: UTF-8

Communication Concept

Communication between the host and the HMI is strictly line-based. Each command sent by the host contains a sequence number and a command identifier. The HMI responds with an ACK message indicating success or failure. User interactions are reported asynchronously as events.

After boot and initialization, the HMI sends a ready event:

{"evt":"sys","state":"ready"}

No commands are accepted before this event is received, ensuring a clean and reliable startup sequence.

User Interface Elements

The firmware provides a set of common UI widgets suitable for control panels, configuration screens, and data visualization:

• Label and text display
• Button with click events
• Slider and progress bar
• Switch and checkbox
• Dropdown list and roller selector
• Spinbox for numeric input
• Text input field with on-screen keyboard
• Arc / rotary control
• Lines and simple line charts
• Message boxes

All UI elements are created dynamically and can be updated later using a generic property command, without recreating the object.

Page Handling (Optional)

For more advanced use cases, the firmware supports a page buffering mechanism. This allows a complete screen to be built in the background while another page remains visible. Once finished, the new page can be displayed instantly without flicker.

For simple applications, this mechanism can be ignored entirely. Commands then operate directly on the visible UI, which is often preferable during development and debugging.

Tested Hardware

• Elecrow / CrowPanel ESP32 RGB displays
• 7-inch and 5-inch variants
• 800 × 480 resolution

Typical Use Cases

• Embedded control panels
• Configuration and service interfaces
• Measurement and visualization systems
• Custom HMI solutions where transparency and control are required

Documentation

A complete protocol description, command reference, and usage examples are available here:
https://www.ulrichradig.de/home/index.php/esp32/hmi-ndjson

License

Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0)

The firmware is provided as binary only. Free for non-commercial use with attribution. Modification and commercial use are not permitted.

Note

Firmware only. No source code included.