Psion Series 3a emulator for Planet Computers Gemini PDA ======================================================== A combination of patched binaries and custom on-screen controls to allow the MS-DOS Psion Series 3a emulator to run on the Planet Computers Gemini PDA using Magic DOSBox. Version 2.0.3 Change log ---------- v2.0.0 Initial public release. v2.0.1 Added 1:1 and 1:125 screen emulation options (see APPENDIX C). Added non-working Alt-E, Alt-U and Alt-I keys to Known Issues. Updated documentation. v2.0.2 Added virtual bezel with PSION and Series 3a logos to 1:1 version. Removed some unneeded graphics from the import files. Updated documentation. v2.0.3 Added keyboard shortcuts for Menu, Diamond and Ctrl-Menu functions. Updated documentation. v2.0.4 Changed delay for Hidden Startup Macro to 10 seconds, because the 1s delay was failing (probably a timing issue with the upgrade from Android 7 to Android 8. Updated documentation. Installation ============ 1. Install Magic DOSbox on the Gemini but don't launch it yet. The free version will work but you won't be able to import the emulator configuration as a single file. Life is much easier with the full version and only the most basic instructions for the free version will be provided here. See APPENDIX B. 2. Install SwiftKey on the Gemini. This is necessary so SwiftKey can act as an interpreter for the Gemini hardware keyboard and send meaningful scancodes to Magic DOSbox. You can make SwiftKey the default system keyboard in conjunction with the Gemini's hardware keyboard; the combination works well but the instructions are outside the scope of this document. If you choose not to have SwiftKey as the system default, you will need to configure Magic DOSbox at step 11 below. 3. Create a folder 'Series 3a' in the Internal Shared Storage of the Gemini. 4. Extract and copy the contents of 'S3aGemini.zip' into this folder. If you have your own Series 3a backup files, you should copy them into the 'M', 'A' and 'B' folders inside the 'Series 3a' folder. These three folders are the virtual internal storage and SSDs of the emulated Series 3a. Note that the EPOC.DLL provided in this zip has been patched to work with the Gemini's quirky hardware keyboard. If you overwrite this with an EPOC.DLL from another source, perhaps a non-English emulator, many keys may no longer function. See APPENDIX A for details of the patch. 5. If you are using the free version of Magic DOSbox, see APPENDIX B. 6. Launch Magic DOSbox. The app will ask for a few general settings when it is first run. Choose 'Public' as the settings location and select 'Standard' rather than 'Fantasy' as the UI theme. 7. On the Magic DOSbox main menu screen, tap the large '+' icon. 7a. Tap 'Import Profile' 7b. Navigate to the 'Series 3a' folder and tap 'Emulator.mgc' 7c. Tap the green check button. (Starting with version 2.0.1 two additional emulator configuration files, 'Emu11.mgc' and 'Emu1125.mgc' are provided, giving alternative screen options. See APPENDIX C for details.) 8. Tap and hold the newly created 'Series 3a' icon until a sub-menu appears. 9. Tap 'Desktop Shortcut' 10. Tap the 'X' button or hit Esc to return to your Android Launcher. You should find a new 'Series 3a' icon somewhere on your Launcher. The emulator can be launched from this icon, or from within Magic DOSbox. 11. Launch the Series 3a emulator. If you are NOT using SwiftKey as the default system keyboard, you will need to configure the correct input method for Magic DOSbox: 11a. Open the 'General Settings' panel by tapping the triangle button on the Android Navigation Bar. (If the bar is not visible, swipe down from the top of the screen). 11b. Scroll down and tap 'Input Method'. 11c. Tap 'SwiftKey Keyboard'. Using the emulator ================== Most of the Psion's keyboard keys are mapped to sensible locations on the Gemini keyboard with the Planet / Alt key acting as the Psion key (but see the Known Issues list and APPENDIX A for some important exceptions). Some apps will not fully scale to the larger emulated display. See the Known Issues list for details. The Series 3a's physical Button Bar is emulated using the on-screen icons across the bottom of the display. A single tap on an icon will move to that app on the System screen, unless a file is open in which case it will switch to that app. A double tap on the System icon is the equivalent of Shift-System on an actual Series 3a, and will cycle between open applications. The Psion's Diamond key is emulated by tapping on the top right of the screen where the Diamond List is normally visible. Note that this hidden button works even when the Diamond List is not visible, either because the Status Window has been hidden by the user or because an app view e.g. Agenda's Year View has temporarily removed the list. New for version 2.0.3: the Diamond key is also mapped to the Gemini's Play/Pause media control. This is Fn-Q on a UK keyboard. This function has not been tested on a non-UK keyboard. There is another invisible button on the right of the screen, between the Diamond List and the Button Bar. A single tap on this area is the equivalent of Ctrl-Menu. On the System screen and in many apps this will cycle between Status Window modes; large, small, invisible. A double tap on this area will bring up the on-screen Help. As with the Diamond List button, these functions work even when the Status Window is not visible. New for version 2.0.3: the Ctrl-Menu function is also mapped to the Gemini's Previous media control. This is Fn-W on a UK keyboard. This function has not been tested on a non-UK keyboard. A single tap anywhere else on the screen will bring up the Menu. New for version 2.0.3: the Menu key is also mapped to the Gemini's Next media control. This is Fn-E on a UK keyboard. This function has not been tested on a non-UK keyboard. The emulation can be ended by pressing Ctrl-Alt-Z or Ctrl-Alt-X. There is a known issue with using Ctrl-Alt-Z that can result in a temporary issue with keyboard input (see Known Issues) so Ctrl-Alt-X might be a good habit to get into until a fix can be found. WARNING: exiting the emulator using either of these combinations is INSTANTANEOUS and does not save any open documents. Depending on how fumble-fingered the user is it might be very easy to accidentally trigger this combination, especially since Alt-Z and Alt-X are quite commonly used for zooming and graceful app exits. Exercise caution and save often! This combination is baked into the emulator and cannot be bypassed. The 'Startup' Macro =================== Unlike a real Series 3a, the emulated machine does not save its state when the power is removed / the emulation is closed. Magic DOSbox allows for macros (called combos) to be run when the emulation begins, which allows for some degree of mitigation. There is an invisible button called Hidden Startup Macro included in the 'Emulator.mgc' definition but it is disabled by default. An understanding of how Magic DOSbox works is essential to getting the most out of this feature, and is beyond the scope of this document, but for those who wish to experiment it can be enabled by going to 'General Settings' | 'Advanced Settings' and enabling Hidden Startup Macro under 'Run At Start'. Remember to re-open the 'General Settings' dialog and tap the 'Save' icon otherwise the setting will not be remembered. By default the macro does the following when the emulator is launched: a. Waits 10000ms for the emulated MS-DOS to pass access to the keyboard bufer over to the Series 3a emulator. b. Sends a Ctrl-Menu keypress to turn on the Status Window. c. Sents a Diamond keypress to turn on the memory status. d. Sends 2 x Ctrl-Z keypresses to set the font zoom to minimum. e. Taps the Time icon to bring up the clock page. f. Sends Psion-H to bring up the Set Home City. g. Sends L, I, V, Enter keypresses to select Liverpool. h. Taps the System icon to return to the System screen. This makes the emulator launch with the look and feel of the Series 3a I remember from the mid 1990s. Obviously the first thing you will want to do if you choose to use this feature (assuming you don't live anywhere near Liverpool!) is to change those key combinations relating to the Time app, or remove that part of the combo. The power of this feature could be significant for users who spend a lot of time working with the emulator. For instance you might choose to automatically open and switch to an Agenda file or a current OPL project. Known issues ============ Keys ---- Some key functions require non-standard combinations. The Pound Sterling symbol, for instance, requires Alt-3 to be pressed rather than the expected Shift-3. The oddest is the Shifted comma key which should produce the / symbol but instead produces a ? UNLESS the Fn key is first pressed in a Fn-Shift-comma rollover. This was discovered purely by accident; until then I was convinced that this key was unavailable and would have to have an on-screen button. Probably the oddest quirk of the Gemini keyboard. The PgUp, PgDn, Home and End functions aren't supported, possibly because Magic DOSbox interprets the cursor keys as a gamepad. Ctrl-Left and Ctrl-Right move the cursor one word to the left or right, but the Fn- and Alt- combinations do nothing. It may be possible to further edit EPOC.DLL to support these keys but it's a long shot. More likely I'll have to implement on-screen keys and/ or swipe gestures. Occasionally, after using Ctrl-Alt-Z to close the emulator, SwiftKey may produce odd output including missing keys and non-ASCII characters both in the emulator and other apps. Pressing Ctrl-Alt seems to reset things (the Planet App Bar may appear temporarily). You may have to do this outide of the emulator itself. This only started happening recently and I've no idea why. Unlike a real Series 3a, which has hardware registers that can be polled for keyboard events, the emulator works by interpreting the host's keyboard scancodes. Most third-party apps, especially games, that handle inputs by scanning the physical hardware will not work on the emulator. See also the Screen section of the Known Issues list. The Alt-U, Alt-I and Alt-E combinations do not work as shortcuts to menu items because of a compatibility issue with SwiftKey. These functions still work when accessed through the menu. CAPS LOCK behaves very oddly. If the Gemini CAPS LOCK (Fn-Tab) is enabled outside of the emulator before switching to the emulator, the emulator will behave as if CAPS LOCK is on. There doesn't seem to be a way to switch this off, from within the emulator or without. The normal Psion shorcut for CAPS LOCK (Psion-Diamond) does not work at all in the emulator. In either case, the CAPS symbol in the Status Window does not appear. Further investigation is required on this oddity. Screen ------ The emulated Psion has a screen resolution of 640 x 264 pixels, scaled by 150% to match the Gemini's 16:9 screen. The original Psion hardware had a resolution of 480 x 160 pixels. Most apps will scale to this new larger size with some notable exceptions. The Agenda's Year View is locked to the smaller size, for example, as are the Time and World apps. Many third-party apps will have been written with the expectation of a 480 x 160 screen and will run either locked to the top left of the display or not at all. See also the Keys section of the Known Issues list. Starting with version 2.0.1 two additional emulator configuration files, 'Emu11.mgc' and 'Emu1125.mgc' are provided, giving alternative screen options. See APPENDIX C for details. Audio ----- The Series 3a sound system is not fully emulated. General system warning sounds will play, but any attempt to play a WVE file will play only the default system alarm sound. This is a limitation of the emulator and not of Magic DOSbox or the Gemini hardware. See also the README.TXT for the emulator itself. APPENDIX A ========== Details of patched locations in EPOC.DLL Hex Original byte New byte Notes offset or character or character ------------------------------------------------------------------------------ 3328 # ` 33DC " @ 33DE %9C # 3426 @ " 342C ~ | 35DE 3 %9C Produces £. Requires Alt-3 not Shift-3 35E0 4 %A9 Produces (c) because the Euro symbol is not present in codepage 850. Requies Alt-4 not Fn-4 $363E . %FA Produces middle dot character. Requires Alt-? not Fn-? APPENDIX B ========== Notes on using the free version of Magic DOSbox. Althogh the emulator is fully functional under the free version of Magic DOSbox, importing of profiles is not supported outside of the paid version. Because of this, some aspects of the emulation including custom paths and on-screen controls would have to either be constructed manually by the user, or copied into the required locations within Magic DOSbox' own configuration folders. Both of those methods are beyond the scope of this document, but for anyone who wants to give it a go all of the configuration files and graphic images are available inside the 'Emulator.mcg' file which is inside the 'S3aGemini.zip' file. 'Emulator.mgc' is itself just a renamed ZIP file. APPENDIX C ========== Alternative screen resolutions. In addition to the main 'Emulator.mgc' configuration import file, two more files called 'Emu11.mgc' and 'Emu1125.mgc' are provided. These are identical to the main configuration but have had the screen resolutions and scaling adjusted to more closely match the original Series 3a hardware. 'Emu11.mgc' runs the emulator at the native Series 3a resolution of 480 x 160 pixels, scaled to 1:1 so it fills the screen horizontally. It also includes a virtual bezel at the top of the screen to "hide" the unused screen area. This is the most Psion-like emulation for apps that expect the native resolution, but doesn't make full use of the Gemini screen. 'Emu1125.mgc' also runs the emulator at the native resolution of 480 x 160 but increases the vertical scaling to 1.25x so that it fills the space above the virtual Button Bar. This also provides more compatible screen emulation but the vertical stretch may appear too extreme for some users. Both of these additional configurations may be installed alongside the main configuration and run on demand, but they use the same emulated Series 3a drives and so will display the same apps. WARNING: The two alternative configurations work by scaling the image beyond the normal 150% limit imposed by Magic DOSbox. Be VERY careful if using the 'Adjust Screen' option when using these configurations, as the GUI will allow you to shrink the screen but not re-enlarge beyond 150%. If the Save icon is then used the configuration will be permanently locked unless re-imported from the MGC file. Note that the virtual bezel in the 1:1 configuration is outside of the emulated DOS screen and will not change colour to match the rest of the screen if the Green, Amber or Grayscale options are selected within Magic DOSbox.