Apple-2-Tools
/
apple2pi
mirror of https://github.com/dschmenk/apple2pi.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Initial documentation for FUSE and input devices

This commit is contained in:
dschmenk 2013-09-11 17:41:58 -07:00
parent b587eff287
commit 2b8ee46d27
2 changed files with 101 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/fuse.txt Executable file
View File

@ -0,0 +1,71 @@
1.0 Introduction:
================
This documents the FUSE driver included in the Apple II Pi project. See the project README.md for installation instructions.
2.0 Contents:
=============
Build and Installation
----------------------
Required Packages
make fusea2pi - Build the binary
fuse-install - Install tools, set group permissions
Commands
--------
fusea2pi - FUSE driver for ProDOS devices under Apple II Pi
a2mount - mount script taking care of uid & gid
fusermount - unmount FUSE mountpoints
3.0 Build and Installation:
===========================
Building the FUSE driver is broken out as a separate step because it has other requirements than the core Apple II Pi package. fusea2pi is the driver binary that mounts ProDOS devices attached to Apple II Pi. It does NOT mount image files or the like.
3.1 Required Packages:
----------------------
To build the FUSE driver, the libfuse-dev deb package has to be installed first. Use apt-get, aptitude, or your favorite package tool to download and install.
3.2 make fusea2pi:
------------------
Type 'make fusea2pi' in the apple2pi/src directory to build the driver. If the libfuse-dev package is installed, the binary should be built without error or warning.
3.3 fuse-install:
-----------------
Installation is a two step process. First, type 'sudo make fuse-install' to place the binary and script in /usr/local/bin. Next, add your user to the "fuse" group with 'sudo addgroup <username> fuse' (replace <username> with your actual user name).
4.0 Commands:
=============
The FUSE driver can be run directly, but the a2mount script removes some of the tedium.
4.1 fusea2pi:
-------------
The FUSE driver for Apple II Pi works closely with the Apple II environment to relect the FUSE function call into a ProDOS MLI call. fusea2pi knows very little about the details of ProDOS. PRoDOS itself does most of the work so that compatibility is guaranteed.
At startup, fusea2pi calls the ProDOS on_line funtion to retrieve all the ProDOS volumes available to the Apple II. fusea2pi then makes a directory for each volume named after the volume. In addition, each volume is made available as a raw device file named after it's position in the ProDOS device table. The two default 5 1/4 drives in slot 6 are always made available for non-ProDOS format floppies that can still be accessed in a raw mode. This way, volumes can be easily backed up (copied elsewhere) and emulators can have access to the physical media.
ProDOS filenames are munged in the same way that CiderPress attaches the meta information, type and aux, to the end of the filename, separated by '#'. Also, filenames are displayed in upper-case. The decision to munge the filenames in this was it in order to make a very visual distincion between the ProDOS files and regular *nix files.
The driver can run directly, but the helper script a2mount is the recommended way to mount ProDOS volumes. Runa as:
fusea2pi <mount point> [fuse options..] [+rw]
The last option (must be last) is a fusea2pi only option which allows the raw device files to be writeable. By default, they are read-only. It can be potentially dangerous to write to the raw device while Linux accesses the mounted filesystem. If an emulator is going to be writing to the raw device files, it is best to leave the mounted filesystem alone until the emulator is exited.
4.2 a2mount:
------------
The a2mount script calls the fusea2pi and fills in some additional parameters to give your username the ownership of the files. This is the preferred way to call fusea2pi. It can accept up to two parameters: one is the mount point, the second is the option +rw argument to make the raw device files writeable. Run as:
a2mount <mount point> [+rw]
4.3 fusermount:
---------------
To unmount the ProDOS filesystem, call the FUSE command as:
fusermount -u <mount point>
5.0 Conclusion:
===============
The FUSE driver for Apple II Pi is a remarkably effective way to access the files on Apple II media. Care must be taken when using the +rw option.
Enjoy,
Dave Schmenk

30
docs/input.txt Executable file
View File

@ -0,0 +1,30 @@
1.0 Introduction:
================
This documents the input devices supported by the Apple II Pi project. See the project README.md for installation instructions.
2.0 Contents:
=============
Keyboard - key mappings and special keys
Mouse - mouse and extra buttons
Joystick - joystick, joymouse, joypad
3.0 Keyboard:
=============
The keyboard is probably the input device used most with Apple II Pi. Now, Apple IIe and //c keyboards changed over the course of their lifetimes. Some were definitely better than others. If you are lucky enough to have the "clicky" //c keyboard, you will find it to be great input device for Linux. I also like some of the later IIe keyboards that aren't as "clicky" as the //c, but have a firm, positive, and smooth action. And the control key is in the proper place.
There are many keys unavailable on the Apple II keyboard that are useful in a modern computer. To fill in the gaps, the OpenApple and SolidApple keys are employed. The OpenApple key is mapped to the Left-Alt key and used to modify all other keys, just like you would excpect. The SolidApple key works as a funcion key to remap other keys. The current FN-x mappings turn the arrow keys into Home, End, Page-Up, and Page-Down. The number keys along the top row become F-1 through F-10. The DELETE key is BackSpace unless modified with Solid Apple to be a real Delete.
Three special key sequences affect the operaton of the Apple II client/server connection. SolidApple-ESCAPE will exit out of the client, returning control to the Apple II and leaving it disconnected from Linux. The Linux Apple II Pi daemon process is still running. The connection can be re-established by either running the STARTUP program, typing 'PR# a$9600', or pressing Ctrl-RESET.
Ctrl-RESET key sequence will re-establish the client/server connection and jump to the BASIC cold-start routine, assuming the client code hasn't been damaged.
Finally, OpenApple-SoldApple-ESCAPE will exit both the client and server programs. The client Apple II code can be restarted as above. The server daemon will have to be started from another computer logged in to the Raspberry Pi, or a USB keyboard connected to the Pi. Type 'sudo a2pid --daemon' to restart the server process.
4.0 Mouse:
==========
The Apple II mouse, if connected, will show up as a standard Linux mouse. The Open Apple key can modify the single mouse button to return MIDDLE_BTTN, and the Solid Apple key can modify the mouse button to return RIGHT_BTTN. If you don't have, or want to use, an Apple II mouse, any compatible USB mouse can be plugged into the Raspberry Pi. The mouse won't be available to the Apple II, but emulators will see it.
5.0 Joystick:
=============
Any Apple II gameport device can show up ad a Linux joystick with the a2joy driver. There is an additional X server rule to make sure joysticks don't get used as mouse control. It is automatically installed in /etc/rc.local but can be changed or removed.