AspeQt User Manual
version 1.0
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, Linux and Mac
OS X. 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 5.2.1 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 Serial-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 officially supported as it uses proprietary USB device drivers.
You can get a RS232 or Serial-to-USB based SIO2PC cable
from Atari8Warez
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 zipped source.
You will need Qt 5.2.1 libraries and build tools to compile. After installing them,
please follow the instructions in compile.txt that comes in the zip file. Pre-built
packages of earlier/current versions for popular Linux distributions may be obtained
from www.atariaxle.de
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, CTS and NONE. Check your SIO2PC
interface’s documentation to learn which one of them is used for your cable. Note
that NONE (no handshaking) is highly experimental and not recommanded for
day-to-day use, in this mode AspeQt will ignore Atari's command line (SIO7) and
will monitor the COM port's RXD (Atari SIO5) line instead. No handshaking mode was
included to experiment with wireless (bluetooth) serial interfaces.
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 and/or on a slow CPU computer.
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. Usually
real COM ports and some VCP (Virtual COM Ports) don't support arbitrary
baud rates, FTDI chip based serial-to-USB cables do support arbitrary baud rates,
and are thus the recommanded type of cable for use with AspeQt.
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. 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 (still in development), and .pro formats. Future
releases may provide support for .scp, .dcm, .di and gzipped (.atz. atr.gz, .xfz
and .xfd.gz) formats.
AspeQt emulates 15 disk drives. You have 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 make AspeQt to show only the
first slot, the first 8 slots, or all 15 slots using options in DISK and WINDOW
menu items.
+ To hide/show drives D9 through DO, use menu item Disk/Hide drives D9-DO (CTRL+H),
+ To toggle AspeQt mini mode use menu item Window/Toggle Mini Mode (CTRL+M),
in mini mode AspeQt shows only the first drive slot,
+ To toggle shade mode in mini mode use menu item Window/Toggle shade
mode (CTRL+S), in shade mode AspeQt shows a semi-transparent window
which does not completely block the view of underlying UI objects,
Note that all drives are actually available for use with your Atari in all
AspeQt display modes whether they are visible or not.
You can mount a disk image to an empty drive slot 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
<<<<<<< .mine
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 DOS2.5 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.5 disk and it’s sequantial access (Basic NOTE/POINT commands will not
work as expected) and read-only . Although Folder Images are simulated and
behave like Atari DOS 2.5, there are some differences. The most important difference
is that each file can be as large as 8MB in size and file sizes are shown as number
of bytes as opposed to number of sectors (unlike Atari DOS). Maximum number of files
in the directory is 64 and subdirectories are not supported. Folder Images are also
compatible with MyDOS, all versions of Spartados and SpartaDOS X. There may be issues
with others.
Folder images are also bootable as of version 0.8.5, but since the folder image is a simulation of a standard DOS 2.5 disk, you can only boot into a DOS that is compatible with AtariDOS disk structure. There are two exceptions to this, first one is SpartaDOS, AspeQt will allow you to boot into a 3.2f version of SpartaDOS but there are some limitations. AspeQt will also allow you to boot into the standard version of MyPicoDOS 4.05. See the following section for for details and limitations:
======= 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 DOS2.5 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.Folder images are also bootable as of version 0.8.5, but since the folder image is a simulation of a standard DOS 2.5 disk, you can only boot into a DOS that is compatible with AtariDOS disk structure. There are two exceptions to this, first one is SpartaDOS, AspeQt will allow you to boot into a 3.2f version of SpartaDOS but there are some limitations. AspeQt will also allow you to boot into the standard version of MyPicoDOS 4.05. See the following section for for details and limitations:
>>>>>>> .r78Folder boot details and limitations:
To boot your Atari with a Folder Image, first mount
a PC folder to disk slot 1 (D1:). Once mounted, right-click on the Folder name and
select Folder Boot Options from the menu,
select the DOS you would like the boot and click
Apply. make sure AspeQt is ready to receive commands from your Atari
and finally turn your Atari ON, selected DOS will be booted. You must select a DOS
boot option if you mounted a Folder Image for the first time and you want to boot
your Atari from that folder whenever the folder is mounted. You normally only select
the DOS option once for each Folder Image. The Folder will remain bootable with
the same DOS between AspeQt sessions.
Warning: AspeQt will copy the necessary DOS files into the mounted
PC Folder to make it bootable. Do not keep any other DOS files (like dos.sys, dup.sys
etc..) on that folder as they will be erased/replaced.
Note that you don't need to supply any DOS files, AspeQt
distribution supplies the files necessary to boot your computer. These DOS files
are copyright of their respective owners, Atari8Warez and AspeQt distributes those
files with the understanding that they are either freeware, abandonware or public
domain and are widely available for download through the internet. If you are the
copyright holder of one or more of these files, and believe that distribution of
these files constitutes a breach of your rights please contact
Atari8Warez. We respect the rights of copyright
holders and won't distribute copyrighted work without the rights holder's consent.
The following DOSes can be booted from a Folder Image:
Atari DOS 2.5 AspeQt Folder images are fully compatible with this DOS, you can boot the DOS and load drivers and binary files (autorun.sys) during the boot process. AspeQt supplies the dos files (dos.sys, dup.sys) and the ramdisk driver (ramdisk.com). You can add your own autorun.sys file by copying the file into the folder $bootata which is located in AspeQt application directory. You can also use DOS 2.0 instead of 2.5 by simply replacing the dos.sys and dup.sys in $bootata folder with the ones from a DOS 2.0 disk.
MyDOS 4.5 This DOS is disk structure compatible with AtariDOS, so everything that's said for AtariDOS 2.5 above is also valid for MyDOS. Boot files folder for MyDOS is $bootmyd
MyPicoDOS 4.05 This game DOS is provided
to support Folder Images which hold Atari games. You can quickly boot and start
your games conveniently from a PC Folder. Only standard
version of MyPicoDOS is provided and supported. When selecting MyPicoDos
as your boot DOS there is an extra option on the menu to
disable high speed SIO code built
into this DOS. If checked, this option will instruct MyPicoDOS to run in normal
speed. This may be necessary under certain configurations. One example is if
you are using an Ultimate 1MB board or a PBI device like IDE Plus 2 on your
Atari with high-speed OS enabled. MyPicoDOS used in high-speed mode will conflict
with the high-speed OS on the Atari, so checking this option and booting and
running MyPicoDOS in normal speed will solve this problem.
AspeQt will also automatically generate a piconame.txt file during
the Folder Image boot process. So if you have game files with long file names
they will be displayed with their full names when MyPicoDOS menu appears.
piconame.txt file will only be created/updated when you boot,
so if you add more game files to your PC folder during your MyPicoDOS session
they will not show with long names until you reboot.
Boot files folder for MyPicoDOS is $bootpic.
it is not recommanded to modify this folder, unlike AtariDOS and MyDOS there
are no customizations you can make for MyPicoDOS.
SpartaDOS 3.2f SpartaDOS is not compatible with AtariDOS. Its disk/file structure and boot scheme is completely different. So this DOS is only partly (and I would say rather crudely) supported. You will be able to boot SpartaDOS version 3.2f from a Folder Image with the following limitations:
To boot SpartaDOS from an AtariDOS structured Folder Image is an impossible task. So AspeQt uses some (not so elegant) tricks to coherce SpartaDOS into booting from an AtariDOS compatible Folder Image by giving it the impression that it's booting from a SpartaDOS formatted disk. Once the boot is completed AspeQt forces SpartaDOS to re-detect the Folder Image as an AtariDOS formatted disk so that it can display and manipulate the files within the folder. The mechanics of this scheme necessarly limits the boot proccess in the following ways:
You can not load drivers or run an autorun.bat file during the boot process
Once booted from, a Folder Image won't be bootable again until you right-click on the Folder Image name, select Folder Boot Options, select SpartaDOS 3.2f f and click Apply. This will reset the Folder Image boot files and will make the folder bootable once again.
You can not modify/delete files in the boot files folder $bootspa
The restrictions and limitations may be lifted in the upcoming versions of AspeQt.
Running Atari executables
Most Atari programs floating around on the internet 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. You can leave the dialog open to boot from the
same executable more than once. A reload button is provided which will reload the
executable into memory. This button is intended for atari software developers who
may be developing on the PC and testing their software after making changes to it.
Reload button will ensure the most recent executable is loaded from the PC, and
as such is mainly a convenience feature for such developers.
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 constantly under development
and may change with each release, so use it with caution.
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. You can print a directory of
files by clicking on the printer button.
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 server device ($46) which communicates with the client module 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[d/*] => Toggle Auto-Commit ON or OFF on a
given disk (d) (where d is 1 to 9 and J to O, following SDX naming conventions)
or on all (*) disks. Toggling auto-commit switch to ON will commit all pending
changes to the affected disk image and all future changes will be comitted automatically.
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 AspeQt
side to assign a permanent file name to the image file before it's saved to PC hard
disk.
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. So if there are pending changes for a disk when
you want to unmount it remotely, first issue a DA remote command to the same disk
to toggle auto-commit. Once auto-commit is toggled ON any pending changes will be
commited to disk. You can then issue the DU command to unmount that disk remotely.
DM[fname.ext] =>
Mount an
existing disk
image command will mount
a supported
disk image
file (.atr, .atx, etc) into the
first available
disk slot. Command will return the used
disk slot number to the Atari. It is important to note that AspeQt needs to
know where the disk image file resides on PC. AspeQt will look for the disk image
file in the "Last Folder Image Directory". A Folder
Image is a window into one of the PC directories where your Atari files may reside.
This Folder Image does not need to be currently mounted to AspeQt but must have
been mounted at least once before so that AspeQt knows the name of this
directory. If a Folder Image has never been mounted,
AspeQt will display an error message indicating that it does not know where to find
the remotely requested disk image file.
DN[fname.ext].[1/2/3/4/5/6] =>
Create and
mount a
new disk
image. Will create
a new
disk image with the given
name, and
mount it. The
disk image
will be
created in
the "Last Folder Image Directory"
used by
AspeQt and be mounted on the first available disk slot. Command will return
the used slot number to the Atari. It is important to note that AspeQt
needs to know where the disk image file will reside on PC. AspeQt will save the
disk image file in the "Last Folder Image Directory".
A Folder Image is a window into one of the PC directories where your Atari files
may reside. This Folder Image does not need to be currently mounted to AspeQt but
must have been mounted at least once before so that AspeQt knows the name of this
directory. If a Folder Image has never been mounted,
AspeQt will display an error message indicating that it does not know where to save
the remotely created disk image file.
The Disk Image
can be created in the following capacities:
1 -
Standard Single
Density (90KB)
2 -
Standard Enhanced
density (130KB)
3 -
Standard Double
Density (180KB)
4 -
Double sided,
double density (360KB)
5 -
Double density
Harddisk (256 bytes/sec, 65535 sectors, 16MB)
6 - Quad density Harddisk (512 bytes/sec, 65535 sectors, 32MB)
Example: ASPECL DNmyhd.atr.6 => will
create and mount a
quad 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.
AspeCl compatibility
AspeCl is currently a command line based client which is fully compatible with and runs only under SpartaDos (v2.5 and up) and SpartaDos X versions. A seperate menu driven client for menu based DOS (like AtariDOS and MyDos versions) will be available in the future. Some of the functionality in AspeCl also depend on the underlying DOSes capabilities. For example setting the Date/Time from the PC is a DOS dependent feature as it requires specific Date/Time drivers from the DOS. Other functionality like mounting/unmounting/swapping disk or folder images are DOS independent and therefore are available under different DOSes.
Original AspeQt code up to version 0.6 Copyright (2010), Fatih Aygün
Updates since version 0.6 Copyright (2012), Ray Ataergin (www.atari8warez.com)