turing-smart-screen-python (fork with Claude Code usage monitor)

Note

This is a fork of mathoudebine/turing-smart-screen-python with added features:

• Claude Code usage monitor theme displaying real-time API consumption (5h window, weekly, Sonnet, extra credits)
• Multi-screen manager to switch between views with configurable keyboard shortcuts

Warning

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Turing / XuanFang / Kipye brands, or any of theirs subsidiaries, affiliates, manufacturers or sellers of their products. All product and company names are the registered trademarks of their original owners.

This project is an open-source alternative software, NOT the original software provided for the smart screens. Please do not open issues for USBMonitor.exe/ExtendScreen.exe or for the smart screens hardware here.

• for Turing Smart Screen, use the official forum here: http://discuz.turzx.com/
• for other smart screens, contact your reseller

A Python system monitor program and an abstraction library for small IPS USB-C displays.

Supported operating systems : macOS, Windows, Linux (incl. Raspberry Pi), basically all OS that support Python 3.9+

✅ Supported smart screens models:

✅ Turing Smart Screen / TURZX
All available sizes and hardware revisions supported: 2.1" / 2.8" / 3.5" / 4.6" / 5" / 5.2" / 8.0" / 8.8" / 9.2" / 12.3" UART and USB protocols supported. Note: no video or storage support for now

✅ XuanFang 3.5"	✅ UsbPCMonitor 3.5" / 5"	✅ Kipye Qiye Smart Display 3.5"
revision B & flagship (with backplate & RGB LEDs)	Unknown manufacturer, visually similar to Turing 3.5" / 5". Original software is UsbPCMonitor.exe	Front panel has an engraved inscription "奇叶智显" Qiye Zhixian (Qiye Smart Display)

✅ WeAct Studio Display FS V1 0.96"	✅ WeAct Studio Display FS V1 3.5"

❌ Not (yet) supported / not tested smart screen models

❔ AIDA64 / AX206 / USB2LCD...	❔ ACEMAGIC S1 Mini PC - integrated 1,9″ display
Not supported for now. Produced by multiple manufacturers, all use the same Appotech AX206 hacked photo frame firmware. Supported by AIDA64 and lcd4linux	Not supported for now but could be integrated: protocol has been decoded, see here.

❔ NXElec BeadaPanel 3/4/5/6/7
Not supported for now but could be integrated: Pankel-Link V1.0 Protocol Specification / Status-Link V1.1 Protocol Specification.

❌ Waveshare 2.1inch / 2.8inch / 5inch / 7inch USB-Monitor	❌ GUITION Smart screen 3.5"
Sold on Waveshare shop or Aliexpress. Managed by proprietary Windows software "Waveshare PC Monitor". Cannot be supported by this project: needs a firmware.	Managed by proprietary Windows software "GUITION Smart screen". Cannot be supported by this project: see here.

❌ (Fuldho?) 3.5" IPS Screen
Managed by proprietary Windows software SmartMonitor.exe. Cannot be supported by this project: see here.

> What is my smart screen model?

Please note all listed smart screens are different products designed and produced by different companies, despite having a similar appearance. Their communication protocol is also different.
This project offers an abstraction layer to manage all of these products in a unified way, including some product-specific features like backplate RGB LEDs for available models!

If you haven't received your screen yet but want to start developing your theme now, you can use the "simulated LCD" mode!

Fork additions

Claude Code usage theme

A dedicated theme (ClaudeCode) that displays your Claude Code plan consumption in real time on the smart screen. Switch between your usual system monitor and the Claude usage view with a keyboard shortcut.

Left: System Monitor (default) | Right: Claude Code Usage

Displayed metrics

Metric	Source	Display
5-Hour Window	five_hour.utilization	Large percentage + orange progress bar + reset time (e.g. Reset 19:30)
Weekly Usage	seven_day.utilization	Large percentage + blue progress bar + reset date (e.g. Reset Tue 26)
Sonnet	seven_day_sonnet.utilization	Percentage + purple progress bar
Extra Credits	extra_usage.used_credits	Spent amount in EUR (converted from cents)
Date / Time	System clock	Displayed at the bottom

