From 6fd47d78e9ee498cc2df430df76e592c533c75b1 Mon Sep 17 00:00:00 2001 From: AKuHAK <621640+AKuHAK@users.noreply.github.com> Date: Mon, 3 Mar 2025 22:57:33 +0200 Subject: [PATCH] Updated Readme to be more user friendly --- README.md | 172 +++++++++++++++++++++++++++++------------------------- 1 file changed, 92 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 45c498d..b50bb9f 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,99 @@ # sd2psXtd Firmware -sd2psXtd is an extended firmware for the popular *Multipurpose MemoryCard Emulator* sd2psx by developer @xyzz (see [here](https://github.com/sd2psx)). It combines cutting-edge extended functionality (like game ID switching, file system access, and dynamic mode selection) with the rock-solid performance of the original sd2psx firmware. +sd2psXtd is an extended firmware for the popular *Multipurpose MemoryCard Emulator* (MMCE) sd2psx by developer @xyzz (see [here](https://github.com/sd2psx)). This firmware is designed for use with **PlayStation 1, PlayStation 2, and arcade machines** based on those system's hardware, utilizing their memory card slots. It combines cutting-edge extended functionality, like Game ID switching, file system access, and dynamic mode selection, with the rock-solid performance of the original sd2psx firmware. **The official MMCEMAN driver can be found [here](https://github.com/ps2-mmce/mmceman).** It provides the same functionality as the official stable firmware and extends it with the following features: -- **PS2:** Game ID switching -- **PS2:** PS1 dynamic mode selection -- **PS2:** MMCEMAN and MMCEDRV support -- **PS2:** Instant card availability -- **PS2:** 1-64 MB card size support -- **PS2:** Support for developer (`DTL-H` & `DTL-T`), Arcade (`COH-H`) and Prototype (`EB`?) models is available. -- **PS1:** BootCard mechanics -- **PS1:** PSRAM support -- **PS1:** Card Switch Controller Combo Support -- **PS1:** Super fast FreePSXBoot -- **General:** Settings file -- **General:** Support for other RP2040-based MMCE devices -- **General:** Per Card Config -- **General:** Game2Folder mapping +- **PS1/PS2:** Instant card availability/PSRAM support (requires devices with PSRAM) +- **PS1/PS2:** Automatic Game ID Virtual Memory Card Switching +- **PS1/PS2:** BootCard Mechanics +- **PS1:** Super fast FreePSXBoot +- **PS1:** Card Switch Controller Combo Support +- **PS2:** Dynamic PS1 Mode Selection +- **PS2:** MMCEMAN and MMCEDRV support +- **PS2:** 1-64 MB card size support +- **PS2:** Support for developer (`DTL-H` & `DTL-T`), Arcade (`COH-H`) and Prototype (`EB`?) models is available. +- **General:** Settings file +- **General:** Support for other RP2040-based MMCE devices +- **General:** Per Card Config +- **General:** Game2Folder mapping -## PS2: Game ID Switching +## PS1/PS2: Automatic Game ID Virtual Memory Card Switching -Like on PS1, *sd2psXtd* can detect the game ID of a PS2 console and switch to a dedicated card per game. Game ID switching can be turned off in the device settings for PS2. +*sd2psXtd* firmware includes an advanced feature that automatically detects the Game ID of the game being launched and switches to a corresponding virtual memory card image specific to that game. An example path for a PS1 game with Game ID `SLES-02618` and Channel 1 would be `sdcard root: MemoryCards/PS1/SLES-02618/SLES-02618-1.mcd`. -This is done in two ways: +## PS1/PS2: Instant Card Availability / PSRAM Support -### History File Tracking +The *sd2psXtd* firmware supports using PSRAM to serve memory cards. For cards that are 8MB or smaller, the firmware exposes the card to the PS2 while it is still being transferred to PSRAM. This allows for immediate use of FMCB/PS2BBL at boot time without needing additional waiting scripts. This feature is particularly beneficial for PlayStation 2 models with simpler OSDSYS programs, resulting in faster boot times (e.g., PSX DESR and Arcade PS2). For PS1, the memory card is always loaded into PSRAM, ensuring instant availability. **Note: This feature is only available on devices equipped with PSRAM.** -When starting a game, the PS2 writes its game ID to a history file on the current memory card. *sd2psXtd* tracks the write to this file and detects which game ID has just been written. After that, a game card for this game is mounted and exposed to the PS2. +### PS1: Game ID Switching -### MMCEMAN Game ID +For PS1, the technical implementation details of Game ID switching are not provided in this README. -*MMCEMAN* is a custom IOP module to communicate with Multipurpose Memory Card Emulators. This can be integrated with OPL so OPL can directly send the game ID of a launched game to *sd2psx*. +### PS2: Automatic Game ID Switching -## PS2: PS1 Dynamic Mode Selection +The PS2 supports two methods for automatic Game ID switching: -When launching in PS2 mode, commands sent to *sd2psx* are monitored. Since PS1 sends controller messages on the same bus as memory card messages, if a controller message is detected, the PS2 switches to PS1 mode. +1. **History File Tracking:** + When a game is launched, the PS2 writes its Game ID to a history file on the active memory card. The *sd2psXtd* firmware monitors this file and identifies the newly written Game ID. Once detected, the firmware mounts the corresponding virtual memory card image for that game and makes it available to the PS2. + +2. **MMCEMAN Game ID:** + *MMCEMAN* is a custom IOP module designed to interact with Multipurpose Memory Card Emulators. This method is primarily intended for developers who need to explicitly communicate a specific Game ID to the device. The firmware then uses this information to switch to the appropriate virtual memory card image. + +## PS1/PS2: BootCard Mechanics + +When BootCard functionality is activated (option `Autoboot=ON` in the appropriate device section inside `.sd2psx/settings.ini`), the device starts with a specific card image at startup, identified by the Game ID `BOOT`. This is particularly useful for loading exploits that utilize memory cards. If BootCard is not activated, the card index and channel from the last session are restored automatically. + +> [!NOTE] +> The virtual memory card image location is `sdcard root: MemoryCards/PS1/BOOT/BootCard-%d.mcd` where `PS1` can be `PS2` depending on the mode, and `%d` is the card channel (1 by default). The card channel number is restored from the last session. + +## PS1: Super fast FreePSXBoot + +*sd2psXtd* allows super fast booting of FreePSXBoot by using some non standard card communication. +Please note: This is only possible using a special FreePSXBoot Version provided at [https://sd2psxtd.github.io/exploits](https://sd2psxtd.github.io/exploits) + +## PS1: Card Switch Controller Combo Support + +Controller Button Mapping for Card and Channel Switching + +The following button combinations are used to perform card and channel switches: + +- L1 + R1 + L2 + R2 + Up: Switch to the Next Card +- L1 + R1 + L2 + R2 + Down: Switch to the Previous Card +- L1 + R1 + L2 + R2 + Right: Switch to the Next Channel +- L1 + R1 + L2 + R2 + Left: Switch to the Previous Channel + +These mappings require that all four buttons (L1, R1, L2, R2) are held down in combination with one of the directional inputs. + +## PS2: Dynamic PS1 Mode Selection + +When launching in PS2 mode, commands sent to *sd2psx* are monitored. Because the PS1 sends controller messages on the same bus as memory card messages, if a controller message is detected, *sd2psx* automatically switches to PS1 mode. While in general this should be safe behavior, if *sd2psx* is used mainly in PS1, manual mode selection is recommended. > [!CAUTION] > **Note 1:** If *sd2psx* is connected to a PS1 in PS2 mode, there is always a risk of damaging your PS1 console. You have been warned! - +> > [!CAUTION] > **Note 2:** Do not use *sd2psx* in dynamic mode on a PS1 multitap, as this **WILL** damage your PS1 multitap device. ## PS2: MMCEMAN and MMCEDRV Support -*MMCEMAN* is a PS2 module for interacting with *Multipurpose Memory Card Emulators*. Its main use cases include: +*MMCEMAN* is a PS2 module designed to interact with *Multipurpose Memory Card Emulators* (MMCEs). Its primary functions include: -- **Card Switching:** MMCEMMAN can request a card change on *MMCEs*, such as setting a channel or selecting a specific card. -- **Game ID Communication:** MMCEMAN can send a game ID to the *MMCE*, which may in turn switch to a dedicated card for this ID if activated. -- **File System Access:** MMCEMAN allows access to *MMCEs* filesystem through standard POSIX file I/O calls -- **Game loading:** MMCEDRV allows for loading games off of *MMCEs* with performance equal to, or in most cases, better than MX4SIO. +- **Card Switching:** MMCEMAN can request a card change on MMCEs, such as setting a channel or selecting a specific card. +- **Game ID Communication:** MMCEMAN can send a Game ID to the MMCE, which can then switch to a dedicated card for this ID if enabled. +- **File System Access from PS2:** MMCEMAN allows the PS2 to access the MMCE's filesystem (the exFAT partition on the SD card) using standard POSIX file I/O calls. This enables full access to files on the SD card, such as backups of purchased PS2 games, from the PS2. +- **File System Access from PC:** The firmware does not provide access to the SD card filesystem through the USB port. To transfer data to and from the SD card, it must be connected to the PC separately. +- **Game Loading:** MMCEDRV allows games to be loaded from MMCEs with performance equal to or better than MX4SIO. -## PS2: Instant Card Availability - -If using 8MB cards, *sd2psXtd* firmware exposes the card to the PS2 while it is still being transferred to PSRAM. This enables using FMCB/PS2BBL at boot time without additional waiting scripts. -Very helpful for PlayStation 2 models with simpler OSDSYS programs, that result on faster boot times (like PSX DESR and Arcade PS2) ## PS2: 1-64 MB Card Size Support -Support for card sizes between 1 and 64 MB has been added. Cards larger than 8 MB rely heavily on quick SD card access, so on older or lower-quality SD cards, these larger cards may become corrupt. +Support for memory card sizes of 1, 2, 4, 8, 16, 32, and 64 MB has been added. Cards larger than 8 MB rely heavily on quick SD card access, so on older or lower-quality SD cards, these larger cards may become corrupt. > [!NOTE] -> While the feature has been extensively tested, it is still recommended to use 8MB cards, as this is the official specification for memory cards. +> While this feature has been extensively tested, it is still recommended to use 8 MB cards, as this is the official specification for PS2 memory cards. ## PS2: Support for Developer, Arcade and Prototype PS2s @@ -72,7 +101,7 @@ PS2 memory cards have been used in variations of PS2 like: *DevKits*, *TestKits* *sd2psXtd* firmware supports these devices by configuring the variant within the PS2 settings. -These PlayStation 2 variations use different magicgate keysets to ensure their memory cards are inaccessible in other devices (e.g., opening a developer memory card on a normal PS2). This is why SD2PSX must actively support them. +These PlayStation 2 variations use different magicgate keysets to ensure their memory cards are inaccessible in other devices. For example, opening a developer memory card on a normal PS2. This is why SD2PSX must actively support them. > [!NOTE] > **Devkit/DTL-H owners**: @@ -80,33 +109,6 @@ These PlayStation 2 variations use different magicgate keysets to ensure their m [^1]: Devkits: official retail memory cards use developer magicgate by default until the console actively requests to use retail magicgate with a dedicated command -## PS1: BootCard Mechanics - -If BootCard functionality is activated, the PS1 starts with BootCards at startup. If BootCard is not activated, the card index and channel from the previous session are restored automatically. - -## PS1: PSRAM Support - -*sd2psXtd* firmware allows PS1 cards to be served from PSRAM. While this is mainly an under-the-hood change, it provides more flexibility in RAM usage. - -## PS1: Card Switch Controller Combo Support - - -Controller Button Mapping for Card and Channel Switching - -The following button combinations are used to perform card and channel switches: - -- L1 + R1 + L2 + R2 + Up: Switch to the Next Card -- L1 + R1 + L2 + R2 + Down: Switch to the Previous Card -- L1 + R1 + L2 + R2 + Right: Switch to the Next Channel -- L1 + R1 + L2 + R2 + Left: Switch to the Previous Channel - -These mappings require that all four buttons (L1, R1, L2, R2) are held down in combination with one of the directional inputs. - -## PS1: Super fast FreePSXBoot - -*sd2psXtd* allows super fast booting of FreePSXBoot by using some non standard card communication. -Please note: This is only possible using a special FreePSXBoot Version provided at https://sd2psXtd.github.io - ## General: Settings File *sd2psXtd* generates a settings file (`.sd2psx/settings.ini`) that allows you to edit some settings through your computer. This is useful when using one SD card with multiple *sd2psx* devices or *MMCE* devices without a display to change settings. @@ -132,11 +134,13 @@ Possible values are: | Setting | Values | |---------------|---------------------------------------| | Mode | `PS1`, `PS2` | -| AutoBoot | `OFF`, `ON` | -| GameID | `OFF`, `ON` | +| FlippedScreen | `ON`, `OFF` | +| AutoBoot | `ON`, `OFF` | +| GameID | `ON`, `OFF` | | CardSize | `1`, `2`, `4`, `8`, `16`, `32`, `64` | | Variant | `RETAIL`, `PROTO`, `ARCADE` | -| FlippedScreen | `ON`, `OFF` | + +*Note: `Variant=ARCADE` is for Namco System 246/256 or Konami Python 1 arcade machines and only the first memory card slot is supported. `RETAIL` is for regular PS2 machines. `PROTO` is for unknown prototype models.* *Note: Make sure there is an empty line at the end of the ini file.* @@ -144,15 +148,15 @@ Possible values are: Support for different MMCE devices that share the same MCU has been added: -- **PicoMemcard+/PicoMemcardZero:** DIY devices by dangiu (see [here](https://github.com/dangiu/PicoMemcard?tab=readme-ov-file#picomemcard-using-memory-card)) without PSRAM. Use *PMC+* or *PMCZero* firmware variant. -- **PSXMemCard:** A commercial device by BitFunX sharing the same architecture as *PMC+*. Use *psxmemcard* firmware variant. -- **PSXMemCard Gen2:** A commercial device by BitFunX, sharing the same architecture as *sd2psx*. Use *sd2psx* firmware variant. +- **PicoMemcard+/PicoMemcardZero:** DIY devices by dangiu (see [here](https://github.com/dangiu/PicoMemcard?tab=readme-ov-file#picomemcard-using-memory-card)) without PSRAM. Use *PMC+* or *PMCZero* firmware variant. +- **PSXMemCard:** A commercial device by BitFunX sharing the same architecture as *PMC+*. Use *psxmemcard* firmware variant. +- **PSXMemCard Gen2:** A commercial device by BitFunX, sharing the same architecture as *sd2psx*. Use *sd2psx* firmware variant. For each device, follow the flashing instructions provided by the creator, using the corresponding *sd2psXtd* firmware file. ## General: Per Card Config -There are some configuration values that can be modified on a per card base within a config file named `CardX.ini` in a card folder, where `X` is the card index. +There are some configuration values that can be modified on a per card base within a config file named `CardX.ini` in a card folder, where `X` is the card index. *Note 1: The `CardSize` setting is only used for PS2 cards and can only be either of `1`, `2`, `4`, `8`, `16`, `32`, `64`.* *Note 2: The BOOT folder should contain a file named `BootCard.ini`* @@ -171,14 +175,16 @@ There are some configuration values that can be modified on a per card base with [Settings] MaxChannels=8 CardSize=8 + ``` +**Channel:** The "Channel" is used for switching between multiple memory card images for a single, specific Game ID. It's represented by a number. Within the folder named after the Game ID, a file named `GameID-3` represents Channel 3. ## General: Game2Folder mapping -There are some games, that share save data for multiple game ids (like the Singstar series etc). For these cases, a custom game to folder mapping can be created. +There are some games, that share save data for multiple Game IDs (like the Singstar series etc). For these cases, a custom game to folder mapping can be created. -If a game with a mapped id is loaded, instead of using the game id based folder, the mapped folder is used for storing the card. +If a game with a mapped id is loaded, instead of using the Game ID based folder, the mapped folder is used for storing the card. The mapping needs to be defined in ```.sd2psx/Game2Folder.ini``` in the following way: @@ -192,12 +198,18 @@ SCXS-23456=FolderName2 *Note: Be aware: Long folder names may not be displayed correctly and may result in stuttering of MMCE games due to scrolling.* *Note 2: Make sure there is an empty line at the end of the ini file.* +# Firmware update + +Follow the instructions for your specific device. In general, you need to put the device in firmware update mode and connect it to a PC via a cable. Transfer the .uf2 file to the SD card device that appears, and wait until the device automatically disappears. + +*Note:* To get Magicgate support in PS2 mode, you need the proprietary file `civ.bin` (8 bytes) in your SD card root on the first boot after the firmware upgrade. Magicgate is used by some games and exploits. + ## Special Thanks to... -- **@xyz**: for sd2psx ❤️ -- **sd2psXtd Team**: (you know who you are 😉 ) -- **@El_isra**: for so much different stuff ❤️ -- **8BitMods Team**: for helping out with card formatting and providing lots of other useful information ❤️ -- **@Mena / PhenomMods**: for providing hardware to some team members ❤️ -- **BitFunX**: for providing PSXMemcard and PSXMemcard Gen2 Hardware for dev ❤️ -- **All Testers**: ripto, Vapor, seewood, john3d, rippenbiest, ... ❤️ +- **@xyz**: for sd2psx ❤️ +- **sd2psXtd Team**: (you know who you are 😉 ) +- **@El_isra**: for so much different stuff ❤️ +- **8BitMods Team**: for helping out with card formatting and providing lots of other useful information ❤️ +- **@Mena / PhenomMods**: for providing hardware to some team members ❤️ +- **BitFunX**: for providing PSXMemcard and PSXMemcard Gen2 Hardware for dev ❤️ +- **All Testers**: ripto, Vapor, seewood, john3d, rippenbiest, ... ❤️