zedmd-rs

A Rust library for controlling ZeDMD dot matrix displays over USB or WiFi (UDP / TCP).

Original C++ library: https://github.com/PPUC/libzedmd

For a detailed description of the USB serial protocol, handshake, command opcodes, zone streaming and ACK flow see serial_protocol.md.

Usage

Use cargo to add the dependency to your project:

cargo add zedmd

Examples

Example	Description
pixel_scan	Scans a single white pixel across every position — useful for verifying the connection and panel
display_test	Cycles through solid colours, gradients, colour bars, checkerboard and static rainbow
plasma	Classic sine-wave colour plasma animation (~9–10 fps USB throughput)
plasma_rgb888	Same plasma using true RGB888 (command 0x04) — use this to verify the RGB888 path works on your device
rings	Animated concentric colour rings — heavier on the connection than plasma (~6–7 fps USB throughput)
rainbow	Animated rainbow
scaling	RGB888 plasma at native, 2x downscaled, and 2x upscaled source resolutions — evaluates scaling quality
settings	Unified settings tool: panel/display settings, WiFi credentials, WiFi UDP delay, and transport mode (USB / WiFi UDP / WiFi TCP / SPI)

Run any example with:

cargo run --example plasma

WiFi

ZeDMD devices with WiFi capability can connect to your local network so you can stream frames over the network instead of USB.

There are two ways to configure WiFi credentials:

Option 1: Over USB (recommended)

Connect the device via USB and use the unified settings example to push SSID, password, port, power and (optionally) transport mode, then save to flash:

cargo run --example settings -- \
  --ssid MyNetwork --password MyPassword --port 5000 --save

Switch transport to WiFi UDP from the same command:

cargo run --example settings -- --transport wifi-udp --save

Or from code:

let comm = zedmd::connect()?;
comm.set_wifi_ssid("MyNetwork")?;
comm.set_wifi_password("MyPassword")?;
comm.set_wifi_port(5000)?;
comm.set_transport_mode(zedmd::types::TransportMode::WifiUdp)?;
comm.save_settings()?;

Reboot the device after saving for new settings to take effect.

Important transport behavior

ZeDMD runs one active transport at a time. After switching to a WiFi transport, USB serial access is expected to be unavailable until you switch transport back to USB from the device's physical settings controls (buttons/menu). Depending on firmware build/version, there may also be a factory-reset or fallback path, but that is firmware-specific and not guaranteed by this Rust crate.

Option 2: Via the device's setup network

When no WiFi is configured (or the configured network is unavailable), the device broadcasts its own setup network:

• SSID: ZeDMD-WiFi
• Password: zedmd1234

Connect to that network and open http://zedmd-wifi.local in a browser to configure target WiFi credentials through the web interface.

Running examples over WiFi

Once the device is connected to your network and configured for WifiUdp or WifiTcp transport, every streaming example (pixel_scan, display_test, plasma, plasma_rgb888, plasma_rgb888_true, rings, rainbow, scaling) accepts a --wifi flag. With no argument they connect to the default mDNS hostname ZeDMD-WiFi.local; pass an IP or hostname to override.

cargo run --example display_test -- --wifi              # ZeDMD-WiFi.local
cargo run --example display_test -- --wifi 10.0.1.173   # explicit host
cargo run --example plasma -- --wifi

The client fetches http://<host>/handshake to discover the device's streaming port and protocol (UDP or TCP) and connects accordingly.

The settings example only supports USB — it configures the device, which generally requires a wired connection.

Allowing access to the USB device on Linux

Option 1: creating a udev rule

You can create an udev rule to allow access to the device. Create a file in /etc/udev/rules.d/99-zedmd.rules with the following content:

sudo nano /etc/udev/rules.d/99-zedmd.rules

# ZeDMD dot matrix USB device rules

ACTION!="add|change", GOTO="zedmd_rules_end"

SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", SYMLINK+="zedmd", MODE="0666" 

LABEL="zedmd_rules_end"

Make sure the vendor and product id match what is listed on lsusb

lsusb
...
Bus 003 Device 034: ID 10c4:ea60 Silicon Labs CP210x UART Bridge

Then reload the udev rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

This will also mount the device on /dev/zedmd

Option 2: Add your user to the dialout group

Alternatively you can give your user access to any serial port. You can do this by adding your user to the dialout group:

sudo usermod -aG dialout $USER

After running the above command, you will need to log out and log back in for the group change to take effect.