Pixelcade LED User Guide

How to install your Pixelcade LED marquee, connect it to your arcade front end, and set it up with Pixelcade Companion.

1. How Pixelcade works

Pixelcade has three parts:

• The LED marquee. An LED matrix panel driven by the Pixelcade controller board. It connects to your arcade computer with a USB cable.
• The Pixelcade software (called pixelweb). It runs in the background on your arcade computer, talks to the marquee over USB, and changes the artwork whenever your front end selects or launches a game.
• Pixelcade Companion. A web page served by the Pixelcade software. You open it in a browser on the cabinet, or on your phone, tablet or laptop, to browse artwork, run widgets, change settings and install updates. Nothing extra needs to be installed to use it, and it's also available as a free app for iPhone and iPad and Android.

When you scroll through games in your front end, it tells Pixelcade the system and game name, and Pixelcade shows the matching marquee. If no exact match exists, it falls back to the system's logo.

Pixelcade also works with optional add-ons: Pixelcade LCD (an LCD marquee, used alone or alongside the LED marquee) and Pixelcade Sidekick (small companion screens that show box art, game descriptions and high scores, see section 16). [TODO: link to LCD guide]

2. Before you start

You'll need:

• Your Pixelcade LED marquee (a ready-to-mount marquee for an existing arcade cabinet, or a DIY kit) and its USB cable
• A way to power it: the Pixelcade SATA power cable or a 12V, 5A power supply. Most kits include one of these (see section 3).
• An arcade computer running one of the supported platforms:
  • Windows with LaunchBox / BigBox, HyperSpin, GameEx, Arcade One or Core Type R
  • Linux-based systems: Batocera, RetroPie, Recalbox, EmuELEC, MiSTer, AtGames Legends Ultimate with R-Cade / Legends Unchained
• An internet connection for the install (the installer downloads the software and the marquee artwork)
• For Companion from another device: your phone, tablet or laptop on the same network as the arcade computer

3. Connect the hardware

1. Mount the marquee in your cabinet's marquee area. How you mount it depends on your cabinet. Most installs are either a flush mount or a protruding mount. See pixelcade.org/mounting for details.
2. Connect power. There are two options:
   • Pixelcade SATA power cable (recommended for PC cabinets). Plugs into a spare SATA power connector from your PC's power supply. Your marquee then turns on and off automatically with your PC.
   • 12V, 5A power supply. For systems without a PC power supply, such as a Raspberry Pi or another single-board computer.
3. Connect the USB cable from the Pixelcade controller board to a USB port on your arcade computer.
4. Power on. The marquee shows the Pixelcade startup logo once the software is running.

4. Install the software

Pick your platform below. Each installer downloads the Pixelcade software and the marquee artwork, and sets Pixelcade to start automatically. All installers are also listed under Download on pixelcade.org.

Windows

1. Download and run the Windows installer from pixelcade.org/download-pc. It installs both Pixelcade and LEDBlinky, which all Windows front ends need.
2. If Windows Firewall asks whether to allow pixelweb.exe, click Allow. Otherwise you won't be able to open Companion from your phone or another computer.
3. Open Companion (see section 5) and go to Settings → Front End Setups to check that your front end is set up correctly (see section 6).

Batocera

1. Connect your Batocera machine to the internet.
2. Open a terminal on the machine, or connect to it over SSH from another computer (Batocera's default login is user root, password linux, unless you've changed it).
3. Run:

   wget https://raw.githubusercontent.com/alinke/pixelcade-linux-builds/main/install-scripts/setup-batocera.sh && chmod +x setup-batocera.sh && ./setup-batocera.sh

4. Answer the installer's questions, then reboot when it finishes.

Full Batocera instructions: pixelcade.org/batocerav2

AtGames Legends Ultimate (R-Cade / Legends Unchained)

1. Enable Pixelcade in R-Cade: R-Cade Main Menu → System Settings → Accessory Settings → Pixelcade Support.
2. If Pixelcade isn't installed yet, Companion's main menu shows an Install Pixelcade tile. Tap it to download and set up Pixelcade on the cabinet.

Full R-Cade instructions: pixelcade.org/rcade

Other Linux platforms

5. Open Pixelcade Companion

Companion is a web page served by Pixelcade on port 8080. Open it in any web browser:

Replace <computer-name> with your arcade computer's network name (for example http://batocera.local:8080). To find the name or IP address, open Companion on the cabinet and go to Settings → Support. The Hostname and IP Address are listed there.

6. Connect your front end

Go to Settings → Front End Setups. Companion checks each supported front end and shows a green check or a red X for every setting Pixelcade needs, so you can see exactly what's left to do.

For anything that isn't set up yet, follow the instructions shown next to it, then refresh the page to check again.

7. A tour of Companion

Companion's main menu has these tiles:

8. Artwork and the default marquee

Browse Artwork

Open Browse Artwork, pick a system, then tap any marquee to show it on your LED marquee right away. Tap the heart icon on a marquee to add it to Pixelcade Attract Mode.

