As you work through this tutorial you will start to get the idea that the purpose of this is to not only show you step by step how to configure a working Amiga 500 emulation but also to teach you some good working habits, a bit about AmigaDOS and its commands, and to get comfortable installing and configuring software. Each step more or less builds on previous steps, and over time I will be assuming more and more that you'll understand shortcut instructions instead of painstakingly pointing out every single step along the way. Think of this guide as training wheels that gradually come off.
We are going to gather some utilities to make our Amiga 500 emulation a little more comfortable. But before we get into that, we are going to create a new volume for our Amiga that will act as a conduit between it and the Raspberry Pi. In Raspberry Pi File Manager, go to the /home/pi/Amiberry folder, and create a new folder called Transfer. In Amiberry's GUI, make sure that we have the Amiga 500 configuration selected and loaded. Then go to the Hard drives/CD section, and click the Add Directory button. Disable the Bootable attribute, and select the Transfer folder we just created.
Hit OK, go back to Configurations, and click Save. Once we start up the Amiga emulation, a new volume will appear in Workbench named Transfer that will allow us to pass files to and from the Amiga OS environment.
Gathering Resources
In Raspberry Pi OS, we are going to download a number of utilities that will make life working with the Amiga as smooth as possible. Most of these utilities will be useful for all three of the different Amiga OS environments we will be building. As you download these resources, move them to the /home/pi/Amiberry/Transfer folder. The source for most of my choices here came from this excellent article on Workbench 1.3 by intric8 over at Amiga Love. That is a good place to go for further explorations of all things Amiga.
LHA
The fashion for compression archive formats changes over the years. Currently ZIP is king. On the classic Mac, it was SIT. On the Amiga, it was LHA or LZH. You'll need this before you can go much farther. Note, the version on a naive search of Aminet will not function properly in Workbench 1.3. You will need the e138 version. Download it here.
UNZIP
Sometimes you do run across a utility for the Amiga that comes in a ZIP archive. For those moments, you need Unzip. Download it here.
SYSINFO
This little utility is a handy way to measure the performance of our created Amiga environments. Not essential, but this tool will tell you what the performance of the emulated machine is vs. the real deal. The Raspberry Pi does a very good job of giving you the real world speed of most Amiga models. Download it here.
QMOUSE
A tiny enhancement for mouse and windows behavior in Amiga Workbench. Download it here (it is part of a Fred Fish shareware disk).
MUCHMORE
A document reader utility that features automatic smooth scrolling, and is a bit easier to use than the MORE command. This is found on the same Fred Fish as QMouse.
DISK MASTER
Disk Master is one of the original 2-pane file managers. Download it here.
WSHELL
A terrific shell enhancement that is much more user-friendly than the default Shell command. Download it here. (Also, check out this great article on WShell by Battleman on Amiga Love.)
Workbench 1.3 Guide
This is a handy guide for how to use AmigaDOS 1.3. Download it here.
A Place for Documentation
We're going to create a drawer for documents on our System volume, but we want this to be visible in Workbench -- meaning we would like it to have an icon. To do this, we will use the Workbench to create the drawer for us. Open the System icon, and then locate the drawer named Empty. Click once on it to highlight it, and then Right click. Select Duplicate from the Workbench menu. A copy of the Empty drawer will be created. Drag this icon into a new location in the System window, and then Right click and select Rename from the Workbench menu. Finally, Right click and select Snapshot from the Special menu.
Installing the Utilities
Install LHA
Start your Amiga emulation, and when it finishes booting up, you should see three volume icons on the workbench: RAM, System, and Transfer. Open System, and start up a Shell (CLI). We are going to be using the Amiga CLI to do much of our work here because the Workbench environment with its icons is more suitable to day to day use, and not for system configuration. For example, the Workbench in 1.3 cannot display files that don't have an icon associated with them (called .info files)
Extract the LHA utility files to RAM:
transfer:lha_e138.run ram:This will run a self-extracting archive containing files we need to install LHA to a RAM disk. RAM: is a handy place to do these kinds of operations because you can mess it up all you want, and your files will be cleaned up after the next reboot. You will be greeted with several prompts as this extracts. Press Y to at the first prompt, and then when complete, Press S to skip the remaining prompts.
Now use this command to copy the lha command to your C: directory. C: in Amiga DOS is where all of the Commands are stored. When you type a command into the CLI, C: is one of the places where Amiga DOS is going to go look for it.
copy ram:lha c:LHA is now installed. Test it out by typing:
lhaYou will be greeted with a wall of text in the way of instructions for the utility.
Install Unzip
In the CLI type the following commands:
makedir ram:unzip
cd ram:unzip
lha x transfer:unzip
cd unzip_v5.40
copy UnZip c:
copy Docs/UnZip.doc SYS:DocumentationDescription of what we did here: Created a new folder in RAM, cd to that folder, extracted an archive from the transfer: volume -- because we didn't specify a target, the files are extacted to the current directory, then we cd to the newly extracted directory, copied the unzip command to the c: directory, and copied the documentation to our Documentation folder. There are other commands related to unzip in that same directory - type dir to get a list of the directory contents and copy other commands that you might want to the c: directory.
Install SysInfo
In the CLI type the following commands:
lha x transfer:SysInfo ram:
copy ram:SysInfo TO SYS:Utilities/SysInfo ALL
copy ram:SysInfo.info TO SYS:UtilitiesClean up Your Workbench
Now if you go into Workbench and open the System volume, and then open the Utilities drawer, you should see a new drawer there called SysInfo. Chances are it's hiding out underneath the Notepad icon. Grab the SysInfo drawer icon and pull it down into a clear area. You might need to adjust the window size to make room. Once it is where you want it, Right click and in the Special menu at the top of the screen, and select Snapshot. That will record the position of whatever is currently highlighted - the volume and its window, or the position of the currently highlighted icon. Workbench 1.3 had very limited abilities to keep your icons tidy - this was a task left largely up to the user.
Open the SysInfo drawer, and Double Click on the SysInfo icon. A screen will open that displays detailed information about your Amiga. In the bottom center, you'll see a button labelled SPEED. Click that, and you should see some comparisions between the speed of your current machine and several different real-world examples of Amigas. The A500 was roughly the same speed as an A2000 so the numbers here are pretty close. The numbers in the "You" column indicate how much faster or slower your Amiga is in comparison to other standard models. In this case, we are faster than an A600 (originally meant to be called the A300) and slower than an A1200 (an improved version of Amiga).
Install QMouse
QMouse is a mouse accelerator utility that also has a number of other tricks up its sleeve, including mouse blanking and screen blanking. It was published on the Fred Fish disks, and is very small and light on system resources, being written in 68000 assembly rather than the more traditional C programming language common on the Amiga. To install it, first we have to extract the entire archive for this particular Fish disk. We'll do it in RAM so that cleanup is a system Reset away.
makedir ram:fish
cd ram:fish
lha x transfer:fish-0262
cd ram:fish/qmouse
copy QMouse TO C:
copy QMouse.Doc#? TO SYS:DocumentationWhat is the #? in that last command? That is a wild card. The # means "any single character" can match. The ? means "any number of characters that match the preceeding rule". By issuing the command this way, the copy command can match both QMouse.Doc and QMouse.Doc.info, and copy both of them.
While we have this all expanded, lets also copy MuchMore to C: as well.
copy ram:fish/c/MuchMore TO C:Now, to activate QMouse we are going to add it to a new startup script so that it runs every time we boot up the Amiga. You might want to take a break at this point, hit F12 , and quit Amiberry. Then create a backup copy of your /home/pi/Amiberry/systems/1.3/System130.hdf file. This is just insurance against messing anything up at this point -- having a backup will reduce any pressure. All set? Restart Amiberry, reload the A500 configuration, and Start. Open up the System volume, and open a Shell.
ed s:startup-sequenceScroll all the way to the bottom of the file, and then just above the line that reads EndCLI >NIL: add the following lines:
;Run user-startup script if one is present
IF EXISTS S:user-startup
C:EXECUTE S:user-startup
EndIF
Now press ESC, then X, then RETURN to save/exit ED. These new lines will tell the startup-sequence to look for and execute a script called user-startup in the s: directory if it is present. Then type:
ed s:user-startupThis will create a new script. This is where we are going to keep all of our custom startup modifications, so as to avoid further editing the startup-sequence. Add these lines and then save/exit out of ED.
;QMouse START
STACK 2000
RUN >NIL: C:QMouse -A0 -CM495 -B -V20000
STACK 20000
;QMouse END
When you have finished the edits, save/exit out of ED. Here's a brief explanation of what we have added to the user-startup:
Lines that begin with a ; are comments - they are for humans to read and understand. Nothing in them is crucial or required, but you should get into the habit of putting these comments around sections you add to system scripts, as future-you will thank you for making them.
STACK 2000 sets the stack to 2000 bytes (2K). Every application in AmigaDOS has its own stack -- a piece of memory the application can use for its own variables and data. Because QMouse is a very lightweight program this is all it needs.
RUN >NIL: means that the command that follows will be run detached from the shell or script that starts it. This allows the shell to be subsequently closed, and the command will continue running in the background.
C:QMouse is the path where the QMouse command is located. RUN needs the path specified in its command line.
-A0 -CM495 -B -V20000 are command line parameters given to QMouse to tell it what options you would like to have available while it is running. These particular options specify no mouse acceleration (-A0)(unneeded on the Raspberry Pi), Clock and Memory display starting at screen column 495 (-CM495), click to Back option enabled (-B), and what the stack size QMouse run commands should have (-V20000).
STACK 20000 restores the stack size to the default of 20000 bytes (20K).
QMouse does a lot more than this, but I will leave it as homework to read the documentation and find out some of its other features.
muchmore sys:documents/QMouse.docHit ESC to exit MuchMore when you are finished.
Hit F12, and then Reset in the Amiberry GUI. Your Amiga will boot up again, but now should have a little clock and memory display in the upper right corner of the Workbench, and you will be able to double-click on windows to bring them to the front, or Left-click and hold, Right-click on windows to send them to the back. Additionally, windows should auto-activate simply by running the pointer over them. Much more convenient than the default behavior. If for some reason you don't like one or more of these features, you can edit the user-startup file to remove those parameters from the qmouse command line.
Install Disk Master
Disk Master is a two-pane file manager that hearkens back to the old text based Norton Commander, and is recognizable today in various incarnations as Total Commander, Double Commander, Midnight Commander, or even in such applications as FileZilla or WinSCP.
Start a Shell and run the following commands:
makedir ram:dm
cd ram:dm
unzip transfer:dm2v34
copy DM2.V34 c:DMNow when you type the command DM in a shell, you will be greeted with Disk Master. The first time you run it it will give a brief error message, but that's the only time you'll see it.
If you find the default palette a little hard to read, you can always use the Right-click to get to the menu, and adjust the palette, and save the configuration. You can also quit by either Right-click and select Quit, or you can use the Right-Amiga Q key combo. On the Pi 400, this is accomplished by holding down Fn and Home (right cursor) and tapping the Q key.
Install WShell
By this point you should now have some familiarity with AmigaDOS commands and ways of doing things. Installation of WShell might be a bit more challenging for novice users, but I believe in you! You've gotten this far! Maybe quit Amiberry and make a backup of your System130.hdr file, just to take the pressure off.
Start a Shell and run the following command:
cd transfer:
lha x wshell20Note that this is an unusual step -- we are extracting the archive in the Raspberry Pi's file system rather than RAM: This is because this particular archive contains both an ADF file which we have to use in Amiberry's GUI, and a PDF file which is large (by Amiga standards) and more importantly, an unknown file format for the Amiga. Note that it will appear that nothing is happening while the PDF file is extracted. It is a 12Mb file, so it will take some time to complete. Once the archive finishes extracting, press F12 to switch over to Amiberry's GUI, go to the Floppy drives section, and use the "..." button in the DF0: section and select the /home/pi/Amiberry/Transfer/WShell2.0/WShell-v2.0.adf file, and then hit Resume. After a brief pause, the WShell volume will appear on the Amiga Workbench. In the shell, type the following commands to install WShell:
cd wshell:
install-wshellTo finish up, add these lines to the S:user-startup file we created earlier:
;WShell START
assign remove CON:
C:DHOpts CON: PIP:
C:FComp
;WShell END
What's happening here? We are removing an assigned device named CON: that normally handles console windows, and we are reassigning it to the new DHOpts display handler. Then we are activating command history using the new FComp command. This is covered in detail in the WShell documentation which can be found in the PDF file in your Raspberry Pi's file system in /home/pi/Amiberry/Transfer/WShell2.0 directory.
To polish this all off, lets add an icon to the System: volume so that we can open WShell from the Workbench, just like the Shell command. Using Workbench, open the System window. Now open the WShell window. Locate the icon for WShell, and drag it to the System window to copy it (remember to Snapshot its position once you have placed it where you want it). Now we need to edit this icon's ToolTypes. This an Amiga concept, and this is a good way to learn about it. ToolTypes are like command line parameters, but for icons in Workbench. Single click on the WShell icon to highlight it, and then Right-click and go to the Window menu and select Info.
You will see the Info Editor. We want to adjust a number of this icon's properties:
change the default tool to c:NewWSH
This tells the system to use the NewWSH command in C: when this icon is opened.
change the first tool types option to CONSOLE=CON:0/140/640/140/WShell/CLOSE
This tells the icon to open a new console window using the CON: device, located at 0/140 (roughly halfway down the screen), 640 pixels width and 140 pixels tall, named WShell, and to include a CLOSE gadget in the window (note that the default Amiga shell had no close gadget).
There is another tool type we need to change here. Using the little up and down arrows, we can move from each different tool type parameter to edit them. To disable a parameter, we put an asterisk in front of that line. We want to disable the following tool type parameter:
*CMD=echo "The project icon command"
When you are finished with these edits, hit SAVE to save and exit the Info editor.
There is one last thing to adjust. The default WShell command prompt is, to me, less than useful. I am sure it meant something important to its creator, but it is just a mystery to me. So lets fix that. This prompt is set in the file S:WShell-startup, so lets edit that.
ed s:wshell-startupWhat I would prefer to see on the command line is the current path for the shell. We already have a clock thanks to qmouse, and we don't really know what the rest of that information is, so lets change the prompt. Consulting the manual, we see that we can set the prompt parameters to %c to get what we want.
When you use WShell instead of the built in Shell, you gain features like command history, implied CD, and command line completion. For example, in a WShell you can type a partial command like "ed s:wsh" and then hit the ESC key and watch it expand it out to the full filename to edit. You can also use shortcuts to CD to other directories like "ram:" instead of "cd ram:", and so on. It will very quickly become second nature. I recommend that you move the WShell2.0.ADF file from the folder in /home/pi/Amiberry/Transfer/WShell2.0 and put it in /home/pi/Amiberry/adf/ for safe keeping and future access. You should also put the associated PDF file somewhere, like /home/pi/Documents for future reference. What has been covered here barely scratches the surface of what WShell can do, so it is worth having a look through the documentation as you get more familiar with the utility.
That's it for this very long tutorial. I hope you learned a bit more about the Amiga, but we're done with the serious stuff for now. In the next installment, we are going to install Deluxe Paint, a fun little program called HippoPlayer for playing some music, more. Thank you for reading!