****************************************************************
*             ATARI FLASHBACK 9/X - PROJECT NEXUS              * 
*           by: RocketFan, Draxxon, Wilfwilfus & RRA           *
*                   V.1.0.40 - Nov. 16, 2021                   *
****************************************************************

For the Atari Flashback 9 (AR3050), AFB9 Gold (AR3650), AFBX (AR3060) and AFBX Deluxe (AR3060S). You will need to flash the correct Custom Firmware for your specific system for this package to work.

First flash the Official AtGames Firmware Update. The procedure varies from the Atari Flashback 9 to the Atari Flashback X. You can visit the AtGames Flashback Zone Firmware Update Portal for instructions on how to flash your specific console. It is recommended that you flash the Official AtGames Firmware Update to your system first, before you flash the Custom Firmware. Note: The update file must be named "atari_update.img" exactly, and placed on the root of the drive for the system to recognize it. Remove the update image file from your drive after a successful update.

https://firmwareupdate.atgames.net/

The Custom Firmware is the same as the Official AtGames Firmware Update with a small edit to allow files to be read from the SD Card or Flashdrive. Visit the AtariAge Forum in the link below to find the correct firmware for your specific model Atari Flashback. If you aren't sure, just ask someone there for help. Note: The Custom Firmware is built off of newer Official Firmware than is currently posted on the AtGames website. The update file must be named "atari_update.img" exactly, and placed on the root of the drive for the system to recognize it. Remove the update image file from your drive after a successful update.

https://atariage.com/forums/topic/320084-atari-flashback-nexus-community-project/#comments

****************************************************************
* BEGINNER                                                     *
****************************************************************

*****************************************
* RUNNING FILES FROM THE EXTERNAL DRIVE *
*****************************************

What the NEXUS pack does is allow you to run files from an SD Card or Flashdrive by use of two control files on the root of your device. They are mount_sd.ini and startup.sh. Those two files must be present for this pack to work. If you have only those files on your external device, and nothing else, they will dump the stock /rom and /emulator partitions from the console to your drive. This takes a very, very, long time. 

The NEXUS pack is a heavily edited /emulator folder with multiple cloned, edited /rom folders. By editing these folders we can add new emulator cores, new game ROMs with box art to the main menu list of games, and even use folders, custom bezels and commands. All of the NEXUS files are on your external drive. Nothing is installed to your system. Without the external drive inserted, your system will function like stock/normal. The NEXUS pack cannot brick your system.

To run the NEXUS pack from your SD Card or Flashdrive, simply unzip the NEXUSv1.0.1.zip file to the root of your device. You will see a /game, /emulator, /rom and slew of alternate "/rom_alt" folders for various other consoles. You will also see the two control files mentioned above, and this instruction_manual.txt you are now reading.

***************
* /ROM FOLDER *
***************

The /rom folder is the default system folder. This is the folder the system will launch into first when you power it on. The NEXUS /rom folder is set up like a hub to all the other /rom_alt folders. To make the console launch directly into a specific game when you power on, place the ROM with the extra .gme extension attatched to the end of the file name in the /rom folder. That game will now auto launch when you power the console on.

********************
* /EMULATOR FOLDER *
********************

Inside the /emulator folder you will see various system files and a /res folder with the default system theme/UI. All of the cores and system bios go here. The default bezel that shows if custom bezels are on, and the specific game does not have a custom bezel, is also found here. 

It also has the ability to have a file named "goto" in the /emulator folder.  If you put the name of a rom folder in there (just the name) then your device will start in that section instead of in the top /rom folder.  For example if you are working in the pico-8 area or just playing a lot of games there you can have a goto file in /emulator which just contains one line with the one word for example:

rom_pico8

Which is the name of that folder. Then when you power on your system - you are going to be there.  This can save a lot of time if you are testing something in a particular area so you don't have to navigate the menus over many power cycles.

Note: You will also find many cores not yet implemented or tested yet. They have been optimized for devices similar to these flashbacks, but not all may work.

****************
* NEW COMMANDS *
****************

A few commands are supported. Currently there are goto, reboot, shutdown, clear_recent, restore_bezels and import_favorites commands. They appear as folders or switches in in-game menus. They use the .cmd file extension.

Goto allows folder support and is the command to travel from folder to folder. 

Reboot is handy if your system memory gets full and you only get a black screen on game launch. Reboot can remedy that. 

Shutdown is useful so you won't get an error message whenever you connect your Flash Drive or SD Card to a PC. 

