Fix and enhancements for rpi-retroflag-AdvancedSafeShutdown.py

[FlashyDuck]

PROBLEM
The current script does not do a proper shutdown of the hardware.

FIXED

• POWER button press fixed - hardware shuts off now

ENHANCEMENTS

• Added a user configuration section at the top of the screen with the following options:

1. RESET button press threshold (reset ES | reboot)
2. LED blink and timing when a button is pressed to acknowledge button press
3. LED blinks and timing for each button press action
4. custom splash image for short/long RESET and POWER press
5. custom single splash image for all button presses
6. fallback splash images - uses Batocera system defaults
7. framebuffer delay for splash*

• I had issues with getting the splash not being shown on screen. I tried to time stopping ES manually and showing an image on screen. This all is basically instant (0.1s). But it really needs around 5.5s for the framebuffer to actually be ready and able to show the splash. Otherwise the splash duration will start, but the splash won't be visible on the screen. I have made this user configurable, because I have tested this with a SSD. I can imagine that the use of a hdd needs a longer wait time.

Note:
First time coding - This script was developed with assistance from several AI tools to help with code structure, debugging, and optimization.

Hardware:

• Retroflag Nespi 4 Case
• Raspberry Pi 4B 4GB
• Crucial MX100 SSD

[crcerror]

PowerEN never should setted to low this will cause in an immediate power cut and you will lose meta-data.

There is a good reason that even retroflag (the manufacturer does not use this).

[FlashyDuck]

@crcerror Okay, that's not good. I made an assumption based on the analysis of ai (claude, chatgpt and deepseek all came up with this solution after analyzing this script and the official retroflag script). And it was working, so it seemed right to me. But yeah, we don't want to loose metadata. I'll go back to the drawing board.

Do you have an idea why the original script doesn't shut off the power? Any thoughts on the other changes?

[crcerror]

I do not know why the current script isn't working for you. Can you check in /boot/boot/config.txt how many entries with dto-overlays are set active? The one with gpio-poweroff or gpio-shutdown is not the correct one.

[FlashyDuck]

@crcerror So it is working for you? V41? When I have time next week I'll start from scratch and give you the answer.

But I was thinking about what you said about PowerEN; I think this script still mitigates that issue with the metadata, because I'm stopping ES before any command. Stopping ES saves the metadata, right? Maybe not pretty, but it works?

[crcerror]

Yes quitting ES before will save metadata. Yes dman and me tested the script for v41 with Pi3 (on myself) and Pi4 (by User report) on NesPi+ housings - so the answer if it worked is yes.

[crcerror]

Nevertheless I think your additions are nice but the customised part could be made better with an external config file. See, nobody wants to edit a system file and use an overlay for making changes permanent. So in current state I doubt the PR will be accepted.

@dmanlfc
@bryanforbes
Please review

[FlashyDuck]

@crcerror So not tested with a Nespi 4 Case and RPI 4b? Is there possibly something different with this combo? If not, then it must be something on my end. I'll dig into it next week.

And yes, not accepting the PR is completely understandable. Although it seems to be working fine with a Nespi 4 case, the basis of this PR seems to be completely wrong, that this script wasn't working in the first place. First need to diagnose that before adding the enhancement seems to be the best route.

The config file was indeed mentioned as a possible enhancement of this script, but I wasn't sure if this was allowed for such a specific script and how I needed to implement this. I know Retroflag script creates a Retroflag folder inside /userdata/. Would that be the preferred way? My thinking was based on reading the wiki https://wiki.batocera.org/splash_boot#changing_emulationstation_s_default_loading_splash where using batocera-save-overlay was already being used to change the ES or boot splash so I didn't think my approach was that different.

[crcerror]

I rechecked the discussion that was done and test were performed on a Pi4 and NESPi 4 case.

It would be nice if you could check your config file in boot partition for dto overlays

[FlashyDuck]

@crcerror Okay, that's really strange...

I have written down exactly what I did yesterday.

TLDR: No difference in dtoverlay? Retroflag touches the dtbo file, but nothing is changed? Only other difference I have found is the use of the shutdown command. Changing that in rpi-retroflag-AdvancedSafeShutdown makes it work. Used that in my script, removed the PowerEN pin parts and implemented your suggestion of a config.py file.

