Stat Screen by Roufsweb

An ultra-efficient, highly modular hardware diagnostic companion dashboard system. Engineered to offload 100% of graphics vector drawing and physics calculations to the Raspberry Pi Pico (RP2040)'s dual ARM Cortex-M0+ cores, achieving extremely smooth updates at 60 FPS with less than 0.1% host PC CPU utilization!

Featuring a stunning, highly visual 'Water Tank' Sloshing Fluid Animation with drifting rising bubbles and dynamic thermal color grading, optimized specifically for the Nokia 105 (128x128) screen.

---

🖥️ Application Dashboard UI

---

🚀 Quick Start - End-User Deployment (Zero Dependencies!)

If you just want to run the application and flash the screen without installing Python, compilers, or coding, use our pre-compiled release packages!

1. Flash the Screen (Pico)

1. Hold the BOOTSEL button on your Raspberry Pi Pico and plug it into your computer via USB.
2. The Pico will mount as a mass storage drive (e.g., F:\).
3. Copy the pre-compiled pico_firmware.uf2 (available in the Latest GitHub Release or /assets/releases/ folder) directly onto the Pico drive.
4. The Pico will flash itself and instantly reboot into standby mode!

2. Launch the Linker Application (PC)

1. Download the standalone Windows executable Stat_Screen.exe from the Latest GitHub Release or the /assets/releases/ folder.
2. Double-click to run Stat_Screen.exe on Windows. No Python, pip, or dependencies are required!
3. Select your Pico COM port from the dropdown list and click ⚡ ACTIVATE LINK to start streaming live telemetry data!

---

📂 Centralized Project Assets

To easily support future display sizes and additional microcontrollers, all assets are centralized under the root /assets folder:

• assets/logo_white/: High-fidelity vector SVG source (code.html), design specifications, and standard preview logo.
• assets/logo_dark/: Classic obsidian dark-theme vector SVG source (code.html) and reference captures.
• assets/icons/: Desktop linker standard launch icon, graphics, and the PySide6 UI screenshot.
• assets/scripts/: Pillow-based pixel rendering builders (render_logo.py) and release automation scripts.
• assets/firmware/: Hardware static BGR565 arrays (LogoImage.h) and core firmware (pico_firmware.ino).
• assets/releases/: Pre-compiled binaries (Stat_Screen.exe and pico_firmware.uf2).

For a detailed file list, see our Centralized Assets README.

---

🔍 Developer Deep-Dive & Build Guides

For developers who want to modify the source code, rebuild the binaries, or customize vector assets, welcome to the deep-dive!

---

⚙️ Key Technical Features

• Host-Efficient Telemetry Protocol (MTP): Streams a highly compressed 32-byte binary packet once every 500ms over USB COM, dropping host diagnostic CPU overhead from ~10% (raw framebuffer streaming) to near-zero.
• Dual-Core Execution Splits:
  • Core 0: Runs a non-blocking sliding-window parser to ingest serial streams and validate data via XOR checksums.
  • Core 1: Computes physics loops (fluid sloshing wave coordinates, bubble rising wiggles, popped bubbles) and renders double-buffered vector graphics at 60 FPS.
• 🫧 'Water Tank' Sloshing Liquid Engine: Models telemetry percentages as colored coolant fluid wiggling inside a glass cylinder using trigonometric sine-wave surface columns: $$y_{\text{surface}}(x) = y_{\text{level}} + A \sin\left(\frac{x - x_{\text{left}}}{\text{width}} \cdot 2\pi + \text{wave_phase}\right)$$
• Bubbles Drift Mechanics: Floating wiggling bubble vectors ($x = x_{\text{base}} + 1.5 \sin(y \cdot 0.15)$) rise through the fluid and pop naturally at the surface.
• Double Side-by-Side System Tanks: Renders two independent sloshing tanks side-by-side for RAM and Disk C: metrics.
• 62.5 MHz Hardware SPI / SIO Drivers: Includes modular display interfaces. Built-in support for ST7789 displays at 62.5MHz and Nokia 105 SPFD54124B bit-banged panels.

---

📐 System Architecture

graph TD
    subgraph Host PC (Companion App)
        diag[QThread Sensors: psutil / WMI / nvidia-smi] -->|Python dict| stream[Protocol Stream: Pack 32-Byte MTP]
        stream -->|USB CDC Serial @ 115200| com[Virtual COM Port]
    end

    subgraph RP2040 (Raspberry Pi Pico Core)
        com -->|Sliding Magic Buffer| core0[Core 0: Serial Listener & Pack Parser]
        core0 -->|Thread-Safe Copy| state[Shared Global Telemetry State]
        
        state -.->|Read under lock| core1[Core 1: 60 FPS Local Rendering Loop]
        
        subgraph Core 1 Engine
            core1 -->|Wave & Bubble Physics| math[AnimationSystem: Easing & Wave Solver]
            math -->|Double Buffer drawing| draw[GraphicsEngine: Shapes & Fonts]
            draw -->|SPI / Bit-bang push| driver[DisplayDriver: ST7789 / Nokia 105]
        end
    end