Clear_recent removes the entries from your recently played games list. 

Restore_bezels will re-enable custom bezels if you turn them off by selecting one of the four default bezels from the in-game options page. 

Import_favorites is found in the universal favorites folder and will import any games you have favorited in the various other sections.

**********************
* EXIT GAME SHORTCUT *
**********************

When exiting a game you no longer have to go back to the current game's details page. You can now instead go directly to the current top menu. This helps if you are playing with a joystick that does not have the extra P1 menu button. 

To implement the Exit Game Shortcut move the "restart_return" file from the /emulator/tools/Exit_Shortcut folder to the /emulator folder. 

NOTE: Use the Select button/switch on the console + Up on a controller for the Menu button. Just an FYI, the Rewind button is Select on the console + Down on the controller.

************************************
* SELECTING A SECTION TO BOOT INTO *
************************************

You must wait until you see the AtGames logo appear then push (and hold) your joystick in a direction. I don't know why, but if you do not wait, and you are pushing a direction from the very start, the system hangs at the AtGames logo.
 

Left - Takes you directly to the main Atari 2600 games collection.

Right - Takes you directly to the Atari 8bit games collection.

Up - Takes you directly to the "Legends Flashback" (non-Atari emulation) layer of the menu.

Down - Puts you in "stock mode" - running as with the standard atGames FW.

Nuetral - To boot into the full glory of the Nexus main menu.

Note: Right and left can be customized to your liking by changing the contents of the right and left files in /emulator. 

*******************************************
* ADDING GAMES WITHOUT ART - /GAME FOLDER *
*******************************************

The NEXUS pack starts you with an empty /game folder. The folder must be named "game" for the system to recognize it and you must have at least one ROM in the folder for the SD Card/Ext Drive option to show on your in-game menu.

ROMs cannot have any spaces " ", periods "." or brackets "[]" in the file name. They also cannot be overly long, around 90 characters, or they will black screen freeze the system, and you will have to power on and off. It will happen every time you scroll to the problem game until you correct it.

All ROM types that are currently found in the NEXUS pack are supported in the /game folder, but, you now must add an extra .gme extension to each game's file name. This is useful because the system truncates the last three charcaters to hide the extension. It is really bad if you have a 2 letter extension as it will hide the last letter of the ROM's file name. This way you see the entire file name with extension. Handy if you have lots of different games. Here are some examples of how an added ROM to the /game folder's file name would look.

Examples: RiverRaid.a26.gme
          MarioBros.nes.gme

Note: It is best to run your ROM from the /game foler in the NEXUS category you would expect to find the game in. An example is if you are running an NES ROM from the /game folder, launch it while in the NES section. The various NEXUS sections all have unique core settings set up for the paticular system/console that section is inteded for. Your ROM in the /game folder may need those core settings running in that section. There are a lot of different games out there and not everything is going to work. Some games may need to be added to the in-game, main menu list of games so individual core settings can be set on a game by game basis.

*****************************
* SUPPORTED FILE EXTENSIONS *
*****************************

These are the currently supported file extensions in the NEXUS Project. (Thanks to KMFDManiac for all of the pre-built cores!)