My findings;

• The Retroflag install script does something with the .dtbo file which you can see by the date change of the file. But the size does not change. I used https://filext.com/file-extension/DTBO to check the contents and the readable text is the same.
• Only difference I could find between both solutions is the way the shutdown command is used.

So I went ahead and tested the rpi-retroflag-AdvancedSafeShutdown script by changing the --shutdown to --reboot and shutdown -h to shutdown -r. Then it works the same way the official Retroflag script behaves. Also tried changing the official Retroflag script from shutdown -r to shutdown -h, but that results in the same problem.

Hardware used:
Nespi 4 Case
Safe Shutdown Switch on the PCB is ON - checked
RPI 4B 4GB
MX100 and EVO 860 ssd

Using Batocera Script

• Clean flash batocera V41
• First boot
• /boot/config.txt
  dtoverlay=vc4-kms-v3d
• Uncomment /userdata/system/batocera.conf
  system.power.switch=RETROFLAG_ADV
• Saved
• Reboot (2x)
• /boot/config.txt
  dtoverlay=vc4-kms-v3d
  dtoverlay=RetroFlag_pw_io.dtbo
• Backup dtbo file
• LED is working
• Reset restarts ES - working
• Power shutsdown Batocera but fan and red LED on RPI stay on - not working
• Waited for like 5 minutes - no change
• Press Power again boots up Batocera
• Press Power for shutdown - same result - red LED on RPI stay on

Using Official Retroflag Script

• Clean flash batocera V41
• First boot
• /boot/config.txt
  dtoverlay=vc4-kms-v3d
• wget -O - "https://raw.githubusercontent.com/RetroFlag/retroflag-picase/master/batocera_install.sh" | bash

 --2025-03-24 10:43:06--  https://raw.githubusercontent.com/RetroFlag/retroflag-picase/master/batocera_install.sh
 Resolving raw.githubusercontent.com... 185.199.110.133, 185.199.111.133, 185.199.108.133, ...
 Connecting to raw.githubusercontent.com|185.199.110.133|:443... connected.
 HTTP request sent, awaiting response... 200 OK
 Length: 1967 (1.9K) [text/plain]
 Saving to: ‘STDOUT’

 -                                                               100%[====================================================================================================================================================>]   1.92K  --.-KB/s    in 0s

 2025-03-24 10:43:06 (10.8 MB/s) - written to stdout [1967/1967]

 --2025-03-24 10:43:08--  https://raw.githubusercontent.com/RetroFlag/retroflag-picase/master/RetroFlag_pw_io.dtbo
 Resolving raw.githubusercontent.com... 185.199.110.133, 185.199.111.133, 185.199.108.133, ...
 Connecting to raw.githubusercontent.com|185.199.110.133|:443... connected.
 HTTP request sent, awaiting response... 200 OK
 Length: 730 [application/octet-stream]
 Saving to: ‘/boot/overlays/RetroFlag_pw_io.dtbo’

 /boot/overlays/RetroFlag_pw_io.dtbo                             100%[====================================================================================================================================================>]     730  --.-KB/s    in 0s

 2025-03-24 10:43:09 (8.92 MB/s) - ‘/boot/overlays/RetroFlag_pw_io.dtbo’ saved [730/730]

 PW IO enabled.
 UART fix.
 power switch fix.
 --2025-03-24 10:43:13--  https://raw.githubusercontent.com/RetroFlag/retroflag-picase/master/batocera_SafeShutdown.py
 Resolving raw.githubusercontent.com... 185.199.109.133, 185.199.110.133, 185.199.108.133, ...
 Connecting to raw.githubusercontent.com|185.199.109.133|:443... connected.
 HTTP request sent, awaiting response... 200 OK
 Length: 2154 (2.1K) [text/plain]
 Saving to: ‘/userdata/RetroFlag/SafeShutdown.py’

 /userdata/RetroFlag/SafeShutdown.py                             100%[====================================================================================================================================================>]   2.10K  --.-KB/s    in 0s

 2025-03-24 10:43:13 (8.82 MB/s) - ‘/userdata/RetroFlag/SafeShutdown.py’ saved [2154/2154]

 grep: /userdata/system/custom.sh: No such file or directory
 Executable script configured.
 RetroFlag Pi Case Switch installation done. Will now reboot after 3 seconds.

