Pixelcade API Documentation

Welcome to the API reference for Pixelcade LED marquee displays, Pixelcade LCD systems, and Pixelcade Pulse WS2812B devices and sub-display controllers. This REST API allows you to control your Pixelcade devices programmatically, displaying custom graphics, animations, text, and real-time information. Legacy (old) Pixelcade API docs here.

Table of Contents

Getting Started

• System Requirements & Setup
• Device Compatibility
• API Versions & Base URLs
• Queue System & Looping (LED Only)

LED & LCD APIs (V1 & V2)

• V1 API Reference (LED + LCD)
  • Displaying Game and Console Marquees
  • Text Display & Scrolling
  • Retro Achievements
  • Animation Overlays (LED Only)
  • News & Information Widgets (LED Only)
  • Spotify Now Playing Widget
  • YouTube Stats Widget
  • Google Calendar Widget
  • Playlist API
  • Screen Saver & Widget Integration
  • Sports Scores (LED Only)
  • Stock and Crypto Ticker (LED Only)
  • In Game Statistics & Game Data
  • Custom Content & Media
  • System Management
• V2 API Reference (LCD Only)
  • Device Information
  • Device Pairing
  • Marquee Management
  • Dot Sub-Display Scores (LCD with Dot Display)
  • Attract Mode (Timeline Playback)
  • Marquee Lists & Content
  • LCD Settings Configuration
  • Effects
  • System Updates

Pulse Sub-Display APIs

• Pulse API Reference
  • Device Information APIs
  • WS2812B LED Strip APIs
  • Batch Zone Control
  • MAX7219 APIs
  • Mini LCD (1602/2004) APIs
  • Local Playback API

Reference Materials

• Complete Examples Reference
• Advanced Technical Notes
• Licensing

System Requirements & Setup

Pixelcade Listener Service

A Pixelcade Listener called pixelweb runs in the background and listens for REST URL calls. These are local REST calls to localhost, so an Internet connection is not required. However, if your host is reachable via the Internet, you can make these calls remotely too.

Launch Commands:

• Windows: pixelweb.exe
• Linux: pixelweb
• Silent Mode: Add -silent parameter to launch without console messages

Pixelweb Command Line Options

Basic Usage:

# Windows
pixelweb.exe [options]

# Linux
./pixelweb [options]

Network & Binding:

• -b string – Optional bind address (default “0.0.0.0”)
• -port int – Optional port to listen on (default 8080)
• -nomdns – Skip mDNS registration

Device Configuration:

• -d string – Path to pixelcade device. Set to “auto” to scan (default “auto”). On Windows use COM#
• -devicescan – Scan for device if not found or not specified with -d
• -delay int – Time in seconds to delay device init
• -swapbluegreen – Swap blue and green (only needed for certain panels)

Display & Startup:

• -image string – Optional image to display on startup (default “mame/pixelcade.png”)
• -system-image string – Optional system image on startup (overrides -image)
• -text string – Optional text to display on startup (default “Welcome to Pixelcade”)
• -nointro – Skip startup text and logo (black screen on startup)
• -startup – Enable startup mode

Text & Font Settings:

• -font string – Default font for text (default “Arial Narrow 7”)
• -fontcolor string – Default font color for text (default “ff0000”)
• -fontcolorrandom – Random default font color, overrides -fontcolor (default true)
• -fontsize int – Default font size for text (default 28)

Image Matching:

• -fuzzy – Enable fuzzy matching for images (default true)
• -fuzzydistance int – Higher number = more distance, less confidence (default 20)
• -fuzzymatches int – Max fuzzy matches before disregarding (default 40)

Artwork & Updates:

• -install-artwork – First time install of Pixelcade LED artwork
• -install-artpack string – Install paid LED art pack (requires license code)
• -update-artwork – Update Pixelcade LED artwork
• -update-doflinx – Update DOFLinx MAME files only
• -check-artwork – Check if LED artwork update is available
• -progress-installer – Alternative installer with command line progress
• -progress-stdout – Print progress output as stdout only

Ticker Settings:

• -sports-ticker-refresh float – Minutes before updating sports scores, minimum 1 (default 1)
• -stock-ticker-refresh int – Minutes before updating stock ticker, minimum 1 (default 1)

Logging & Debug:

• -silent – Silent mode, no log output
• -debug – Debug log level
• -trace – Trace log level
• -colorlogging – Show console and ROM in color in listener window (default true)
• -logfile string – Optional log file path

System & Paths:

• -p string – Path to pixelcade root (default varies by system)
• -demo – Enable demo mode
• -version – Show Pixelcade software version

Example Commands:

# Silent mode with custom port
pixelweb -silent -port 8090

# Custom font and color settings
pixelweb -font "Neon 80s" -fontcolor "00ff00" -fontsize 24

# Debug mode with log file
pixelweb -debug -logfile "/var/log/pixelcade.log"

# Custom device path (Windows)
pixelweb.exe -d "COM3" -delay 5

# Fuzzy matching disabled with custom artwork
pixelweb -fuzzy=false -image "custom/startup.png"

# Demo mode with custom ticker refresh rates
pixelweb -demo -sports-ticker-refresh 5 -stock-ticker-refresh 10

Important: Ensure you have the latest version of Pixelcade software to guarantee all APIs are included.

Device Compatibility

Pixelcade LED vs LCD vs Pulse Support

Pixelcade LED: Supports all V1 REST APIs
Pixelcade LCD: Limited V1 support + exclusive V2 APIs
Pulse Sub-Displays: Dedicated API set for WS2812B LED strips, MAX7219 displays, and Mini LCD controllers

LED Limitations (V1 APIs)

• URL Format: Use pixelcadedx-xxxxxxxx.local instead of localhost (where xxxxxxxx is unique LCD ID)
• USB Connection: Use 169.254.100.1:8080 when connected directly via USB
• No Loop Commands: Omit ?l= parameter – queue feature doesn’t work
• No Animations: GIF animations not supported
• Text Behavior: Scrolling text loops continuously until next API call
• No Advanced Text: Font size, speed, lines, and offset not supported
• No Local Playback: localplayback command not supported
• Stream Only: No write mode support
• LED Isolation: Add &ledonly to display only on LED (not relay to LCD)

Pulse System Requirements

• Hardware: Pixelcade V2 hardware (purple board) with firmware 23 or higher
• Components: WS2812B LED strips, MAX7219 7-segment/dot matrix displays, Mini LCD displays (1602/2004)
• Zones: Maximum 36 zones (0-35) supported for LED strip management
• Features: Zone-based control, matrix text/score display, auto-detection capabilities

API Versions & Base URLs

V1 API (LED + LCD with limitations)

