holocube

# HoloCube Controller Control the GeekMagic HelloCubic-Lite with HoloClawd firmware via REST API. **Firmware:** https://github.com/andrewjiang/HoloClawd-Open-Firmware ## Device Info - **Model:** HelloCubic-Lite with HoloClawd Firmware - **Display:** 240x240px ST7789 TFT - **Default IP:** 192.168.7.80 (configurable) ## Quick Start **Pomodoro Timer**: ```bash # Run pomodoro timer with lobster mascot (25 min work, 5 min break) cd ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples && uv run --script pomodoro.py # With custom task label (max 20 chars) cd ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples && uv run --script pomodoro.py --task "BUILD NETWORK" # With Spotify integration cd ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples && uv run --script pomodoro.py --task "LP UPDATE" --spotify-work "spotify:episode:5yJKH11UlF3sS3gcKKaUYx" --spotify-break "spotify:episode:4U4OloHPFBNHWt0GOKENVF" # Custom timings cd ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples && uv run --script pomodoro.py --work 50 --short 10 --long 20 ``` **Drawing API** (requires holocube_client.py from repo): ```bash # Draw something on the display python3 -c " from holocube_client import HoloCube, Color, draw_lobster cube = HoloCube('192.168.7.80') cube.clear(Color.BLACK) draw_lobster(cube, 120, 120) # Draw lobster in center " ``` ## Python Client Library The `holocube_client.py` module provides full programmatic control: ```python from holocube_client import HoloCube, Color, draw_lobster, draw_confetti cube = HoloCube("192.168.7.80") # Drawing primitives cube.clear("#000000") # Clear screen cube.pixel(x, y, color) # Single pixel cube.line(x0, y0, x1, y1, color) # Line cube.rect(x, y, w, h, color, fill=True) # Rectangle cube.circle(x, y, r, color, fill=True) # Circle cube.triangle(x0, y0, x1, y1, x2, y2, color) # Triangle cube.ellipse(x, y, rx, ry, color, fill=True) # Ellipse cube.roundrect(x, y, w, h, r, color, fill=True) # Rounded rectangle cube.text(x, y, "Hello", size=3, color="#00ffff") # Text # High-level helpers cube.centered_text(y, "Centered", size=2) cube.show_message(["Line 1", "Line 2"], colors=[Color.CYAN, Color.WHITE]) cube.show_timer(seconds, label="FOCUS") cube.show_progress(0.75, label="Loading") # Lobster mascot draw_lobster(cube, 120, 120) # Normal lobster draw_lobster(cube, 120, 120, happy=True, frame=0) # Party mode with confetti draw_confetti(cube, 120, 120, frame=1) # Animate confetti ``` ## Pomodoro Timer Full pomodoro timer with cute lobster buddy located in the HoloCube firmware repo: ```bash # Always run from the examples directory cd ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples # Default: 25 min work, 5 min break uv run --script pomodoro.py # With custom task label uv run --script pomodoro.py --task "CODE REVIEW" uv run --script pomodoro.py --task "BUILD NETWORK" # With Spotify integration (Andrew's favorite URIs) uv run --script pomodoro.py --task "LP UPDATE" \ --spotify-work "spotify:episode:5yJKH11UlF3sS3gcKKaUYx" \ --spotify-break "spotify:episode:4U4OloHPFBNHWt0GOKENVF" # Custom timings uv run --script pomodoro.py --work 50 --short 10 --long 20 # With trackers uv run --script pomodoro.py --water 2 --exercise 1 --focus 3 ``` **Location**: `~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples/pomodoro.py` - Uses `spotify.sh` in the same directory for playback - Supports icon-based trackers (water, exercise, focus, pills) - Interactive command listener for live controls Options: - `--task`: Task label displayed during work (max 20 chars, auto-uppercased) - `--work`: Work duration in minutes (default: 25) - `--short`: Short break in minutes (default: 5) - `--long`: Long break in minutes (default: 15) - `--sessions`: Sessions before long break (default: 4) - `--spotify-work`: Spotify URI for work sessions - `--spotify-break`: Spotify URI for break sessions - `--water`: Water glasses consumed today - `--exercise`: Exercise sessions completed - `--focus`: Focus sessions completed - `--pills-done`: Mark daily pills as taken Features: - Lobster mascot watches you work (focused expression) - During breaks: happy lobster with twinkling confetti - Flashing alerts between sessions - Tracks completed sessions - Optional Spotify playback via AppleScript (macOS) - Icon-based trackers displayed on screen - Interactive command listener via keyboard ## Trackers The pomodoro timer supports visual trackers using the Kyrise icon pack. Pass tracker values as arguments to display them during your session: ```bash cd ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples # Water tracking (glasses consumed) uv run --script pomodoro.py --water 3 # Exercise sessions uv run --script pomodoro.py --exercise 1 # Focus sessions completed uv run --script pomodoro.py --focus 2 # Pills taken today uv run --script pomodoro.py --pills-done # Combine multiple trackers uv run --script pomodoro.py --task "DEEP WORK" --water 3 --exercise 1 --focus 2 ``` Tracker icons appear on the HoloCube display with their current counts. ## Stock Firmware Tools ### holocube.py - GIF Upload (Stock Firmware) ```bash uv run --script holocube.py upload animation.gif uv run --script holocube.py show animation.gif uv run --script holocube.py list ``` ### gifgen.py - Procedural Animation Generator ```bash uv run --script gifgen.py fire output.gif uv run --script gifgen.py plasma output.gif uv run --script gifgen.py matrix output.gif uv run --script gifgen.py sparkle output.gif ``` ## Drawing API Endpoints HoloClawd firmware exposes these REST endpoints: ```bash # Clear screen curl -X POST http://192.168.7.80/api/v1/draw/clear -d '{"color":"#000000"}' # Draw shapes curl -X POST http://192.168.7.80/api/v1/draw/circle -d '{"x":120,"y":120,"r":50,"color":"#ff0000","fill":true}' curl -X POST http://192.168.7.80/api/v1/draw/rect -d '{"x":10,"y":10,"w":100,"h":50,"color":"#00ff00"}' curl -X POST http://192.168.7.80/api/v1/draw/triangle -d '{"x0":120,"y0":50,"x1":80,"y1":150,"x2":160,"y2":150,"color":"#0000ff"}' curl -X POST http://192.168.7.80/api/v1/draw/ellipse -d '{"x":120,"y":120,"rx":60,"ry":30,"color":"#ffff00"}' curl -X POST http://192.168.7.80/api/v1/draw/line -d '{"x0":0,"y0":0,"x1":240,"y1":240,"color":"#ffffff"}' curl -X POST http://192.168.7.80/api/v1/draw/text -d '{"x":60,"y":100,"text":"Hello","size":3,"color":"#00ffff"}' # Batch multiple commands curl -X POST http://192.168.7.80/api/v1/draw/batch -d '{"commands":[...]}' ``` ## Firmware **Source:** https://github.com/andrewjiang/HoloClawd-Open-Firmware Build and flash: ```bash git clone https://github.com/andrewjiang/HoloClawd-Open-Firmware.git cd HoloClawd-Open-Firmware pio run # Build curl -X POST -F "file=@.pio/build/esp12e/firmware.bin" http://192.168.7.80/api/v1/ota/fw ``` ## Color Reference ```python Color.BLACK = "#000000" Color.WHITE = "#ffffff" Color.RED = "#ff0000" Color.GREEN = "#00ff00" Color.BLUE = "#0000ff" Color.CYAN = "#00ffff" Color.MAGENTA = "#ff00ff" Color.YELLOW = "#ffff00" Color.ORANGE = "#ff6600" Color.PURPLE = "#9900ff" ``` ## Troubleshooting - **Can't connect**: Check WiFi, device should be at 192.168.7.80 - **Drawing slow**: Each HTTP call takes ~50ms, use batch API for complex drawings - **Screen flickers**: Only clear screen on first frame, use background colors for text updates