.gme - /game folder's extra extension, /rom folder's auto launch game
.cmd - command file
.goto - go to command
.uex - exectutable file
.bmp - retroplayer.x - image_core.so
.gif - retroplayer.x - image_core.so
.jpg - retroplayer.x - image_core.so
._png - retroplayer.x - image_core.so
.avi - retroplayer.l - ffmpeg_libretro.so
.flv - retroplayer.l - ffmpeg_libretro.so
.mpg - retroplayer.l - ffmpeg_libretro.so
.mp3 - retroplayer.l - pocketcdg_libretro.so
.mp3 + .cdg - retroplayer.l - pocketcdg_libretro.so
.a26 - retroplayer.9 - stella_libretro.so
.a269 - retroplayer.9 - stella_libretro.so
.a26x - retroplayer.x - stella_libretro.so
.a26l - retroplayer.l - stella_libretro.so
.26a - retroplayer.l - stella_libretro.so.6_1_5512
.a78 - retroplayer.x - prosystem_libretro.so
.a52 - retroplayer.x - atari800_libretro.so
.atr - retroplayer.x - atari800_libretro.so
.bas - retroplayer.x - atari800_libretro.so
.car - retroplayer.x - tari800_libretro.so
.xex - retroplayer.x - atari800_libretro.so
.vgz - retroplayer.l - gme_libretro.so
.sap - retroplayer.l - gme_libretro.so
.lnx - retroplayer.l - handy_libretro.so
.jag - retroplayer.l - virtualjaguar_libretro.so
.zi3 - retroplayer.x - km_mame2003_xtreme_libretro.so
.zim - retroplayer.x - lr-mame2000.so
.zim9 - retroplayer.9 - lr-mame2000.so
.ziml - retroplayer.l - lr-mame2000.so
.zin - retroplayer.l - fbneo_libretro.so
.zip - retroplayer.x - lr-fbalpha.so
.cv - retroplayer.l - libcv.so
.int - retroplayer.l - freeintv_libretro.so
.ody - retroplayer.x - o2em_libretro.so
.t64 - retroplayer.l - vice_x128_libretro.so
.z80 - retroplayer.l - fuse_libretro.so
.tzx - retroplayer.l - fuse_libretro.so
.tap - retroplayer.l - fuse_libretro.so
.nes - retroplayer.9 - quicknes_libretro.so
.nesl - retroplayer.l - quicknes_libretro.so
.fds - retroplayer.l - nestopia_libretro.so
.fig - retroplayer.l - snes_mtfaust_skopt-arm32-cortex-a9.so
.sfc - retroplayer.l - snes9x_libretro.so
.mgw - retroplayer.l - gw_libretro.so
.gb - retroplayer.l - mgba_libretro.so
.gbc - retroplayer.l - mgba_libretro.so
.gba - retroplayer.l - mgba_libretro.so
.vb - retroplayer.l - mednafen_vb_libretro.so
.min - retroplayer.l - pokemini_libretro.so
.pce - retroplayer.l - mednafen_pce_fast_libretro.so
.sgx - retroplayer.l - mednafen_supergrafx_libretro.so
.ws - retroplayer.l - mednafen_wswan_libretro.so
.wsc - retroplayer.l - mednafen_wswan_libretro.so
.ngp - retroplayer.l - mednafen_ngp_libretro.so
.ngc - retroplayer.x - mednafen_ngp_libretro.so
.game - retroplayer.l - dinothawr_libretro.so
.lutro - retroplayer.l - lutro_libretro.so
.nz - retroplayer.l - lowresnx_libretro.so
.p8 - retroplayer.l - retro8_libretro.so
.f8 - Pico-8 emulator
.tic - retroplayer.l - tic80_libretro.so
.32X - retroplayer.l - picodrive_libretro.so
.bin - retroplayer.9 - picodrive_libretro.so
.chd - retroplayer.l - genesis_plus_gx_libretro.so
.gg - retroplayer.l - genesis_plus_gx_libretro.so
.md - retroplayer.l - genesis_plus_gx_libretro.so
.sms - retroplayer.l - genesis_plus_gx_libretro.so
.* - retroplayer.9 - genesis_plus_gx_libretro.so

Note: For systems like this you always want "non-merged" ROM-sets, because then each game has everything it needs to run standalone. 

******************
* UPDATE PATCHES *
******************

Project NEXUS recieves update patches pretty regularly. It is important to get every update and to apply it in numbered order. It is a build up process and things may stop working if you apply an update without applying all the previous updates in order. Depending on how you extract your update, you want to find all the /rom_alt folders and possibly the /emulator and or /rom folder depending on the update, and copy them to the root of your drive. It should ask you if you want to copy over the old files, say yes. If you mess up and say no, just do it again and say yes.

****************************************************************
* INTERMEDIATE                                                 *
****************************************************************

****************
* RETROPLAYERS *
****************

Retroplayer is the "emulator LibRetro front-end" application for this device. It is analogous to RetroArch, just way leaner, not open source, and not so configurable. There are a few retroplayers available in the /emulator folder.

retroplayer.cust - The original retroplayer from the most excellent Brad_from_the_80's custom firmware.

retroplayer.l - The retroplayer from the AtGames Legends Flashback. It does not support the .a26 select button, but does allow for limited button mapping.

retroplayer.x - The Retroplayer from the most recent rom dump of an up to date, Feb 2021, Atari Flashback X. It is needed for .a26 paddle support. (Thank you Schnafe!)

retroplayer.9 - The Retroplayer from the Atari Flashback 9 - It runs the Stella core/VCS games better.