• LED Base URL: http://localhost:8080
• LCD Base URL: http://pixelcadedx-xxxxxxxx.local:8080
• LCD USB Connection: http://169.254.100.1:8080 (when connected via USB)
• Alternative URLs: IP address (http://192.168.1.206:8080) or DNS name (http://batocera.local:8080)

V2 API (LCD Only)

• Base URL: http://pixelcadedx-xxxxxxxx.local:8080
• USB Base URL: http://169.254.100.1:8080
• Format: All V2 endpoints return JSON objects with Status format: {"succeeded": true/false, "message": "..."}

Pulse API (Sub-Display Controllers)

• Base URL: http://localhost:8080 or http://your-hostname:8080
• Test Format: curl localhost:8080/[endpoint]
• Components: WS2812B LED strips, MAX7219 displays, Mini LCD controllers
• Requirements: Pixelcade V2 hardware with firmware 23+

Queue System & Looping (LED Only)

Loop Commands

Loop commands control how long content displays or how many times it repeats by adding ?l={number} to any API call:

• GIF animations: Loop x times
• PNG images: Display for x seconds
• Scrolling text: Loop x times

Queue Feature

If another loop command (GIF, PNG, or scrolling text) is sent while a current loop is running, that next loop command will be sent to a Queue for playback after the current loop command has finished. The Queue can contain an unlimited number of commands in any combination of GIF animations, still PNG images, and scrolling text.

Queue Management:

• Clear Queue: Send any command without the loop parameter (&l=x) or send a write command
• Priority: Non-loop commands immediately take priority, start, and empty the Queue
• Display Behavior: Display will be cleared/blanked after the last queue item finishes unless l=99999 is specified (keeps last item displayed until interrupted)
• Custom Scripts: When using the Queue feature in custom scripts, ensure all calls include &event=FEScroll

Examples:

# LED: Queue sequence - text → PNG → GIF → blank
curl "http://localhost:8080/text?t=Game%20Playing%20Pacman&l=1&c=blue&event=FEScroll"
curl "http://localhost:8080/arcade/stream/mame/pacman?l=3&event=FEScroll"  
curl "http://localhost:8080/arcade/stream/mame/pacghosts.gif?l=2&event=FEScroll"

# LED: Keep last item displayed (no blank)
curl "http://localhost:8080/arcade/stream/mame/pacman?l=99999"

# LED: Clear queue immediately
curl "http://localhost:8080/arcade/stream/mame/galaga"

API Reference (LED + LCD)

Gaming & Arcade Display

Display Game Marquees

Stream or write game-specific artwork to your Pixelcade display.

Endpoint: GET /arcade/{mode}/{console}/{rom}

Parameters:

• mode: stream or write
  • stream: Real-time display (requires Pixelcade listener), instant playback
  • write: Permanent storage to microSD card (works offline), includes physical write with delay. LED only
• console: Console/emulator name (e.g., mame, nes, snes)
• rom: ROM/game name

Console Names: Standard console names are documented at: https://github.com/alinke/pixelcade/ Console mapping file available at: https://github.com/alinke/pixelcade/blob/master/console.csv

Query Parameters:

• ?nogif – Display only PNG if both PNG and GIF exist, do not display the video marquee on LCD
• ?gifonly – Display only GIF if both PNG and GIF exist
• ?t={text} – Display scrolling text if no artwork found
• ?l={number} – Loop GIF x times or display PNG for x seconds (LED only – see Queue System above)
• ?event={flag} – Context flag for frontend integration
• ?nomini – If they exist, don’t send metadata to the mini displays (7segment, miniLCD, and dot matrix displays), show LED strips
• ?nostrip – Skip LED strips, show mini displays
• ?clearstrip – Clear & turn off LED strips, show mini displays 
• ?clearmini – Show LED strips, clear & turn off all mini displays
• ?clearstrip&clearmini – Clear everything (strips + mini displays), only show main marquee
• ?nostrip&nomini – Skip all effects, only show main marquee (no clearing)
• ?minilcdonly – Show metadata only on miniLCD, skip 7segment and dot matrix displays, LED strips still active
• ?minilcdonly&nostrip – Show metadata only on miniLCD, skip 7segment, dot matrix, and LED strips

Frontend Event Integration: Provide context for arcade frontend integration by adding event flags to your API calls.

Event Flags: (Case sensitive)

• FEStart – Frontend launched
• FEScroll – Scrolling through games
• GameStart – Game launched
• InGame – An event that happens in game like DOFLinx in game effects for example
• FEScreenSaver – Screensaver mode
• FEQuit – Frontend closing

Behavior Notes:

• If both PNG and GIF exist: GIF plays first, then PNG
• Multiple GIFs (e.g., qbert_01.gif, qbert_02.gif): Random selection per API call
• Missing artwork: Shows default marquee or fallback text
• Default marquee path: <pixelcade home folder>/console/default-marquee.png

Examples:

# LED: Display Pac-Man artwork
GET /arcade/stream/mame/pacman
curl http://localhost:8080/arcade/stream/mame/pacman

# LCD: Same command with LCD URL
GET http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman
curl http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman

# LCD via USB: Direct USB connection
curl http://169.254.100.1:8080/arcade/stream/mame/pacman

# LED: Write 1942 to storage
GET /arcade/write/mame/1942
curl http://localhost:8080/arcade/write/mame/1942

# LED: Display only PNG version
GET /arcade/stream/Atari%202600/pacman?nogif
curl "http://localhost:8080/arcade/stream/Atari%202600/pacman?nogif"

# LED: Loop GIF 3 times, ignore PNG
GET /arcade/stream/Atari%202600/pacman?l=3&gifonly
curl "http://localhost:8080/arcade/stream/Atari%202600/pacman?l=3&gifonly"

# LED: Stream with fallback text
GET /arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&c=green
curl "http://localhost:8080/arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&c=green"

# LED: Stream with single loop fallback
GET /arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&l=1
curl "http://localhost:8080/arcade/stream/mame/Missing-Game?t=Game%20Playing%20Missing-Game&l=1"

# Complex ROM names
GET /arcade/stream/nes/WURM%20-%20Journey%20to%20the%20Center%20of%20the%20World(U).zip
curl "http://localhost:8080/arcade/stream/nes/WURM%20-%20Journey%20to%20the%20Center%20of%20the%20World(U).zip"

# Using hostname instead of localhost
GET http://pixelcade.local:8080/console/stream/nes
curl http://pixelcade.local:8080/console/stream/nes

Display Console Marquees

Display console/emulator specific artwork.

Endpoint: GET /console/stream/{console}

Query Parameters:

• ?t={text} – Fallback scrolling text with all text formatting options

Console Names: Use standard console names from: https://github.com/alinke/pixelcade/ Console mapping reference: https://github.com/alinke/pixelcade/blob/master/console.csv

Examples:

# LED: Console display with fallback text
GET /console/stream/mame?t=MAME%20Arcade%20System
curl "http://localhost:8080/console/stream/mame?t=MAME%20Arcade%20System"

# LCD: Same command
curl "http://pixelcadedx-f26967ec.local:8080/console/stream/mame?t=MAME%20Arcade%20System"

# LCD via USB: Direct connection
curl "http://169.254.100.1:8080/console/stream/mame?t=MAME%20Arcade%20System"

Looping & Queue System (LED Only)

Control display duration and create command sequences.

Loop Commands: GET /arcade/stream/{console}/{rom}?l={x}

• GIF animations: Loop x times
• PNG images: Display for x seconds

Queue Feature:

• Commands with ?l={x} enter sequential queue
• Queue processes commands one after another
• Clear queue: send command without loop parameter
• Use l=99999 to keep last item displayed
• Add &event=FEScroll for frontend scripts

Examples:

# LED: Loop Pac-Man 3 seconds, then display indefinitely
GET /arcade/stream/mame/pacman?l=3
curl "http://localhost:8080/arcade/stream/mame/pacman?l=3"

# LED: Queue sequence example
GET /text?t=Game%20Playing%20Pacman&l=1&c=blue
curl "http://localhost:8080/text?t=Game%20Playing%20Pacman&l=1&c=blue"
GET /arcade/stream/mame/pacman?l=3
curl "http://localhost:8080/arcade/stream/mame/pacman?l=3"
GET /arcade/stream/mame/pacghosts.gif?l=2
curl "http://localhost:8080/arcade/stream/mame/pacghosts.gif?l=2"
# Results: Blue text 1 loop → Pac-Man PNG 3 seconds → Ghost GIF 2 loops → blank

Cycle Mode (LED Only)

Alternate between artwork and scrolling text indefinitely.

Endpoint: GET /arcade/stream/{console}/{rom}?t={text}&l={number}&color={color}&cycle

Behavior:

• PNG: Displays for x seconds
• GIF: Loops once regardless of loop parameter
• Text: Scrolls once before cycling back
• Stop: Send any command without loop parameter

Example:

# LED: Cycle between Pac-Man artwork and high scores
GET /arcade/stream/mame/pacman?t=High%20Scores%20Al%20200,000%20Erin%203,000&l=5&color=green&cycle
curl "http://localhost:8080/arcade/stream/mame/pacman?t=High%20Scores%20Al%20200,000%20Erin%203,000&l=5&color=green&cycle"

Text Display & Scrolling

Basic Text Display

Display custom scrolling text with full formatting control.

Endpoint: GET /text

Required Parameters:

• ?t={text} – Your text content (use %20 for spaces)

Optional Parameters (LED Only):

• ?c={color} or ?color={color} – Text color
• ?s={speed} – Scroll speed (1-150, lower = faster, capped at 150)
• ?font={name} – TTF font name (not filename)
• ?size={size} – Font size (14-32, default: 28)
• ?lines={count} – Number of lines (2 or 4; overrides font and size settings)
• ?yoffset={pixels} – Vertical offset adjustment (+/- pixels)
• ?xoffset={pixels} – Horizontal offset adjustment (+/- pixels)
• ?l={count} or ?loop={count} or ?loops={count} – Number of times to loop (-1 = infinite until next command)
• ?scroll=false – Fixed text display (no scrolling, auto-sizes with multi-line if needed, auto-sets infinite loops)
• ?scroll=true – Force scrolling even if text fits on screen
• ?blink={ms} – Blink interval in milliseconds (runs until next command). Note: blinking only works when text is 9 characters or less (i.e., text does not scroll)
• ?left=true or ?leftjustify=true or ?centered=false – Left-justify multi-line text (default is centered)
• ?ledonly – Skip LCD, send only to LED panel (bypasses dot matrix and WS2812B routing)
• ?system={name} – System/console name (mapped via console aliases for LCD display)
• Use \n in text for explicit line breaks (e.g., t=Line1\nLine2)

Color Options:

• Named: red, blue, cyan, gray, darkgray, green, lightgray, magenta, orange, yellow, pink, white
• Hex: 6-digit format without # (e.g., 45B39D, ff6d00)
• Default: Red (or random if configured)

Font Details:

• Add custom TTF fonts to /fonts folder
• Example fonts: “Handwriting”, “Tall Films Fine”, “Haunting Attraction”
• Default: “Arial Narrow 7”
• Lines 2 or 4 override font and size settings

Examples:

# Basic scrolling text (LED/LCD)
GET /text?t=Welcome%20to%20Pixelcade

# LED: Styled text with hex color
GET /text?t=Hello%20World&c=ff6d00

# LED: Multi-parameter example
GET /text?t=Game%20Playing%20Pacman&l=1&c=yellow&s=50

# LED: Multi-line with offset
GET /text?t=Player%201%20Score%20999,999&lines=2&c=green&yoffset=-2

# LED: Looping text (5 times)
curl "http://localhost:8080/text?t=Press%20Start&l=5&c=yellow"

# LED: Infinite loop (runs until next command)
curl "http://localhost:8080/text?t=INSERT%20COIN&loop=-1&c=cyan"

# LED: Fixed text (no scrolling, auto-sizes to fit)
curl "http://localhost:8080/text?t=GAME%20OVER&scroll=false&c=red"

# LED: Blinking text (500ms interval, runs until next command)
# Note: blink only works with 9 chars or less (non-scrolling text)
curl "http://localhost:8080/text?t=PLAYER%201&blink=500&c=green"

# LED: 2-line text (static, no scrolling)
curl "http://localhost:8080/text?t=HIGH%20SCORE%201000000&lines=2&c=yellow&scroll=false"

# LED: 4-line text (uses smallest font for more content)
curl "http://localhost:8080/text?t=P1%20999999%20P2%20888888&lines=4&c=orange"

# LED: Fixed 4-line text (combines scroll=false with lines=4)
curl "http://localhost:8080/text?t=GAME%20STATS%20HERE&scroll=false&lines=4&c=cyan"

# LED: 4-line left-justified text
curl "http://localhost:8080/text?t=PLAYER%201%20SCORE&lines=4&c=cyan&left=true"

# LED: Explicit line breaks using \n (centered, default)
curl "http://localhost:8080/text?t=LINE%201\nLINE%202\nLINE%203\nLINE%204&lines=4&c=green"

# LED: Explicit line breaks using \n (left-justified)
curl "http://localhost:8080/text?t=LINE%201\nLINE%202\nLINE%203\nLINE%204&lines=4&c=green&left=true"

# Color change commands
GET /text/color/green
GET /text/speed/50

LCD Text Behavior:

• Text scrolls continuously until next API call
• Advanced formatting not supported
• If LCDLEDCompliment=yes in settings.ini, adds &led parameter

Retro Achievements

RetroAchievements Integration

Display achievement notifications with custom animations.

Endpoint: GET /achievements/stream/{console}/{achievement_id}?t={text}&currentgame={rom}

Required Parameters:

• console – Console name
• achievement_id – RetroAchievements achievement ID
• ?t={text} – Achievement description text
• ?currentgame={rom} – Current game ROM name

Behavior:

1. If PNG/GIF matching achievement ID exists in <pixelcade folder>/achievements, plays that file
2. Shows achievement scrolling text for 1 loop
3. Displays game marquee matching console and rom name
4. If no achievement artwork: shows random animation (1 of 10), then text, then game marquee

Example:

# LED: RetroAchievement notification
GET /achievements/stream/coleco/177575?t="First Flight : Clear 3 rounds of Skill Level 1"&currentgame=zaxxon
curl "http://localhost:8080/achievements/stream/coleco/177575?t=\"First Flight : Clear 3 rounds of Skill Level 1\"&currentgame=zaxxon"

# LCD: Same via network
curl "http://pixelcadedx-f26967ec.local:8080/achievements/stream/coleco/177575?t=\"First Flight : Clear 3 rounds of Skill Level 1\"&currentgame=zaxxon"

# LCD: Same via USB
curl "http://169.254.100.1:8080/achievements/stream/coleco/177575?t=\"First Flight : Clear 3 rounds of Skill Level 1\"&currentgame=zaxxon"

Animation Overlays (LED Only)

Overlapping Animation Effects

Display animations that overlay/overlap with currently running animations instead of queuing.

Endpoint: GET /animation/overlay/{console}/{rom}

Parameters:

• console – Console/emulator name
• rom – ROM/game name (must have corresponding GIF animation)

Use Cases: This API is typically used for effects that occur back-to-back in rapid succession, such as:

• DOFLinx Integration: In-game explosions, gunfire, or impact effects
• Arcade Effects: Multiple simultaneous visual effects during gameplay
• Pinball Events: Overlapping table events that shouldn’t wait for previous animations

Behavior:

• Overlapping: Second request overlaps with first animation vs. waiting for completion
• GIF Only: Only works with GIF animations (ignores PNG files)
• No Queue: Bypasses the normal Queue System entirely
• Single Playback: Each animation plays once regardless of loop parameters
• LED Exclusive: Not available on LCD displays

How It Differs from Standard Animation APIs:

• Standard /arcade/stream: Animations queue sequentially, wait for previous to finish
• Overlay /animation/overlay: Animations overlay immediately, creating combined effects

Error Handling:

• Returns error if no GIF found for the specified console/rom combination
• Returns “Write in progress” error if device is busy with write operations
• Silently skips if running in LCD-only mode

News & Information Widgets

News Ticker

Display scrolling news from RSS feeds.

Start Ticker: GET /ticker?start
Stop Ticker: GET /ticker?stop

Optional Parameters:

• ?feed={urls} – Comma-separated RSS feed URLs
• ?c={color} – Font color (red, green, blue, yellow, white, cyan, magenta, orange)
• ?s={speed} – Scroll speed (integer, default: 7)
• ?newsTickerRefresh={minutes} – Refresh interval (30-14400 minutes, default: 60)

Default Feeds:

• https://news.yahoo.com/rss
• https://finance.yahoo.com/news/rssindex

Examples:

# Minimal start
GET /ticker?start
curl "http://localhost:8080/ticker?start"

# LCD: Start ticker via network
curl "http://pixelcadedx-f26967ec.local:8080/ticker?start"

# LCD: Start ticker via USB
curl "http://169.254.100.1:8080/ticker?start"

# Custom configuration
GET /ticker?start&feed=https://news.yahoo.com/rss,http://feeds.bbci.co.uk/news/world/rss.xml&c=blue&s=10&newsTickerRefresh=120
curl "http://localhost:8080/ticker?start&feed=https://news.yahoo.com/rss,http://feeds.bbci.co.uk/news/world/rss.xml&c=blue&s=10&newsTickerRefresh=120"

# Stop ticker
GET /ticker?stop
curl "http://localhost:8080/ticker?stop"

Weather Display

Endpoint: GET /weather?location={location}

Examples:

# LED: Weather by ZIP code
GET /weather?location=90210
curl "http://localhost:8080/weather?location=90210"

# LCD: Weather by city via network
curl "http://pixelcadedx-f26967ec.local:8080/weather?location=London,UK"

# LCD: Weather via USB
curl "http://169.254.100.1:8080/weather?location=New%20York"

Digital Clock

Endpoint: GET /clock

Parameters:

• ?12h={true/false} – 12-hour format
• ?showSeconds={true/false} – Display seconds
• ?showMilliseconds={true/false} – Display milliseconds
• ?timeSeparator={char} – Separator character
• ?timeFormat={24} – Time format
• ?color={color} – Clock color

Example:

# LED: Display 12-hour clock with seconds
GET /clock?12h=true&showSeconds=true&timeSeparator=:&color=blue
curl "http://localhost:8080/clock?12h=true&showSeconds=true&timeSeparator=:&color=blue"

# LCD: Same command via network
curl "http://pixelcadedx-f26967ec.local:8080/clock?12h=true&showSeconds=true&color=blue"

# LCD: Simple clock via USB
curl "http://169.254.100.1:8080/clock?color=green"

Spotify Now Playing Widget

Display currently playing Spotify track with album art on your Pixelcade. Requires Spotify Premium account and one-time OAuth authorization.

Start Widget: GET /spotify
Get Now Playing: GET /spotify/now-playing
Get Settings: GET /spotify/settings

Optional Parameters:

• ?nointerrupt – Run continuously until explicitly stopped
• ?showAlbumArt={true/false} – Display album art (default: true)

OAuth Setup Endpoints:

• GET /oauth/spotify/config – Get OAuth configuration status
• GET /oauth/spotify/status – Check if Spotify is connected
• GET /oauth/spotify/callback – OAuth callback handler
• GET /oauth/spotify/code?code={auth_code} – Submit authorization code
• GET /oauth/spotify/disconnect – Disconnect Spotify account

Easter Egg Effects:

Certain songs trigger special LED strip effects:

• Fire – Songs with “fire” in the title
• Halloween – “Thriller”, “Monster”, “Spooky”
• Christmas – “Jingle Bells”, “Silent Night”, Christmas songs
• Thunder – “Thunderstruck”, “Lightning”, “Electric”
• Party – Songs with “Party”, “Celebrate”, “Dance”
• Purple – “Purple Rain” or any song by Prince
• Rick Roll – “Never Gonna Give You Up”

Examples:

# Start Spotify widget
curl "http://localhost:8080/spotify"

# Start in nointerrupt mode (for screensaver)
curl "http://localhost:8080/spotify?nointerrupt"

# Get currently playing track info
curl "http://localhost:8080/spotify/now-playing"

# Check OAuth status
curl "http://localhost:8080/oauth/spotify/status"

# Disconnect Spotify
curl "http://localhost:8080/oauth/spotify/disconnect"

Now Playing Response:

{
  "playing": true,
  "track": "Bohemian Rhapsody",
  "artist": "Queen",
  "album": "A Night at the Opera",
  "year": "1975",
  "albumType": "album",
  "popularity": 89,
  "explicit": false,
  "albumArtURL": "https://i.scdn.co/image/..."
}

YouTube Stats Widget

Display YouTube channel statistics. Requires Google OAuth authorization.

Start Widget: GET /youtube
Get Stats: GET /youtube/stats

Optional Parameters:

• ?nointerrupt – Run continuously until explicitly stopped

OAuth Setup Endpoints:

• GET /oauth/youtube/config – Get OAuth configuration
• GET /oauth/youtube/status – Check connection status
• GET /oauth/youtube/callback – OAuth callback handler
• GET /oauth/youtube/disconnect – Disconnect YouTube account

Examples:

# Start YouTube stats widget
curl "http://localhost:8080/youtube"

# Get channel statistics
curl "http://localhost:8080/youtube/stats"

# Check OAuth status
curl "http://localhost:8080/oauth/youtube/status"

Google Calendar Widget

Display upcoming calendar events. Requires Google OAuth authorization.

Start Widget: GET /calendar
Get Settings: GET /calendar/settings

Optional Parameters:

• ?nointerrupt – Run continuously until explicitly stopped

OAuth Setup Endpoints:

• GET /oauth/calendar/config – Get OAuth configuration
• GET /oauth/calendar/status – Check connection status
• GET /oauth/calendar/disconnect – Disconnect Calendar

Examples:

# Start calendar widget
curl "http://localhost:8080/calendar"

# Check OAuth status
curl "http://localhost:8080/oauth/calendar/status"

Playlist API

Create and manage custom playlists of marquees and widgets. Playlists can include game marquees, console images, and information widgets that cycle automatically.

Playlist Control

Start Playlist: GET /playlist/start
Stop Playlist: GET /playlist/stop
Get Status: GET /playlist/status
Get Settings: GET /playlist/settings

Optional Parameters:

• ?nointerrupt – Lock playlist (attract mode), prevents interruption by other API calls
• ?interval={seconds} – Time between items (1, 3, 5, 10, 20, 30, 60, 300)
• ?includeAnimated={true/false} – Include animated GIFs

Examples:

# Start playlist
curl "http://localhost:8080/playlist/start"

# Start in attract mode (locked)
curl "http://localhost:8080/playlist/start?nointerrupt"

# Start with custom interval
curl "http://localhost:8080/playlist/start?interval=10"

# Stop playlist
curl "http://localhost:8080/playlist/stop"

# Get current status
curl "http://localhost:8080/playlist/status"

Playlist Item Management

Get Items: GET /playlist/items
Set Items: POST /playlist/items (JSON body)
Add Item: GET /playlist/item/add?type={type}&id={id}&duration={seconds}
Remove Item: GET /playlist/item/remove?index={index} or ?type={type}&id={id}
Update Duration: GET /playlist/item/duration?index={index}&duration={seconds}

Item Types:

• marquee – Game or console marquee (id format: “system-game”, e.g., “mame-pacman”)
• widget – Information widget (id: “clock”, “weather”, “sports”, “stocks”, “news”, “spotify”, “youtube”, “calendar”)

Examples:

# Add a marquee to playlist
curl "http://localhost:8080/playlist/item/add?type=marquee&id=mame-pacman&duration=10"

# Add a widget to playlist
curl "http://localhost:8080/playlist/item/add?type=widget&id=clock&duration=60"

# Add Spotify widget
curl "http://localhost:8080/playlist/item/add?type=widget&id=spotify&duration=120"

# Remove item by index
curl "http://localhost:8080/playlist/item/remove?index=0"

# Remove item by type and id
curl "http://localhost:8080/playlist/item/remove?type=marquee&id=mame-pacman"

# Update item duration
curl "http://localhost:8080/playlist/item/duration?index=0&duration=30"

# Get all items
curl "http://localhost:8080/playlist/items"

Get Items Response:

{
  "items": [
    {"type": "marquee", "id": "mame-pacman", "duration": 10},
    {"type": "widget", "id": "clock", "duration": 60},
    {"type": "marquee", "id": "nes-mario", "duration": 10}
  ],
  "itemsEnriched": [
    {
      "index": 0,
      "type": "marquee",
      "id": "mame-pacman",
      "duration": 10,
      "system": "mame",
      "game": "pacman",
      "displayName": "pacman",
      "thumbnailPath": "/thumbnail/mame-pacman.jpg"
    }
  ],
  "count": 3,
  "defaultInterval": 5
}

Playlist Favorites

Add Favorite: GET /playlist/favorite/add?marquee={system-game}
Remove Favorite: GET /playlist/favorite/remove?marquee={system-game}
Check Favorite: GET /playlist/isfavorite?marquee={system-game}

Examples:

# Add to favorites
curl "http://localhost:8080/playlist/favorite/add?marquee=mame-pacman"

# Remove from favorites
curl "http://localhost:8080/playlist/favorite/remove?marquee=mame-pacman"

# Check if favorite
curl "http://localhost:8080/playlist/isfavorite?marquee=mame-pacman"

Available Widgets

Endpoint: GET /playlist/widgets

Get list of available widget types for playlist.

Response:

{
  "widgets": [
    {"id": "sports", "name": "Sports Ticker", "icon": "sports", "defaultDuration": 60},
    {"id": "stocks", "name": "Stocks Ticker", "icon": "trending_up", "defaultDuration": 60},
    {"id": "weather", "name": "Weather Widget", "icon": "cloud", "defaultDuration": 60},
    {"id": "news", "name": "News Ticker", "icon": "article", "defaultDuration": 60},
    {"id": "clock", "name": "Clock Widget", "icon": "schedule", "defaultDuration": 60},
    {"id": "spotify", "name": "Spotify Now Playing", "icon": "music_note", "defaultDuration": 60},
    {"id": "youtube", "name": "YouTube Stats", "icon": "smart_display", "defaultDuration": 60},
    {"id": "calendar", "name": "Calendar", "icon": "calendar_today", "defaultDuration": 60}
  ]
}

Screen Saver & Widget Integration

Integrate Pixelcade widgets and attract mode with your arcade frontend’s screen saver mode. These endpoints display information widgets that run continuously until explicitly stopped.

Widget Endpoints for Screen Saver Mode

Use these endpoints when your frontend enters screen saver mode. The ?nointerrupt parameter ensures the widget continues running until explicitly stopped.

Available Widget Endpoints:

Clock Types

The clock widget supports themed arcade clocks. Use the clockType parameter to select a theme:

• pacman – Pac-Man themed clock
• mspacman – Ms. Pac-Man themed clock
• galaga – Galaga themed clock
• arkanoid – Arkanoid themed clock
• tron – Tron themed clock
• burgertime – Burger Time themed clock
• dkong – Donkey Kong themed clock
• invaders – Space Invaders themed clock
• centipede – Centipede themed clock
• asteroids – Asteroids themed clock
• digdug – Dig Dug themed clock
• frogger – Frogger themed clock
• tetris – Tetris themed clock
• tempest – Atari Tempest vector style
• retro – Generic 80s neon arcade style
• sf2 – Street Fighter II themed clock
• metroid – Metroid themed clock
• castlevania – Castlevania themed clock
• puzzlebobble – Puzzle Bobble / Bust-a-Move themed clock

Clock Examples:

# Standard digital clock
curl "http://localhost:8080/clock?nointerrupt"

# Pac-Man themed clock
curl "http://localhost:8080/clock?nointerrupt&clockType=pacman"

# Galaga themed clock
curl "http://localhost:8080/clock?nointerrupt&clockType=galaga"

# Tron themed clock
curl "http://localhost:8080/clock?nointerrupt&clockType=tron"

Stop Widgets & Pixelcade Attract Mode (Exit Screen Saver)

Endpoint: GET /attract/stop

Call this endpoint when your frontend exits screen saver mode to stop all running widgets (including attract mode) and return Pixelcade to normal arcade marquee mode.

Example:

# Stop all widgets and attract mode, return to arcade mode
curl http://localhost:8080/attract/stop

Frontend Integration Example

# When screen saver starts - display Pac-Man clock
curl "http://localhost:8080/clock?nointerrupt&clockType=pacman"

# Or start attract mode with user playlist
curl "http://localhost:8080/attract?nointerrupt"

# Or display Spotify now playing
curl "http://localhost:8080/spotify?nointerrupt"

# Or display Plex now playing
curl "http://localhost:8080/plex?nointerrupt"

# Or display traffic dashboard
curl "http://localhost:8080/commute?nointerrupt"

# Or display daily horoscope
curl "http://localhost:8080/horoscope?nointerrupt"

# Or display world clock
curl "http://localhost:8080/worldclock?nointerrupt"

# When user exits screen saver - stop all widgets and resume normal operation
curl "http://localhost:8080/widgets/stop"

# Then display the current game marquee
curl "http://localhost:8080/arcade/stream/mame/pacman"

Integration Notes:

• Call the widget endpoint when your frontend enters screen saver/attract mode
• Call /widgets/stop when the user exits screen saver mode – this stops all running widgets including attract mode
• After stopping widgets, send your next marquee command to resume normal operation
• The /attract and /playlist endpoints are interchangeable – both work identically
• Configure default settings (favorite teams, stocks, clock type, etc.) using the Pixelcade Companion apps at pixelcade.org/apps
• OAuth Required: Some widgets require one-time OAuth authorization via the Companion app: Spotify, Plex, Last.fm, YouTube, Google Calendar, Google Photos, Google Tasks, and Yahoo Fantasy
• API Key Required: The Traffic/Commute widget requires a Google Maps API key configured in the Companion app

Sports Scores

Sports Ticker

Endpoint: GET /sports/{league}?teams={team-codes}

Supported Leagues:

• nfl, nba, nhl, mlb, wnba
• eng.1 (Premier League), esp.1 (La Liga), ger.1 (Bundesliga)
• ita.1 (Serie A), fra.1 (Ligue 1), por.1 (Primeira Liga)
• ned.1 (Eredivisie), mex.1 (Liga MX), usa.1 (MLS)
• uefa.champions (Champions League)
• college-football, mens-college-basketball, womens-college-basketball, college-baseball

Complete Team Code Reference

NFL Teams

WSH - Washington Commanders    ARI - Arizona Cardinals       ATL - Atlanta Falcons
BAL - Baltimore Ravens         BUF - Buffalo Bills           CAR - Carolina Panthers
CHI - Chicago Bears           CIN - Cincinnati Bengals      CLE - Cleveland Browns
DAL - Dallas Cowboys          DEN - Denver Broncos          DET - Detroit Lions
GB  - Green Bay Packers       HOU - Houston Texans          IND - Indianapolis Colts
JAX - Jacksonville Jaguars    KC  - Kansas City Chiefs      LAC - Los Angeles Chargers
LAR - Los Angeles Rams        LV  - Las Vegas Raiders       MIA - Miami Dolphins
MIN - Minnesota Vikings       NE  - New England Patriots    NO  - New Orleans Saints
NYG - New York Giants         NYJ - New York Jets           PHI - Philadelphia Eagles
PIT - Pittsburgh Steelers     SEA - Seattle Seahawks        SF  - San Francisco 49ers
TB  - Tampa Bay Buccaneers    TEN - Tennessee Titans

NBA Teams

WSH - Washington Wizards      ATL - Atlanta Hawks           BKN - Brooklyn Nets
BOS - Boston Celtics          CHA - Charlotte Hornets       CHI - Chicago Bulls
CLE - Cleveland Cavaliers     DAL - Dallas Mavericks        DEN - Denver Nuggets
DET - Detroit Pistons         GS  - Golden State Warriors   HOU - Houston Rockets
IND - Indiana Pacers          LAC - Los Angeles Clippers    LAL - Los Angeles Lakers
MEM - Memphis Grizzlies       MIA - Miami Heat              MIL - Milwaukee Bucks
MIN - Minnesota Timberwolves  NO  - New Orleans Pelicans    NY  - New York Knicks
OKC - Oklahoma City Thunder   ORL - Orlando Magic           PHI - Philadelphia 76ers
PHX - Phoenix Suns           POR - Portland Trail Blazers   SA  - San Antonio Spurs
SAC - Sacramento Kings        TOR - Toronto Raptors         UTAH- Utah Jazz

NHL Teams

WSH - Washington Capitals     ANA - Anaheim Ducks           ARI - Arizona Coyotes
BOS - Boston Bruins          BUF - Buffalo Sabres          CAR - Carolina Hurricanes
CBJ - Columbus Blue Jackets  CGY - Calgary Flames          CHI - Chicago Blackhawks
COL - Colorado Avalanche     DAL - Dallas Stars            DET - Detroit Red Wings
EDM - Edmonton Oilers        FLA - Florida Panthers        LA  - Los Angeles Kings
MIN - Minnesota Wild         MTL - Montreal Canadiens      NJ  - New Jersey Devils
NSH - Nashville Predators    NYI - New York Islanders      NYR - New York Rangers
OTT - Ottawa Senators        PHI - Philadelphia Flyers     PIT - Pittsburgh Penguins
SEA - Seattle Kraken         SJ  - San Jose Sharks         STL - St. Louis Blues
TB  - Tampa Bay Lightning    TOR - Toronto Maple Leafs     VAN - Vancouver Canucks
VGK - Vegas Golden Knights   WPG - Winnipeg Jets

MLB Teams

ARI - Arizona Diamondbacks   ATL - Atlanta Braves          BAL - Baltimore Orioles
BOS - Boston Red Sox         CHC - Chicago Cubs            CHW - Chicago White Sox
CIN - Cincinnati Reds        CLE - Cleveland Guardians     COL - Colorado Rockies
DET - Detroit Tigers         HOU - Houston Astros          KC  - Kansas City Royals
LAA - Los Angeles Angels     LAD - Los Angeles Dodgers     MIA - Miami Marlins
MIL - Milwaukee Brewers      MIN - Minnesota Twins         NYM - New York Mets
NYY - New York Yankees       OAK - Oakland Athletics       PHI - Philadelphia Phillies
PIT - Pittsburgh Pirates     SD  - San Diego Padres        SEA - Seattle Mariners
SF  - San Francisco Giants   STL - St. Louis Cardinals     TB  - Tampa Bay Rays
TEX - Texas Rangers          TOR - Toronto Blue Jays       WSH - Washington Nationals

WNBA Teams

ATL - Atlanta Dream          CHI - Chicago Sky             CONN- Connecticut Sun
DAL - Dallas Wings          IND - Indiana Fever           LA  - Los Angeles Sparks
LV  - Las Vegas Aces        MIN - Minnesota Lynx          NY  - New York Liberty
PHX - Phoenix Mercury       SEA - Seattle Storm           WSH - Washington Mystics

English Premier League

ARS - Arsenal               AVL - Aston Villa             BRE - Brentford
BOU - AFC Bournemouth       BHA - Brighton & Hove Albion  BUR - Burnley
CHE - Chelsea               CRY - Crystal Palace          EVE - Everton
FUL - Fulham               LIV - Liverpool               LUT - Luton Town
MCI - Manchester City       MUN - Manchester United       NEW - Newcastle United
NFO - Nottingham Forest     SHU - Sheffield United        TOT - Tottenham Hotspur
WHU - West Ham United       WOL - Wolverhampton Wanderers

German Bundesliga

FCA - FC Augsburg          FCU - FC Union Berlin         BOC - VfL Bochum
SVW - SV Werder Bremen     BVB - Borussia Dortmund      SGE - Eintracht Frankfurt
SCF - SC Freiburg          HEI - FC Heidenheim           TSG - TSG 1899 Hoffenheim
KIE - Holstein Kiel        RBL - RB Leipzig              B04 - Bayer 04 Leverkusen
M05 - FSV Mainz 05         BMG - Borussia Mönchengladbach FCB - FC Bayern München
STP - FC St. Pauli        VFB - VfB Stuttgart           WOB - VfL Wolfsburg

French Ligue 1

SCO - Angers SCO           AJA - AJ Auxerre              BRE - Stade Brestois 29
HAC - Le Havre AC          LIL - Lille OSC              ASM - AS Monaco
MON - Montpellier HSC      NAN - FC Nantes              NICE- OGC Nice
OL  - Olympique Lyonnais   OM  - Olympique de Marseille  PSG - Paris Saint-Germain
RCL - RC Lens              SR  - Stade de Reims          REN - Stade Rennais FC
ASSE- AS Saint-Étienne     STR - RC Strasbourg Alsace    TFC - Toulouse FC

Spanish La Liga

ALM - Almería              ATM - Atlético Madrid         BAR - Barcelona
BET - Real Betis           CAD - Cádiz                   CEL - Celta Vigo
EIB - Eibar               ELC - Elche                   GET - Getafe
GRN - Granada             LEV - Levante                 LUG - Lugo
MAL - Málaga              RAK - Rayo Vallecano          REAL- Real Madrid
RSO - Real Sociedad       VLL - Valladolid              VAL - Valencia

Italian Serie A

ATA - Atalanta             BOL - Bologna                 CAG - Cagliari
EMP - Empoli              FIO - Fiorentina              GEN - Genoa
INTER - Inter Milan        JUVE- Juventus                LAZ - Lazio
LEC - Lecce               MIL - Milan                   MON - Monza
NAP - Napoli              ROM - Roma                    SAMP- Sampdoria
SPE - Spezia              TOR - Torino                  UDI - Udinese

Portuguese Primeira Liga

ABA - Abissola            BEN - Benfica                 BOL - Belenenses SAD
FAM - Famalicão           MAR - Marítimo                NAC - Nacional
POR - Portimonense        PRA - Praiense                RIO - Rio Ave
SCP - Sporting CP         TON - Tondela                 VIT - Vitória de Guimarães
BRG - Braga               VSC - Vitória SC              PFC - Paços de Ferreira

Dutch Eredivisie

ADO - ADO Den Haag        AZ  - AZ Alkmaar              BAS - FC Basel
DEN - FC Den Bosch        FCO - FC Utrecht              FYN - Feyenoord
HEE - FC Heerenveen       HER - Heracles Almelo         PEC - PEC Zwolle
PSV - PSV Eindhoven       RKC - RKC Waalwijk            SPE - Sparta Rotterdam
VIT - Vitesse             WIL - Willem II               GRON- FC Groningen

Mexican Liga MX

AMERICA - Club América    ATLAS - Atlas FC              CHIVAS - Chivas Guadalajara
CRUZAZUL - Cruz Azul      FCJUAREZ - FC Juárez          PACHUCA - Club Pachuca
PUMAS - UNAM Pumas        TIGRES - Tigres UANL          TOLUCA - Deportivo Toluca
SANTOS - Santos Laguna    LEON - Club León              MORELIA - Monarcas Morelia
PUEBLA - Club Puebla      XALAPA - Veracruz             QUERETARO - Querétaro

Major League Soccer (USA)

ATL - Atlanta United FC   CHI - Chicago Fire FC        CLT - Charlotte FC
COL - Colorado Rapids     DC  - D.C. United            FCB - FC Cincinnati
LAFC- Los Angeles FC      LAG - LA Galaxy               MIA - Inter Miami CF
MIN - Minnesota United FC MTL - CF Montréal             NE  - New England Revolution
NYC - New York City FC    NYRB- New York Red Bulls      ORL - Orlando City SC
PHI - Philadelphia Union  PORT- Portland Timbers        RSL - Real Salt Lake
SJ  - San Jose Earthquakes SEA - Seattle Sounders FC    SKC - Sporting Kansas City
TOR - Toronto FC          VAN - Vancouver Whitecaps FC

UEFA Champions League

ARS - Arsenal             ATLETI - Atlético Madrid      BAR - Barcelona
BAY - Bayern Munich       BVB - Borussia Dortmund      BENE- Benfica
BRUGGE - Club Brugge      CHE - Chelsea                 DORTMUND - Borussia Dortmund
INTER - Inter Milan       JUVE- Juventus                LIVERPOOL - Liverpool
MANC- Manchester City     PSG - Paris Saint-Germain    REAL- Real Madrid
NAPOLI - Napoli          ROMA- AS Roma

Examples:

# All NFL scores
GET /sports/nfl
curl "http://localhost:8080/sports/nfl"

# Specific teams
GET /sports/nfl?teams=KC,GB,SF
curl "http://localhost:8080/sports/nfl?teams=KC,GB,SF"

# LCD: NBA scores via network
curl "http://pixelcadedx-f26967ec.local:8080/sports/nba?teams=LAL,BOS,MIA"

# LCD: Premier League via USB
curl "http://169.254.100.1:8080/sports/eng.1?teams=ARS,CHE,LIV"

Financial Data

Stock & Crypto Ticker

Endpoint: GET /stocks

Parameters:

• ?tickers={symbols} – Comma-separated ticker symbols (default: “AAPL,GOOG,MSFT”)
• ?c={color} – Display color
• ?s={speed} – Scroll speed (default: 10)

Examples:

# Default stocks
GET /stocks
curl "http://localhost:8080/stocks"

# Custom stocks with color
GET /stocks?tickers=AAPL,GOOG,MSFT&c=blue&s=10
curl "http://localhost:8080/stocks?tickers=AAPL,GOOG,MSFT&c=blue&s=10"

# LCD: Crypto via network
curl "http://pixelcadedx-f26967ec.local:8080/stocks?tickers=BTC-USD,ETH-USD,ADA-USD&c=orange"

# LCD: Stocks via USB
curl "http://169.254.100.1:8080/stocks?tickers=TSLA,NVDA&c=green"

Statistics & Game Data

In-Game Statistics Display

Endpoint: GET /stats

Parameters:

• ?label={text}&value={number} – Primary stat (required)
• ?livesLabel={text}&livesValue={number} – Lives display
• ?shots={number} – Shot count
• ?hits={number} – Hit count
• ?ratio={number} – Hit ratio percentage
• ?separator={style} – Column separator (solid, dashed, doubledot)

Examples:

# LED: Display stage information
GET /stats?label=STAGE&value=2
curl "http://localhost:8080/stats?label=STAGE&value=2"

# LED: Full statistics with all parameters
GET /stats?label=STAGE&value=2&shots=99&hits=44&ratio=20&separator=solid
curl "http://localhost:8080/stats?label=STAGE&value=2&shots=99&hits=44&ratio=20&separator=solid"

# LED: Lives/ships display
curl "http://localhost:8080/stats?livesLabel=Ships&livesValue=5&shots=99&hits=44&ratio=20&separator=solid"

# LCD: Same commands work (via network)
curl "http://pixelcadedx-f26967ec.local:8080/stats?label=STAGE&value=3"

# LCD: Via USB connection
curl "http://169.254.100.1:8080/stats?livesLabel=Lives&livesValue=3"

Custom Content & Media

Animation Library

Endpoints:

• GET /animations/stream/{filename} – Stream specific animation
• GET /animations/stream/{filename}?r – Random animation
• GET /animations/list – List available animations

Examples:

# LED: Stream specific animation
GET /animations/stream/0rain
curl http://localhost:8080/animations/stream/0rain

# LED: Loop animation 3 times (uses Queue System)
GET /animations/stream/0rain?l=3
curl "http://localhost:8080/animations/stream/0rain?l=3"

# LED: Random animation
curl "http://localhost:8080/animations/stream/explosion?r"

# LED: List all animations
curl http://localhost:8080/animations/list

# LCD: Stream animation via network (no loops)
curl http://pixelcadedx-f26967ec.local:8080/animations/stream/0rain

# LCD: Stream animation via USB
curl http://169.254.100.1:8080/animations/stream/0rain

Still Images & Lists

Endpoints:

• GET /still/list – List single frame images
• GET /arcade/list – List MAME game names
• GET /currentgame – Get last selected game (format: console%game-name)

Examples:

# LED: List still images
curl http://localhost:8080/still/list

# LED: List MAME games
curl http://localhost:8080/arcade/list

# LED: Get current game
curl http://localhost:8080/currentgame

# LCD: Same commands via network
curl http://pixelcadedx-f26967ec.local:8080/still/list
curl http://pixelcadedx-f26967ec.local:8080/currentgame

# LCD: Same commands via USB
curl http://169.254.100.1:8080/arcade/list

File Upload (Using curl/libcurl)

# Upload PNG to images folder
curl -i -X POST -H "Content-Type: multipart/form-data" \
  -F "upload=@/Users/al/artwork/galaga.png" \
  -F "upload-type=STILL_IMAGE" \
  http://localhost:8080/upload

# Upload GIF to animations folder
curl -i -X POST -H "Content-Type: multipart/form-data" \
  -F "upload=@/Users/artwork/pacman.gif" \
  -F "upload-type=ANIMATED_GIF" \
  http://localhost:8080/upload

# Upload to specific console without displaying
curl -i -X POST -H "Content-Type: multipart/form-data" \
  -F "upload=@/Users/al/artwork/pacman.PNG" \
  -F "upload-type=STILL_IMAGE" \
  -F "console=alu" \
  -F "displaynow=0" \
  http://localhost:8080/uploadplatform

# Upload to MAME and display immediately
curl -i -X POST -H "Content-Type: multipart/form-data" \
  -F "upload=@/Users/al/artwork/pacman.gif" \
  -F "upload-type=ANIMATED_GIF" \
  -F "console=MAME" \
  -F "displaynow=1" \
  http://localhost:8080/uploadplatform

System Management

Device Control

System Commands:

• GET /quit – Shutdown Pixelcade listener
• GET /reboot – Reboot OS (Pi/LCD only)
• GET /shutdown – Shutdown OS (Pi/LCD only)
• GET /localplayback – Local playback mode (LED only)
• GET /arcade/stream/black/dummy – Blank display

Examples:

# LED: Shutdown listener
curl http://localhost:8080/quit

# LED: Blank display
curl http://localhost:8080/arcade/stream/black/dummy

# LCD: Reboot via network
curl http://pixelcadedx-f26967ec.local:8080/reboot

# LCD: Shutdown via USB
curl http://169.254.100.1:8080/shutdown

Device Information

Endpoint: GET /info

Returns JSON with:

{
  "name": "My Pixelcade LED",
  "type": "LED",
  "hostname": "almacbook.lan",
  "ipAddress": "192.168.87.21",
  "firmwareVersion": "PDXR0023",
  "hardwareID": "PIXL0020",
  "v2board": true,
  "bootLoaderID": "SUBV0002",
  "firmwareSubVersion": "SUBV0002",
  "softwareVersion": "6.5.9",
  "resolution": "128x32",
  "pixelcadeRoot": "/Users/al/Documents/code/pixelcadeusbtools/pixelweb/dist",
  "bindAddr": "0.0.0.0",
  "bindPort": 8080,
  "defaultFont": "/Users/al/Documents/code/pixelcadeusbtools/pixelweb/dist/fonts/Arial Narrow 7.ttf",
  "defaultFontColor": "ff0000",
  "defaultFontColorRandom": true,
  "defaultFontSize": 28,
  "devicePath": "auto",
  "deviceScan": false,
  "fuzzyMatching": true,
  "pngFuzzyDistanceThreshold": 10,
  "pngFuzzyMaxMatchesThreshold": 40,
  "noIntro": false,
  "startupImage": "mame/pixelcade.png",
  "startupMode": false,
  "startupText": "Welcome to Pixelcade",
  "systemImage": "",
  "debugLogging": false,
  "traceLogging": false,
  "noLogging": false,
  "colorLogging": true,
  "initDelay": 0,
  "demoMode": false,
  "noMdns": false,
  "lcdMarquee": true,
  "lcdMarqueeHostName": "",
  "lcdMarqueeIPAddress": "",
  "lcdLEDCompliment": true,
  "lcdSearchStartUpDelay": 0,
  "lcdMultiple": false,
  "lcdUsbConnected": true,
  "lcdOnly": false,
  "lcdUsbIPAddress": "169.254.100.1",
  "lcdFirmwareVersion": "6.3.0.0",
  " ": true,
  "hasLEDStripSupport": true,
  "ledStrip": true,
  "ledStripBrightness": 12,
  "ledStripNumPixels": 762,
  "sevenSegment": true,
  "sevenSegmentNumModules": 8,
  "dotMatrix": true,
  "dotMatrixNumModules": 8,
  "miniLCD": true,
  "miniLCDType": 3,
  "scoreDisplay": "dotMatrix",
  "textDisplay": "pixelcadeled",
  "ledStripOffUponGameStart": false,
  "batchMode": true
}

Key Information Fields:

• Hardware: type, firmwareVersion, hardwareID, v2board, resolution
• Network: hostname, ipAddress, bindAddr, bindPort
• Display Capabilities: ledActive, hasLEDStripSupport, sevenSegment, dotMatrix, miniLCD
• LCD Integration: lcdMarquee, lcdUsbConnected, lcdUsbIPAddress, lcdLEDCompliment
• Settings: fuzzyMatching, defaultFont, defaultFontColor, debugLogging
• LED Strip: ledStrip, ledStripBrightness, ledStripNumPixels
• Sub-Displays: sevenSegmentNumModules, dotMatrixNumModules, scoreDisplay, textDisplay

Examples:

# LED: Get device information
GET /info
curl http://localhost:8080/info

# Using IP address
curl http://192.168.1.206:8080/info

# Using hostname
curl http://pixelcade.local:8080/info

Settings Configuration

Endpoint: GET /settings?key={setting}&value={value}

Valid Settings:

• fuzzyMatching, debugLogging, traceLogging, noLogging, colorLogging
• defaultFontColorRandom, noIntro, demoMode, noMdns, deviceScan, displayName

Response Examples:

{"key": "fuzzyMatching", "value": "false"}
{"key": "error", "value": "wrongKeyName is not a valid setting key"}

Software Updates

• GET /update/artwork – Download latest LED artwork
• GET /update/doflinx – Download latest DOFLinx MAME definitions

LCD Only API Reference

Device Information

Get LCD Specifications

Endpoint: GET /v2/info/

Example:

# LCD: Get device info via network
GET http://pixelcadedx-xxxxxxxx.local:8080/v2/info
curl http://pixelcadedx-xxxxxxxx.local:8080/v2/info

# LCD: Get device info via USB
curl http://169.254.100.1:8080/v2/info

Response:

{
  "name": "Tricks 'n Lies",
  "hostname": "pixelcadedx-xxxxxxxx", 
  "firmwareVersion": "2.9.0.9",
  "resolution": {
    "width": 1920,
    "height": 360
  },
  "isPaired": false,
  "hasJoinedNetwork": true
}

Device Pairing

Check Pairing Status

Endpoint: GET /v2/utility/pairing/

Response:

{
  "succeeded": true,
  "message": "paired"
}

Set Pairing State

Endpoints:

• GET /v2/utility/pairing/set/on – Set to paired
• GET /v2/utility/pairing/set/off – Set to unpaired

Example:

# LCD: Set to paired via network
GET http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/pairing/set/on
curl http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/pairing/set/on

# LCD: Set to paired via USB
curl http://169.254.100.1:8080/v2/utility/pairing/set/on

# LCD: Check pairing status
curl http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/pairing/

Response:

{
  "succeeded": true,
  "message": "Device now set to Paired"
}

Marquee Management

Set Default Marquee

Endpoint: GET /v2/utility/marquee/set/{1|2|3}

Example:

GET http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/marquee/set/2

Response:

{
  "succeeded": true,
  "message": "New Default Set@2"
}

Marquee Thumbnails

Endpoint: GET /v2/thumbnails/{system}/{marquee}

Returns 640px wide thumbnail JPEG of requested marquee.

Example:

GET http://pixelcadedx-xxxxxxxx.local:8080/v2/thumbnails/mame/deathsml

Marquee Editing

Display Temporary Marquee

Endpoint: POST /v2/marquees/{system}/{marquee}/display

Content-Type: image/jpg (required)

Example:

curl -X POST -H "Content-Type: image/jpg" \
  "http://pixelcadedx-f26967ec.local:8080/v2/marquees/mame/blazstar/display" \
  --data-binary "@blazstar.jpg"

Save Marquee Permanently

Endpoint: POST /v2/marquees/{system}/{marquee}/save

Undo Marquee Changes

Endpoint: POST /v2/marquees/{system}/{marquee}/undo

One level of undo available to revert recent changes.

Dot Sub-Display Scores (LCD with Dot Display)

Send Score to Dot Display

Endpoint: GET /score?s={score}

Behavior:

• Displays on Pixelcade Dot sub-displays only
• Supports matrix or 7-segment displays
• Score won’t scroll if under 8 characters (matrix can display 4)
• Text can also be sent in addition to numbers
• Not all characters render on 7-segment displays

Example:

# LCD: Send score via network
GET http://pixelcadedx-xxxxxxxx.local:8080/score?s=1000
curl "http://pixelcadedx-xxxxxxxx.local:8080/score?s=1000"

# LCD: Send score via USB
curl "http://169.254.100.1:8080/score?s=1000"

# LCD: Send high score
curl "http://pixelcadedx-xxxxxxxx.local:8080/score?s=999999"

Attract Mode (Timeline Playback)

Get Current Timeline

Endpoint: GET /v2/utility/attractmode/timeline/

Response:

{
  "isPlaying": false,
  "media": [
    {
      "marqueeName": "pacman",
      "delay": false,
      "playVideo": true,
      "playGIFs": false
    },
    {
      "marqueeName": "blazstar", 
      "delay": true,
      "playVideo": true,
      "playGIFs": false
    }
  ]
}

Set Timeline

Endpoint: POST /v2/utility/attractmode/timeline/

Content-Type: application/json

Example:

curl -X POST -H 'content-type: application/json' \
  http://pixelcadedx-xxxxxxxx.local:8080/v2/utility/attractmode/timeline/ \
  -d @timeline.json

Control Timeline Playback

Start: GET /v2/utility/attractmode/timeline/play/
Stop: GET /v2/utility/attractmode/timeline/stop/

Marquee Lists & Content

List Marquees by System

Endpoint: GET /list/image/{system}

Example:

GET http://pixelcadedx-xxxxxxxx.local:8080/list/image/mame

Response:

{
  "system": "atari2600",
  "count": 693,
  "files": [
    "atari2600-Return to Haunted House (USA).jpg",
    "atari2600-Pac-Man (Atari) (USA).jpg",
    "atari2600-Combat (USA).jpg"
  ]
}

List All Content

Endpoints:

• GET /list/image/all – All image marquees across systems
• GET /list/video – All video marquees across systems

LCD Settings Configuration

LCD-Specific Settings

Endpoint: GET /settings?key={setting}&value={value}

LCD Settings:

• marqueeOverlays=yes/no – Enable/disable marquee overlays
• SubDisplayScrollingOnly=yes/no – Text only on dot displays vs LCD
• ImageMarqueesOnly=yes/no – Disable/enable video snaps
• UseConsoleMapping=yes/no – Server-side vs local console mapping
• SetSubDisplayNumModules=4/8 – Dot display module count
• PixelcadeDotType=matrix/7segment – Dot display type
• DisplayName={name} – Set LCD display name
• textColor={color} – Scrolling text color
• font={fontname} – Set font

Available Fonts: “Orbitron-SemiBold”, “Orbitron-Regular”, “Eight-Bit-Madness”, “Arial Narrow 7”, “Benegraphic”, “Candy Stripe (BRK)”, “Casio FX-702P”, “Daddy Longlegs NF”, “Decoder”, “DIG DUG”, “dotty”, “DPComic”, “Early GameBoy”, “Fiddums Family”, “Ghastly Panic”, “GilbertC”, “Gnuolane”, “Grapevine”, “Grinched”, “Handwriting”, “Harry P”, “Haunting Attraction”, “Minimal4”, “Morris Roman”, “MostlyMono”, “Neon 80s”, “Nintendo DS BIOS”, “Not So Stout Deco”, “Paulistana Deco”, “Pixelated”, “Pixeled”, “RetroBoundmini”, “RM Typerighter medium”, “Samba Is Dead”, “Shlop”, “Space Patrol NF”, “Star Jedi Hollow”, “Star Jedi”, “Still Time”, “Tall Films Fine”, “taller”, “techno overload (BRK)”, “TR2N”, “TRON”, “Vectroid”, “Videophreak”

Text Colors: “random”, “red”, “cyan”, “darkgray”, “lightgray”, “orange”, “yellow”, “blue”, “gray”, “green”, “magenta”, “pink”, “white”

Examples:

# Enable marquee overlays
GET http://pixelcadedx-xxxxxxxx.local:8080/settings?key=marqueeOverlays&value=yes

# Set font
GET http://pixelcadedx-xxxxxxxx.local:8080/settings?key=font&value=Neon%2080s

# Set dot display type
GET http://pixelcadedx-c59b51ea:8080/settings?key=PixelcadeDotType&value=7segment

# Get all settings
GET http://pixelcadedx-xxxxxxxx.local:8080/settings?key=getSettings

Settings Response:

{
  "font": "Neon 80s",
  "SubDisplayScrollingOnly": false,
  "ImageMarqueesOnly": false, 
  "SubDisplayNumModules": "8",
  "FontColor": "751d7d",
  "consoleMapping": false,
  "marqueeOverlays": true
}

Effects

Procedural Animation Effects

Trigger real-time procedural animation effects rendered directly to the LCD framebuffer. Effects are generated programmatically — no artwork files required.

Endpoint: GET /animation/overlay/mameoutput/{effect}

Query Parameters:

• ?loop=N or ?loops=N or ?l=N — Play N complete cycles (default: 1). Use 0 to loop indefinitely until interrupted by a subsequent request.

Overlap Behavior:

If a second effect request arrives while a first is still playing, both animations render concurrently on the framebuffer for a brief overlap window (~200ms), then the first fades out and the second continues. This is designed for rapid back-to-back game events such as explosions or score notifications.

Examples:

# Play a single explosion effect
curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/explosion"

# Loop an effect 3 times
curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/levelup?loop=3"

# Loop indefinitely (until next request)
curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/achievement?l=0"

# Trigger two explosions in rapid succession (they will overlap visually)
curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/explosion" &
sleep 0.1 && curl "http://pixelcadedx-xxxxxxxx.local:8080/animation/overlay/mameoutput/explosion3"

Available Effects

Explosions — Generic Numbered

Explosions — Extended Duration

Explosions — Color & Shape Variants

Player Start

Coins

Level Up

Achievements

Pac-Man

Galaga

1942 / 1943

Space Shooters

Classic Arcade

Donkey Kong

Gorf

Arkanoid

Burger Time

Tetris

Aliens

Defender

Altered Beast

System Updates

Update LCD System

Endpoint: GET /update

Initiates system update checking for new artwork and firmware from private GitHub repository.

Example:

GET http://pixelcadedx-xxxxxxxx.local/update

Pulse API Reference

Complete WS2812B LED Strip, MAX7219, and Mini LCD API Reference for Pixelcade V2 hardware with firmware 23+.


WS2812B APIs


LED Strip Effects

Start Effect

Endpoint: GET /ledstrip/zone/zone-id/effect/{effect}?[parameters]

Start a LED strip effect with optional parameters. zone-id can be a number starting with 0 or can be a name

Common Parameters:

• r, g, b – Primary color (0-255)
• r2, g2, b2 – Secondary color (0-255)
• speed – Effect speed (1-255)
• loops – Number of loops (0=infinite)
• intensity – Brightness (0-255)
• reverse – Reverse direction (true/false)
• duration – Duration in seconds

Supported Zones Names:

• left_strip
• right_strip
• left_speaker_ring
• right_speaker_ring
• center_matrix
• left_matrix
• right_matrix

Examples:

curl "localhost:8080/ledstrip/zone/left_strip/effect/rainbow?speed=100&intensity=200"
curl "localhost:8080/ledstrip/zone/center_matrix/effect/fire?r=255&g=100&b=0&speed=150"
curl "localhost:8080/ledstrip/zone/left_matrix/effect/cyclon?speed=200"

Clear Zone Effect

Endpoint: GET /ledstrip/zone-id/clear

Clear / blank out that zone

Example:

curl localhost:8080/ledstrip/left_strip/clear

Available LED Strip Effects

Basic Effects

explosion, comet, chaser, fire, strobe, glitch, party, pulse, rainbow, scanner, wave, sparkle, twinkle, cylon

Advanced Effects

explosion_dual, explosion_multi, particle_explosion, fireworks, fire_flicker, twinklefox, marquee, meteor_rain, chase_wave, fireworks_burst, lightning, starscape

Advanced Explosion Effects

starburst_explosion, cascade_explosion, fragmentation_explosion, ring_explosion, multistage_explosion, explosion_burst

Holiday/Themed Effects

christmas, halloween, valentine, independence

Gun Game Effects

gun_flash_recoil, gun_muzzle_trail, gun_explosion_pulse, gun_laser_shot, gun_shotgun_spread, gun_reload_sequence, gun_crosshair_lock, gun_damage_indicator

Racing Effects

racing_speedometer, racing_track_lights, racing_turbo_boost, racing_drift_smoke, racing_finish_line

Retro/Arcade Ambient Effects

retro_scan, circuit_trace, pixel_cascade, neon_glow, retro_pulse, data_stream, arcade_attract, power_up, game_over, level_clear, coin_drop, neon_flicker, vintage_warmth, digital_rain, retro_grid, plasma_field, soft_breathing, ambient_flow, retro_fade, gentle_ripple

Console-Specific Effects

Arcade Systems: console_mame, console_fba, console_daphne, console_sammy_atomiswave, console_sega_naomi, console_sega_model_2, console_sega_model_3, console_taito_type_x, teknoparrot_arcade, teknoparrot_neon

Nintendo: console_nes, console_snes, console_n64, console_nintendo_gamecube, console_nintendo_wii, console_nintendo_wii_u, console_nintendo_famicom_disk_system, console_virtualboy

Sega: console_sega_sg-1000, console_mastersystem, console_genesis, console_segacd, console_sega32x, console_sega_saturn, console_dreamcast

Sony: console_psx, console_ps2, console_sony_playstation_3, console_psp

Microsoft: console_microsoft_xbox, console_xbox360

Atari: console_atari2600, console_atari5200, console_atari7800, console_atarijaguar, console_atarilynx

NEC: console_pcengine, console_nec_pc_engine-cd, console_supergrafx

Other Consoles: console_3do, console_philips_cd-i, console_vectrex, console_coleco, console_intellivision, console_amiga, console_fairchild_channel_f, console_bally_astrocade

Handhelds: console_gb, console_gbc, console_gba, console_nintendo_ds, console_nintendo_3ds, console_gamegear, console_ngp, console_ngpc

LED Strip and Ring MAME Game-Specific Effects

mame_pacman, mame_dkong, mame_galaga, mame_frogger, mame_mspacman, mame_digdug, mame_qbert, mame_polepos, mame_btime, mame_joust, mame_robotron, mame_zaxxon, mame_tron, mame_timeplt, mame_1942, mame_paperboy, mame_ghouls, mame_gauntlet, mame_commando, mame_rampage, mame_bublbobl, mame_arkanoid, mame_outrun, mame_rygar, mame_ddragon, mame_rtype, mame_shinobi, mame_contra, mame_sf, mame_opwolf, mame_aburner, mame_narc, mame_splatter, mame_goldnaxe, mame_ffight, mame_tmnt, mame_gorf, mame_centiped, mame_milliped, mame_asteroid, mame_defender, mame_stargate, mame_tempest, mame_wiz, mame_berzerk, mame_mpatrol

LED Strip Achievement Effects

achievements_1, achievements_2, achievements_3, achievements_4, achievements_5, achievements_6, achievements_7, achievements_8, achievements_9, achievements_10, achievements_11, achievements_12, achievements_13, achievements_14, achievements_15, achievements_16, achievements_17, achievements_18, achievements_19, achievements_20

MAME Output Effects

mameoutput_startup_coin1, mameoutput_1player, mameoutput_2players, mameoutput_startup_insertcoin1, mameoutput_startup_insertcoin2, mameoutput_startup_insertcoin3, mameoutput_startup_insertcoin4, mameoutput_startup_insertcoin5, mameoutput_startup_insertcoin6, mameoutput_startup_insertcoin-sf

Matrix Basic Effects

matrix_rain, pacman_chase, matrix_digital_rain, matrix_ripple, matrix_spiral, matrix_crosshatch, matrix_diamonds, matrix_plasma, matrix_fire_2d, matrix_snake, matrix_checkerboard, matrix_bouncing_ball, matrix_swirl, matrix_snowfall

Matrix Explosion Effects

matrix_explosion_radial, matrix_explosion_shockwave, matrix_explosion_fireball

Matrix Gun Effects

matrix_gun_muzzle_flash, matrix_gun_bullet_trail, matrix_gun_impact_spark, matrix_grenade_explosion, matrix_shotgun_spread, matrix_laser_blast, matrix_plasma_burst

Matrix Pulse Effects

matrix_circle_pulse, matrix_cross_pulse, matrix_diamond_pulse, matrix_square_pulse, matrix_pulsing_diamonds, matrix_pulsing_squares, matrix_pulsing_circles, matrix_diamond_pulse2, matrix_concentric_squares

Matrix Animation Effects

matrix_scrolling_text, matrix_spinning_square, matrix_horizontal_dashes, matrix_vertical_streak, matrix_shift_left_right, matrix_shift_right_left, matrix_shift_bottom_top, matrix_shift_top_bottom, matrix_splash_center, matrix_round_and_round, matrix_arrow_shift, matrix_v_line_pulse, matrix_vertical_bars, matrix_starburst, matrix_checkboard2, matrix_spiral2, matrix_laser_scan, matrix_pixel_storm

Matrix Energy/Electrical Effects

matrix_electrical_arc, matrix_electrical_power, matrix_plasma_sideways, matrix_energy_beam, matrix_lightning_storm, matrix_energy_field

Matrix Particle/Sparkle Effects

matrix_sparkle_left, matrix_sparkle_right, matrix_sparkle_corners, matrix_particle_stream, matrix_stars_field, matrix_pixel_rain

Matrix Color/Visual Effects

matrix_color_fade, matrix_color_wave, matrix_rainbow_spiral, matrix_neon_grid, matrix_scan_lines, matrix_data_cascade, matrix_circuit_board, matrix_hex_matrix, matrix_neon_pulse, matrix_glitch_noise, matrix_waveform, matrix_binary_code, matrix_radar_sweep

Matrix Score Display

matrix_score

Matrix 8×32 MAME Game-Specific Effects

matrix_8x32_mame_polepos, matrix_8x32_mame_btime, matrix_8x32_mame_zaxxon, matrix_8x32_mame_tron, matrix_8x32_mame_timeplt, matrix_8x32_mame_paperboy, matrix_8x32_mame_gng, matrix_8x32_mame_commando, matrix_8x32_mame_rampage, matrix_8x32_mame_bublbobl, matrix_8x32_mame_rygar, matrix_8x32_mame_ddragon, matrix_8x32_mame_rtype, matrix_8x32_mame_shinobi, matrix_8x32_mame_contra, matrix_8x32_mame_opwolf, matrix_8x32_mame_aburner, matrix_8x32_mame_narc, matrix_8x32_mame_splatter, matrix_8x32_mame_goldnaxe, matrix_8x32_mame_ffight, matrix_8x32_mame_gorf, matrix_8x32_mame_centiped, matrix_8x32_mame_milliped, matrix_8x32_mame_asteroid, matrix_8x32_mame_defender, matrix_8x32_mame_stargate, matrix_8x32_mame_tempest, matrix_8x32_mame_wotw, matrix_8x32_mame_berzerk, matrix_8x32_mame_mpatrol, matrix_8x32_mame_galaga, matrix_8x32_mame_1942, matrix_8x32_mame_pacman, matrix_8x32_mame_mspacman, matrix_8x32_mame_qbert, matrix_8x32_mame_digdug, matrix_8x32_mame_dkong, matrix_8x32_mame_invaders, matrix_8x32_mame_frogger, matrix_8x32_mame_tetris, matrix_8x32_mame_robotron, matrix_8x32_mame_joust, matrix_8x32_mame_vssmb

Matrix 8×8 MAME Game-Specific Effects

matrix_8x8_mame_polepos, matrix_8x8_mame_btime, matrix_8x8_mame_zaxxon, matrix_8x8_mame_tron, matrix_8x8_mame_timeplt, matrix_8x8_mame_paperboy, matrix_8x8_mame_gng, matrix_8x8_mame_commando, matrix_8x8_mame_rampage, matrix_8x8_mame_bublbobl, matrix_8x8_mame_rygar, matrix_8x8_mame_ddragon, matrix_8x8_mame_rtype, matrix_8x8_mame_shinobi, matrix_8x8_mame_contra, matrix_8x8_mame_opwolf, matrix_8x8_mame_aburner, matrix_8x8_mame_narc, matrix_8x8_mame_splatter, matrix_8x8_mame_goldnaxe, matrix_8x8_mame_ffight, matrix_8x8_mame_gorf, matrix_8x8_mame_centiped, matrix_8x8_mame_milliped, matrix_8x8_mame_asteroid, matrix_8x8_mame_defender, matrix_8x8_mame_stargate, matrix_8x8_mame_tempest, matrix_8x8_mame_wotw, matrix_8x8_mame_berzerk, matrix_8x8_mame_mpatrol, matrix_8x8_mame_galaga, matrix_8x8_mame_galaga_explosion, matrix_8x8_mame_1942_explosion, matrix_8x8_mame_dkong, matrix_8x8_mame_invaders, matrix_8x8_mame_qbert, matrix_8x8_mame_pacman, matrix_8x8_mame_mspacman, matrix_8x8_mame_1942, matrix_8x8_mame_frogger, matrix_8x8_mame_digdug

Matrix 8×32 Explosion Effects

matrix_8x32_explosion1, matrix_8x32_explosion2, matrix_8x32_explosion3, matrix_8x32_explosion4, matrix_8x32_explosion5, matrix_8x32_explosion6, matrix_8x32_explosion7, matrix_8x32_explosion8, matrix_8x32_explosion9

Matrix 8×8 Explosion Effects

matrix_8x8_explosion1, matrix_8x8_explosion2, matrix_8x8_explosion3, matrix_8x8_explosion4, matrix_8x8_explosion5, matrix_8x8_explosion6, matrix_8x8_explosion7, matrix_8x8_explosion8, matrix_8x8_explosion9

Matrix 8×8 Achievement Effects

matrix_8x8_achievements_1, matrix_8x8_achievements_2, matrix_8x8_achievements_3, matrix_8x8_achievements_4, matrix_8x8_achievements_5, matrix_8x8_achievements_6, matrix_8x8_achievements_7, matrix_8x8_achievements_8, matrix_8x8_achievements_9, matrix_8x8_achievements_10, matrix_8x8_achievements_11, matrix_8x8_achievements_12, matrix_8x8_achievements_13, matrix_8x8_achievements_14, matrix_8x8_achievements_15, matrix_8x8_achievements_16, matrix_8x8_achievements_17, matrix_8x8_achievements_18, matrix_8x8_achievements_19, matrix_8x8_achievements_20

Matrix 8×32 Achievement Effects

matrix_8x32_achievements_1, matrix_8x32_achievements_2, matrix_8x32_achievements_3, matrix_8x32_achievements_4, matrix_8x32_achievements_5, matrix_8x32_achievements_6, matrix_8x32_achievements_7, matrix_8x32_achievements_8, matrix_8x32_achievements_9, matrix_8x32_achievements_10, matrix_8x32_achievements_11, matrix_8x32_achievements_12, matrix_8x32_achievements_13, matrix_8x32_achievements_14, matrix_8x32_achievements_15, matrix_8x32_achievements_16, matrix_8x32_achievements_17, matrix_8x32_achievements_18, matrix_8x32_achievements_19, matrix_8x32_achievements_20

Matrix 8×8 MAME Output Effects

matrix_8x8_mameoutput_startup_coin1, matrix_8x8_mameoutput_1player, matrix_8x8_mameoutput_2players, matrix_8x8_mameoutput_startup_insertcoin1, matrix_8x8_mameoutput_startup_insertcoin2, matrix_8x8_mameoutput_startup_insertcoin3, matrix_8x8_mameoutput_startup_insertcoin4, matrix_8x8_mameoutput_startup_insertcoin5, matrix_8x8_mameoutput_startup_insertcoin6, matrix_8x8_mameoutput_startup_insertcoin-sf

Matrix 8×32 MAME Output Effects

matrix_8x32_mameoutput_startup_coin1, matrix_8x32_mameoutput_1player, matrix_8x32_mameoutput_2players, matrix_8x32_mameoutput_startup_insertcoin1, matrix_8x32_mameoutput_startup_insertcoin2, matrix_8x32_mameoutput_startup_insertcoin3, matrix_8x32_mameoutput_startup_insertcoin4, matrix_8x32_mameoutput_startup_insertcoin5, matrix_8x32_mameoutput_startup_insertcoin6, matrix_8x32_mameoutput_startup_insertcoin-sf

Basic LED Strip Control

Set Individual Pixel

Endpoint: GET /ledstrip/pixel/{index}?r={red}&g={green}&b={blue}

Set a specific LED pixel to a color.

Parameters:

• index – LED index (0-based)
• r, g, b – RGB color values (0-255)

Example:

curl "localhost:8080/ledstrip/pixel/10?r=255&g=0&b=0"

Clear All LEDs

Endpoint: GET /ledstrip/clear

Clear all LEDs and stop effects.

Example:

curl localhost:8080/ledstrip/clear

Zone Flood Fill

Endpoint: GET /ledstrip/zone/{zoneid}/flood?r={red}&g={green}&b={blue}

Set all LEDs in a zone to a solid color. Stops any running effects on the zone first.

Parameters:

• zoneid – Zone ID (number 0-35) or zone name (e.g., left_strip, center_matrix)
• r – Red value (0-255)
• g – Green value (0-255)
• b – Blue value (0-255)

Examples:

# Flood left_strip zone with red
curl "localhost:8080/ledstrip/zone/left_strip/flood?r=255&g=0&b=0"

# Flood center_matrix zone with green
curl "localhost:8080/ledstrip/zone/center_matrix/flood?r=0&g=255&b=0"

# Flood zone 0 with blue
curl "localhost:8080/ledstrip/zone/0/flood?r=0&g=0&b=255"

# Flood right_strip with white
curl "localhost:8080/ledstrip/zone/right_strip/flood?r=255&g=255&b=255"

Set Range

Endpoint: GET /ledstrip/range?start={start}&count={count}&r={red}&g={green}&b={blue}

Set a range of LEDs to a color.

Example:

curl "localhost:8080/ledstrip/range?start=10&count=5&r=255&g=255&b=0"

LED Strip Configuration

Set Brightness

Endpoint: GET /ledstrip/brightness/{brightness}

Set LED strip brightness (0-255).

Example:

curl localhost:8080/ledstrip/brightness/128

Get Brightness

Endpoint: GET /ledstrip/getbrightness

Read current LED strip brightness from device.

Example:

curl localhost:8080/ledstrip/getbrightness

Response:

{
  "brightness": 128,
  "percentage": 50,
  "success": true
}

Set Pixel Count

Endpoint: GET /ledstrip/numpixels/{numpixels}

Configure total number of LEDs (1-2000).

Example:

curl localhost:8080/ledstrip/numpixels/300

Get Pixel Count

Endpoint: GET /ledstrip/getpixelcount

Read current pixel count from device.

Example:

curl localhost:8080/ledstrip/getpixelcount

Response:

{
  "numPixels": 762,
  "success": true
}

Enable/Disable LED Strip

Endpoint: GET /ledstrip/enabled?enabled={true/false}

Enable or disable the LED strip.

Example:

curl "localhost:8080/ledstrip/enabled?enabled=true"

Control LED Processing

Endpoints:

• GET /ledstrip/pause – Pause Core1 (LED processing)
• GET /ledstrip/restart – Restart Core1 (LED processing)

Examples:

curl localhost:8080/ledstrip/pause
curl localhost:8080/ledstrip/restart

Zone Management

Configure Zone

Endpoint: GET /ledstrip/zone/{zoneid}/setup?start={start}&end={end}&name={name}&type={type}&resolution={resolution}&reverse={true/false}

Configure a LED zone with optional reverse direction for strip zones.

Parameters:

• start, end – Pixel range
• name – Zone name
• type – Zone type (strip/matrix/button)
• resolution – Matrix resolution (8×8, 8×32, 16×16, etc.)
• reverse – Reverse direction (only for strip zones)

Examples:

curl "localhost:8080/ledstrip/zone/0/setup?start=0&end=63&name=left_matrix&type=matrix&resolution=8x8"
curl "localhost:8080/ledstrip/zone/1/setup?start=64&end=127&name=right_strip&type=strip&reverse=true"

Delete Zone

Endpoint: GET /ledstrip/zone/{zoneid}/delete

Delete a configured LED zone.

Example:

curl localhost:8080/ledstrip/zone/0/delete

Zone Effect Control

Endpoint: GET /ledstrip/zone/{zoneid}/effect/{effect}?[parameters]

Start an effect on a specific zone (by ID or name).

Examples:

curl "localhost:8080/ledstrip/zone/0/effect/matrix_ripple?r=0&g=255&b=255"
curl "localhost:8080/ledstrip/zone/left_matrix/effect/matrix_ripple?r=0&g=255&b=255"

Stop Zone Effects

Endpoint: GET /ledstrip/zone/{zoneid}/stop

Stop effects on a specific zone or all zones.

Examples:

curl localhost:8080/ledstrip/zone/0/stop
curl localhost:8080/ledstrip/zone/all/stop

Clear Zone

Endpoint: GET /ledstrip/zone/{zoneid}/clear

Clear and stop effects on a specific zone.

Example:

curl localhost:8080/ledstrip/zone/0/clear

Button Zone Control

Endpoint: GET /ledstrip/button/{zoneid}?state={on/off}&r={red}&g={green}&b={blue}

Control button zone state and color.

Examples:

curl "localhost:8080/ledstrip/button/0?state=on&r=255&g=0&b=0"
curl "localhost:8080/ledstrip/button/0?state=off"

Get Zone Configuration

Endpoint: GET /ledstrip/zones/config?all={true/false}

Get zone configuration. Use all=true to include inactive zones.

Examples:

curl localhost:8080/ledstrip/zones/config
curl "localhost:8080/ledstrip/zones/config?all=true"

Matrix Text & Score Display

Matrix Text

Endpoint: GET /ledstrip/zone/{zoneid}/matrix/text?text={text}&r={red}&g={green}&b={blue}&speed={speed}&font={font}

Display scrolling text on a matrix zone (by ID or name).

Parameters:

• text – Text to display (use %20 for space to clear)
• r, g, b – Text color (0-255)
• bgr, bgg, bgb – Background color (0-255)
• speed – Scroll speed (1-255, higher = faster)
• font – Font type (0=5x7_original, 1=3x5_compact, 2=4x6_balanced, 3=3x7_narrow)
• ltr – Left-to-right scrolling (add parameter for LTR)

Examples:

curl "localhost:8080/ledstrip/zone/0/matrix/text?text=PLAYER%201&r=255&g=255&b=255&speed=120"
curl "localhost:8080/ledstrip/zone/score_matrix/matrix/text?text=GAME%20OVER&font=2"
curl "localhost:8080/ledstrip/zone/0/matrix/text?text=%20"

Stop Matrix Text

Endpoint: GET /ledstrip/zone/{zoneid}/matrix/text/stop

Stop matrix text display on a specific zone.

Example:

curl localhost:8080/ledstrip/zone/0/matrix/text/stop

Matrix Score

Endpoint: GET /ledstrip/zone/{zoneid}/matrix/score?text={score}&font={font}&r={red}&g={green}&b={blue}&centerx={true/false}&centery={true/false}

Display static score/text on a matrix zone (by ID or name).

Parameters:

• text – Score/text to display (use %20 for space to clear)
• font – Font type (0=5x7_original, 1=3x5_compact, 2=4x6_balanced, 3=3x7_narrow)
• r, g, b – Text color (0-255)
• bgr, bgg, bgb – Background color (0-255)
• centerx, centery – Center alignment (default: true)
• offsetx, offsety – Position offset (-127 to 127)

Examples:

curl "localhost:8080/ledstrip/zone/0/matrix/score?text=98765&font=3&r=0&g=255&b=0"
curl "localhost:8080/ledstrip/zone/score_zone/matrix/score?text=HIGH%20SCORE&centerx=true"
curl "localhost:8080/ledstrip/zone/0/matrix/score?text=%20"

Stop Matrix Score

Endpoint: GET /ledstrip/zone/{zoneid}/matrix/score/stop

Stop matrix score display on a specific zone.

Example:

curl localhost:8080/ledstrip/zone/0/matrix/score/stop

Auto-Detection Features

Auto Score Display

Endpoint: GET /ledstrip/score?s={score}&font={font}&r={red}&g={green}&b={blue}

Automatically finds best available display for score (dot matrix, 7-segment, or WS2812B matrix).

Examples:

curl "localhost:8080/ledstrip/score?s=98765&font=2&r=0&g=255&b=0"
curl "localhost:8080/ledstrip/score?s=%20"

Stop Auto Score

Endpoint: GET /ledstrip/score/stop

Stop auto-detected score display.

Example:

curl localhost:8080/ledstrip/score/stop

Auto Text Display

Endpoint: GET /ledstrip/text?text={text}&r={red}&g={green}&b={blue}&speed={speed}&font={font}

Automatically finds best zone for text display.

Examples:

curl "localhost:8080/ledstrip/text?text=PLAYER%201&r=255&g=255&b=255&speed=120"
curl "localhost:8080/ledstrip/text?text=%20"

Stop Auto Text

Endpoint: GET /ledstrip/text/stop

Stop auto-detected text display.

Example:

curl localhost:8080/ledstrip/text/stop

Manufacturer Display

Endpoint: GET /ledstrip/manufacturer?rom={romname}&r={red}&g={green}&b={blue}&speed={speed}

Display manufacturer/publisher name for a MAME ROM using metadata lookup.

Parameters:

• rom – MAME ROM name (e.g., “pacman”, “galaga”)
• r, g, b – Text color (default: 255,255,255)
• speed – Scroll speed (default: 90)

Examples:

curl "localhost:8080/ledstrip/manufacturer?rom=pacman"
curl "localhost:8080/ledstrip/manufacturer?rom=galaga&r=0&g=255&b=255&speed=100"

Response:

{
  "rom": "pacman",
  "publisher": "Namco",
  "gameName": "Pac-Man",
  "year": "1980",
  "zone": 0,
  "zoneName": "text_matrix",
  "status": "success"
}

Batch Zone Control

Send effects to multiple zones in a single API call for synchronized lighting effects. Two batch modes are available: simple (same effect on all zones) and multi-effect (different effects per zone).

Simple Batch (Same Effect on Multiple Zones)

Endpoint: GET /ledstrip/batch/simple?zones={zone-list}&effect={effect}&[parameters]

Apply the same effect with identical parameters to multiple zones simultaneously.

Parameters:

• zones – Comma-separated list of zone names or IDs (required)
• effect – Effect name to apply to all zones (required)
• r, g, b – Primary color (0-255)
• speed – Effect speed (1-255)
• loops – Number of loops (0=infinite)
• reverse – Reverse direction (true/false)
• intensity – Brightness (0-255)
• duration – Duration in seconds

Examples:

# Chase effect on left and right strips with 3 loops
curl "http://localhost:8080/ledstrip/batch/simple?zones=left_strip,right_strip&effect=chase&r=0&g=255&b=255&speed=60&loops=3&reverse=false"

# Rainbow effect on all speaker rings
curl "http://localhost:8080/ledstrip/batch/simple?zones=left_speaker_ring,right_speaker_ring&effect=rainbow&speed=100&intensity=200"

# Pulse effect on multiple zones
curl "http://localhost:8080/ledstrip/batch/simple?zones=left_strip,right_strip,left_matrix,right_matrix&effect=pulse&r=255&g=0&b=128&speed=80"

Multi-Effect Batch (Different Effects Per Zone)

Endpoint: GET /ledstrip/batch?zones={zone-config-list}

Apply different effects with unique parameters to each zone in a single batched command. Zone configurations are separated by @ and parameters within each zone are separated by ~.

Zone Configuration Format:

zone~effect~r~g~b~speed~loops~reverse

Multiple Zones Format:

zones=zone1~effect~r~g~b~speed~loops~reverse@zone2~effect~r~g~b~speed~loops~reverse@...

Parameters per zone (tilde-separated):

1. zone – Zone name or ID (required)
2. effect – Effect name (required)
3. r – Red value (0-255)
4. g – Green value (0-255)
5. b – Blue value (0-255)
6. speed – Effect speed (1-255)
7. loops – Number of loops (0=infinite)
8. reverse – Reverse direction (true/false)

Examples:

# Three zones with different effects
curl "http://localhost:8080/ledstrip/batch?zones=left_strip~pulse~255~0~0~50~3~false@right_strip~chase~0~255~0~60~0~true@left_speaker_ring~fadecolor~100~100~255~40~5~false"

# Left and right strips with mirrored chase effects
curl "http://localhost:8080/ledstrip/batch?zones=left_strip~chase~255~128~0~70~0~false@right_strip~chase~255~128~0~70~0~true"

# Matrix and strip combination
curl "http://localhost:8080/ledstrip/batch?zones=center_matrix~matrix_ripple~0~255~255~100~0~false@left_strip~comet~255~0~128~80~0~false@right_strip~comet~255~0~128~80~0~true"

Notes:

• Invalid zones or effects are skipped with a warning (batch continues with valid entries)
• All zones in a batch are updated in a single USB command for tight synchronization
• Default parameters from query string are used if zone-specific parameters are omitted
• Use the simple batch endpoint when applying identical effects for cleaner URLs

MAX7219 APIs

7-Segment Display

Display Text

Endpoint: GET /max7219/7seg/text?text={text}&brightness={brightness}

Display text on 7-segment display.

Example:

curl "localhost:8080/max7219/7seg/text?text=HELLO&brightness=8"

Display Number

Endpoint: GET /max7219/7seg/number?s={number}&brightness={brightness}

Display number on 7-segment display. Use s=%20 (space) to clear.

Examples:

curl "localhost:8080/max7219/7seg/number?s=12345&brightness=10"
curl "localhost:8080/max7219/7seg/number?s=%20"

Set Brightness

Endpoint: GET /max7219/7seg/brightness?brightness={brightness}

Set 7-segment brightness (0-15).

Example:

curl "localhost:8080/max7219/7seg/brightness?brightness=12"

Clear Display

Endpoint: GET /max7219/7seg/clear

Clear 7-segment display.

Example:

curl localhost:8080/max7219/7seg/clear

Configure Modules

Endpoint: GET /max7219/7seg/config?modules={count}

Configure 7-segment module count (4 or 8).

Example:

curl "localhost:8080/max7219/7seg/config?modules=8"

Enable/Disable

Endpoint: GET /max7219/7segment/enabled?enabled={true/false}

Enable or disable 7-segment display.

Example:

curl "localhost:8080/max7219/7segment/enabled?enabled=true"

Dot Matrix Display

Matrix Text

Endpoint: GET /max7219/matrix/text?text={text}&brightness={brightness}&font={font}&loops={loops}&speed={speed}

Display scrolling text on matrix display.

Parameters:

• text – Text to display
• brightness – Brightness (0-15)
• font – Font type (0=8×8, 1=small)
• loops – Number of loops (1-65535)
• speed – Speed in milliseconds (20-2000)

Example:

curl "localhost:8080/max7219/matrix/text?text=HELLO&brightness=10&font=0&loops=3&speed=200"

Matrix Score

Endpoint: GET /max7219/matrix/score?s={score}&brightness={brightness}&font={font}&loops={loops}&speed={speed}

Display score on matrix display.

Parameters:

• s – Score/text to display
• brightness – Brightness (0-15)
• font – Font type (0=8×8, 1=small)
• loops – Number of loops (1-65535)
• speed – Speed in milliseconds (20-2000)

Example:

curl "localhost:8080/max7219/matrix/score?s=98765&brightness=10&font=0&loops=1&speed=160"

Set Pixel

Endpoint: GET /max7219/matrix/pixel?x={x}&y={y}&state={on/off}

Set individual pixel on matrix display.

Example:

curl "localhost:8080/max7219/matrix/pixel?x=4&y=3&state=on"

Matrix Configuration

Endpoints:

• GET /max7219/matrix/brightness?brightness={brightness} – Set brightness (0-15)
• GET /max7219/matrix/clear – Clear matrix display
• GET /max7219/matrix/config?modules={count} – Configure module count (4 or 8)
• GET /max7219/matrix/enabled?enabled={true/false} – Enable/disable matrix
• GET /max7219/matrix/modules?modules={count} – Set module count (4 or 8)

Examples:

curl "localhost:8080/max7219/matrix/brightness?brightness=12"
curl localhost:8080/max7219/matrix/clear
curl "localhost:8080/max7219/matrix/config?modules=8"
curl "localhost:8080/max7219/matrix/enabled?enabled=true"

Mini LCD (1602/2004) APIs

Basic Display Functions

Print Text

Endpoint: GET|POST /minilcd/print?text={text}

Print text at current cursor position.

Example:

curl "localhost:8080/minilcd/print?text=Hello%20World"

Print At Position

Endpoint: GET|POST /minilcd/printat?text={text}&col={col}&row={row}

Print text at specific position.

Example:

curl "localhost:8080/minilcd/printat?text=Score&col=0&row=1"

Clear Display

Endpoint: GET|POST /minilcd/clear

Clear entire LCD display.

Example:

curl localhost:8080/minilcd/clear

Set Cursor

Endpoint: GET|POST /minilcd/setcursor?col={col}&row={row}

Set cursor position for next print operation.

Example:

curl "localhost:8080/minilcd/setcursor?col=5&row=1"

Advanced Functions

Center Text

Endpoint: GET|POST /minilcd/centertext?text={text}&row={row}

Center text on specified row.

Example:

curl "localhost:8080/minilcd/centertext?text=GAME%20OVER&row=1"

Clear Row

Endpoint: GET|POST /minilcd/clearrow?row={row}

Clear a specific row.

Example:

curl "localhost:8080/minilcd/clearrow?row=2"

Backlight Control

Endpoint: GET|POST /minilcd/backlight?state={on/off}

Control LCD backlight.

Examples:

curl "localhost:8080/minilcd/backlight?state=on"
curl "localhost:8080/minilcd/backlight?state=off"

Game Information

Endpoint: GET|POST /minilcd/gameinfo?console={console}&rom={rom}

Display game information from metadata.

Example:

curl "localhost:8080/minilcd/gameinfo?console=mame&rom=pacman"

Response:

{
  "status": "success",
  "console": "mame",
  "rom": "pacman",
  "platform": "MAME",
  "game": {
    "id": "pacman",
    "name": "Pac-Man",
    "year": "1980",
    "publisher": "Namco",
    "genre": "Maze"
  },
  "message": "Game info displayed on Mini LCD"
}

Mini Statistics

Endpoint: GET|POST /minilcd/ministats?label={label}&value={value}&livesLabel={label}&livesValue={value}&shots={shots}&hits={hits}&ratio={ratio}

Display game statistics (level, lives, shots, hits, accuracy ratio).

Parameters:

• label, value – Level/stage info
• livesLabel, livesValue – Lives info
• shots, hits, ratio – Shooting stats

Examples:

curl "localhost:8080/minilcd/ministats?label=Level&value=5&livesLabel=Lives&livesValue=3"
curl "localhost:8080/ministats?label=Stage&value=12&shots=150&hits=98&ratio=65"

Configuration

Get Configuration

Endpoint: GET /minilcd/config

Get current mini LCD configuration.

Example:

curl localhost:8080/minilcd/config

Response:

{
  "status": "enabled",
  "type": "I2C LCD",
  "resolution": "20x4",
  "address": "0x27",
  "backlight": "on"
}

Enable/Disable

Endpoint: GET|POST /minilcd/setenabled?enabled={true/false}

Enable or disable the mini LCD display.

Example:

curl "localhost:8080/minilcd/setenabled?enabled=true"

Set Type

Endpoint: GET|POST /minilcd/settype?type={type}

Set LCD type configuration.

LCD Types:

• 0 – 16×2
• 1 – 20×2
• 2 – 16×4
• 3 – 20×4
• 4 – 8×2

Example:

curl "localhost:8080/minilcd/settype?type=3"

Response:

{
  "status": "success",
  "type": 3,
  "typeName": "20x4",
  "message": "Mini LCD type set to 20x4 successfully"
}

Important Pulse API Notes

• Hardware Requirements: Pixelcade V2 hardware (purple board) with firmware 23 or higher
• Color Values: RGB parameters use 0-255 range
• Zone Management: Zone IDs can be numeric (0-35) or zone names if configured
• Text Encoding: Text parameters should be URL-encoded (spaces as %20)
• Boolean Parameters: Accept true/false, 1/0, on/off, yes/no
• JSON Responses: Most APIs return JSON responses with status information
• Maximum Zones: 36 zones (0-35) supported for WS2812B LED strips
• Matrix Requirements: Matrix zones require proper resolution configuration for text/score display
• Effect Compatibility: Some effects work better with specific zone types (strip vs matrix)
• Clear Commands: Use text=%20 (URL-encoded space) to clear text/score displays
• Auto-Detection: Auto-detection APIs automatically choose the best available display type
• Zone Names: Zone names can be used instead of IDs for most zone-specific endpoints
• Strip Zones: Support optional reverse parameter during setup
• Font Types: 0=5x7_original, 1=3x5_compact, 2=4x6_balanced, 3=3x7_narrow
• Module Requirements: 7-segment and dot matrix displays require 8+ modules for score display capability
• Mini LCD Support: Multiple display types supported (16×2, 20×2, 16×4, 20×4, 8×2)
• Metadata Required: Game info and manufacturer APIs require corresponding metadata JSON files

Complete Examples Reference

Arcade Frontend Integration

# LED: Game selection browsing
GET /arcade/stream/mame/pacman?event=FEScroll
curl "http://localhost:8080/arcade/stream/mame/pacman?event=FEScroll"

# LED: Game launch with queue
GET /text?t=Game%20Playing%20Pacman&l=1&c=blue
curl "http://localhost:8080/text?t=Game%20Playing%20Pacman&l=1&c=blue"
GET /arcade/stream/mame/pacman
curl "http://localhost:8080/arcade/stream/mame/pacman"

# LCD: Same workflow (no loops) via network
GET http://pixelcadedx-f26967ec.local:8080/text?t=Game%20Playing%20Pacman
curl "http://pixelcadedx-f26967ec.local:8080/text?t=Game%20Playing%20Pacman"
GET http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman
curl "http://pixelcadedx-f26967ec.local:8080/arcade/stream/mame/pacman"

# LCD: Same workflow via USB
curl "http://169.254.100.1:8080/text?t=Game%20Playing%20Pacman"
curl "http://169.254.100.1:8080/arcade/stream/mame/pacman"

Multi-Platform Examples

# LED with hostname
GET http://pixelcade.local:8080/console/stream/nes
curl http://pixelcade.local:8080/console/stream/nes

# LCD device management via network
GET http://pixelcadedx-f26967ec.local:8080/v2/info/
curl http://pixelcadedx-f26967ec.local:8080/v2/info/
GET http://pixelcadedx-f26967ec.local:8080/v2/utility/pairing/set/on
curl http://pixelcadedx-f26967ec.local:8080/v2/utility/pairing/set/on

# LCD device management via USB
curl http://169.254.100.1:8080/v2/info/
curl http://169.254.100.1:8080/v2/utility/pairing/set/on

# Non-arcade use case (LED)
GET /arcade/write/user/
curl http://localhost:8080/arcade/write/user/

Complex Display Sequences (LED Only)

# Multi-step queue example
GET /text?t=Game%20Playing%20Pacman&l=1&c=blue
GET /arcade/stream/mame/pacman?l=3  
GET /arcade/stream/mame/pacghosts.gif?l=2
# Result: Blue text → Pac-Man PNG 3 seconds → Ghost GIF 2 loops → blank

# Cycle mode with high scores
GET /arcade/stream/mame/pacman?t=High%20Scores%20Al%20200,000&l=5&color=green&cycle

Advanced Technical Notes

URL Requirements

• URLs cannot contain spaces in ROM names
• Cannot accept full ROM file paths – use ROM name only
• Extensions optional (e.g., 1942.zip or 1942)

File Organization

V1 (LED/LCD) Paths:

• Console art: /console/{console-name}.png|gif
• Game art: /mame/{rom-name}.png|gif, /user/ for non-arcade
• Multiple GIFs: {game}_01.gif, {game}_02.gif (random selection)
• Animations: /animations/gifsource/
• Fonts: /fonts/ (TTF format)

V2 (LCD) Paths:

• Managed through V2 API endpoints
• Thumbnails available via /v2/thumbnails/
• Upload via POST endpoints with proper content types

Hardware Compatibility

• LED: Full V1 API support, write mode, advanced text formatting
• LCD: Limited V1 support, exclusive V2 APIs, no loops/animations
• Dot Displays: Score display via /score endpoint (LCD systems only)

Performance Notes

• Stream mode: Instant playback, requires listener running
• Write mode: Physical write delay, works offline (LED legacy only)
• Queue system: Sequential processing, unlimited commands (LED only)
• LCD text: Continuous scrolling until interrupted

Licensing

Pixelcade software, API, and artwork is licensed for Pixelcade hardware only.

For technical support, visit the Pixelcade community forums. For integration assistance, consult the hardware documentation and ensure you’re using the correct API version for your device type.