AspeQt User Manual

AspeQt User Manual

Introduction

AspeQt is a cross-platform, free and open source Atari 8-bit serial peripheral emulator. The name is an acronym for Atari serial peripheral emulator for Qt, Qt being the cross-platform application development framework used by AspeQt.

You can download AspeQt from the SourceForge project page.

AspeQt emulates various Atari 8-bit peripherals like disk drives and printers via a SIO2PC cable. If you are familiar with software like SIO2PC, APE, Atari810, AtariSlO etc., you probably won’t have any problems getting used to AspeQt.

Even though AspeQt is not fully mature yet, it is easy to use and, despite its shortcomings, has many features that you may find useful, the highlights being:

Cross-platform GUI with drag and drop support
8 emulated disk drives with support for 512 bytes per sector disk images
High speed operation up to 6 times faster than the normal speed
Ability to use PC folders as emulated disks
Disk image explorer for viewing and modifying disk image contents
Ability to run Atari executable without messing with disc images and Doses
Printer emulation
Cassette image playback

System Requirements

AspeQt currently runs under Windows and Linux but porting to Mac OS X and other Unix-like operating systems shouldn’t require too much effort. The absolute minimums aren’t easy to tell but a modern Linux distribution with Qt 4.6 libraries or a Windows XP (or newer) is recommended.

Although AspeQt is reported to run on a Pentium 233 MMX, a modem processor and a decent amount of RAM is strongly recommended for smooth operation. It runs fine on 64-bit CPUs.

In order to do anything useful with AspeQt, you will need an Atari 8-bit computer and a SIO2PC cable. SIO2PC cable is an interface that connects the Atari’s serial bus to the PC’s serial port. Since many newer PCs lack a real serial port, you may need a UART card, or a high quality RS232-to-USB adapter (FTDI chip based devices were tested successfully, others may not work as intended) or a SIO2PC USB interface (instead of serial), If you opt for the later however, please note that the “AtariMax SIO2PC Universal Interface USB Edition” is not supported as it uses proprietary USB device drivers.

You can get a custom made RS232 based SIO2PC cable from Atari8Warez or a standard RS232 based SIO2PC interface from AtariMax.

You don’t need any real Atari disk drives or printers to use AspeQt.

Installation

On Windows, AspeQt comes with all the required DLLs in a ZIP file. Just unzip the archive to a folder and run aspeqt.exe. You may manually create shortcuts on your desktop, start menu and quick launch bar if you want. Future releases may include an installer but it doesn’t exist yet.

On Linux, AspeQt comes as a gzipped source tarball. You will need Qt 4.6 libraries and build tools to compile. After installing them, please follow the instructions in compile.txt that comes in the tarball. Future versions may include pre-built packages for popular distributions but they don’t exist yet.

If you want to use the AtariSlO backend, which is highly recommended if you have a real RS-232 serial port, you will need the AtariSlO package. Please follow the documentation that comes with that package to compile and install it.

Configuration

In order to be able to use AspeQt, you need to configure it to suit your hardware. When it’s running for the first time, a dialog will pop up asking you if you wish to open the configuration dialog. Click “Yes” to open the Options dialog. You can also access this dialog from the Tools/Options menu item.

On Linux, you have to choose a serial I/O backend first. If you have installed the AtanSlO package and you have a RS-232 port, the recommended way is to use the AtariSlO backend. If you have a USB adapter or you don’t want to use AtariSIO for any other reason, choose the standard serial port backend. This is also the only available backend on Windows.

Configuring the standard serial port backend
First, enter a port name. On Windows, it should be something like COM1, COM2 etc. Check the device manager to see which one of them is installed. On Linux, it should be /dev/ttyS0, /dev/ttyS1 etc. for RS-232 ports or /dev/ttyUSB0, /dev/ttyUSB1 etc. for USB adapters.

Next, you will have to select a handshaking method. The handshaking method tells AspeQt which one of the RS-232 pins is connected to Atari’s command line. There are 3 supported methods: RI, DSR and CTS. Check your SIO2PC interface’s documentation to learn which one of them is used for your cable.

The “High speed mode baud rate” combo box selects the transfer speed to be used for the high speed mode. Some OS /DOS for the Atari supports higher transfer speeds than the standard 19200 bits per second. Not all DOS /OS are capable of using 3x speed and some treat 2x as a special case for XF551 drives, so you may need some experimentation to find the best setting. 1x option is provided for unreliable connections, like when using a cheap USB adapter or when running AspeQt under virtualization software.

If your serial port supports arbitrary bit rates, you may check the “Use non-standard” speeds check box and select a POKEY divisor to be used in high speed mode, the lower the divisor, the higher the speed.

The exact formula for the nominal speed is:

baudRate = clock/ (2*(divisor+7))

Where dock is ~1,773,447 for PAL, and ~1,789,772 for NTSC, however, it’s not always possible to reach nominal speeds. So, 1x is divisor 40, 2x is divisor 16 and 3x is divisor 8. Divisor 0 is ~l26kbits/second and that means approximately 6x.

Please note that very few OS /DOS will be able to function with such high speeds. Currently the only tested software that can reach divisor 0 with AspeQt is the hisio OS patch. Also note that not all RS232 ports /adapters will support arbitrary bit rates. As a final warning, some Atari 8-bit computers have capacitors connected to their SIO lines that can interfere with high speed transfers. In short, speeds beyond 3x are highly experimental.

Configuring AtariSIO backend

Note: AtariSIO is available under Linux only!