• Extra Reboot
• /batocera.conf
  system.power.switch=RETROFLAG
• /boot/config.txt
  dtoverlay=vc4-kms-v3d
  dtoverlay=RetroFlag_pw_io.dtbo
• Backup dtbo file
• LED is working
• Reset press restarts ES - working
• Power press blinks LED, shutsdown Batocera and turns off the case - working

Because --reboot and shutdown -r were working I went ahead with that solution and have rewritten my script. Also implemented your suggestions and split the user part to a config.py file.

• Removed the PowerEN Pin parts from the script and switched to using 'shutdown -r now'
• Moved the user configuration section to a config.py file (using /userdata/system/configs/retroflag/)
• Tested this and everything is working. After making changes to config.py only a reboot is required for changes to take effect.

So I guess this PR is already outdated haha. Should I close this and open a new one or should I just change the files in my fork?

I'll wait with doing anything until we have figured out the shutdown -h problem. Lets me know if you need more info.

[crcerror]

You do not need to worry about RetroFlag_pw_io.dtbo it's the same - it's a copy of the one from retroflag.
About the shutdown -h command - it is simply the halt-state for the CPU maybe poweroff works.
But these are only sideeffects I'd say...

So what is correct:
First and Second-boot setups the dto. Then you have no other relevant regarding this running.

So what is off:
Well if you run the batocera-installer it will setup a custom.sh file and will load the script, too.
And I often talked in discrod about .... The old rpi.GPIO and the new gpiod seem to different init the GPIOs. I had some serious effects in setting up those.
@dmanlfc What do you think?

@FlashyDuck Did all work with v39? This was the last version using rpi.GPIO lib, just to check if nothing is off with your case. But I doubt because you showed me clean tests.

[FlashyDuck]

@crcerror

Retroflag_ADV in V39 works (nespi 4 and rpi 4b)

Remembered I had an Nespi Plus case laying around... Put in a rpi 3b+

• V41 works with Retroflag_ADV
• Changed the script to reflect my changes, so --shutdown to --reboot and shutdown -h to shutdown -r. This works as well.

So riddle me this; why does Retroflag_ADV V41 work on the NESPi Plus case and not the NESPi 4 case? The pins being used are the same. So it's either something with the case or the rpi 4. Because you mentioned that V41 was tested with a nespi 4 and rpi 4b, then this excluded the case. The only thing I can think of that it's a firmware thing with rpi 4b?

So installed Raspberry Pi OS to check the eeprom...

BOOTLOADER: update available
CURRENT: THU MAY 11 06:26:03 AM UTC 2023 (1683786363)
LATEST: TUE FEB 11 05:00:13 PM UTC 2025 (1739293213)
RELEASE: default (/usr/lib/firmware/raspberrypi/bootloader-2711/default)
Use raspi-config to change the release.

VL805_FW: Dedicated VL805 EEPROM
VL805: upt to date
CURRENT: 000138c0
LATEST: 000138c0

Updated. Reflashed V41. No luck. Still not working.

So I'm really out of ideas here...

[crcerror]

Okay thanks for feedback about v39
I added all this scripts from Batocera 5.22/5.23 up to v39
I never tested a NesPi4 case and used Pi4B, P3B+, Pi3A+, P3B, P2B to test them with NESPi+ case

You already pointed it out. There is no difference in connecting between these 2 cases.....
But with the Pi4 I had to add a gpio-shutdown overlay dto during boot.

So you are also right for your outfindings --- the Pi4 behaves completely differently compared to its predecessors.

Sooooo.... you confirmed a working v39, then the last conclusion I can made ... There is something wrong in the script

Please explain: You say if you change from shutdown -h to shutdown -r then this works?
-h means HALT and sets the CPU to deepsleep
-r simply means REBOOT

And if I apply these changes to a Pi3 then -r would reboot the board, and -h would cut power :)
So the changes from Pi4 to Pi3 are totally different.

It would be nice if you would join discord. From here be can better bisect the issue.

[FlashyDuck]

@crcerror

But with the Pi4 I had to add a gpio-shutdown overlay dto during boot.

Can you explain this further? Because it's definitely a Pi 4B issue.

