smalltv-ultra-skill

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:

1. Claude Code + skill for easiest direct control
2. Desktop + MCPB for secure local MCP access without exposing the raw device API

Installation

Claude Desktop (recommended)

1. Open Claude Desktop
2. Go to Customize > Browse plugins > Personal
3. Click the + button, then "Add marketplace from GitHub"
4. 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):

1. Download the latest .mcpb from GitHub Releases.
2. Install the bundle in your MCPB-compatible client.
3. Provide device IP in the install/user-config prompt.