The startup.sh copies this to /tmp as just "retroplayer" where it is then referenced by the runcommand script. You can use a different retroplayer to experiment by either modifying the copy line in startup.sh, or modify the line for an individual core in "runcommand" to just reference it from the original folder (like /media/usbhd-sda1/emulator/retroplayer.afb9 instead of /tmp/retroplayer). The retroplayer is copied to /tmp because /tmp is a RAM drive. Retroplayer is restarted for each game, and the executable is much larger than the game roms (for older games). So by placing it there load times should be faster.

The AFB9 retroplayer may work better for .a26, and it is a much smaller executable than the others.  But in my experience I could not use .zip games when using it. There are some missing sprite bugs in Atari 2600 games like Asteroids, Battle Zone, Moonsweeper and Mousehunt.

***************
* DATA FOLDER *
***************

When you first "go to" a rom folder, if it does not contain a /data folder it makes a copy of the one on your actual Atari Flashback device. Inside you will find save files with art, favorites and recently played data, BGM and SD Card settings and the retroplayer.ini file. The retroplayer.ini is a key file because it has per-core and per-game settings that really impact things. There are some global settings, like On Screen Display which shows an on screen HUD with FPS counter, and a few other options. There are also some [Core] settings options. Here are some examples:

[Global]
AudioSample=50
ScanlineFilter=0
RewindStep=4
UseBezel=1
BezelPath=/tmp/cbezel.png
Language=0
UseOSD=0
MaxBlackTimeout=600

[Core]
atari800_resolution=336x240
atari800_system=130XE (128K)
atari800_ntscpal=NTSC
atari800_internalbasic=0
atari800_sioaccel=0
atari800_cassboot=0
atari800_artifacting=0
atari800_keyboard=poll
atari800_swapJoysticks=disabled
atari800_startMakesSpace=disabled
atari800_momentaryKeyboard=disabled
stella_filter=disabled
stella_crop_hoverscan=disabled
stella_ntsc_aspect=par
stella_pal_aspect=par
stella_palette=standard
stella_console=ntsc
stella_stereo=off
stella_phosphor=auto
stella_phosphor_blend=0
stella_paddle_joypad_sensitivity=0
mame2000-show_gameinfo=disabled
mame2000-skip_disclaimer=enabled
mame2003-plus_skip_disclaimer=enabled
mame2003-plus_skip_warnings=enabled
mame2003-plus_sample_rate=48000
mame2003-plus_external_hiscore=enabled
mame2003-plus_gamma=1.2
,mame2003-xtreme-mouse_device=pointer
mame2003-xtreme-mouse_device=mouse
mame2003-xtreme-use_artwork=enabled
mame2003-xtreme-skip_disclaimer=enabled
mame2003-xtreme-skip_warnings=enabled
fba-cpu-speed-adjust=100
fba-aspect=DAR
fba-diagnostic-input=None
fba-hiscores=enabled
fba-samplerate=44100
fba-sample-interpolation=disabled
fba-fm-interpolation=disabled
fbneo-cyclone=disabled
fbneo-analog-speed=200%
fbneo-samplerate=48000
fbneo-diagnostic-input="Hold Start"
fbneo-cpu-speed-adjust=100%
fbneo-frameskip=0
fbneo-frameskip-v2=disabled
fbneo-frameskip-v2-threshold=33

For example the mame2000 options must be in place for those ROMs (.zim for mame2000 ROMs .zip for final burn alpha ROMs). The fba-cpu-speed setting has an impact on performance, and so on. You can also use settings for games on an individual basis. An entry would look like this:

[TailofBetaLyrae.xex]
atari800_system=800XL (64K)

Note: If your /rom_alt/data/retroplayer.ini file ever becomes corrupted, there is a retroplayer.bak backup file in the same folder as well. Just delete your corrupted file, make a copy of the retroplayer.bak file and name it retroplayer.ini and replace your old file.

**************
* KEYMAPPING *
**************

To even be able to map your keys the ROM has to be ran using the Legends Flashback retroplayer L. To set the buttons go to /rom_alt/data/retroplayer.ini and edit it with notepad. Here is the legend so you know what button corresponds to what number.

#RETRO   B    Y    SLT  STA  UP   DWN  LEFT RGT  A    X    L    R    L2   R2   L3   R3
#INDEX   0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15

Here is an example of a key mapping entry.

[KeyMappingUser]
MarioBros.nesl=0, 1, 9, 8, 10, 11

Note: The special .nesl extension that is used so that the ROM is ran using the retroplayer L and buttons can be changed. In this case the A and B buttons were swapped so that this previously unplayable one-button game is now playable.