Loading

---

📡 MicroTelemetry Protocol (MTP) Specification v1.0

The communication protocol transfers real-time telemetry packets from the PC to the RP2040 over a virtual USB COM serial port. Packets are streamed as a raw 32-byte binary chunk every 500ms, minimizing host overhead.

Byte-Level Packet Layout

Offset	Type	Field	Description	Range
0	uint8_t	magic1	Constant 0xAA (Magic Header Byte 1)	0xAA
1	uint8_t	magic2	Constant 0x55 (Magic Header Byte 2)	0x55
2	uint8_t	packet_type	0x01 = Real-time Telemetry, 0x02 = Configuration	0x01 / 0x02
3	uint8_t	cpu_load	CPU utilization percentage	0 - 100
4	uint8_t	cpu_temp	CPU temperature in °C	0 - 120
5-6	uint16_t	cpu_freq	CPU clock speed in MHz (Little-Endian)	0 - 65535
7	uint8_t	gpu_load	GPU utilization percentage	0 - 100
8	uint8_t	gpu_temp	GPU temperature in °C	0 - 120
9	uint8_t	gpu_vram	GPU VRAM utilization percentage	0 - 100
10	uint8_t	ram_percent	System RAM utilization percentage	0 - 100
11-12	uint16_t	ram_used_mb	System RAM used in Megabytes (Little-Endian)	0 - 65535
13-14	uint16_t	ram_total_mb	System RAM total in Megabytes (Little-Endian)	0 - 65535
15	uint8_t	disk_percent	C: Drive disk utilization percentage	0 - 100
16-19	float	net_dl_rate	Network Download Rate in MB/s (32-bit Float)	Any
20-23	float	net_ul_rate	Network Upload Rate in MB/s (32-bit Float)	Any
24	uint8_t	active_cards	Toggled screens mask: Bit0 (CPU), Bit1 (GPU), Bit2 (RAM), Bit3 (DISK)	0x00 - 0x0F
25	uint8_t	cycle_sec	Screen loop cycle interval in seconds	1 - 10
26-29	uint32_t	uptime_sec	Host PC uptime in seconds (Little-Endian)	0 - 4.29B
30	uint8_t	active_options	Bitmask of enabled telemetry fields (OPT_SHOW_*)	0x00 - 0xFF
31	uint8_t	checksum	XOR checksum of bytes 0 to 30	0x00 - 0xFF

CRC Integrity & Synchronization

• Magic Header Lock: The Pico firmware operates a non-blocking sliding-window parser. It constantly scans serial bytes, resetting its offset buffer unless it detects the sequential magic bytes 0xAA 0x55, providing immunity to startup noise or serial buffer alignment shifts.
• Integrity Validation: Every telemetry packet is validated by checking the final byte against an XOR checksum computed across all previous 31 bytes: $$\text{Checksum} = \bigoplus_{i=0}^{30} \text{Byte}_i$$ Any packet failing the checksum check is discarded immediately to prevent diagnostic glitches.

---

💻 Developer Setup & Rebuild Guides

1. Compile & Rebuild Pico Firmware

1. Open the Arduino IDE.
2. Install the Raspberry Pi Pico board core by Earle Philhower (Settings -> Boards Manager).
3. Open the file pico_firmware/pico_firmware.ino in the IDE.
4. Select Raspberry Pi Pico as your target board.
5. Hit Upload (or run standard compilation to build a new .uf2 file).
6. To switch to a ST7789 240x240 display later, simply uncomment #define SELECT_ST7789 and comment out #define SELECT_NOKIA105 at the top of the .ino file! All scales adapt automatically!

2. Running Desktop Linker from Python Source

1. Open a terminal inside the project root directory:

   cd desktop_app

2. Install required development libraries:

   pip install PySide6 psutil pyserial

3. Run the python script directly:

   python main.py

3. Rebuilding Standalone Windows .exe

If you modify the companion app source code and want to recompile the standalone executable:

1. Ensure PyInstaller is installed: pip install pyinstaller.
2. Open a terminal in desktop_app/ and run:

   pyinstaller Stat_Screen.spec

3. The new compiled standalone binary will be created in dist/Stat_Screen.exe.

---

🎨 Premium Visual Palette & Thermal Grade

• Obsidian Base: #03070C carbon black background, #0D1520 glassmorphic cards, and #08101C matrix grid lines.
• Submerged Dropshadow: Submerged status text overlays draw a +1px black shadow behind the white body text, ensuring 100% legibility over moving waves!
• Active Thermal Coolants:
  • Cool/Safe (< 50%): Turquoise/Green (#00FFA2).
  • Moderate (50% - 80%): Amber Gold (#FFAA00).
  • Critical Load (>= 80%): Warning Red (#FF3344).

---

📜 License

Developed under the GNU Affero General Public License v3.0 (AGPL-3.0). Created by Roufesweb Diagnostic Labs. See LICENSE for details.