🤖 AI Agent Directives: Dopamine Hardware Bridge

🏗 Architecture Overview

You are working in the dopamine-hardware repository. This is a Python-based edge hardware bridge running on a Raspberry Pi 4 (Debian/Raspberry Pi OS Lite 64-bit). Its primary purpose is to act as a resilient, headless peripheral controller for the "Onion Tasker" Cloudflare Worker.

Hardware Attached:

• Printer: Epson TM-T20III Thermal Receipt Printer (USB: Vendor 04b8, Product 0e28).
• Scanner: Tera D5100 2D Barcode Scanner (Acts as a USB HID Keyboard).

The 3-Tier Fallback Protocol: This bridge communicates with the Cloudflare Worker via three resilient methods:

1. Tier 1 (VPC Push): Flask server running on 0.0.0.0:8080, exposed via Cloudflare Tunnel (cloudflared). The Worker makes direct HTTP requests.
2. Tier 2 (WebSocket): Background thread maintaining a persistent WSS connection to the Worker for pub/sub broadcasts.
3. Tier 3 (REST Polling): Background thread polling the Worker's pending jobs queue every 15 seconds to recover from network outages.

🛠 System Environment

• Python Version: 3.13
• Virtual Environment: Located at /home/pi/dopamine-hardware/.venv
• Daemon: Managed by systemd (dopamine.service).
• Logging: Dual-logging system. Logs are written to a local SQLite database (dopamine_logs.db) AND streamed asynchronously to the Cloudflare Worker telemetry endpoint.

🚨 Critical Agent Rules

1. Never use sudo pip or --break-system-packages: All Python dependencies MUST be installed inside the .venv.
2. Thread Safety: The printer is accessed by multiple threads (VPC, WS, REST). All printer interactions MUST be wrapped in the printer_lock to prevent USB bus collisions.
3. No GUI Modules: This is a headless environment. Never import tkinter, matplotlib.pyplot (with GUI backends), or anything requiring an X11 server.
4. Resilience over Everything: Hardware fails, cables get unplugged, networks drop. Every hardware or network call MUST have a strict try/except block that logs the failure gracefully without crashing the main threads.