*************************
* ADDING GAMES WITH ART *
*************************

To add games with art to one of the various /rom_alt folders you need a working, compatible ROM with the same naming conventions as the /game folder ROMs, no spaces, periods, brackets, etc. You will also need a large thumbnail and a small thumbnail. The large thumbnail needs to be 183 x 255 pixels, the smaller one needs to be 122 x 170 pixels. If there are no thumbnails, it will still work but have blank art showing in-game. Optionally you can create a custom bezels that is 1280 x 720 pixels. All the art files need to be in .png format and named exactly the same as the ROM name in the case of the large art. Small thumbs get a letter "s" at the end of the filename. Bezels get the letter "b" at the end. Here is an example:

millipede.zip         - ROM file
millipede.zip.png     - Large thumbnail
millipede.zip.s.png   - Small thumbnail
millipede.zip.b.png   - Custom bezel

You will also need to create an entry in the same /rom_alt folder's all-games.ini file. An example of an entry looks like this:

[Piracy]
File=/rom/PIRACY.bas
Platform=BASIC
Sort=Piracy 1 0
Year=1982
Genre=Anschuetz/Weisgerber/Anschuetz
Description=In the game of Piracy, the player navigates a ship using a map. The goal isto collect treasure before your immediate or overall damage is too great, arewere rammed by a ship, or you use too much fuel.
Note=Anschuetz/Weisgerber/Anschuetz 1982

File= is always /rom/exactnameofgame.rom (not /rom_alt/exactnameofgame.rom)
Platform= should reflect the console/system the ROM is played on. (It has no impact in-game)
Sort= sorts the games alphabetically in the in-game main menu. Captialized letters show up before lowercase letters. Use the number 1 after games in a series so the first one shows up first in the list. Like Sort=Sonic 1 and Sort=Sonic 2 (or 3).
Year= is the year the game was published (It has no impact in-game)
Genre= can be "atari" for games to show in the Atari Game list, "paddle" to show in the Paddle Games list, "atari, paddle" to show in both lists. (Anything else you may wish to note will have no impact in-game)
Description= is a short game summary. Descriptions that are too long will bog down or even lock up the in-game menu.
Note= Add the publisher and year of publishing if known. (You must add something here or the Description= text will not display properly) (Thanks to RRA for all the work on descriptions!)

*****************
* CUSTOM BEZELS *
*****************

The enable for the custom bezels is to have a dbezel.png bezel art file in your /emulator folder. This will be the default bezel for any rom folder with a custom theme in it. Remove this file to turn off the mechanism. It should be 1280 x 720 pixels in .png format. (Thanks to The Bezel Project for all of the pre made bezels.)

You must then edit and modify the /rom_alt/data/retroplayer.ini for any /rom_alt folder with custom bezels so that the global setting is /tmp/cbezel.png.  The lines will look like this:

[Global]
UseBezel=1
BezelPath=/tmp/cbezel.png

For any game that you wish to have a custom bezel, name it similar to the cover artwork's small thumbnail, but with a "b" for bezel instead of "s" for small. For example, if the game file is: Sonic3.bin, then the art files are Sonic3.bin.png and Sonic3.bin.s.png. The bezel file would then be Sonic3.bin.b.png with a total size of 1280 x 720 pixels in .png format.

Note: You can optionally have a file /rom_alt/data/res/images/dbezel.png which will act as the default bezel for a particular custom theme.

If you break the custom bezels file path by selecting one of the systems theme bezels on the options settings page, use the Restore (custom bezels) command switch to fix it.

****************************************************************
* ADVANCED                                                     *
****************************************************************

**************************
* RETROMENU & RUNCOMMAND *
**************************

The retromenu.run and runcommand files must be kept in the /emulator folder. The startup.sh (placed in the root of the SD Card/Flashdrive) works with those to manage switching between ROM-sets and starting games. Multiple themes are now supported. If you add a /res (resources) folder into a particular /rom_alt folder it will be picked up when the "go to" that rom folder occurs. If there is not a /res folder for a /rom_alt folder, the system will instead use the default theme from the /emulator/res folder.

The runcommand script is a wrapper script which retromenu uses to launch all the games. It has a case statement for each ROM extension that runs one of the various retroplayers with the correct core to load the game. The case statement can be customized or extended easily if desired. Currently GenPlusGX is the default core for any unrecognized extensions. You can support as many extensions as needed for the same core just by copying that section of the case and changing the extension.