Pi 3B+ works in both Nespi 4 and Nespi Plus case - shutdown and power is cut. Fan stops. So no case issue.
Pi 4B doesn't work in either case - shutdown, but power stays on. Red LED on Pi stays on. Fan keeps spinning.

You say if you change from shutdown -h to shutdown -r then this works?
-h means HALT and sets the CPU to deepsleep
-r simply means REBOOT

And if I apply these changes to a Pi3 then -r would reboot the board, and -h would cut power :)
So the changes from Pi4 to Pi3 are totally different.

Yes, changing it to reboot makes everything work. It starts to reboot but shortly after that cuts power. Like I mentioned in the issue topic, by changing the code to this makes it work:

elif event_line_offset == POWER_PIN:
    print("POWER button pressed")
    try:
        output = int(subprocess.check_output(['batocera-es-swissknife', '--espid']))
        if output:
            subprocess.run("batocera-es-swissknife **--reboot**", shell=True, check=True)
        else:
            subprocess.run("shutdown **-r** now", shell=True, check=True)
    except Exception as e:
        print(f"Poweroff command error: {e}")

It's basically the exact same thing that the official Retroflag script does. They also only use shutdown -r now.

Tested above code with he Pi 3B+ in a Nespi Plus case and this works exactly the same as the Pi 4B and/or Nespi 4 case.

• Press power button
• Screen goes black - Batocera shuts down
• LED on case goes out - fan still spinning - LEDS on rpi still working
• LED on case goes on
• Everything shuts off after a few seconds

Are the GPIO pins 'reset' when rebooting? And can they detect the position of the Power button? I'm just guessing here...

[crcerror]

But with the Pi4 I had to add a gpio-shutdown overlay dto during boot.
Can you explain this further? Because it's definitely a Pi 4B issue.

Yes, as I got my Pi4 - I saw that it did not work properly with the cases. So I added the line below to /boot/config.txt and then it worked. This worked till v39 as the change from rpi.GPIO to gpiod was done. So let's say .... 3-4 years it worked without any problem.

dtoverlay=gpio-poweroff,gpiopin=4,active_low=1,input=1

With the change to gpiod this did not work proper anymore and we switched to the one from retroflag.

Are the GPIO pins 'reset' when rebooting? And can they detect the position of the Power button? I'm just guessing here...

I really can't say about it. But let me retry later on Pi3B. But this is a good explaination of things I was facing.
So if you release the power-button then the circuit is interrupted and maybe it checks on reboot if it's enabled or not.
So if you reboot with shutdown -r then the circuit is active and the Pi should reboot.
If you press the power button then it checks on reboot if the button is released if yes then it powers off correctly. If not it reboots. Let me do some tests please....

So I guess you know how to enter SSH or plain terminal?
To make boot partition writeable you can use batocera-es-swissknife --remount
It's a toggle command so if you use it twice your partition gets r/o-status again.
you can edit the config file with nano /boot/config.txt close nano with CTRL+X and confirm file change
Then let us do some tests...

[crcerror]

I an confirm that reboot + retroflags overlay cuts power on the Pi3. For me there is no difference between shutdown -r and reboot command. Also tested with shutdown - h or poweroff there is no difference between these commands. The Pi3 does not care which command is used here. Everything works.

So I diassembled the retroflag-overlay. Can you please add following two lines to config.txt?
Please make the /boot/config.txt writeable with batocera-es-swissknife --remount

gpio=2,3=pu,ip
gpio=4=pd,ip

and comment/remove line dtoverlay=RetroFlag_pw_io.dtbo

[FlashyDuck]

I an confirm that reboot + retroflags overlay cuts power on the Pi3. For me there is no difference between shutdown -r and reboot command. Also tested with shutdown - h or poweroff there is no difference between these commands. The Pi3 does not care which command is used here. Everything works.

Yeah, the Pi4 really needs the reboot for the Pi4 (or case?) to be able to cut power a few seconds after the reboot. My suggestion is to just go with that fix? It's the same thing Retroflag does, it's the simplest change to the original script and it just seems to work?

So I diassembled the retroflag-overlay. Can you please add following two lines to config.txt? Please make the /boot/config.txt writeable with batocera-es-swissknife --remount

