12/14/2021»»Tuesday

Dragon For Mac 6 User Manual

12/14/2021
    53 - Comments

Table of Contents

  • 1 Getting started
    • 1.1 Installation & running
    • 1.2 Building from source
  • 2 Hardware emulation
    • 2.2 Cartridges
  • 3 Files
  • 4 User interface
    • 4.1 User interface module

Dragon Individual, v14 User Guide (PDF) (pdf. Open a new window) Dragon Professional for Mac, v6 User Guide (PDF) (pdf. Open a new window) Dragon 13 User Guide (pdf. Open a new window) Dragon Medical Practice Edition 4 Client Help (Open a new window) User guides for older versions of Dragon; Bluetooth Wireless Headset Guides Dragon Microphones. Dragon Professional for Mac User Guide 1 Get started 25 Using the Dragon menu 25 Related topics: 26 The Status Window 26 To show or hide the Status Window 26 To set whether the Status Window should be visible when Dragon starts up 26 Microphone mode button 26 Recognition mode button 27 Window menu button 27 Related topics: 27 The Guidance window 28. To register your copy of Dragon Professional Individual for Mac After activating your Dragon Professional Individual for Mac license, Dragon prompts you to register your product. If you choose to skip registration, you can access it at any time by clicking the icon in the menu bar and selecting Help Register for Support. Where Dragon Medical Practice Edition is installed. In addition, Dragon Medical Practice Edition and Dragon SDK Client Edition 11 can share user profiles and vocabularies. You can only run one product at a time. For example, if you are running Dragon Medical Practice Edition, you cannot run any of the SDK Client tools or samples.

This is really the first time that a Dragon product has started to make inroads into transcribing audio with more than one voice. Traditionally Dragon has be.

XRoar is a Dragon emulator that runs on a wide variety of platforms. Due tohardware similarities, XRoar also emulates the Tandy Colour Computer (CoCo)models 1 & 2. Some features are:

  • Emulates Dragon 32, Dragon 64, Dragon 200-E, Tandy CoCo 1 & 2, and compatibles.
  • Emulates DragonDOS, Delta and RSDOS disk systems.
  • Emulates the Orchestra 90-CC stereo sound cartridge.
  • Supports both raw and translated keyboard modes.
  • Reads and writes virtual cassettes (compact .cas files and audio files).
  • Reads and writes VDK, JVC and DMK format virtual floppy diskettes.
  • Saves and loads machine snapshots.
  • Provides a GDB target for remote debugging.
  • Games Master Cartridge support, including SN76489 sound chip.
  • MOOH RAM expansion + SPI support.
  • Glenside IDE support.

XRoar is easily built from source under Linux, and binary packages are providedfor Mac OS X and Windows.

XRoar can also be compiled to WebAssembly, and redistributing it in this formmay provide a convenient way for users to run your Dragon software. SeeXRoar Online for an example.

XRoar is free software; you can redistribute it and/or modify it under theterms of the GNU General Public License as published by the Free SoftwareFoundation, either version 3 of the License, or (at your option) any laterversion.

XRoar is distributed in the hope that it will be useful, but WITHOUT ANYWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR APARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along withthis program. If not, see <https://www.gnu.org/licenses/>.

1 Getting started

1.1 Installation & running

Pre-built binary packages are available from theXRoar home page. If one is notavailable for your architecture, you will need to build from source. XRoarshould build and run on any POSIX-like system for which SDL version 2 isavailable.

You will also need BASIC ROM images—binary dumps of the firmware from anoriginal machine. The originals were part-written by Microsoft, so they arenot distributed in the XRoar packages.

1.1.1 Mac OS X binary package

Download and unzip the appropriate .zip distribution for your system.Drag the application icon to /Applications/.

For troubleshooting or testing options, it’s often a good idea to run from thecommand line, but application packages don’t make that trivial. A symboliclink to somewhere in your PATH is all that’s required. e.g.:

After this, you can start the emulator by simply typing xroarfollowed by any command line options.

ROM images should be placed in a directory you create under your HOMEnamed ~/Library/XRoar/roms/ (not the system directory,/Library/). Name any configuration file you create~/Library/XRoar/xroar.conf.

The Mac OS X build provides a menu for access to certain features, and oftenaccepts the more familiar Command+key in place of theCtrl+key shortcuts listed in this manual.

1.1.2 Windows binary package

Download and unzip the appropriate .zip distribution for your system.

The easiest way forward is to simply put ROM images into the directory createdwhen you unzip the distribution, and then run the .exe straight fromthere. You can also put any configuration file (xroar.conf) here.

However, if you want to avoid having to move files around each time youupgrade, you can create Documents/XRoar to contain your configurationfile, and a subdirectory of that, Documents/XRoar/roms for ROM images.

Note when troubleshooting that the logging from the Windows binary is probablyonly going to be visible if you run it with the -C option (must be thefirst option) to allocate a console.

The Windows build provides menu-based access to certain features.

1.2 Building from source

1.2.1 Dependencies

If there is no binary package for your system, you will have to build fromsource. XRoar can use various backend toolkits, and you will need to ensureyou have their development files installed. If you’re using Debian, this can(at the time of writing) be achieved with the following simple command:

Under Mac OS X, first be sure to install Apple’sXcode package. The easiest way tothen ensure you have XRoar’s dependencies available is to use a system likeHomebrew or MacPorts. For Homebrew, the following command will install the requireddependencies:

Otherwise, you’ll have to do a bit of platform-specific research to ensure youhave all the dependencies for a full build:

GTK+, the GIMP toolkit, provides the mostfull-featured user interface. It is only usable as such if you also haveGtkGlExt, an OpenGL extensionused to provide video output. Otherwise, it can provide a file requester foruse by other user interfaces.

SDL, Simple Directmedia Layer, provides aslightly more basic user experience. Menus are added using native code underMac OS X and Windows; any other target using SDL will support only keyboardshortcuts. Unless you are building for Linux, SDL is required to usejoysticks. Version 2 required.

POSIX Regular Expressions are used in option parsing, soTRE is required on non-POSIXplatforms (e.g. Windows).

Other supported audio APIs: OSS, ALSA, PulseAudio, CoreAudio. Some otheroptions are still in the code base, but have not been tested in a while.

libsndfile is recommended toenable support for using audio files as cassette images.

1.2.2 Compilation

Once you have the dependencies, building XRoar follows a familiar procedure:

The configure script has a lot of options guiding what it tests for,specifying cross-compilation, changing the install path, etc. List them allwith the --help option.

By default, configure will set up an install prefix of/usr/local, but this can be changed by using the--prefix=path option.

Once built, run make install as root (or use sudo, as inthe example above) to install the binary and info documentation on your system.The executable is called xroar. ROM images should be placed either inyour home directory as ~/.xroar/roms/, or under the installationprefix as prefix/share/xroar/roms/. Any configurationfile should be created as ~/.xroar/xroar.conf.

XRoar can be built on one platform to run on another. The Windows binarypackage is built like this. To specify a cross-compile, use the--host=host argument to configure. For example, tobuild for Windows, you might use ‘./configure --host=i686-w64-mingw32’.Getting everything “just so” for a cross-build can be a tricky procedure, andthe details are beyond the scope of this manual.

XRoar can be built to a WebAssembly target usingEmscripten. With the SDK installed, runemconfigure ./configure --enable-wasm to set up the buildenvironment. Build with emmake make. HTML/JavaScript and CSSexamples for interfacing to the output are included in the wasm/subdirectory.

1.3 Running programs

Images of ROM cartridges, cassettes and disks can all be attached by pressingCtrl+L. Cassettes will be positioned at the beginning of the“tape” and disks will be inserted into the first drive.

To attach an image and try to automatically start it, pressCtrl+Shift+L instead. XRoar will try and start theprogram using the normal method for the type of image:

  • If a BASIC program is found on a cassette, XRoar types “CLOAD”, waitsfor the program to load, then types “RUN”.
  • For machine code programs on cassette, XRoar types “CLOADM” if theyappear to load in an autorun fashion, otherwise “CLOADM:EXEC”. Specialbuilt-in rules try and recognise some programs and issue a customised series ofcommands.
  • If a ROM cartridge is inserted, the emulated machine is power cycled.
  • If a disk image is autorun, XRoar types “BOOT” (Dragon) or “DOS” (CoCo).

If you have trouble with a program, refer to its loading instructions: it mayrequire a different series of commands to get going. If you still have issues,see Cartridges, Cassettes, or Floppy Disks.

