Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
upgrade_manually [2020/10/31 14:22] – [Error messages when upgrading] joinskiupgrade_manually [2023/11/18 23:56] (current) – [Upgrading/downgrading Batocera] Adjust wording, fix typos maximumentropy
Line 1: Line 1:
-~~NOTOC~~ +====== Manual upgrades/downgrades ======
-===== Manual upgrades/downgrades ===== +
-Upgrades/Downgrades can be done manually : +
-  * in case you want to reinstall a previous version +
-  * in case the upgrades are broken +
-  * in case you want to upgrade to a custom version+
  
-To upgrade/downgrade manually +This is for if you: 
-  - download the file boot.tar.xz of the version you want. The official ones are available here http://batocera.org/upgrades +  * can'upgrade/downgrade from stable to beta or vice versa using **MAIN MENU** > **UPDATES & DOWNLOADS** > **UPDATE TYPE** > "Stable" or "Beta" and updating or [[:access_the_batocera_via_ssh|using SSH]] for the same thing, 
-  ''.tar.xz'' file is an archive format, like a ''.zip''. Just unzip this file onto your SD card/USB key to replace existing files.+  want to downgrade to [[:current_and_previous_releases#older_releases|an older revision]], or 
 +  * want to install custom version of Batocera.
  
-Or, starting with batocera.linux 5.23: +===== The Batocera drive layout =====
-  - [[access_the_batocera_via_ssh|from SSH]], adapt the url to the right architecture and run : ''batocera-upgrade https://batocera.org/upgrades/x86_64/stable/last'' (this example is for PC x86_64, please adapt the URL to the right architecture)+
  
-For batocera.linux 5.7 to 5.22: +First a little explanation of how Batocera is laid out on your drive, as this will help in understanding exactly what files need to be placed where later on:
-  - [[access_the_batocera_via_ssh|from SSH]], the command line would be: ''/recalbox/scripts/recalbox-upgrade.sh https://batocera.org/upgrades/x86_64/stable/last'' (for PC x86_64, please adapt to the right architecture)+
  
-These commands upgrade -- or potentially downgrade -- the Batocera system. Upgrading or downgrading //doesn't remove// any of your user data (ROMsmetadata...). Like neverever.+{{batocera_drive_layout.png?720|An illustration showing how the batocera system is laid out on a USB stick: the BATOCERA partition firstcontaining all the programsand then the SHARE, containing all the userdata}}
  
-==== Error messages when upgrading ====+  * The **boot** partition is what appears as the FAT32 partition when you plug the drive into another system. The boot partition contains the files required to boot, this is mounted in read-only mode to ''/boot/'' during boot. The read-only ''batocera'' SquashFS file is also contained in the boot partition. On boot, this filesystem is mounted at ''/'' to run Batocera proper. You'll also find ''batocera-boot.conf'' here. In Batocera **v31** and lower, the custom splash videos you have uploaded would be copied here too. This partition is assigned 6 GB of space (4 GB with older images of Batocera), with 2 GB used by Batocera. Files in only this partition are overwritten when updating Batocera; it's relatively simple to upgrade/downgrade Batocera versions because of this design. 
 +  * The userdata contains "the rest", all the BIOS files, ROMs, save data, user configuration (including ''batocera.conf''). This partition is not touched when upgrading/downgrading. This is designed to be portable between all versions of Batocera, even Batocera builds running on different platforms (granted, weaker platforms like [[:choose_a_single_board_computer|SBCs]] won't magically gain the ability to play ROMs for emulators they don't have).
  
-If you get an error message telling you that you don't have enough space on your Batocera system partition when you upgrade, there might be several explanations. +===== Upgrading/downgrading Batocera =====
  
-One of them is that you have [[splash_boot|stored several splash boot video files]] on the ''/boot'' partitionRemove themand try to upgrade again. +In Batocera **5.23** and higher, it is advised to upgrade/downgrade using the ''batocera-upgrade'' command [[access_the_batocera_via_ssh|via SSH]]. Grab the [[:current_and_previous_releases|URL of the version you want]] to upgrade/downgrade to and run ''%%batocera-upgrade [URL]%%''For example, to upgrade to the latest stable for x86_64:
  
-The other explanationYour first installation was an older version, where the boot-partition was smaller (in newer versions of batocera the space had to be rised because of more features). +<code> 
-In this case, you could either delete the "batocera"-file (it is just called batocera, without a file-extension, is about 1gb big and is located in the boot folder of the first/boot partition). +batocera-upgrade https://batocera.org/upgrades/x86_64/stable/last 
-After that, extract the boot.tar.xz file onto that drive and if successfullrename the file "batocera-update" located in the boot folder to just "batocera"). +</code> 
-But be aware, that you would have to do this manual workaround (update-procedure) every time, you want to update to a new version.+ 
 +Or to downgrade to a specific [[:current_and_previous_releases#current_builds_older_releases_and_betas|older version]]like in the example below to downgrade to Batocera 36 for PC x86_64. Don't copy that command on another architecture like a Raspberry Pi, you need to adapt the URL to it. 
 + 
 +<code> 
 +batocera-upgrade https://mirrors.o2switch.fr/batocera/x86_64/stable/last/archives/36/ 
 +</code> 
 + 
 +<WRAP center round info 60%> 
 +The command ''%%cat /boot/boot/batocera.board%%'' can be used to display the arch that should be used.  For example, on a PC this will display x86_64. 
 +</WRAP> 
 + 
 + 
 +You should then see output similar to this: 
 + 
 +<code> 
 +Starting the upgrade... 
 +url: https://updates.batocera.org/x86_64/stable/last/boot.tar.xz 
 +need to download 1876mb 
 +/userdata/system/upgrade/boot.tar.xz     0%[                              ]   9.55M  1.82MB/   eta 19m 42s 
 +</code> 
 + 
 +For very old versions, from Batocera 5.**7** to 5.**22**, the command (for PC x86_64, please adapt to the right architecture) would instead be
 + 
 +<code> 
 +/recalbox/scripts/recalbox-upgrade.sh https://batocera.org/upgrades/x86_64/stable/last 
 +</code> 
 + 
 +These commands download the compressed upgrade (or potentially downgrade) file and expand it to overwrite the Batocera system on the boot partition. Upgrading or downgrading like this //doesn't remove// any of your user data (ROMs, saves, metadata...). Like never, ever
 + 
 +On the next reboot of Batocerait will instead use the upgraded version. If the automatic upgrade tool is not suitable for your purpose, then you can manually upgrade/downgrade as specified below instead. 
 + 
 +==== Upgrade from a local boot.tar.xz file ==== 
 + 
 +To upgrade/downgrade manually from a downloaded ''boot.tar.xz'' file: 
 +  - Download the ''boot.tar.xz'' file of the version you want. The official ones are available at https://mirrors.o2switch.fr/batocera/ (for older versions, navigate to your architecture and go to /stable/last/archives/). [[:current_and_previous_releases#current_builds|Here's a list of architectures and links to their builds.]] 
 +  Backup your boot configuration files (''batocera-boot.conf'' and ''config.txt'') from the Batocera machine (if you have edited them and require the edits to boot properly) to a safe location. 
 +  - Unzip the ''boot.tar.xz'' file (it'just like ''.zip'', you can use 7-zip on Windows) to get the ''boot.tar'' file
 +  Unzip the ''boot.tar'' file into the root of your Batocera drive's [[:edit_boot_partition|boot partition]] (this is the default partition you see when inserting the drive into Windows) and overwrite the existing files. You may have to [[:edit_boot_partition#plugging_it_into_another_machine|assign a drive letter under Windows Disk Management]] to see it in the file explorer. 
 +  - Restore your boot configuration files if you wish to do so. 
 + 
 +===== What the batocera-upgrade command does ===== 
 + 
 +Ordinarily, the built-in updating tool will do all of the following automatically: 
 +  - Download the boot image file to ''/userdata/system/upgrade/boot.tar.xz'' in the userdata partition 
 +  - Check the md5sum of the file to ensure that it was downloaded correctly (this may take a bit of time, depending on the speed of your drive
 +  After validation, remount the boot partition in rewritable mode 
 +  - Back up your boot config files: ''/boot/batocera-boot.conf'' to ''/boot/batocera-boot.conf.upgrade'' and ''/boot/config.txt'' to ''/boot/config.txt.upgrade'' 
 +  - Unzip the contents of ''/userdata/system/upgrade/boot.tar.xz'' to ''/boot/'' 
 +  - Restore your boot config files: ''/boot/batocera-boot.conf.upgrade'' to ''/boot/batocera-boot.conf'' and ''/boot/config.txt.upgrade'' to ''/boot/config.txt'' 
 +  - Do a "final cleanup" 
 +  - Remove ''/userdata/system/upgrade/boot.tar.xz'' 
 + 
 +===== Not enough space to update ===== 
 + 
 +==== Userdata partition ==== 
 + 
 +If you get an error message telling you that you don't have enough space on your userdata partition to download the filethere might be several reasons: 
 +  * Your drive is less than 8 GB total. Batocera can //run// on these drives but you will be missing out on using the built-in updater. 
 +  * Your userdata partition does not have at least 2 GB additional free space to download the ''boot.tar.xz'' file
 + 
 +To work around there not being enough free space in the **userdata** partition, you can do any of the following: 
 +  * Temporarily remove some of your ROMs, BIOS, and other userdata to make enough free space to download the ''boot.tar.xz'' file. 
 +  * Download the ''boot.tar.xz'' from [[:current_and_previous_releases#current_builds|the server]] for the intended Batocera version onto another computer, connect the Batocera drive to it, and extract the contents of ''boot.tar'' directly to the boot partition of Batocera. 
 + 
 +==== Boot partition ==== 
 + 
 +If you get an error message telling you that you don't have enough space on your Batocera boot partition while attempting to upgradethere might be several reasons: 
 +  * Your drive is less than 8 GB total. Batocera can //run// on these drives but you will be missing out on using the built-in updater. 
 +  * On Batocera **v31** and lower, the [[splash_boot|splash video file(s)]] (which are copied to the ''/boot'' partition) are/is taking up too much space. Remove them/it, reboot and try to upgrade again. 
 +  * Your first installation was an older version of Batocera, where the ''/boot'' partition was initially assigned less space (compared to installations of newer Batocera versions). 
 +  * Your installation is corrupted. 
 + 
 +To work around there not being enough free space in the **boot** partitionyou can do any **one** of the following: 
 + 
 +=== Use another computer === 
 + 
 +Use another computer to extract the update files onto the Batocera drive. Be aware that by doing this you would have to do this manual workaround every time you need to update
 +    Insert your drive into another computer 
 +    - Back up the contents of the FAT32 boot partition of the Batocera drive (Windows should only be able to see this partition and nothing else by defaultto another location 
 +    - Delete the ''/boot/batocera'' file from the Batocera drive (it is just called ''batocera'' without a file-extension and is about 2 GB large (smaller in older versions)) 
 +    - Extract the ''boot.tar'' file to the root of that partition 
 +    - Replug the Batocera back into your Batocera machine and boot Batocera. <WRAP center round tip> 
 +If Batocera fails to boot, you can restore the data you backed up in step 2. 
 +</WRAP> 
 + 
 +=== Remove the old version first === 
 + 
 +Remove the old version of Batocera //before// overwriting it with the update. Be aware that by doing this you would have to do this manual workaround every time you need to update. 
 +    - Boot into Batocera[[:access_the_batocera_via_ssh|SSH into it]] or use the file manager's xterm and run the following: <code>mount -o remount,rw /boot</code> 
 +    - Backup your ''/boot/boot/batocera'' file to another device or the userdata partition if you have enough space there (''cp /boot/boot/batocera /userdata/system/batocera-backup'', or you can exit the xterm with ''[Alt]''+''[F4]'' and then use the file manager to copy the file to your ''/userdata/system/'' folder) 
 +    - Run the following command to delete the ''batocera'' file and immediately upgrade: <code>rm -i /boot/boot/batocera && batocera-upgrade</code> Confirm the file you want to delete. <WRAP center round info> 
 +You should then get an output that looks like this: <code>Starting the upgrade... 
 +url: https://updates.batocera.org/x86_64/beta/last/boot.tar.xz 
 +need to download 1876mb 
 +m/upgrade/boot.tar.xz     0%[                              ]   9.55M  1.82MB/   eta 19m 42s</code> 
 +</WRAP> 
 +    - Wait for the upgrade to completely finish, then reboot to apply the changes. <WRAP center round tip> 
 +If Batocera fails to boot, you can restore the backup you made in step 2 and then remove it with (replacing the first path if you used a different location for your backup): <code>cp /userdata/system/batocera-backup /boot/boot/batocera && rm /userdata/system/batocera-backup</code> 
 +</WRAP> 
 + 
 +=== Flash a spare drive === 
 + 
 +[[:install_batocera|Flash]] a spare USB/portable hard-drive with a new copy of Batocera and boot into that, copy all your ''/userdata/'' (everything in Share) from your old Batocera drive to your spare USB/portable hard-drive and then reflash the old Batocera drive with a new version of Batocera (or just continue to use your spare USB/portable hard-drive). 
 + 
 +=== Reflash the drive === 
 + 
 +Backup your ''/userdata/'' to another device (you may lose file attributes by doing this, causing problems with WINE/Cemu) and [[:install_batocera|reflash Batocera]]. 
 + 
 +=== Manually extend the boot partition === 
 + 
 +Extend the boot partition of your drive using an advanced tool like [[https://gparted.org/|gparted]] or [[wp>GNOME_Disks|GNOME Disks (a.k.a. gnome-disk-utility)]]. <wrap em>This will likely destroy your userdata partition</wrap>, so back up all your ROMs, saves, configs, etc. first. This is not the recommended method, as it may cause irreversible damage to your drive and it may damage the MBR/GPT table, causing the drive to become unbootable. Consider the other options first or just staying on your current version of Batocera. Batocera **v30** requires at least 6 GB total assigned to the boot partition and 2 GB free space in the userdata partition to be able to use the built-in updater.
  
-So it may be better, to backup all the files from your share-partition (roms, saves, bios, etc.) and start a fresh new install, by flashing the .img.gz file with for example balenaEtcher onto the drive, where you want to have batocera installed, then boot from it and copy back all roms, saves etc. to the share-partition of this new installation of batocera. 
-==== The batocera.linux usb key ==== 
-{{system:usbkey.png?700|}} 
  • upgrade_manually.1604150563.txt.gz
  • Last modified: 3 years ago
  • by joinski