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:

# 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):

# 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 confetti

Pomodoro 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 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:

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)

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

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:

# 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 "file=@.pio/build/esp12e/firmware.bin" http://192.168.7.80/api/v1/ota/fw

Color 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