- name
- holocube
- description
- Control GeekMagic HelloCubic-Lite holographic cube display with HoloClawd firmware. Supports drawing API, pomodoro timer with lobster mascot, GIF uploads, and procedural animations.
- homepage
- https://github.com/andrewjiang/HoloClawd-Open-Firmware
- metadata
- {"clawdbot":{"emoji":"🦞","os":["darwin","linux"]}}
- triggers
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:
# 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 20Drawing API (requires holocube_client.py from repo):
# 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:
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 confettiPomodoro Timer
Full pomodoro timer with cute lobster buddy located in the HoloCube firmware repo:
# 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 3Location: ~/Bao/TimeToLockIn/HoloClawd-Open-Firmware/examples/pomodoro.py
- Uses
spotify.shin 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:
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 2Tracker icons appear on the HoloCube display with their current counts.
Stock Firmware Tools
holocube.py - GIF Upload (Stock Firmware)
uv run --script holocube.py upload animation.gif
uv run --script holocube.py show animation.gif
uv run --script holocube.py listgifgen.py - Procedural Animation Generator
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.gifDrawing API Endpoints
HoloClawd firmware exposes these REST endpoints:
# 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:
git clone https://github.com/andrewjiang/HoloClawd-Open-Firmware.git
cd HoloClawd-Open-Firmware
pio run # Build
curl -X POST -F " [email protected] /build/esp12e/firmware.bin" http://192.168.7.80/api/v1/ota/fwColor Reference
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