AspeQt User Manual
(version 0.8.5)
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:
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 not guaranteed to work
in every case.
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.
AspeQt emulates 15 disk drives. You can see one
slot for each of them labeled D1 through DO (letter O). D9
through DO are only supported by SpartaDOS X and compatible DOS (see SDX
manual for details on supported disk drive identifiers). You can mount a disk image by:
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. Folder Images are compatible with
Atari DOS, MyDOS, all versions of Spartados and SDX, there may be some compatibility
issues with other 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”.
Support for ASCII and ATASCII is provided.
Running multiple instances
of AspeQt (Sessions)
AspeQt allows you to save and load your disk 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” menu items.
As of version 0.8.2 AspeQt fully implements multi session capability.
This means you can now launch multiple instances of AspeQt using different
session files and have different configurations for each session.
This makes possible serving more than one Atari computer from one PC so long as
you have more than one COM port and SIO2PC cable available. Simply create
different sessions with different settings and save them to a permanent session
file (a file with .aspeqt file extension).
If you plan on serving more than one Atari computer simultaneously, make sure
that the PC is fast enough to handle similtaneous SIO requests as Atari SIO is
very time critical and can fail if the requests are not serviced in a timely
fashion. Experiment with the multi-session capability and verify that it
can be run reliably before you put it on serious use.
The following parameters can be configured for individual sessions (stored
in each session file)
The following configuration parameters are global and apply to all sessions (stored in Windows registry)
The following configuration parameters apply when AspeQt is launched without a session file (stored in Windows registry)
To launch a session, create a shortcut
(Windows) or a
link (Unix/Linux) in a folder with the session file name as a command line argument:
An example of a shortcut for Windows would be:
"C:\Program Files\AspeQt\aspeqt.exe" C:\Program
Files\AspeQt\session.aspeqt
AspeQt client software for the Atari (AspeCl)
AspeQt also implements a client service device which communicates with the client module of AspeQt (AspeCl) that runs on the Atari computer. AspeCl is a general purpose client module and incorporates the following functionalities:
AspeCl Usage (command line switches, at least one must be specified)
Aspecl TS | TO | TF | DA | DS | DU | DM | DN
TS
=> Set
Date/Time on
Atari
TO =>
Set Date/Time
on Atari
and turn
TD Line
ON
TF =>
Set Date/Time
on Atari
and turn
TD Line
OFF
DA[ds] => Toggle
auto-save OFF (s=0) or ON (s=1), on a given disk image (d)
(where d is 1 to 9 and J to O, following SDX naming conventions).
Toggling auto-save switch to ON will commit all pending changes to the affected
disk image. Can be used to make sure all changes are committed before unmounting
a disk image remotely. If the toggle is set ON on a newly created and mounted
disk image (mounted locally by AspeQt), operator intervention will be required from the server (AspeQt)
side to assign a permanent file name to the image file before it's saved to PC hard disk.
DN remote command below does not have this limitation as it already assigns a
file name to the new disk image.
DS[dd]
=> Swap
disks, where
dd represents
the drive
numbers to
be swapped
(i.e DS1J
will swap
disks 1
and 10)
DU[d/*] =>
Unmount disk(s).
Will either
unmount a
single disk
[d], or
all disks
[*]. Unmount will
not unmount
disks that
have changes
until the
changes are
commited. Disks set
to "auto-commit"
in AspeQt
will be
unmounted immediately as the
changes to
these images
are commited
automatically as they occur.
DM[fname.ext] =>
Mount an
existing disk
image. Will mount
a supported
disk image
file from
the last
disk image
directory used
by AspeQt. The
new image
will be
mounted to
the first
available disk
slot. Command will return the used disk slot number to Atari.
DN[fname.ext].[1/2/3/4/5] =>
Create and
mount a
new disk
image. Will create
a new
disk image,
assign a
name to
it, and
mount it. The
disk image
will be
created in
the last
image directory
used by
AspeQt and be mounted on the first available disk slot. Command will
return the used slot number to Atari.
1 -
Standard Single
Density
2 -
Standard Enhanced
density
3 -
Standard Double
Density
4 -
Double sided,
double density
5 -
Double density
Harddisk
Example: ASPECL DNmyhd.atr.5 => will
create and mount a double
density harddisk
.atr image
with the
name myhd
And here's an example of invoking
AspeCl with
multiple command
line switches:
ASPECL TF
DS18 DMbasicxe.atr
=> will
set the
date/time and
turn TD
line OFF,
will swap
disks 1-8,
and will
mount basicxe.atr disk image to the
first available disk slot, returning back the slot number to Atari. Note that
disk drive numbers must be 2 digits including the leading 0 (zero)
Apetime
AspeQt can also use
Apetime to set the date/time on the Atari computer. Apetime is available in the
APE package. Support for Apetime however is
deprecated with the introduction of AspeCl.
Copyright (2010), Fatih Aygün
Updates by:
Copyright (2012), Ray Ataergin (www.atari8warez.com)