REST Call

Result

http://localhost:8080/arcade/[stream or write/[console name]/[rom name]

Displays a console/emulator specific PNG or GIF. If the console specific PNG or GIF does not exist, displays the default marquee or displaying scrolling text if ?t=[alt-scrolling-text] was specified.

Stream or write a PNG (still image) or GIF animation to the LED marquee. In write mode, the PNG or GIF will continue to display after the Pixelcade listener has been shutdown. Write includes a physical write to the microSD card on the PIXEL board and then the PNG or GIF is playing back locally with no dependency on the PC or Pi. With stream mode , the Pixelcade listener must be running. Stream mode playback is instant while there is a delay with write. 

Note that write is only available in the legacy Pixelcade version at this time.

Additional URL params

?nogif – Only display a PNG if there is also a matching GIF

?gifonly – Only display a GIF if there is also a matching PNG

Note if both a PNG and a GIF exist for the same game, the GIF will play first and then the PNG.

Some games have multiple GIFs (the LED art pack adds more multiple GIFs) like for example:

qbert_01.gif

qbert_02.gif

qbert_03.gif

If there is a multiple GIF as defined by the naming convention game_0x.gif, then Pixelcade will pick one of them at random per each API call and then land on the game PNG (ex. qbert.png). 

Path of the default marquee which can be changed by the user: <pixelcade home folder>/console/default-marquee.png

http://localhost:8080/console/stream/[console-name]?t=[alt-scrolling-text]

Displays a console/emulator specific PNG or GIF. If the console specific PNG or GIF does not exist, displays the default marquee or displaying scrolling text if ?t=[alt-scrolling-text] was specified

The same optional text parameters (font, size, lines, yoffset, etc.) can be used here too.

http://localhost:8080/quit

Shuts down the Pixelcade listener

http://localhost:8080/reboot

Raspberry Pi or Pixelcade LCD: Reboots the OS

http://localhost:8080/shutdown

Raspberry Pi or Pixelcade LCD: Shuts down the OS

http://localhost:8080/localplayback

Puts Pixelcade into local playback mode meaning it will play the last png or gif that was written to it’s microSD card

http://localhost:8080/arcade/stream/black/dummy

Blanks out the LED marquee

http://localhost:8080/text?t=<Your%20Scrolling%20Text%20Here>

Send scrolling text. Make sure to add %20 for all spaces.

http://localhost:8080/text?t=[scrolling-text]&c=[color]&s=[speed]&font=[font name]&size=[font size]&lines=[number of lines]&yoffset=[offset number]&loop=[number of times to loop scrolling text]

?t=[your text] is required, the rest of the parameters are optional. ?t=hello world will scroll the text “Hello World”

&c=[color] changes the scrolling text color. Possibles values are: red, blue, cyan, gray, darkgray, green, lightgray, magenta, orange, yellow, pink, and white. &c=green or &color=green will change the text to green.

Hex color values may also be entered in 6 digit format without the # sign. &c=45B39D for example

For scrolling speed, smaller number means faster scrolling. Range 10 – 150. &s=10 for example

The color will default to red if no color is specified or if an invalid color is specified. Of if a color is not specified and random is specified as the default color in settings.ini, then a random color will be used.

New TTF (TrueType) fonts can be added to the /fonts folder. Specify the TTF font name, not the file name. Example font names are “Handwriting”, “Tall Films Fine”, and “Haunting Attraction”. The default font is “Arial Narrow 7”.

Font size ranges are typically 14 – 32. &size=20 would change the font size to 20. Default font size is 28.

lines can be 1, 2, or 4. &lines=4 would change to 4 lines of text. If 2 or 4 is selected, the font and font size will be over-riden.

As some fonts will not center vertically correctly, the yoffset parameter can be used to adjust. &yoffset=-4 for example will move the text up by 4 pixels and &yoffset=4 will move the text down by 4 pixels.

Displays scrolling text for x loops. See the Queue feature described below for more info on the queue works.  Ex. &l=5 will loop the scrolling text 5 times.

Note if the text is shorter than the length of the display (Pixelcade is 132 pixels wide for example), then the text will not scroll.

If LCDLEDCompliment=yes in settings.ini (this is the default), then the additional param &led is sent to the LCD call which then tells Pixelcade LCD not to scroll text since there is already a Pixelcade LED that is scrolling text. Ex. http://pixelcadedx-xxxxxxxx:8080/text?t=Now Playing Pacman&led 

http://localhost:8080/arcade/stream/[console name]/[rom name]?t=[alt-scrolling-text]

If a matching PNG or GIF image is not found, then display scrolling text (Ex. Game Playing Asteroids Deluxe)

The same optional text parameters (font, size, lines, yoffset, etc.) can be used here too.

http://localhost:8080/arcade/stream/[console name]/[rom name]?l=x

Loops a GIF animations x times or displays a still image PNG for x seconds

QUEUE FEATURE

If another loop command (GIF, PNG, or scrolling text) is sent while in the current loop, 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. 

To abort and clear all items in the Queue, simply send a new command that does not contain the loop parameter (&l=x) or send a write command. This command will immediately take priority, start, and empty the Queue.

Note that the display will be cleared / blanked out after the last loop command in the Queue has finished unless a loop value of 99999 is specified which tells Pixelcade to let the previous Queue item finish and then will stay on the last PNG or GIF until its interrupted. 

If using the Queue feature in a custom script, ensure all your calls have the additional param &event=FEScroll

http://localhost:8080/arcade/stream/[console name]/[rom name]?t=[scrolling text]&l=[number of times to loop the GIF or seconds if a PNG]&color=[text color]&cycle

