NetID Monitor

A lightweight cross-platform daemon that automatically detects a WeAct Studio USB display (or compatible Turing Smart Screen) when plugged in and pushes the machine's hostname and IP address to it.

Deploy this on every machine in your network for instant visual identification.

---

Supported Hardware

Display	Resolution	Notes
WeAct Studio 3.5" (FS V1)	320 × 480	Default layout
WeAct Studio 0.96" (FS V1)	80 × 160	Use --small flag
Turing Smart Screen 3.5"	320 × 480	Same protocol

The dongle appears as a USB CDC serial port (Virtual COM Port).

---

Requirements

• Python 3.8+
• pyserial
• Pillow

pip install pyserial Pillow

---

Quick Start

# Auto-detect display and push once
python netid_monitor.py --once

# Run as a daemon (auto-reconnect, refresh every 10s)
python netid_monitor.py

# List serial ports to find your display manually
python netid_monitor.py --list-ports

# Specify port explicitly
python netid_monitor.py --port /dev/ttyACM0
python netid_monitor.py --port COM3          # Windows

# 0.96" small display
python netid_monitor.py --small

# Faster refresh, custom brightness
python netid_monitor.py --interval 5 --brightness 120

---

Linux Installation (systemd)

sudo bash deploy/install-linux.sh

This will:

1. Install dependencies via apt/pip
2. Copy files to /opt/netid-monitor/
3. Add your user to the dialout group (serial port access)
4. Install and start netid-monitor@<user>.service

View logs:

journalctl -u netid-monitor@$USER -f

Stop / disable:

sudo systemctl stop  netid-monitor@$USER
sudo systemctl disable netid-monitor@$USER

Serial port permissions (Linux)

If you get Permission denied on /dev/ttyACM*:

sudo usermod -aG dialout $USER
# Log out and back in

---

Windows Installation (Scheduled Task)

Run as Administrator:

deploy\install-windows.bat

This will:

1. Install Python dependencies via pip
2. Copy files to C:\netid-monitor\
3. Register a Scheduled Task that runs at login

Manual control:

schtasks /Run /TN "NetID Monitor"
schtasks /End /TN "NetID Monitor"
schtasks /Delete /TN "NetID Monitor" /F

Driver: On Windows you may need the STM32 VCP driver if the device isn't detected:
https://www.st.com/en/development-tools/stsw-stm32102.html

---

CLI Options

Flag	Default	Description
--port PORT	auto	Serial port (e.g. COM3, /dev/ttyACM0)
--small	off	Layout for 0.96" 80×160 display
--interval N	10.0	Refresh interval in seconds
--brightness N	80	Backlight brightness (0–255)
--once	off	Push once and exit
--list-ports	off	List serial ports and exit
--verbose	off	Debug logging

---

How It Works

1. Scans USB serial ports on startup and after every failed push
2. Identifies WeAct/Turing displays by USB VID/PID or device description
3. Sends a HELLO/reset sequence, sets brightness, then renders a 320×480 (or 80×160) RGB565 frame via the CDC serial protocol
4. Refreshes on the configured interval; auto-reconnects if unplugged/replugged

---

Emulator (no hardware required)

emulator.py opens a live desktop window showing exactly what the USB display would render. Useful for iterating on display layout without a physical dongle.

Prerequisites:

• Windows: tkinter is included with the standard Python installer (python.org) — nothing extra needed.
• Debian/Ubuntu: tkinter is a separate package:

  sudo apt install python3-tk

• macOS: tkinter is included with the Python installer from python.org. If using Homebrew Python, install python-tk via Homebrew.

Usage:

# Large screen (320×480), live hostname and IP, 3× pixel scale
python emulator.py

# Small screen (80×160), scaled up for visibility
python emulator.py --small --scale 4

# Override values to test edge cases
python emulator.py --hostname "very-long-hostname-01" --ip "192.168.100.200"

# Fast refresh for rapid iteration
python emulator.py --interval 2 --verbose

The layout editor can be run from the editor/ directory:

python editor/editor_server.py

Emulator options:

Flag	Default	Description
--small	off	Use 80×160 small-screen layout
--interval N	10	Refresh interval in seconds
--hostname STR	(live)	Override hostname string
--ip STR	(live)	Override IP address string
--scale N	3	Integer pixel upscale factor (1–8)
--verbose	off	Debug logging

---

Troubleshooting

Problem	Fix
Display not detected	Run --list-ports, try --port explicitly
Permission denied (Linux)	sudo usermod -aG dialout $USER then re-login
Garbled display	Try --interval 15 to reduce serial load
Wrong screen size	Add --small for 0.96" display
Windows: no COM port	Install STM32 VCP driver

---

Attribution

This project is inspired by and builds upon the following open-source projects:

• turing-smart-screen-python by mathoudebine — Python library for Turing Smart Screen and compatible USB displays, providing the serial protocol implementation and display communication approach used here.
• WeActStudio.SystemMonitor by WeAct Studio — Reference firmware and protocol documentation for WeAct Studio USB displays, which informed the USB VID/PID identification and CDC serial framing used in this project.

Both projects are licensed under the GNU General Public License v3.0.

---

License

This project is licensed under the GNU General Public License v3.0.