TinySysPanel

中文说明：请查看 README_CN.md

TinySysPanel turns a Raspberry Pi 3.5-inch SPI display into a real-time PC hardware monitoring dashboard.

TinySysPanel 可以把树莓派 3.5 寸 SPI 小屏变成电脑硬件监控副屏，适合桌搭、嵌入式学习和树莓派项目展示。

Optional demo GIF

Overview

TinySysPanel runs a lightweight Python agent on a Windows PC and displays real-time CPU, RAM, GPU, network and disk information on a Raspberry Pi 3.5-inch SPI screen.

The Windows side exposes a local JSON API. The Raspberry Pi side fetches that API over the LAN and renders a compact 480 x 320 dashboard through pygame and the Linux framebuffer.

Features

• Windows PC hardware monitoring agent.
• Raspberry Pi 3.5-inch SPI display client.
• CPU / RAM / GPU / Network / Disk display.
• PC ONLINE / PC OFFLINE status.
• JSON API with /health and /stats.
• pygame framebuffer rendering.
• RGB565 framebuffer fallback when SDL cannot open the framebuffer directly.
• systemd autostart example.
• config.json based configuration.
• Real hardware screenshots and demo assets.

Hardware Tested

This project is currently tested on the following setup:

• Raspberry Pi 4B.
• LCDWiki / GoodTFT 3.5-inch SPI display.
• ILI9486 display controller.
• ADS7846 / XPT2046 touch controller.
• Framebuffer: /dev/fb1.
• Windows PC with NVIDIA GPU.

This does not mean every SPI display is supported. Other panels may need different overlays, framebuffer devices, or rotation settings.

Project Structure

tinysyspanel/
├─ README.md
├─ LICENSE
├─ CHANGELOG.md
├─ CONTRIBUTING.md
├─ SECURITY.md
├─ .gitignore
├─ .github/
│  ├─ ISSUE_TEMPLATE/
│  │  ├─ bug_report.md
│  │  └─ feature_request.md
│  └─ pull_request_template.md
├─ pc-agent/
│  ├─ main.py
│  ├─ hardware_reader.py
│  ├─ config.json
│  ├─ config.example.json
│  ├─ requirements.txt
│  └─ run_windows.bat
├─ raspberry-pi-client/
│  ├─ dashboard.py
│  ├─ display.py
│  ├─ config.json
│  ├─ config.example.json
│  ├─ requirements.txt
│  └─ run_pi.sh
├─ docs/
│  ├─ api.md
│  ├─ raspberry_pi_setup.md
│  ├─ systemd_service.md
│  ├─ troubleshooting.md
│  └─ windows_agent_setup.md
└─ assets/
   ├─ README.md
   ├─ dashboard_online.jpg
   ├─ dashboard_offline.jpg
   ├─ desk_setup.jpg
   └─ demo.gif

Quick Start

Windows PC Agent

cd pc-agent
copy config.example.json config.json
pip install -r requirements.txt
python main.py

Or run:

cd pc-agent
.\run_windows.bat

Verify:

curl http://127.0.0.1:5000/health
curl http://127.0.0.1:5000/stats

Raspberry Pi Display Client

cd raspberry-pi-client
cp config.example.json config.json
python3 -m pip install -r requirements.txt
sudo python3 dashboard.py

Or run:

cd raspberry-pi-client
chmod +x run_pi.sh
./run_pi.sh

sudo is usually required because writing to /dev/fb1 needs framebuffer permission.

Configuration

pc-agent/config.json

{
  "host": "0.0.0.0",
  "port": 5000,
  "refresh_interval": 2,
  "enable_gpu": true,
  "enable_network": true
}

Use 0.0.0.0 when the Raspberry Pi should access the API from the LAN.

For a fresh Windows config:

copy config.example.json config.json

raspberry-pi-client/config.json

{
  "pc_api_url": "http://YOUR_PC_IP:5000/stats",
  "screen_width": 480,
  "screen_height": 320,
  "framebuffer": "/dev/fb1",
  "refresh_interval": 2,
  "theme": "dark",
  "show_local_pi_stats": false
}

Replace YOUR_PC_IP with the Windows PC LAN IP address.

For a fresh Raspberry Pi config:

cp config.example.json config.json

API Preview

GET /health

{
  "ok": true,
  "service": "TinySysPanel PC Agent"
}

GET /stats

{
  "ok": true,
  "pc_name": "DESKTOP-XXXX",
  "timestamp": 1780000000,
  "cpu": {
    "usage": 35.2,
    "temp": null
  },
  "ram": {
    "used_gb": 8.6,
    "total_gb": 16.0,
    "percent": 53.7
  },
  "gpu": {
    "name": "NVIDIA GeForce RTX 4060 Laptop GPU",
    "usage": 42.0,
    "temp": 65.0,
    "vram_used_gb": 3.1,
    "vram_total_gb": 8.0
  },
  "network": {
    "upload_kbps": 120.5,
    "download_kbps": 1024.8
  },
  "disk": {
    "percent": 68.4
  }
}

null means the value is unavailable. The Raspberry Pi dashboard displays unavailable values as N/A.

systemd Autostart

TinySysPanel can run automatically after the Raspberry Pi boots. See docs/systemd_service.md for the full service file and commands.

Troubleshooting

PC OFFLINE

• Confirm the Windows PC Agent is running.
• Open http://127.0.0.1:5000/health on the Windows PC.
• Confirm pc_api_url uses the real Windows LAN IP.
• Confirm the PC and Raspberry Pi are on the same network.

/dev/fb1 not found

• Run ls -l /dev/fb*.
• Confirm SPI and the TFT overlay are enabled.
• If your display appears as /dev/fb0, update framebuffer in raspberry-pi-client/config.json.

Windows firewall blocks port 5000

Run PowerShell as Administrator:

New-NetFirewallRule -DisplayName "TinySysPanel PC Agent 5000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5000

Wrong PC IP address

Run ipconfig on Windows and use the active LAN IPv4 address:

"pc_api_url": "http://YOUR_PC_IP:5000/stats"

GPU shows N/A

V0.1.2 reads NVIDIA GPU data through nvidia-smi. If nvidia-smi is unavailable or fails, GPU fields stay null.

CPU temperature shows N/A

This is common on Windows because CPU temperature is not always exposed through psutil.

Raspberry Pi service starts too early

If the screen shows PC OFFLINE immediately after boot, keep or increase ExecStartPre=/bin/sleep 10 in the systemd service.

Roadmap

• Web preview dashboard planned.
• Theme presets planned.
• ESP32 TFT client planned.
• Windows tray mode planned.
• Auto discovery planned.
• More display layouts planned.

License

MIT License. See LICENSE.