Data is fetched from the Claude API endpoint (/api/oauth/usage) using your local OAuth credentials (~/.claude/.credentials.json). A shared cache (_ClaudeUsageCache) ensures the API is called at most once every 30 seconds, regardless of how many sensors read from it.

Custom data sources

All Claude sensors are implemented in library/sensors/sensors_custom.py as standard CustomDataSource subclasses, fully compatible with the theme engine:

Class	Type	Value
ClaudeFiveHourUsage	numeric + history	5h utilization % (0-100)
ClaudeFiveHourReset	text only	Reset time (Reset HH:MM)
ClaudeWeeklyUsage	numeric + history	7-day utilization % (0-100)
ClaudeWeeklyReset	text only	Reset date (Reset Mon DD)
ClaudeSonnetUsage	numeric	Sonnet 7-day utilization %
ClaudeExtraUsage	numeric	Extra credits spent (EUR)

You can reuse these classes in any other theme by referencing them in theme.yaml under STATS > CUSTOM.

Credentials

The credentials path is resolved in this order:

1. CLAUDE_CREDENTIALS environment variable (if set)
2. ~/.claude/.credentials.json (default)

This is important when running as a systemd service (where ~ resolves to /root). The provided start.sh auto-detects the first non-root user's home directory.

---

Multi-screen manager

The multi-screen manager (multiscreen.py) replaces main.py as the main entry point. It manages an array of screens and lets you cycle through them with configurable keyboard shortcuts.

python3 multiscreen.py

[multiscreen] Turing Smart Screen - Multi-screen Manager
[multiscreen] 2 screen(s) configured:
  [0] System Monitor (theme: 3.5inchTheme2)
  [1] Claude Code Usage (theme: ClaudeCode)

[multiscreen] Keybindings:
  next: ctrl + shift + end
  prev: ctrl + shift + home

[multiscreen] CTRL+C to exit
[multiscreen] Started: System Monitor (PID 12345)

Configuration: multiscreen.yaml

All screens and keybindings are defined in a single YAML file. Nothing is hardcoded.

# Add as many screens as you want
screens:
  - name: "System Monitor"
    theme: "3.5inchTheme2"

  - name: "Claude Code Usage"
    theme: "ClaudeCode"

  # - name: "My Custom Theme"
  #   theme: "MyThemeFolder"

# All keybindings are configurable
keybindings:
  next: "ctrl + shift + end"       # Next screen in the list
  prev: "ctrl + shift + home"      # Previous screen in the list
  # screen_0: "ctrl + shift + f1"  # Jump directly to screen index 0
  # screen_1: "ctrl + shift + f2"  # Jump directly to screen index 1

Keybinding reference

Action	Description
next	Switch to the next screen (wraps around)
prev	Switch to the previous screen (wraps around)
screen_N	Jump directly to screen at index N (0-based)

Available keys for combos:

Category	Keys
Modifiers	ctrl, shift, alt
Navigation	home, end, page_up, page_down, up, down, left, right
Function	f1 - f12
Special	space, tab, enter, esc, insert, delete
Characters	Any single character (a, b, 1, 2, etc.)

Combos are written with + separators: "ctrl + shift + f1", "alt + home", etc.

How it works

When you press a hotkey, the manager:

1. Sends SIGTERM to the currently running main.py process
2. Updates the THEME value in config.yaml (preserving comments)
3. Launches a new main.py process with the new theme

The switch takes about 1-2 seconds. If the monitor process crashes, the manager auto-restarts it.

---

Running at boot (systemd)

A start.sh script is provided that handles venv activation, serial port permissions, and credential path detection.

Service file