After installing and running the AtariSIO module and making sure that you have the required permissions, you just need to enter a device name which should be /dev/atarisio0 under normal circumstances and select a handshaking method as described above for the standard serial port backend. Please refer to AtariSIO documentation on how to build and install AtariSIO.

Usage

After making sure that you installed and configured AspeQt correctly, you can start using it with your Atari. If you used similar software before, it should be fairly straight forward.

Disk images
Instead of using real disks, AspeQt uses disk images. These are regular files that contain an image of an Atari disk. There are several formats, the most common being the .atr format, currently AspeQt only supports .atr, .xfd, atx (preliminary), and .pro formats. Future releases will provide support for .scp, .dcm, .di and gzipped (.atz. atr.gz, .xfz and .xfd.gz) formats.

Currently, AspeQt does not support copy protected image formats like VAPI or ATP. AspeQt emulates 8 disk drives. You can see one slot for each of them labeled Dl through DB. You can mount a disk image by:

Dragging and dropping a file to the desired slot
Using the “Disk/Mount disk image” menu item (the first available slot will be used)
Using the “Mount disk image” tool button available in each slot
Right dicking on a slot and selecting the “Mount disk image” menu item
Selecting a recently used disk image from the “Disk” menu
By pressing Alt + 1 through Alt + 8

You can see the result of your operation in the log display which is below the disk slots, if the operation is completed successfully, your Atari should be able to see the mounted disk image just like a real disk in a real drive.

You can use the tool buttons and context menu items to perform other operations like saving the disk image, enabling write protection for the image, reverting the image to its last saved state, ejecting (unmounting) the image, creating a new image and so on. You can also swap images using drag and drop.

Folder images
Folder images provide a similar function to the features variously named as “PC mirror’, “Simulated disk”, “Share point” etc. by other peripheral emulators. This is basically a simulated Atari disk. Instead of a disk image, you can mount a folder in your PC that contains some Atari files and Atari will see it as a disk with the same files in it.

Currently, the mounted folder will be seen as a standard DOS 2.0s disk and it’s read-only. Also, there may be some compatibility issues with some DOS. The folder images are not bootable. But all of these shortcomings may change with the future versions.

Running Atari executables
Most Atari programs floating around on the net come as Atari DOS executables. These files may have .exe, .com, .xex or any other extension. Instead of messing with disk image software and DOS, you may directly run these files in your Atari using AspeQt.

You can either drag and drop a file with .exe, com or .xex extension into any slot or you can use the menu item “File/Boot Atari executable” to access this feature. A dialog with the necessary instructions will pop up and the file will be loaded and run.

The executable booter has an optional high speed code which will allow you to load programs a lot faster. You can enable/disable it with the “Tools/Options/Emulation/Use high speed executable loader” check box. The high speed code is not able to cope with higher speeds than divisor 3 so check your configuration before attempting to load a file in this way.

Please note that this feature is not compatible with every executable and, in practice, it’s not even possible to implement such a loader. High speed loader has even more issues. So there will always be some programs that you won’t be able to run with the executable booter but hopefully the number of the compatibility problems will decrease with future versions of AspeQt.

Image explorer

Warning: This feature is highly experimental. Use it at your own risk!

As mentioned above, AspeQt uses disk images instead of real disks. These images may contain Atari files and it’s not always easy to extract them from an image or to add a file into an image. By clicking the ‘Image properties’ tool button or by using the context menu, you can explore the files in a mounted disk image.

There are various file systems (ways of putting files in a disk) used by Atari. AspeQt supports the most common one, the Atari Dos file system (including the most used variants, like Dos 2.5 and MyDos) fully, including MyDos style subdirectories. It also has read-only support for SpartaDos file system. Other file systems (like Dos 3.0) are not supported at the moment.

By using the tool bar buttons in the image explorer, you can drag and drop, extract, add, delete Atari files with optional text conversion. You can also drag and drop files between different images and rename files by pressing F2 after selecting the name or extension of a file.

Cassette images
AspeQt can playback cassette images in .cas format. These are PC files that contain data extracted from an Atari cassette. You can either drag and drop a file with .cas extension into any slot or you can use the menu item “File/Playback cassette image” to access this feature. A dialog with the necessary instructions will pop up and the file will be played back.

The cassette emulator can be configured to ignore the baud rate that is embedded in the image file in favor of a custom one. This may speed up the load times but can cause compatibility problems. You can enable/disable it with the “Tools/Options/Emulation/Use custom baud rate for cassette emulation” check box. When enabled, you can use the spin box below to set the custom baud rate. The available values range from 425 through 875 bps. These values are the lowest and highest speeds that the Atari OS can process. The normal speed is 600 bps.

The cassette emulation does not support rewinding or seeking in the images. This may change in the future versions.

Printer output
AspeQt emulates a generic text-only Atari printer. It only emulates the first printer device, that is “P1:” You can view, save or print the emulated printer output using the “File/View printer text output”.

Other features
AspeQt allows you to save and load your sessions, that is, the order and names of the mounted images and their settings. You can access this feature from the “File/Open session” and “File/Save session as” menu items.

AspeQt also provides a date/time downloader device which communicates with AspeCl (the client module of AspeQt that runs on the Atari computer). AspeCl downloads the date/time from AspeQt and sets the same on the Atari, optionally turning the TD line ON or OFF through the use of command line switches. AspeCl is a general purpose client module and more functionality (other than Date/Time) will be added in future releases.

AspeQt can also use APETIME to set the date/time on the Atari computer. APETIME is available in the APE package, in the utilities disk image. Support for APETIME however is deprecated with the introduction of AspeCl.