CYCLE MODE

Cycle indefinitely between a GIF or PNG and scrolling text.  A typical use case would be launching a game and then displaying a marquee for say 5 seconds and then scrolling high scores and then back to the marquee. If the target is a PNG, the PNG will display for x seconds where x is the loop param. If the target is a GIF, the GIF will loop only 1 time. The text will always scroll only one time before cycling back to the PNG or GIF.  To interrupt the cycle, you must send another API command without a loop parameter.

Example:

http://localhost:8080/arcade/stream/mame/pacman?t=High%20Socres%20Al%20200,000%20Erin%203,000&l=1&color=green&cycle

http://localhost:8080/arcade/stream/[console name]/[rom name]?event=[Arcade Front End Event Flag]

Possible Values:

• FEStart
• FEScroll
• GameStart
• FEScreenSaver
• FEQuit

ARCADE FRONT END EVENT FLAGS

For arcade front ends integrating with Pixelcade, it’s highly recommended to add events flag to each API call as this gives Pixelcade context enabling Pixelcade to know if the event is coming from front end scrolling or a game launch for example. 

• FEStart – when your front end is launched (optional)
• FEScroll – when scrolling through games (wheels for example) through the front end but not actually launching the game (required)
• GameStart – launching the game (required)
• FEScreenSaver (optional)
• FEQuit – when exiting your front end (nice to have)

Note: case sensitive

Example:

http://localhost:8080/arcade/stream/mame/pacman?event=FEScroll

http://localhost:8080/ticker?start

http://localhost:8080/ticker?stop

TICKER MODE

Starts and stops a scrolling text ticker based on content from RSS feeds. Up the 5 RSS feed sources can be configured and are defined in Pixelcade’s settings.ini. The ticker will stop automatically when any arcade call is sent or when the ticker stop command is called.

Note the news ticker is only available in the legacy Pixelcade version at this time

http://localhost:8080/achievements/stream/[console name]/[achievement_id]?t=[achievement_scrolling_text&currentgame=[rom name]

ACHIEVEMENTS

This API is specifically for integration with RetroAchievements , here is an example. 

If a PNG or GIF matching the achievements ID file name exists in <your Pixelcade folder>/achievements , then that file will play , then followed by the achievements scrolling text for 1 loop, and then lastly the game marquee will display that matches the console and rom name. If the achievements ID file does not exist (which will be the more common case), then a random animation (between 10 animations) will display, then the achievements scrolling text, and then the game marquee. 

Example:

http://localhost:8080/achievements/stream/coleco/177575?t=”First Flight : Clear 3 rounds of Skill Level 1″&currentgame=zaxxon

http://localhost:8080/pinball/table/animation

PINBALL EVENT ANIMATIONS

Displays animations specifically in the /pinball artwork folder, click here for demo

ex. http://localhost:8080/pinball/btmn_106/s4

If a second pinball API comes in when the first one did not complete yet, the animations will overlay

If the table does not exist, it will default to animations in the pinball/auto folder. The default animations in pinball/auto are s1, s2, s3…. s16.

For training mode to see what animation name the pinball table is passing (so you can later add the corresponding artwork), use 

http://localhost:8080/pinball/btmn_106/s4?training which will then scroll text on Pixelcade LED showing what animation name is being sent by the table.

Note this is only available on the Pixelcace LED legacy version at this time

http://localhost:8080/text?t=&l=x

Displays scrolling text for x loops. The Queue feature described above applies also to scrolling text with the loop parameter.

API Access to Widgets

Weather

http://localhost:8080/weather?location=x

x can be a zip code or a city/country name

Clock

http://localhost:8080/clock

Sports Scores Ticker

http://localhost:8080/sports/x

x can be: nfl, nba, nhl, mlb

http://localhost:8080/info

Returns a JSON with info and settings from pixelcade.ini

{"name":"My Pixelcade LED","type":"LED","hostname":"al-xps15","ipAddress":"192.168.87.47","firmwareVersion":"PIXR0021","hardwareID":"PIXL0025","bootLoaderID":"IOIO0401","softwareVersion":"5.7.0-debug (89044191)","resolution":"128x32","pixelcadeRoot":"C:\\Pixelcade","bindAddr":"0.0.0.0","bindPort":8080,"defaultFont":"C:\\Pixelcade\\fonts\\Arial Narrow 7.ttf","defaultFontColor":"red","defaultFontColorRandom":true,"defaultFontSize":28,"devicePath":"auto","deviceScan":false,"fuzzyMatching":true,"pngFuzzyDistanceThreshold":20,"pngFuzzyMaxMatchesThreshold":40,"noIntro":false,"startupImage":"mame/pixelcade.png","startupMode":false,"startupText":"Welcome to Pixelcade","systemImage":"","debugLogging":false,"traceLogging":false,"noLogging":false,"colorLogging":false,"initDelay":0,"demoMode":false,"noMdns":false}

http://localhost:8080/settings?key=<key-name>&value<true or false or string>

Settings

Valid Key names are:

{"key":"fuzzyMatching","value":"false"}

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

http://localhost:8080/animations/stream/[file name]

Streams or writes an animation that exists in the /animations/gifsource folder. Add the parameter ?r to return a random animation. 

http://localhost:8080/animations/list

Returns a list of animation names from /animations

http://localhost:8080/still/list

Returns a list of single frame image names from /images

http://localhost:8080/arcade/list

Returns a list of mame game names from /mame

http://localhost:8080/currentgame

Returns the name of the last game selected in the format console%game-name Ex. mame%pacman