*************************
* GOTO & OTHER COMMANDS *
*************************

"Go to" lets you do anything you want. You can have a carousel of rom folders, or have a tree, or forward and back entries, or any combination. You can name the new /rom folders anything you want. You can stick with "/rom_alt" and so on, or call them anything more descriptive like /homebrew. You still must have a /rom folder which is where the system starts.

If you want to go to a /rom_alt_1 folder create the two artwork files for it and add an entry in the all-games.ini file inside the rom folder.  Some example files and all-games.ini entries are in the other /rom_alt folders. The .goto extension (all lower case) is what triggers the switch. The first part of the artwork's file names, the all-games.ini entry and the new /rom_alt folder name must match exactly, including the case.

The others are mainly examples to show how utility commands can be implemented in the mechanism. They are handled as special cases in the runcommand script. If you add a command I highly recommend a development stage where you are echoing your command to the command.txt log file before you even start to execute it.  You are excuting as root on the device and things can get messed up! For an example of logging, look at the line "echo "command not supported:  $filename" >>/media/usbhd-sda1/command.txt" which is already in runcommand.  The >> in linux appends to the log file. Restore custom bezels command was added if the path to the custom bezels gets broken.

**********************
* MULTI-BUTTON GAMES *
**********************

Multi-button games are supported by expoiting the player 2 controls as additional inputs for player one. Meaning you will not be able to play multi-button games with a second player simultaneously because player one will be using both controller ports.

Some users have wired two Atari joysticks into a 6-button arcade fightstick case. Others have come up with inexpensive solutions to couple two Atari Joysticks together. Note: Only some cores currently support using the player 2 controls for player 1. The various Mame and the Atari 800 and 7800 ProSystem cores to name a few.

Noteably the Atari 800 core gets constant updates by RocketFan and has had some extra changes made to get lots of Atari 8 bit Home Computer (and Atari BASIC and 5200) games to be very playable. Here are examples of the core options which have been added in support of the AtGames Atari Flashback devices to date:

"atari800_mapkeysJ2",
"Key mappings for Atari Flashback joystick 2 (retro_key values); #,#,#,#,#",

"atari800_mapkeys",
"Key mappings for legends flashback A,C,X,Y buttons (retro_key values); #,#,#,#",

"atari800_fireA",
"Fire with retro A button (for LFB) instead of retro B button (for AFB); disabled|enabled",

"atari800_combineActions",
"Combine the retro B button with retro A button (for AFB trigger both from a single button); disabled|enabled",

"atari800_swapJoysticks",
"Swap the player 1 and 2 joysticks for game play; disabled|enabled",

"atari800_momentaryKeyboard",
"Keyboard will auto-close after each character pressed.; disabled|enabled",

"atari800_startMakesSpace",
"Pressing start will also emit a keyboard space.; disabled|enabled",

"atari800_J2FA2",
"Use Joystick 2 fire button as second action button.; disabled|enabled",

Note: The atari800_combineActions and atari800_J2FA2 options can't play together.  They are two different ways to trigger the second action for 5200 games.  If both are set then combineActions will take priority.

************************
* RETROK NUMERIC CODES *
************************

Create an entry for your game in the /rom_alt/data/retroplayer.ini in the appropriate folder where your game resides - or wherever you will be launching it from if you will be running it from the /game folder. The entry looks like this:

[defender.xex]
atari800_mapkeysJ2=#,#,#,#,# 

