SmallTV Ultra Skill
A Claude skill for controlling, customizing, and developing firmware for the GeekMagic SmallTV Ultra — an ESP8266-based IoT device with a 240x240 TFT display.
What is the SmallTV Ultra?
The GeekMagic SmallTV Ultra is a tiny WiFi-connected display powered by an ESP8266 with a 1.5" 240x240 IPS screen. Out of the box it shows weather, time, crypto prices, and a photo album — all controlled via an HTTP API with no authentication.
What This Skill Covers
| Path | Description |
|---|
| Control | Use the stock firmware HTTP API — change themes, adjust brightness, upload images/GIFs, configure weather, and more |
| Custom Content | Generate and push 240x240 images/GIFs to the display — dashboards, stats, notifications, art |
| Alternative Firmware | Install community firmware (bvweerd, ESPHome, Tasmota) with guided safety checks and rollback |
| Custom Firmware | Write your own ESP8266 firmware from scratch with PlatformIO, TFT_eSPI, and OTA flashing |
The skill includes complete device reference documentation, API details, and step-by-step guides for each path.
Choose Your Setup
Use this quick guide first:
| Setup | Best for | Can reach SmallTV directly? | What to use |
|---|
| Claude Code + skill | Local terminal workflow | Yes | Install skill from marketplace |
| Claude Desktop (Chat mode) + skill | Desktop chat workflow | No | Use local proxy + tunnel bridge |
| Claude Desktop (Cowork mode) + skill | Cowork VM workflow | No (in this project setup) | Use local proxy + tunnel bridge |
| Claude Desktop (Chat or Cowork) + local MCPB | Desktop with local MCP tools | Yes (via local MCP on your machine) | Install prebuilt .mcpb |
If you are unsure, pick:
- Claude Code + skill for easiest direct control
- Desktop + MCPB for secure local MCP access without exposing the raw device API
Installation
Claude Desktop (recommended)
- Open Claude Desktop
- Go to Customize > Browse plugins > Personal
- Click the + button, then "Add marketplace from GitHub"
- Enter
yaniv-golan/smalltv-ultra-skill
Alternatively, click + > "Upload plugin" to install from a local copy.
Claude Code (CLI)
# Add the marketplace and install
claude plugin marketplace add yaniv-golan/smalltv-ultra-skill
claude plugin install geekmagic-smalltv-ultra
# Or load from a local copy (no install needed)
claude --plugin-dir /path/to/smalltv-ultra-skill
Runtime and Network Reachability
This plugin can be used from Claude Desktop (Chat/Cowork modes) and Claude Code. The key difference is whether that runtime can directly reach your SmallTV private LAN IP (for example 192.168.x.x).
| Runtime | Where it runs | Can reach private LAN device directly? |
|---|
| Claude Desktop (Chat mode) | Anthropic-managed runtime | No |
| Claude Desktop (Cowork mode) | Local VM on your machine | No (in this project setup) |
| Claude Code (CLI) | In your terminal on your machine | Yes, if your machine can reach the device |
| Claude cloud code execution | Anthropic-managed cloud VM | No (private LAN is not directly routable) |
If your runtime cannot reach LAN directly, use a bridge (local MCP server or local proxy+tunnel).
Secure Quick Tunnel
If your runtime cannot reach the device LAN directly, you can run a local token-protected proxy and tunnel it with cloudflared. See the Secure Quick Tunnel guide for full setup instructions.
Local MCP Server Option (mcp-bash)
This repo also includes a local MCP server project at mcp/smalltv-local, built with mcp-bash.
Use this when you want Claude or any MCP-capable app/client to call your SmallTV through your local machine without exposing the device directly.
Recommended install path (simplest):
- Download the latest
.mcpb from GitHub Releases.
- Install the bundle in your MCPB-compatible client.
- Provide device IP in the install/user-config prompt.