The keyboard layout of modern machines is not identical to that of the Dragon,so XRoar provides two ways of working. The default, “untranslated”, is tomap key positions as closely as possible (e.g. the key to the right ofP maps to @). Pressing Ctrl+Z toggles“translated” mode, which tries to map key symbols closely instead(e.g. pressing ' will press Shift+7 in the emulatedmachine).

In addition, a couple of keys aren’t always available on modern keyboads, soEscape maps to the Dragon’s BREAK key, and Home maps toCLEAR. See Keyboard.

XRoar will make use of attached joysticks, but can also emulate them with thecursor keys and Left Alt. Press Ctrl+J to cycle throughthree emulation modes: No joystick emulation (default), Right joystick, Leftjoystick. See Joysticks.

1.4 Configuration

This manual details the options available for configuring XRoar. Each optioncan be passed on the command line or placed in a configuration file calledxroar.conf. xroar.conf is read first, and any command lineoptions then take precedence. Directives are listed in xroar.conf oneper line.

Lines in the configuration file each contain an option followed by whitespacefollowed by a value. Trailing whitespace is ignored. Empty lines are skipped,and any line where the first non-whitespace character is a hash (‘#’) istreated as a comment.

An option may be preceded by leading dashes as from the command line, butwithin the configuration file they are not necessary. Most options may bepreceded by ‘no-’ to invert their meaning or clear their value.

If a value contains special characters, or if you want trailing whitespace tobe included in the value, you must “escape” those characters. Sectionscontained within pairs of single or double quotes are escaped, except thebackslash (‘’) which introduces an escape sequence:

SequenceDescription
0Null (NUL), ASCII 0. Note that this is only permitted whennot followed by another octal digit, as it may be confused with an octalbyte, so it may be preferable to use ‘x00’ instead.
aBell (BEL), ASCII 7, no equivalent on the Dragon keyboard.
bBackspace (BS), ASCII 8, LEFT.
eEscape (ESC), ASCII 27, no equivalent on the Dragon keyboard, butmapped to BREAK by the -type option.
fForm Feed (FF), ASCII 12, CLEAR.
nNewline (NL), ASCII 10, DOWN. Not usually used by theDragon as a line ending, instead try ‘r’.
rCarriage Return (CR), ASCII 13, ENTER.
tHorizontal Tab (HT), ASCII 9, RIGHT.
vVertical Tab (VT), ASCII 11, no equivalent on the Dragon keyboard.
nnn8-bit byte with value specified as a three-digit octalnumber, nnn.
xhh8-bit byte with value specified as a two-digithexadecimal number, hh.
uhhhh16-bit Unicode codepoint specified as a four-digithexadecimal number, hhhh. Internally, this will be encoded as UTF-8.

Any other character following a backslash—including another backslash—isincluded verbatim. For example, this will be necessary in the configurationfile under Windows when file paths include the backslash as a directoryseparator.

However, on the command line, it is assumed that your shell will handleargument quoting, thus any quote characters will be included verbatim. Escapesequences are still parsed, except in the instance that an option expects afilename, as shells often use their own escaping mechanisms when autocompletingfilename arguments.

Installation and Compilation list good default locations forxroar.conf, but it is actually searched for in a list of directories.You can override this search path with the XROAR_CONF_PATH environmentvariable, which contains a colon-separated (‘:’) list of directories.Here are the defaults:

PlatformDefault XROAR_CONF_PATH
Unix/Linux~/.xroar:prefix/etc:prefix/share/xroar
Mac OS X~/Library/XRoar:~/.xroar:prefix/etc:prefix/share/xroar
Windows:~DocumentsXRoar:~AppDataLocalXRoar:~AppDataRoamingXRoar
Mac

Note the leading colon (‘:’) in the Windows default indicates an empty entry,meaning it will look in the current working directory first (i.e. you can putxroar.conf into the directory from which you run XRoar).

A leading tilde character (‘~’) indicates the user’s home directory: theHOME environment variable on Unix systems, or USERPROFILE onWindows. prefix is the installation prefix, which is usually/usr/local.

To bypass the search path and start XRoar using a specific configuration file,pass -c filename as the very first option to XRoar.

To print the current configuration to standard output (suitable for redirectionto a config file), run with -config-print. This will include all thebuilt-in machine and cartridge definitions. For a complete version includingdefault values, use -config-print-all.

2 Hardware emulation

2.1 Machines

With no other options, XRoar searches the ROM path and determines whichsupported machine has firmware ROM images are available. It tries in thisorder: Dragon 64, Dragon 32, Tandy CoCo. This can be overridden with the-default-machine name option. XRoar has built-in configurationsfor the following machines:

NameDescription
dragon32Dragon 32 (PAL).
dragon64Dragon 64 (PAL).
dragon200eDragon 200-E (PAL).
tanoTano Dragon (NTSC).
cocoTandy Colour Computer (PAL).
cocousTandy Color Computer (NTSC).
mx1600Dynacom MX-1600 (PAL-M).

You can create new machine configurations or reconfigure existing ones. Selecta machine configuration with -machine name, and use thefollowing options to modify it:

-machine-desc name

Description shown in -machine help.

-machine-arch arch

Base machine architecture. One of ‘dragon64’, ‘dragon32’ or ‘coco’.

-machine-cpu cpu

Fitted CPU. One of ‘6809’ or ‘6309’. Hitachi 6309 support is not as well tested.

-bas rom

ROM image to use for Colour BASIC (CoCo only).

-extbas rom

ROM image to use for Extended BASIC.

-altbas rom

64K-mode Extended BASIC for Dragon 64 & Dragon 200-E.

-nobas
-noextbas
-noaltbas

Indicate the corresponding ROM is not fitted in this machine.

-ext-charset rom

ROM image to use for external character generator.

-tv-type type One of ‘pal’, ‘ntsc’ or ‘pal-m’.

PAL-M is treated the same as NTSC, except with magenta-green artefactinginstead of blue-red (simulated composite rendering only at the moment).

-vdg-type type

Indicate the VDG variant fitted. One of ‘6847’ or ‘6847t1’.

-ram kbytes

Amount of RAM fitted.

-machine-cart name

Default cartridge to attach. See Cartridges.

-nodos

Indicate that XRoar is not to automatically attempt to attach a DOS cartridgeto this machine (the default is to try).

For example, if the following lines were placed in your xroar.conf, anew machine could be selected with -default-machine pippin:

2.2 Cartridges

The default cartridge for a machine is selected with the -machine-cartoption. XRoar has built-in definitions for four cartridges:

dragondos

DragonDOS, official disk interface cartridge from Dragon Data Ltd. Based onthe WD2797 Floppy Disk Controller chip.

delta

Delta System, Premier Microsystems’ disk interface cartridge for the Dragon.Mk 2, based on the WD2791 controller.

rsdos

RSDOS, Tandy’s disk interface cartridge for use with the CoCo. Based on theWD1793 controller.

gmc

John Linville’s Games Master Cartridge provides the ability to bank switch upto 64K of cartridge ROM, along with an on-board SN76489 sound chip. Be awarethat as provided, the cartridge is designed to auto-start an on-board ROM, andXRoar reflects this use. If you want to use it as a standalone cartridge,you’ll need to use the -no-cart-autorun option.

orch90

The Orchestra 90-CC cartridge provides stereo 8-bit audio output. The defaultROM is CoCo-only, but the hardware is compatible with the Dragon.

ide

Glenside IDE interface for hard disks. See Hard Disks.

nx32

Tormod Volden’s NX32 RAM expansion cartridge.

mooh

Tormod Volden’s MOOH RAM expansion cartridge.

mpi

Multi-Pak Interface. A CoCo add-on by Tandy that allows up to fourcartridges to be connected, selectable by software or hardware switch.

mpi-race

RACE Computer Expansion Cage. A Dragon add-on by RACE similar to the MPI.Addressing and behaviour differs.

You can create new cartridge configurations or reconfigure existing ones.Select a cartridge configuration with -cart name, and use thefollowing options to modify it:

-cart-desc text

Cartridge description shown in -cart help.

-cart-type type

Set cartridge base type. One of ‘rom’, ‘dragondos’, ‘delta’,‘rsdos’ or ‘orch90’.

-cart-rom filename

The ROM image specified will be mapped from $C000.

-cart-rom2 filename

The ROM image specified will be mapped from $E000.

-cart-becker

Enable becker port where supported.

-cart-autorun

Auto-start cartridge using FIRQ.

Defining extra cartridges is most usefully done in the configuration file, forexample:

This will define a cartridge called ‘sdose6’ as a DragonDOS cartridge withits ROM replaced with sdose6.rom, and an additional ROM calleddosdream.rom.

XRoar will automatically attempt to find a disk interface relevant to thecurrent machine unless a specific default has been configured for the machinewith -machine-cart, or automatic selection is disabled with the-nodos option.

Selecting a ROM image file with the -load or -run commandline options, or with Ctrl+L orCtrl+Shift+L, will attach a ROM cartridge.

Within the emulator, cartridges can be enabled or disabled by pressingCtrl+E. You will almost certainly want to follow this with ahard reset (Ctrl+Shift+R).

2.2.1 Multi-Pak Interface

If you attach a Multi-Pak Interface (MPI), you’ll want to populate one or moreof its slots (numbered 0-3). Use -mpi-load-cart[slot=]name to attach a named cartridge to the specified (ornext) slot. Configure the initially selected slot with -mpi-slotslot.

It’s not recommended to load more than one DOS cartridge into the MPI.As things stand, only the last one (in slot order) will have the emulateddrives properly connected.

These options also apply to the RACE Computer Expansion Cage, which providessimilar features, albeit with slightly different behaviour.

2.2.2 Becker port

Dragon For Mac 6 User Manual Guide Video

XRoar supports an emulator-only feature that enables it to connect to a serverusing a TCP connection to access remote facilities such as disk images and MIDIdevices—the “becker port”. This appears as a memory-mapped device, andXRoar supports it as an optional feature of the DOS cartridge.

Enable this port when configuring a cartridge with -cart-becker. The-becker option tells XRoar to prefer a cartridge with it enabled whenautomatically selecting one.

The IP and port to connect to can be specified with the -becker-ip and-becker-port options. These default to ‘127.0.0.1’ and‘65504’ respectively, matching the defaults for DriveWire 4, the mostpopular server application used to provide such facilities.

3 Files

In general, files can be attached on the command line with -loadfilename, or by pressing Ctrl+L. XRoar judges the type offile based on its filename extension. To attempt to intelligently autorun afile, use -run filename or press Ctrl+Shift+L.See Running programs for the methods XRoar will use to autorun a file.

3.1 Cassettes

XRoar supports three types of cassette image:

ExtensionDescription
.casCassette file. Simple binary representation of data contained on atape. CUE support appends metadata describing cycle widths and representingsilence.
.wavCassette audio file. XRoar can read sampled audio from originalcassettes.
.bas, .ascASCII BASIC file. XRoar will convert text on the fly into blocks suitablefor loading in ASCII mode. Read-only.

To create a cassette image for writing (with the CSAVE orCSAVEM BASIC commands, for example), use the -tape-writefilename option, or press Ctrl+W. If a file already exists,new data will be appended to it. Rewind the output take to overwrite it. Notea slight behaviour difference: CAS files can only be overwritten or appendedto, WAV files can overwrite existing data (leaving later data intact).

The currently open tape files used for reading and writing are distinct.

Some cassette tapes are distributed with only one of the stereo channelscontaining data, and these sometimes cause loading issues. How stereo audiofiles are read can be adjusted with the -tape-pan value option,where value is a number from 0.0 to 1.0. 0.0 will fully pan towards theleft channel, while 1.0 will fully pan to the right. The default is 0.5 (equalparts from both channels).

A certain amount of hysteresis is applied to the input when reading audiofiles. By default this is 1%, but this can be changed with the-tape-hysteresis percent option.

Select the output frame rate when writing to audio files with-tape-ao-rate hz. The default is 9600Hz.

Some debugging actions can be triggered each time the cassette motor switchesoff (e.g. when finished loading). See Debugging.

The -tape-fast option accelerates tape loading by intercepting ROMcalls. Disable with -no-tape-fast. On by default.

When fast loading is enabled, the -tape-pad-auto option will, for.cas files, ignore the motor delay when insufficient initial leaderbytes are detected. This helps with old tape images that would not load onreal hardware if simply converted to an audio file. On by default; switch offwith -no-tape-pad-auto.

The -tape-rewrite option enables rewriting of anything read from theinput tape to the output tape. This is useful for creating “well formed”.cas files. Use the -tape-rewrite-gap-ms ms option toset the inter-block gap in milliseconds (default 500ms). You can set theleader length following gaps with the -tape-rewrite-leader bytesoption (default 256 bytes).

Where available, these options can be changed on the fly in the GUI.

3.2 Floppy Disks

If a disk interface cartridge is selected, XRoar supports virtual disks. Threevirtual disk formats are supported:

ExtensionDescription
.dmkDisk image file in a format defined by David Keil. These images store a lot ofinformation about the structure of a disk and support both single and doubledensity data.
.jvc, .os9, .dskDisk image file in a basic sector-by-sector format with optionalheader information.
.vdkAnother disk image file format, used by PC-Dragon.

To insert a disk into a particular drive, press Ctrl+[1-4].

When you attach a disk, it is read into memory, and subsequent disk operationsare performed on this in-memory copy. Write enable defaults to on (so writeoperations on the copy will work), but write back defaults to off, so updateswill not be written to the disk image file. To toggle write enable, pressCtrl+[5-8], where the number to press is the drive number plus4. To toggle write back, press Ctrl+Shift+[5-8]. Evenwith write back enabled, image files will not be updated until the disk in avirtual drive is changed, or you quit the emulator.

Where available, these options can also be changed on the fly in the GUI.

Write back can be set to default to on with the -disk-write-backcommand line option.

To flush any changes made to in-memory disk images to their backing file (butonly those with write back enabled), press Ctrl+Shift+D.

The JVC format specifies that the disk images without headers are single-sided,but some double-sided disk images have been made available without headers.These cannot normally be distinguished from a single-sided disk that happens tohave twice the number of tracks. If an OS-9 filesystem is present, theidentification sector is inspected to determine the correct disk structure.This step will always be performed for headerless images with the .os9filename extension, but may be disabled for the other valid JVC filenameextensions with -no-disk-auto-os9.

You can create a new blank disk in a virtual drive by pressingCtrl+Shift+[1-4]. You will be a prompted for a filename,and the filename extension determines which type of file will be written.

Note that RS-DOS for the Tandy Colour Computer numbers its drives from zeroinstead of one, so when you perform operations on Drive 1, from the CoCo’spoint of view, that will be Drive 0.

3.3 Hard Disks

Some support is now in place for IDE hard disk images. The ‘ide’cartridge type emulates a Glenside IDE controller mapped to addresses$FF50–$FF58.

A fixed image file named hd0.img in the current working directory isassumed. If the image does not exist when you try to use the IDE cartridge, anew 256MB image is created. Images consists of a 512 byte identifier block(ASCII string “1DED15C0” then all zeroes) followed by a 512 byte IDENTIFYheader, then the sector data. In examples, the 256 byte sector data ofstandard CoCo disks is doubled up to fill the 512 byte sectors of the hard diskimage.

3.4 ROM cartridges

ROM cartridge images have a .rom or .ccc filename extension.Because XRoar supports other types of cartridge, loading a ROM image actuallyjust creates a cartridge instance of type ‘rom’. See Cartridges.

3.5 Snapshots

XRoar can save out a snapshot of the emulated machine state and read thesnapshots back in later. To save a snapshot, press Ctrl+S.When using Ctrl+L to load a file, anything ending in .snawill be recognised as a snapshot.

What is included in snapshots: Selected machine architecture, complete hardwarestate, current keyboard map, filenames of attached disk image files.

What is not (yet) included: Actual disk image data (only where to findit), attached cassettes or cartridge ROM contents.

3.6 Binary files

File types containing raw binary data to be loaded into RAM:

ExtensionDescription
.binBinary file (DragonDOS or CoCo). XRoar can load these directly into memoryand optionally autorun them. Read-only
.hexIntel hex record. An ASCII format that encodes binary data andwhere in memory to load it. Read-only

3.7 Firmware ROM images

Firmware ROM image files are configured as part of a machine or a cartridge.They have a filename extension of .rom or .dgn, and can bespecified as:

  • Complete path to a file.
  • Base filename of an image, to be discovered within a search path.
  • Base filename of an image, omitting the extension. XRoar will search as above, appending the known ROM filename extensions.
  • An ‘@’ character followed by the name of a ROM list.

A ROM list is a comma-separated list of images, each following the rules above.ROM lists may refer to other ROM lists. Define a ROM list with-romlist name=image[,image]…. View thedefined ROM lists with -romlist-print.

To make life easier, the default image for each type of machine or cartridgeusually refers to a ROM list which contains all the corresponding filenamesseen “in the wild”:

Firmware ROMROM listCanonical image names
Dragon 32 BASIC@dragon32d32
Dragon 64 32K BASIC@dragon64d64_1
Dragon 64 64K BASIC@dragon64_altd64_2
Dragon 200-E 32K BASIC@dragon200ed200e_1
Dragon 200-E 64K BASIC@dragon200e_altd200e_2
Dragon 200-E Charset@dragon200e_charsetd200e_26
Tandy Colour BASIC@cocobas13, bas12, bas11, bas10
Tandy Extended BASIC@coco_extextbas11, extbas10
DragonDOS@dragondos_compatdplus49b, sdose6, ddos40, cdos20
Delta System@deltadelta
RS-DOS@rsdosdisk11, disk10
RS-DOS with becker port@rsdos_beckerhdbdw3bck
Orchestra 90-CCorch90

The default search path for images specified only as a base filename varies byplatform, and is detailed in Getting started. This path can can beoverridden with the option -rompath=path, where path is acolon-separated list of directories to search. The path is parsed in the samemanner as the configuration file search path (see Getting started).

The XROAR_ROM_PATH environment variable can also be used to specify thesearch path, but this behaviour is deprecated and may be removed in a futureversion.

A CRC32 value is calculated and reported for each ROM image loaded. XRoaruses these CRCs to determine whether certain breakpoints can be used (e.g. forfast tape loading). The lists of CRCs matched can be defined in a similar wayto ROM lists using the -crclistlist=crc[,crc]… option. Each crc is a 8-digithex number preceeded by ‘0x’, or the name of a nested list preceeded by‘@’. Use this if you have a modified version of a BASIC ROM thatmaintains compatible entry points with an original. View the current listswith -crclist-print.

Sometimes it may be useful to force CRC matching so that breakpoints apply(e.g. you are modifying a ROM image and don’t wish to have to add its CRC tothe match list each time you modify it). The -force-crc-match optionforces the CRCs to be as if an original ROM image were loaded.

4 User interface

4.1 User interface module

The user interface depends on supporting toolkit packages as described inBuilding from source. Selection of user interface module may affectwhich other types of module are available: in particular, video output isstrongly tied to the user interface.

-ui module

Select user-interface module. -ui help to list compiled-in modules.

4.1.1 GTK+ user interface

Select with -ui gtk2.

This is the most full-featured user interface. It provides extensive dynamicmenus, and control dialogues for cassette and disk files. This is thepreferred interface under Linux.

Only one video module is usable with this user interface: ‘gtkgl’.

4.1.2 SDL user interface

Select with -ui sdl.

More limited than the GTK+ interface, providing keyboard shortcuts and, inthe Mac OS X and Windows variants, some basic menus.

Under Mac OS X, many operations are usable by pressing Command+keyas well as the usual shortcut of Ctrl+key.

4.2 Video output

-vo module

Video output module to use. Available modules depend on the selecteduser-interface module. -vo help gives a complete list for eachpossible user-interface.

-fs

Start full-screen. Toggle full-screen with Ctrl+F or F11.

-fskip frames

Specify frameskip. Default is ‘0’. For slower machines.

-gl-filter filter

Filtering method to use when scaling the screen. One of ‘linear’,‘nearest’ or ‘auto’ (the default). OpenGL output modules only.

-invert-text

Start up with inverted text mode.

-ccr renderer

Composite video cross-colour renderer. One of ‘simple’ (very fast),‘5bit’ (fast, more accurate) or ‘simulated’ (slow, very accurate).Default is ‘5bit’.

Real NTSC machines start in one of two cross-colour states at random. Gamesoften prompt the user to “Press Enter if the screen is red”, for example.You can press Ctrl+A, to cycle through three modes: Off,Blue-red and Red-blue.

Inverted text mode may be toggled by pressing Ctrl+Shift+I.

4.3 Audio output

-ao module

Select audio output module. -ao help for a list.

-ao-device device

Module-specific device specifier. e.g. /dev/dsp for OSS.

-ao-format format

Specify audio sample format. -ao-format help for a list.

-ao-rate hz

Specify audio frame rate, where supported. The default is taken from theoperating system if possible, otherwise it will usually be ‘48000’.

-ao-channels n

Specify number of channels (1 or 2). Default is usually 2.

-ao-fragments n

Specify number of audio fragments.

-ao-fragment-ms ms

Specify audio fragment size in milliseconds.

-ao-fragment-frames frames

Specify audio buffer size in frames.

-ao-buffer-ms ms

Specify total audio buffer size in milliseconds.

-ao-buffer-frames frames

Specify total audio buffer size in frames.

-ao-gain db

Specify audio gain in dB relative to 0 dBFS. Only negative values really makesense here. The default is ‘-3.0’.

-volume volume

Older way to specify volume. Simple linear scaling, using values 0–100.

Audio latency is a concern for emulators, so XRoar allows the bufferingcharacteristics to be configured with the fragment and buffer options above.Not all audio modules support all options, but setting the total audio buffersize will usually have an effect. Bear in mind that any figures reported byXRoar reflect what it was able to request, and won’t include any extrabuffering introduced by the underlying sound system.

When the Orchestra 90-CC cartridge is attached, its stereo output needs to bemixed with the Dragon’s normal audio. To allow a small amount of headroom forthis, the default gain is set to ‘-3.0’ (dB relative to full scale), butbe aware that it would still be possible for this to clip depending on what’shappening on the internal sound bus. A setting of -ao-gain -9.0 wouldgive plenty of headroom (at the expense of a quieter overall sound).

4.4 Keyboard

The default mapping of host keys to emulated keys is based on the originalpositions of the keys, with certain exceptions: cursor keys are mappeddirectly, Escape maps to the Dragon’s BREAK key, and Homemaps to CLEAR. Other keys may also be mapped to CLEAR if there isa choice in your selected keymap that doesn’t conflict with a regular characterin translated mode.

For position-based mapping, XRoar needs to be informed of the layout of thehost’s keyboard. If it is not the default (UK), use the -keymapcode option.

XRoar can also be put into “translated” keyboard mode, where characters typedon a PC keyboard are translated into the equivalent keystrokes on the Dragon.Use the -kbd-translate option to default to this mode. PressCtrl+Z at any time to toggle between the two modes.

In translated mode, Shift+Return is mapped to the Caps Lockcombination (Shift+0 usually, Shift+ENTER on the Dragon200-E). Similarly, Shift+Space is mapped to the “pause output”combination (Shift+@ usually, Shift+Space on theDragon 200-E).

-keymap code

Dragon For Mac 6 User Manual Download

Specify host keyboard layout. -keymap help for a list. Default is‘uk’.

-kbd-translate

Start up in “translated” keyboard mode.

-type string

Intercept ROM calls to type string into BASIC on startup.

The keyboards of the Dragon, Dragon 200-E and Tandy CoCo operate in the sameway, but the matrix and/or key layouts differ. When you select a machine (seeMachines), the appropriate layout is selected for you, but you can cyclebetween the three by pressing Ctrl+K.

XRoar will simulate the “ghosting” effects inherent in a simple matrixdesign, but the accuracy of this simulation will depend very much on your hostkeyboard, which vary greatly in the amount of simultaneous keypresses theysupport (for more information, search for “NKRO”).

4.5 Joysticks

XRoar supports attached joysticks, or can emulate them using the keyboard ormouse (“virtual joysticks”). There are a few built-in configurations, or newones can be defined. Here are the built-ins:

NameDescription
joy0First two axes and first two buttons of first physical joystick
joy1First two axes and first two buttons of second physical joystick
kjoy0Keyboard based virtual joystick using cursor keys and Left Alt.
mjoy0Mouse based virtual joystick mapped to screen position

By default, ‘joy0’ (the first physical joystick) is mapped to the Dragon’sright joystick port, and ‘joy1’ (the second physical joystick) to the leftport. Map different named joysticks with -joy-right name and-joy-left name. Right and left joystick mapping can be easilyswapped by pressing Ctrl+Shift+J.

A configured “virtual joystick” can be used by pressingCtrl+J. The first press substitutes it for the right joystick,the second press with the left joystick and a third press disables it again.The virtual joystick defaults to the keyboard-based ‘kjoy0’ describedabove, but can be reconfigured with -joy-virtual name.

A joystick configuration can be created or configured by selecting it by namewith -joy name, and then configuring its axes with-joy-axis index=spec and buttons with -joy-buttonindex=spec. In each case, spec has the syntaxmodule:args, with args being a comma-separated list, theformat of which is specific to module:

ModuleAxis argsButton args
physicaljoystick-index,[-]axis-indexjoystick-index,button-index
keyboardkey-name0,key-name1key-name
mousescreen-offset0,screen-offset1button-number

For physical joysticks a ‘-’ before the axis index inverts the axis. Keynames for the keyboard module depend on the underlying toolkit. The defaultscreen offsets for the mouse module are ‘X=2,254’ and ‘Y=1.5,190.5’which gives reasonable behaviour for some games and utilities.

4.6 Printing

XRoar supports redirecting the Dragon parallel printer output to a file or pipewith the -lp-file or -lp-pipe option. Printed data will besent to the appropriate stream. Pressing Ctrl+Shift+Pwill flush the current stream by closing it (so if the stream is a pipe, thefilter will complete). The stream will be re-opened when any new data is sent.

The pipe feature allows you to use useful print filters such asenscript, e.g. -lp-pipe 'enscript -B -N r -dprinter-name'. This will send a job to your printer, using carriagereturns as line feeds (the Dragon default), each time you pressCtrl+Shift+P (or exit the emulator).

-lp-file filename

Append printer output to filename.

-lp-pipe command

Pipe printer output to command.

Note that the CoCo uses a serial printer port. As full serial support is yetto be added, a very limited form of print redirection is implemented for theCoCo using a ROM BASIC intercept. This is enough to support BASIC commandslike LLIST, but will not cope with programs implementing their own serialroutines.

4.7 Debugging

XRoar can act as a remote target for GDB using a network socket. When GDBconnects, emulation is stopped. GDB can then inspect memory, instruct thetarget to set breakpoints and watchpoints (read, write and access), single stepor continue execution. A version of GDB patched to specifically support 6809targets can also perform disassembly and inspect registers. For moreinformation on how to use GDB, see theGDB Documentation.

Enable the GDB remote target with -gdb. The default IP and port forthe target are ‘127.0.0.1’ and ‘65520’. These can be overridden withthe -gdb-ip and -gdb-port options.

XRoar also supports a simpler “trace mode”, where it will dump a disassemblyof every instruction it executes to the console. Toggle trace mode on or offwith Ctrl+V. Trace mode can be enabled from startup with the-trace option.

User-interface debugging flag can be enabled with -debug-uivalue, where only one value is currently supported:

0x0001

Keyboard event debugging.

Hex & binary file debugging can be enabled with -debug-filevalue, where the value is a bitwise ORing of the following:

0x0001

Print summary information such as load or exec addresses.

0x0002

Hex dump of all data read into memory.

0x0004

Print filename block metadata when autorunning a tape.

Floppy controller debugging can be enabled with -debug-fdc value,where the value is a bitwise ORing of the following:

0x0001

Show FDC commands.

0x0002

Show all FDC states.

0x0004

Hex dump of read/write sector data.

0x0008

Hex dump of becker port conversation data.

The GDB stub can also emit debug information about its own operation with-debug-gdb value, where value is a bitwise ORing of:

0x0001

Connection open and close.

0x0002

Show packet data.

0x0004

Checksum reporting.

0x0008

Report on general queries.

The special value argument of -1 parses as “all bits set”, and so enables allcorresponding debug options.

XRoar prints various other informational messages to standard output bydefault, including when the state of certain toggles is modified. Verbositycan be changed with the -verbose level option. -quietis equivalent to -verbose 0. Levels are:

0

Quiet. Only warnings and errors printed.

1

Print startup diagnostics and emulator state changes (default).

2

Report some emulated machine state changes.

3

Miscellaneous internal debugging.

XRoar can be told to exit after a number of (emulated) seconds with the-timeout seconds option.

XRoar can quit a number of seconds after the cassette motor is switched offwith the -timeout-motoroff seconds option. This is useful inthe case of automatic tape rewriting. A value of 1 is usually sufficient toaccount for the brief motor click that occurs after header blocks and duringgapped loading.

Similarly, a snapshot can be automatically written after loading with the-snap-motoroff file option. The file is overwritten each timethe motor transitions to off. This can be used to help analyse the machinestate immediately after loading, before any autorun code has taken effect.

To see debug output from the pre-built Windows binary, run it with -Cas the first option to allocate a console.

4.8 Keyboard shortcuts

A summary of commonly available shortcuts.

Ctrl+A

Cycle through cross-colour video modes (hi-res only).

Ctrl+D

Open disk control dialogue (GTK+ only).

Ctrl+Shift+D

Flush disk images.

Ctrl+E

Toggle DOS emulation on/off - reset to take effect.

Ctrl+F, F11

Toggle full screen mode.

Ctrl+Shift+H, Pause

Toggles pause mode (HALTs the CPU). As seen on the Dynacom MX-1600.

Ctrl+Shift+I

Toggle text mode inverse video.

Ctrl+J

Cycle through joystick emulation modes (None, Right, Left).

Ctrl+Shift+J

Swap left and right joysticks.

Ctrl+K

Cycle through Dragon, Dragon 200-E and CoCo keyboard layouts.

Ctrl+L

Load a file (see below).

Ctrl+Shift+L

Load a file and attempt to autorun it where appropriate.

Ctrl+M

Cycle through emulated machine types (resets machine).

Ctrl+Shift+P

Flush printer output.

Ctrl+Q

Quit emulator.

Ctrl+R

Soft reset emulated machine.

Ctrl+Shift+R

Hard reset emulated machine.

Ctrl+S

Save a snapshot.

Ctrl+T

Open the tape control dialogue (GTK+ only).

Ctrl+V

Toggle trace mode.

Ctrl+W

Attach a virtual cassette file for writing.

Ctrl+Z

Enable keyboard translation mode.

F12

While held, the emulator will run at the maximum possible speed.

Dragon Medical User Manual

Shift+F12

Toggle rate limiting. Emulator will run at maximum speed until pressed again.

5 Troubleshooting

Some commonly encountered issues:

  • I only see a checkerboard pattern of orange and inverse ‘@’ signs.

This probably indicates that XRoar could not locate any BASIC ROM images.Acquire some and put them in the directory appropriate to your platform. XRoartries to find ROMs for machines in the following order if you do not specify adefault machine: Dragon 64, Dragon 32, CoCo.

  • This program is supposed to be in colour, but all I see is black & white.

Try pressing Ctrl+A one or more times. What this really meansis that you’re used to running the program on an NTSC machine, and it makes useof cross-colour, but XRoar is emulating a PAL machine. Try starting with-default-machine tano or -default-machine cocous.

Figure 5.2: Time Bandit, Dunlevy & Lafnear, 1983 in different artefact modes

6 Acknowledgements

I made reference to the MAME 6809 core for clues on how the overflow bit in thecondition code register was handled.

Thanks to all the people on theDragon Archive Forums forhelpful feedback and insight.

Darren Atkinson’s Motorola 6809 and Hitachi 6309 Programmers Referencehas been very useful for 6309 support and fleshing out some of the illegalinstructions on the 6809.

Alan Cox contributed the IDE code.

Tormod Voldon contributed support for his NX32 and MOOH devices (includinggeneral SPI and SD image support).

User Guides

The User Guide, which covers all product editions, provides details on installation, optional settings, voice commands and dictation of different types of text. The guide also includes tips and notes to help you use the software more effectively.

Be sure to also take advantage of our illustrated workbook. For the latest technical details, please see the KnowledgeBase.

    (pdf)
  • Dragon Medical Practice Edition 4 Client Help(Open a new window)

Bluetooth Wireless Headset Guides

Dragon User Manual

Dragon Microphones
Calisto Microphones
  • We recommend plugging the Bluetooth microphone’s dongle (wireless adaptor) into your computer before you open Dragon.
  • While the Calisto II's headset is charging, its indicator light glows solid red, but once the headset is fully charged, this light goes off.
  • The headset does not automatically power on. Once the headset is charged and paired to its dongle, you must power it up by holding its button for about 6 seconds (it then emits 4 ascending beeps), then pressing it for 1 second to activate its radio link to its dongle
Title: Using the Calisto II Bluetooth wireless microphone with Dragon

This video includes how to charge and power up the headset, as well as turn on the connection to its USB wireless adapter. It also covers how to check the “recording device” settings in the Windows Control Panel.

Quick Start Cards

The Quick Start Card helps you quickly install and activate Dragon.

For documentation of non-English Dragon products, visit our international web sites.