Comma delimited, where it provides keys for the Fire, Up, Down, Left and Right on Joystick 2, in that order. Use 0 (zero) to skip a position.

   RETROK_UNKNOWN        = 0,
   RETROK_FIRST          = 0,
   RETROK_BACKSPACE      = 8,
   RETROK_TAB            = 9,
   RETROK_CLEAR          = 12,
   RETROK_RETURN         = 13,
   RETROK_PAUSE          = 19,
   RETROK_ESCAPE         = 27,
   RETROK_SPACE          = 32,
   RETROK_EXCLAIM        = 33,
   RETROK_QUOTEDBL       = 34,
   RETROK_HASH           = 35,
   RETROK_DOLLAR         = 36,
   RETROK_AMPERSAND      = 38,
   RETROK_QUOTE          = 39,
   RETROK_LEFTPAREN      = 40,
   RETROK_RIGHTPAREN     = 41,
   RETROK_ASTERISK       = 42,
   RETROK_PLUS           = 43,
   RETROK_COMMA          = 44,
   RETROK_MINUS          = 45,
   RETROK_PERIOD         = 46,
   RETROK_SLASH          = 47,
   RETROK_0              = 48,
   RETROK_1              = 49,
   RETROK_2              = 50,
   RETROK_3              = 51,
   RETROK_4              = 52,
   RETROK_5              = 53,
   RETROK_6              = 54,
   RETROK_7              = 55,
   RETROK_8              = 56,
   RETROK_9              = 57,
   RETROK_COLON          = 58,
   RETROK_SEMICOLON      = 59,
   RETROK_LESS           = 60,
   RETROK_EQUALS         = 61,
   RETROK_GREATER        = 62,
   RETROK_QUESTION       = 63,
   RETROK_AT             = 64,
   RETROK_LEFTBRACKET    = 91,
   RETROK_BACKSLASH      = 92,
   RETROK_RIGHTBRACKET   = 93,
   RETROK_CARET          = 94,
   RETROK_UNDERSCORE     = 95,
   RETROK_BACKQUOTE      = 96,
   RETROK_a              = 97,
   RETROK_b              = 98,
   RETROK_c              = 99,
   RETROK_d              = 100,
   RETROK_e              = 101,
   RETROK_f              = 102,
   RETROK_g              = 103,
   RETROK_h              = 104,
   RETROK_i              = 105,
   RETROK_j              = 106,
   RETROK_k              = 107,
   RETROK_l              = 108,
   RETROK_m              = 109,
   RETROK_n              = 110,
   RETROK_o              = 111,
   RETROK_p              = 112,
   RETROK_q              = 113,
   RETROK_r              = 114,
   RETROK_s              = 115,
   RETROK_t              = 116,
   RETROK_u              = 117,
   RETROK_v              = 118,
   RETROK_w              = 119,
   RETROK_x              = 120,
   RETROK_y              = 121,
   RETROK_z              = 122,
   RETROK_LEFTBRACE      = 123,
   RETROK_BAR            = 124,
   RETROK_RIGHTBRACE     = 125,
   RETROK_TILDE          = 126,
   RETROK_DELETE         = 127,

   RETROK_KP0            = 256,
   RETROK_KP1            = 257,
   RETROK_KP2            = 258,
   RETROK_KP3            = 259,
   RETROK_KP4            = 260,
   RETROK_KP5            = 261,
   RETROK_KP6            = 262,
   RETROK_KP7            = 263,
   RETROK_KP8            = 264,
   RETROK_KP9            = 265,
   RETROK_KP_PERIOD      = 266,
   RETROK_KP_DIVIDE      = 267,
   RETROK_KP_MULTIPLY    = 268,
   RETROK_KP_MINUS       = 269,
   RETROK_KP_PLUS        = 270,
   RETROK_KP_ENTER       = 271,
   RETROK_KP_EQUALS      = 272,

   RETROK_UP             = 273,
   RETROK_DOWN           = 274,
   RETROK_RIGHT          = 275,
   RETROK_LEFT           = 276,
   RETROK_INSERT         = 277,
   RETROK_HOME           = 278,
   RETROK_END            = 279,
   RETROK_PAGEUP         = 280,
   RETROK_PAGEDOWN       = 281,

   RETROK_F1             = 282,
   RETROK_F2             = 283,
   RETROK_F3             = 284,
   RETROK_F4             = 285,
   RETROK_F5             = 286,
   RETROK_F6             = 287,
   RETROK_F7             = 288,
   RETROK_F8             = 289,
   RETROK_F9             = 290,
   RETROK_F10            = 291,
   RETROK_F11            = 292,
   RETROK_F12            = 293,
   RETROK_F13            = 294,
   RETROK_F14            = 295,
   RETROK_F15            = 296,

   RETROK_NUMLOCK        = 300,
   RETROK_CAPSLOCK       = 301,
   RETROK_SCROLLOCK      = 302,
   RETROK_RSHIFT         = 303,
   RETROK_LSHIFT         = 304,
   RETROK_RCTRL          = 305,
   RETROK_LCTRL          = 306,
   RETROK_RALT           = 307,
   RETROK_LALT           = 308,
   RETROK_RMETA          = 309,
   RETROK_LMETA          = 310,
   RETROK_LSUPER         = 311,
   RETROK_RSUPER         = 312,
   RETROK_MODE           = 313,
   RETROK_COMPOSE        = 314,

   RETROK_HELP           = 315,
   RETROK_PRINT          = 316,
   RETROK_SYSREQ         = 317,
   RETROK_BREAK          = 318,
   RETROK_MENU           = 319,
   RETROK_POWER          = 320,
   RETROK_EURO           = 321,
   RETROK_UNDO           = 322,
   RETROK_OEM_102        = 323,