To change how game names appear under the thumbnails, go to Settings → General → Label Style and choose No Label, On Top, On Bottom or Overlay.

Set Default Marquee

The default marquee is what Pixelcade shows when no game is selected, such as when your front end starts up. Open Set Default Marquee and choose the artwork you want.

9. Your own artwork and mappings

Upload Custom Artwork

Open Upload Custom Artwork, choose a system, and upload your images.

• File names: name each file after the game, using the same game name your front end uses (for example pacman.png or galaga.jpg). The file name without the extension becomes the game name.
• Size: every Pixelcade LED marquee is 128 × 32 pixels. Larger images are resized automatically using nearest-neighbor scaling, which keeps pixel art sharp.
• Formats: everything is saved as PNG. JPG, HEIC, WebP, GIF and BMP files are converted automatically.
• Best results: make your artwork at exactly 128 × 32 pixels as a PNG, so no resizing or conversion is needed.
• Custom systems: use Add Custom System to create your own system. Deleting a custom system also deletes all of its artwork, and this can't be undone.

After uploading, you'll find your artwork under that system in Browse Artwork.

Custom System Mappings

Each front end has its own names for systems. One might call a system "Nintendo Entertainment System" and another "nes". Pixelcade already knows the common names. If your setup uses a name Pixelcade doesn't recognize, the marquee won't find the right artwork for that system.

Open Custom System Mappings to map your front end's system name to the matching Pixelcade system. Your mappings are saved in metadata/custom_mappings.json in the Pixelcade folder, and you can delete them at any time.

10. Scrolling text

Open Scrolling Text, type a message, and send it to the marquee. You can choose the font, color, size and scroll speed.

If you have the optional extra displays (see section 15), you can choose which display shows scrolling text in Settings → Pixelcade Pulse.

11. Widgets

Widgets turn your marquee into a live information display. Open Widgets and tap a widget to start it. Tap it again to stop. Widgets can also be added to Pixelcade Attract Mode so they rotate with your favorite marquees.

Each widget has its own settings (teams, locations, accounts and so on). Open them from the widget's settings button, or see all of them on one page under Widgets → Widget Settings. Settings save automatically as you change them.

12. Pixelcade Attract Mode

Pixelcade Attract Mode is a playlist that cycles through your favorite marquees and widgets, so your cabinet looks alive when nobody is playing.

Build your playlist

1. In Browse Artwork, tap the heart icon on any marquee to add it.
2. Open Pixelcade Attract Mode to see your playlist. Add widgets, remove items, and set how long each one stays on screen.
3. Press Start to run it.

Start it automatically with your front end's screensaver

Go to Settings → Attract Mode. Companion can set up LEDBlinky, LaunchBox / BigBox, HyperSpin, Batocera and R-Cade so that Pixelcade Attract Mode starts when the front end's screensaver starts, and stops when it ends. Click the button for your front end.

If your front end isn't listed, it can still be set up manually. Ask in the #support channel on the Pixelcade Discord.

13. Settings reference

Settings are organized into tabs. Tabs for features you don't use can be ignored.

General

Other tabs

14. In Game Effects (DOFLinx)

With In Game Effects, the marquee reacts to what's happening inside the game, such as explosions, and can show live scores and high scores. It's powered by DOFLinx. It's supported on:

• Windows: select MAME games
• Batocera, R-Cade and Recalbox: games on the FBNeo wheel

It isn't available on MiSTer. More information and the list of supported games: pixelcade.org/doflinx

Configure it under Settings → In Game Effects:

• Status: whether DOFLinx is installed and running. On R-Cade you can install, disable or uninstall DOFLinx from here.
• Explosions Display and Score Display: where effects and scores appear.
• Show high scores on game start.
• Cabinet Buttons: which buttons are Coin, Player 1 Start and Player 2 Start. On AtGames Legends Ultimate these are set up automatically during install.
• MAME Configuration: where your MAME installation is (on Arcade One, any extra MAME folders).

DOFLinx and its game definition files are updated from the Updates page, which also links to the DOFLinx documentation and the list of games with effects.

15. Pixelcade Pulse: LED strips and extra displays

Pixelcade Pulse drives extra lighting and small displays from the same Pixelcade board: addressable LED strips, rings or matrices, a 7-segment score display, a scrolling dot-matrix display and a mini LCD.

Wiring LED strips

Pulse uses standard WS2812B addressable LEDs. The chain starts at the 3-pin blue connector on the Pixelcade V2 board. Connect your first strip to it with a Pixelcade Pulse cable, which comes in two versions:

More information, including LED strips and cables: pixelcade.org/pulse

Configure Pulse

Set it up under Settings → Pixelcade Pulse:

• LED strips: split your strips into zones, set how many LEDs each zone has, and choose effects, colors, speed and brightness. The page shows the total number of active LEDs, so you can tell whether you're over the 90-LED limit for the 3-pin cable.
• Pause during gameplay: turns off Pulse light effects while you're playing, and brings them back when you exit to the front end.
• Additional Displays: turn on the 7-segment, dot-matrix and mini LCD displays, set how many modules each has, and run Test (Hello World) to check the wiring. You also choose which display shows live MAME scores (with DOFLinx) and which shows scrolling text.

16. Pixelcade Sidekick displays (optional)

Pixelcade Sidekick displays are small companion screens that sit alongside your marquee. They show information about the game or system you've selected in your front end, and they change automatically as you browse, just like the marquee.

A Sidekick can show:

• Game artwork: box art, logo, fan art, screenshots, flyers, cabinet and control panel art
• Game information: description, history, move lists and high scores
• RetroAchievements for the selected game
• System information when you're browsing a system rather than a game

On touchscreen models, swipe to move between these cards. Or turn on the carousel to cycle through them automatically.

Sidekick displays come in many sizes, from small 2-inch screens up to 10.1-inch panels, including a round display and a long bar display. A cabinet can have more than one, for example one on each side of the control panel.

Connecting a Sidekick

1. Plug the Sidekick into a USB port on your arcade computer. Pixelcade finds it automatically.
2. Open Companion and go to Settings → Sidekick. Your display is listed there.
3. Choose what it shows on startup, for a game and for a system. You can also set the brightness and language, and turn the carousel on or off.
4. Most models can also connect over WiFi, so they don't need a USB cable to the computer once set up. Connect over USB first, then use Configure WiFi on the Sidekick settings page.

Sidekick artwork and firmware are updated from the Updates page. Firmware updates need a USB connection.

A Sidekick also works without an LED marquee. In that case, turn on No Pixelcade LED Marquee Connected under Settings → General.

Supported displays, where to buy them, and more information: pixelcade.org/sidekick

17. Keeping Pixelcade up to date

Open the Updates tile. Each component shows whether it's up to date:

Update Everything updates the artwork, Art Pack, DOFLinx and the software in order, then the firmware last, because a firmware update restarts the board. Anything that's already current is skipped.

Turn on Include Beta Updates (or Use beta release on a single item) to try new features early.

Under Advanced Options:

• Full Sync (Re-download Everything): use this if artwork looks incomplete even though it says it's up to date.
• Reset Firmware Settings: resets LED strip, display and other hardware settings back to defaults, without changing your firmware version.

18. Troubleshooting

The marquee doesn't change when I select a game

• Go to Settings → Front End Setups and fix anything marked with a red X.
• On Windows, make sure LEDBlinky 8.3 or later is installed and set to your front end.
• Open the Log page and select a game. The log shows the system and game name your front end sent. If the system name isn't recognized, add it in Custom System Mappings.
• Turn on Fuzzy Matching if your game names don't exactly match the artwork names.

I can't open Companion from my phone

• Make sure the phone is on the same network as the arcade computer (not on mobile data or a guest network).
• Use the IP address instead of the .local name. It's listed under Settings → Support on the cabinet.
• On Windows, Windows Firewall may be blocking Pixelcade. Allow pixelweb.exe through the firewall: open Windows Security → Firewall & network protection → Allow an app through firewall, then make sure pixelweb.exe is allowed on Private networks.

The marquee is blank or shows nothing

• Check the power and USB connections. On a Pixelcade V2 board, the status LED should blink slowly. That means the board has power and is running normally.
• If you use the SATA power cable, the marquee only gets power while the PC is on.
• Open http://localhost:8080 on the cabinet. If the page doesn't load, the Pixelcade software isn't running. Restart the computer, or start Pixelcade again.
• Check that No Pixelcade LED Marquee Connected is off under Settings → General.
• If the marquee still doesn't respond after a firmware update, follow pixelcade.org/reset-firmware.

Some artwork is missing

On the Updates page, update Core Artwork. If artwork is still missing, use Full Sync (Re-download Everything) under Advanced Options.

Contacting support

1. Turn on Debug Logging under Settings → General, then reproduce the problem.
2. Go to Settings → Support and copy the device information.
3. Post it, along with a description of the problem, in the #support channel on the Pixelcade Discord.

19. Advanced: pixelcade.ini and the URL API

pixelcade.ini

All settings are stored in pixelcade.ini, which is usually in the same folder as the Pixelcade program (pixelweb, or pixelweb.exe on Windows). Companion edits this file for you, so most people never need to open it. If you do edit it by hand, quit Pixelcade first and restart it afterward. Some keys are marked "do not manually update" because Companion keeps them in sync with the firmware. Leave those alone.

Controlling Pixelcade from scripts

If your front end isn't directly supported, or you want to write your own scripts, you can control Pixelcade with simple web requests to port 8080. A few common ones are below. The full list is in the Pixelcade API documentation.

Example from a Linux shell:

curl "http://localhost:8080/arcade/stream/mame/pacman"
curl "http://localhost:8080/text?t=Game%20Over"