gpio=2,3=pu,ip
gpio=4=pd,ip

and comment/remove line dtoverlay=RetroFlag_pw_io.dtbo

Tried it, but doesn't work. After the change and pressing shutdown results in the same issue. No power cut. And after a reboot 'dtoverlay=RetroFlag_pw_io.dtbo' is again written to /boot/config.txt. Tried both RETROFLAG and RETROFLAG_ADV in batocera.conf.

I went the same route. Added logging to the script for the Power button press specifically, but that didn't show anything weird. Converting the dtbo files (both the Retroflag one as the one you said you used in V39) to dts and have them checked with several llm's. The only issues they all seem to find right away was with the Retroflag one:

• compatibility with the RPI 4 is not mentioned (possible problem with driver/kernel? No idea, just repeating what was mentioned)
• Typo? "output-hight;" should be "output-high;"?
  Those were the 'simplest' changed. So adding the Pi4 as compatible hardware and fixing the typo. Nothing, same result. Tried other dtbo versions made by claude based on all the info I had, but nothing works.

Where I'm left; The way gpiod communicates with Pi4 (EEPROM) is different? But honestly, no clue where to go from here...

[crcerror]

@FlashyDuck Yeah I did forget to say ... /usr/bin/rpi_gpioswitch just reverts the changes done to the script.
The complete if-block starting at Line 372 and the next 5 Lines needs to be commented out or removed
Then type batocera-save-overlay to make changes permanent

Where did you read output-hight?
I assume that there is an error in the retroflag overlay. Because as I disassembled this it spit out some errors. But I saw how this overlay works now.....

[crcerror]

This weekend your outfindings will be tested and fixed then. It seems that only a few people do have a Pi4 in a NESPi case nowadays.

[FlashyDuck]

@FlashyDuck Yeah I did forget to say ... /usr/bin/rpi_gpioswitch just reverts the changes done to the script. The complete if-block starting at Line 372 and the next 5 Lines needs to be commented out or removed Then type batocera-save-overlay to make changes permanent

Not sure what you meant with the 'next 5 lines' because some of those lines were already commented out. This is what that code block looked like after changing it.

#https://www.retroflag.com
function retroflag_start()
{
    #------ CONFIG SECTION ------
    #Check if dtoverlay is setted in /boot/config -- Do this arch related!
    if ! grep -q "^dtoverlay=RetroFlag_pw_io.dtbo" "/boot/config.txt"; then
        mount -o remount,rw /boot
        #echo "# Overlay setup for proper powercut, needed for Retroflag cases" >> "/boot/config.txt"
        #echo "dtoverlay=RetroFlag_pw_io.dtbo" >> "/boot/config.txt"
    #fi
    #[ $CONF -eq 1 ] && return
    #------ CONFIG SECTION ------

    #$1 = rpi-retroflag-GPiCase/rpi-retroflag-AdvancedSafeShutdown
    "$1" &
    pid=$!
    echo "$pid" > "/tmp/$1.pid"
    wait "$pid"
}

Tried it with RETROFLAG_ADV and this seems to break the script

• /boot/config.txt stays the same
• LED on case is not working
• Reset button press does a full system reset; does not matter if you're in game or in ES.
• Power does a immediate shutdown/power cut

Where did you read output-hight? I assume that there is an error in the retroflag overlay. Because as I disassembled this it spit out some errors. But I saw how this overlay works now.....

I converted RetroFlag_pw_io.dtbo with WSL to RetroFlag_pw_io.dts. Line 24 says "output-hight;". According to all LLM's this should be "output-high;"? But changing this and converting the dts back to dtbo does not change the behavior.

This weekend your outfindings will be tested and fixed then. It seems that only a few people do have a Pi4 in a NESPi case nowadays.

Great! Look forward to the results.

[crcerror]

@FlashyDuck your script-looks odd. The original script does not have any code-lines commented out. It's very likely that therefore you can also adjust the code because the code is broken. The "correct way" to disable the setup to write a new overlay is this