*********************
* DIAGNOSTIC OUTPUT *
*********************

You can get diagnostic output from a core by modifying the runcommand (runcommand.lfb on a legends flashback) file in the /emulator folder.  A typical core startup case/command looks like this:

"nx")
  /usr/bin/startx /tmp/retroplayer.l ${dev}/emulator/lowresnx_libretro.so $gm >/dev/null 2>&1 ;# >${dev}/output_nx.txt
   ;;

The ;# starts a commented-out section of the line.

Normally any output goes to /dev/null meaning in Linux it is just thrown away.  That is healthy because you don't want to write any more data to a flash drive than needed - they are slow and have limited life in terms of writes.  However, some useful information can be output by the cores such as the expected core settings (set in retroplayer.ini - see above) and sometimes information on errors.

To enable the output, remove the /dev/null and comment parts and modify the line to this:
/usr/bin/startx /tmp/retroplayer.l ${dev}/emulator/lowresnx_libretro.so $gm >${dev}/output_nx.txt

Or you can include error output by adding the 2>&1 part at the end:
/usr/bin/startx /tmp/retroplayer.l ${dev}/emulator/lowresnx_libretro.so $gm >${dev}/output_nx.txt 2>&1

Then run your game.  After you exit, the output buffer may not be flushed to disk, so I recommend you navigate to the shutdown option and use that, which will be sure to flush the output to the file output_nx.txt (or whatever matches the core) in the root of your drive.

When done you should put the line back to the original >/dev/null 2>&1 state by following the example in another case from the file.

************
* GPIO MAP *
************

AFBX:
P1 Up....................1192
P1 Down..................1193
P1 Left..................1194
P1 Right.................1195
P1 Fire..................1196
Left Difficulty..........1197
Right Difficulty.........1198
P2 Up....................1081
P2 Down..................1082
P2 Left..................1083
P2 Right.................1084
P2 Fire..................1085
Select...................1086
Start....................1087

AFB9:
P1 Up....................1035
P1 Down..................1032
P1 Left..................1036
P1 Right.................1034
P1 Fire..................1037
Left Difficulty..........1075
Right Difficulty.........1082
P2 Up....................1009
P2 Down..................1026
P2 Left..................1014
P2 Right.................1017
P2 Fire..................1027
Select...................1089
Start....................1086

Use GPIO from a script as in this example:

#Tell Linux we want to have access to gpio pin 1197
echo 1197 > /sys/class/gpio/export
#Set it as an input pin (probably defaults that way)
echo "in" > /sys/class/gpio/gpio1197/direction
#Read the value and store it.
cat /sys/class/gpio/gpio1197/value >${dev}/gpio1197.txt

#Tell Linux we want to have access to gpio pin 1198
echo 1198 > /sys/class/gpio/export
#Set it as an input pin (probably defaults that way)
echo "in" > /sys/class/gpio/gpio1198/direction
#Read the value and store it.
cat /sys/class/gpio/gpio1198/value >${dev}/gpio1198.txt

*********
* TOOLS *
*********

In the /emulator/tools folder you will find all kinds of programs and help for these devices and the Exit Game Shortcut. Advanced Renamer lets you remove spaces, periods and brackets, change or add extensions, etc. to large numbers of filenames at once. Flexxi Art Resizer does just what it says to large batches of images, you can even convert files to .png format. The all-games.ini maker was lifted from the Legends Flashback. While it should be noted that it won't fill in every section of the all-games.ini entry correctly, it is a huge time saver and ensures that ROM filenames match. There are also drivers, tools and instructions on how to flash the AFBX and AFBX Deluxe 2019 models without the reset hole on the bottom of the console.

****************************************************************
* SPECIAL THANKS                                               *
****************************************************************

An Extra Special Thanks goes out to R.Rifonas AKA RMR_MD, Brad "From the 80's" and Mr. Fister for the Custom Firmware that makes all of this possible. Also, thank you very much to the many, many members of the AtariAge Forums who have helped to make this community project even better over the years! You can find their names all throughout the NEXUS!

****************************************************************
*                                             ©2021 BitLifters *
****************************************************************