How does it work - venice1200/MiSTer_tty2oled GitHub Wiki

MiSTer

When the MiSTer boots up the script S60tty2oled is called from the MiSTer's Startup System.
This script does nothing more than calling the script tty2oled.sh in /media/fat/tty2oled/ and sent it to the background,
but only if tty2oled.sh is found and is executable.
The script tty2oled.sh checks at first the system for the device /dev/ttyUSB0.
If the device is not found the scripts ends here.
If the device is found the tty-device parameter are set with the stty command.
Now the script sends an First Transmission.
First Transmission?
During my tests I got sometimes weird display startup behavior when the MiSTer's was powerred on.
Sometimes the text MENU was written instead of the MiSTer Picture shown.
Maybe some sleeping bits in the serial channel :smirk:.
After I added the First Transmission to the script the problem was gone 😃.
Now the main loop is started and checks the existence of the file /tmp/CORENAME.
If the file doesn't exist the script tries again and again and ...
If the file exists, the file's content is read using cat /tmp/CORENAME,
stored into the variable newcore and send to the tty Device (Standard and SD Version).
The new USB-Version sends the Picture-Data or the Corename to the ESP (see below).
At the end of the main loop the script waits for the next change of /tmp/CORENAME and re-starts the loop.
Every loop the Corename is checked but data are sent only if the Corename has changed.

Arduino (Standard Version) --Deprecated--

The Arduino receives the transferred Corename.
If the Corename is within a list of known Names the corresponding picture is shown.
If the Corename is unknown just the Corename is shown.
The used font for the Text can be changed within the Arduino Code.
See the list of fonts for all in the Library included fonts.
To prevent Display flickering the Text or Picture is only updated if the received Corename has changed.

Known Corenames
The following Corenames are identified and an dedicated or generic Picture is shown.
Arcade:
asteroid, atetris, atetrisc, centiped, centiped3, dkong, dkongdks, dkong3, dkong3b, frogger,
llander, mooncrgx ,mpatrol, pong, pooyan, popeye, sbrkout, zaxxon
Computers:
AcornAtom, AO486, APPLE-I, Apple-II, ARCHIE, AtariST, ATARI800, C64, Minimig, MSX, PET2001, VIC20
Console:
ATARI2600, ATARI5200, ATARI7800, AtariLynx, Astrocade, ChannelF, Coleco, GAMEBOY, GBA, Genesis,
MEGACD, NEOGEO, NES, ODYSSEY, Playstation, SMS, SNES, TGFX16, VECTREX
Other:
CHESS, MEMTEST, MENU (Menu Logo fading in with an particle effect), QWERTZ (first transmission).

Tip: Check the Arduino Code of the Standard Version for Supported Corenames.

Arduino (SD Version)

The SD Version supports the live download of Pictures from SD Card. No need to keep the Pictures in Code.
You need an Arduino compatible Hardware plus/with an SD Slot/Breakout.
I use an ESP32 TTGO-T8 v1.7.1 with an integrated SD Slot.
The SD Card must be formatted with FAT or FAT32.
If the SD Card was found an SD-Card Icon is shown on the Startup Screen.
The Arduino Sketch searches for the XBM converted pictures in the root folder of the SD Card.
The Pictures must have the size of 256x64 Pixel for the used SSD1322 Display.
The filename must be the same as the name of the core plus .xbm as extension.
Example: The Arcade Lunar Lander has the corename llander means the filename needs to be llander.xbm.
The Arduino receives the transferred Corename and checks the SD Card for an corresponding file.
If the file is found it's loaded and shown on the Display.
If the file or the SD card is not found just the Corename is shown as Text.
With the SD Card it's easy to add or update the Pictures by adding or changing the files on the SD Card.
▶️ Just get all files from XBM Folder and copy them to your SD Card.

Arduino (USB Version)

Github User ojaksch created an tty2oled version which sends the Picture-Data via USB-Serial from the MiSTer to the ESP.
I took the Magic out of his Version and built the new USB-Version.
You need to copy the XBM/GSC Pictures to the MiSTer into the folder /media/fat/tty2oled/pics/[XBM/GSC].
If the Corename has changed the tty2oled.sh script checks at first the folder /media/fat/tty2oled/pics/[XBM/GSC] .
If the folder doesn't exist it's assumed that the SD-Version is used and only the Corename is sent.
If the folder exists the script searches for an corresponding GSC/XBM file in /media/fat/tty2oled/pics/[XBM/GSC].
For your Personal Pictures use the folder /media/fat/tty2oled/pics_pri.
Pictures in this folder are used with priority.

The next steps depends on which command mode is used.
Old Command Mode:
If an XBM file is found the short text "att" is sent from the MiSTer to the ESP. This announces another Text to be sent.
Now the text "CORECHANGE" is sent. This informs the ESP that Picture-Data will be send at next.
New Command Mode:
If an XBM/GSC file is found the command "CMDCOR,[Corename]" is sent from the MiSTer to the ESP.
This informs the ESP that Picture-Data will be send at next.

The command tail -n +4 "${picturefolder}/${1}.xbm" | xxd -r -p > ${TTYDEV} is used on the MiSTer to sent the Picture-Data to the ESP.
If no XBM file is found only the Corename is sent.
▶️ You can use now the MiSTer's SMB Share to copy new Pictures to the MiSTer's Filesystem.
No need to modify the code or to remove the SD Card.
▶️ With the new USB-Version Installer/Updater you can install and update the tty2oled Scripts, Pictures and the Device Firmware from the MiSTer's Script Menu.
▶️ The requirements for the XBM Pictures are the same as for the SD-Version.
▶️ With an later Version we introduced GSC Pictures which allows the usage of 16 Greyscale Level Pictures.
See https://github.com/venice1200/MiSTer_tty2oled/wiki/Build_GSC_Gimp

Core with Picture

Core shown by name

Technical Note:
The SD Version uses an dedicated SPI Interface because of issues using an OLED and an SD Card together on one ESP32 SPI Interface.

Sleepmode Note
If you running tty2oled on the MiSTer System and you like to set the tty2oled script control "on-hold" use the sleepmode.
Create the file "/tmp/tty2oled_sleep" and the tty2oled Dameon goes to sleep.
Remove the file and the tty2oled Daemon goes back to work.