#https://www.retroflag.com
function retroflag_start()
{
    #------ CONFIG SECTION ------
    #Check if dtoverlay is setted in /boot/config -- Do this arch related!
    #if ! grep -q "^dtoverlay=RetroFlag_pw_io.dtbo" "/boot/config.txt"; then
    #    mount -o remount,rw /boot
        #echo "# Overlay setup for proper powercut, needed for Retroflag cases" >> "/boot/config.txt"
        #echo "dtoverlay=RetroFlag_pw_io.dtbo" >> "/boot/config.txt"
    #fi
    #[ $CONF -eq 1 ] && return
    #------ CONFIG SECTION ------
....

[FlashyDuck]

@crcerror Okay, I flashed batocera again and started over to make sure I wasn't working with a previous mistake. Script works again (LED and Reset works), but same result unfortunately for the Power button. Only Batocera shuts down, the Pi/case don't.

[crcerror]

@FlashyDuck This was expectable. So we need the reboot commands in rpi-retroflag-AdvancedSafeShutdown ... and we need

gpio=2,3=pu,ip
gpio=4=pd,ip

or

dtoverlay=RetroFlag_pw_io.dtbo

in our config.txt, I'm not sure what you tested if you reflahsed.

[FlashyDuck]

Sorry for the confusion; with reflashed I meant I started fresh again and then applied the changes you mentioned in your previous posts. The behavior compared to 'stock' config.txt was the same. The case/Pi didn't turn off after shutdown.

Yeah, I think we should just switch to the reboot commands for shutdown. That way you can keep the Retroflag dtbo file and change as little as possible.

[crcerror]

@FlashyDuck So we make minimal changes to the default script. But as bonus.... Please use the script attached for own usage.

It's a dedicated shutdown script for NESPi4-cases ... it will not work on Pi3. It gives write errors if the backgroundimage is applied.

Place the script to /userdata/system/services and acticate in ES -> Menu -> System Settings -> Services

USER_POWERSWITCH

REMOVE .log EXTENSION BEFORE USAGE

[FlashyDuck]

@crcerror Any info on the write errors with the Pi3? I'll try it out on my Pi3 and Nespi Plus case and see if I encounter the same issue.

I'm guessing using it as a Service keeps it safe from Batocera updates? I'll try that out. Would this still work with a seperate config file? Because I had already made some improvements to the script based on your suggestion.

Just a how to for anyone that also wants to try it out;

• replace /usr/bin/rpi-retroflag-AdvancedSafeShutdown contents with the one from this .txt file
• create /userdata/retroflag
• place config.txt in that folder. Rename it to config.py.
• create /userdata/retroflag/splash
• place your images in that folder
• edit config.py image paths to /userdata/retroflag/splash/imagename.png and save.
• don't forget to batocera-save-overlay and reboot.

I wasn't sure which folder I should use for the config file, so I added some fallback paths in the script to look for a config.

As far as I can tell this is working on a Pi4 and Nespi 4 case.

config.txt
rpi-retroflag-AdvancedSafeShutdown.txt

[crcerror]

Yes if you use it as service then you can upgrade safely. It is userdata and will not touched then.

With this possibility there is no need for an external file.

[FlashyDuck]

@crcerror Apologies for the delay.

I couldn't get your userservice script to work. Buttons worked, but the splash wasn't being cleared. Went ahead to try and convert my latest version and oh boy... learned that you can't use "tabs" in bash the hard way.

Anyway, I have made some enhancements to the service script. Improved readability for other users, changed the shutdown to also use -r and some other small stuff like only using the dtbo file (easier to copy/paste). I have tested this and it's working correctly on a PI4 with NESPi4 case.

NESPI4_CASE_BUTTONS.txt
NOTE FOR USERS: download, remove .txt extension and follow steps in script.

Is this something to be added to system services? Or is there some place where you can share this script for people to find it?

And bbout the PI3B....
I tried to figure out where this script goes wrong on the PI3B, but to be honest I'm out of my depth here. What I have figured out is that the way the framebuffer works on the PI3B is (completely) different than the PI4. I've tried a lot of things with fbv, but can't get it to show a splash fullscreen and there is some weird green flash when clearing the buffer. The only thing I can think of is to use the splash mechanic that Batocera uses at boot, because that does work properly, but I have tried to look at the code and even let Claude and ChatGPT try and help me figure out a solution for the PI3B, but nothing worked. So I give up on the PI3B...

EDIT:
I guess I should close this pull request, right?