# /etc/systemd/system/turing-smart-screen.service
[Unit]
Description=Turing Smart Screen - Multi-screen Manager
After=network.target graphical.target
Wants=graphical.target

[Service]
Type=simple
WorkingDirectory=/path/to/smart-screen-python-claude
ExecStart=/bin/bash /path/to/smart-screen-python-claude/start.sh
Restart=always
User=root
Group=root
Environment="PYTHONUNBUFFERED=1"
Environment="DISPLAY=:1"
Environment="XAUTHORITY=/run/user/1000/gdm/Xauthority"

[Install]
WantedBy=multi-user.target

Important: The DISPLAY and XAUTHORITY environment variables are required for pynput to capture keyboard shortcuts from within a systemd service. Adjust the DISPLAY value (:0, :1, etc.) and XAUTHORITY path to match your system (echo $DISPLAY and echo $XAUTHORITY in a terminal).

Commands

sudo systemctl daemon-reload
sudo systemctl enable turing-smart-screen.service   # start at boot
sudo systemctl start turing-smart-screen.service     # start now
sudo systemctl status turing-smart-screen.service    # check status
journalctl -u turing-smart-screen.service -f         # follow logs

---

Additional dependencies

On top of the base project requirements:

pip install pynput requests

---

Files changed from upstream

File	Change
library/sensors/sensors_custom.py	Added 6 Claude usage sensor classes + shared API cache
res/themes/ClaudeCode/	New theme (background image + theme.yaml)
multiscreen.py	New multi-screen manager with hotkey support
multiscreen.yaml	New configurable screens array and keybindings
start.sh	New launcher script for systemd with credential detection
generate_background.py	Script to regenerate the Claude theme background
config.yaml	DISPLAY_REVERSE: true (hardware-specific)

---

How to start

> Follow instructions on the wiki to configure and start this project.

There are 2 possible uses of this project Python code:

• as a System Monitor, a standalone program working with themes to display your computer HW info and custom data in an elegant way. Check if your hardware is supported.
• integrated in your project, to fully control the display from your own Python code.

System monitor

This project is mainly a complete standalone program to use your screen as a system monitor, like the original vendor app.
Some themes are already included for a quick start!

> Configure and start system monitor

• Fully functional multi-OS code base (operates out of the box, tested on Windows, Linux & MacOS).
• Display configuration using GUI configuration wizard or config.yaml file: no Python code to edit.
• Compatible with multiple smart screen models (Turing, XuanFang...). Backplate RGB LEDs are also supported for available models!
• Support multiple hardware sensors and metrics (CPU/GPU usage, temperatures, memory, disks, etc) with configurable refresh intervals.
• Allow creation of themes (see res/themes) with theme.yaml files using theme editor to be shared with the community!
• Easy to expand: custom Python data sources can be written to pull specific information and display it on themes like any other sensor.
• Auto-detect COM port based on the selected smart screen model.
• Tray icon with Exit option, useful when the program is running in background.

> List and preview of included themes

... view full list

> Themes creation/edition (using theme editor)

> Themes shared by the community

and more... Share yours!

Control the display from your Python projects

If you don't want to use your screen for system monitoring, you can just use this project as a module from any Python code to do some simple operations on the display:

• Display custom picture
• Display text
• Display horizontal / radial progress bar
• Screen rotation
• Clear the screen (blank)
• Turn the screen on/off
• Display soft reset
• Set brightness
• Set backplate RGB LEDs color (on supported hardware rev.)

This project will act as an abstraction library to handle specific protocols and capabilities of each supported smart screen models in a transparent way for the user. Check simple-program.py as an example.

> Control the display from your code

Troubleshooting

If you have trouble running the program as described in the wiki, please check open/closed issues & the wiki Troubleshooting page

They're talking about it!

• Hackaday - Cheap LCD Uses USB Serial

• CNX Software - Turing Smart Screen – A low-cost 3.5-inch USB Type-C information display

• Phazer Tech - Turing Smart Screen Python

Star History