THIS IS BETA DOCUMENTATION, FOR THE BETA VERSION OF THE NITROS-9 EASE OF USE PACKAGE.

PLEASE SEND FEEDBACK TO:

• L. CURTIS BOYLE (curtisboyle at sasktel dot net),
• BILL NOBEL (b_nobel at hotmail dot com),
• AND DAVID LADD (davidwladd at gmail dot com).

We want to try and make this package as easy to use/understand as possible.

Previous and current versions of NitrOS-9 Ease of Use can be downloaded for free at: http://www.lcurtisboyle.com/nitros9/nitros9.html
OR
https://colorcomputerarchive.com/repo/Disks/Operating%20Systems/NitrOS-9%20Ease%20of%20Use/

First off: What is “NitrOS-9”?

NitrOS-9 is the successor to OS-9, by Microware, for the Tandy Color Computer (and Dragon) computer lines.

It is a real-time, multi-user, multi-tasking operating system, with some similarities to Unix, that came in two flavors: Level 1, for machines with up to 64K, and Level 2, for >64K.

NitrOS-9 itself started as a commercial product in 1992 to take advantage of the power of the Hitachi 6309 CPU in Level 2, for the Coco 3.

North America just found out about the extra features in the 6309 earlier that year.

Later, in 2002, it was released to the public as a collaborative open source project, and then back ported first to the 6809, and then parts of it back to Level 1 (for the Coco 1/2, and the Dragon 64).

OK… but what is “EOU” (Ease of Use)?

The NitrOS-9 “EASE OF USE” (EOU) project's goal is to make available a “pre set-up” version of NitrOS-9, so that the beginning or new user to NitrOS-9 user does not have to worry about setting up a boot disk/file, setting up Multi-Vue (the GUI program), setting up programs to have their needed file(s) set up in specific directories, etc.

It is meant to be “point and click”, and have (almost) all programs set up to run from straight from the GUI itself, like a modern operating system.

It is also meant to have more robust HELP than the stock OS-9 help has; by including various 3rd party games, applications, utilities, etc.

This by no means indicates that a power user can't use this package - they can do everything from the command line like they are used to, if they wish.

With a lot of really useful extra commands compared to stock OS-9 Level II.

If I am a retro game enthusiast… would I need to run NitrOS-9?

Tandy themselves had a limit as to the size of games that they would allow on cartridge.

All of their larger Coco 3 games required OS-9.

Since NitrOS-9 actually runs a little faster, and has a full GUI, you can now run all of those, as well as many 3rd party games, straight from the GUI.

A couple of cartridge games have even been ported to NitrOS-9, with some improvements over the originals (like Shanghai and Thexder).

And, unlike the originals, since EOU is set up as a 128MB Hard drive image, you don't have to worry about swapping disks while playing, either.

Sounds interesting, but why would I want to use it when I already have the SDC Explorer? Can't I already run these programs from there?

Yes, you can, although running them from the SDC Explorer means that you are running a custom floppy disk image for each program.

This means to switch applications, you have to reboot with a new DSK image every time.

It also means your preferred settings, etc. have to be redone every time you switch programs, and you can only run one at a time.

Also, most of those do not have the point and click GUI; they just boot the single application/game, and that's it.

And, finally, you can't access anything you saved (whether a text file you have made, a saved game, etc.) from any other programs.

The advantage of EOU is that you have (or will soon, as get more and more pre-installed) access to all of those programs at once, and can even run more than one at once.

And they all launch the same way…

double click the icon, just like a modern OS like Windows or OSX.

And you can launch EOU straight from SDC Explorer, too.

And launching programs from the GShell GUI is as easy as using SDC Explorer - point & double-click.

• A Coco 3 with a minimum of 512k, either 6809 or 6309, with a CocoSDC, OR
• A Coco 3 emulator (MAME or VCC or OVCC) set up as a Coco 3 with the specs above, but replacing the CocoSDC with a hard drive emulation (built into both emulators).

In order to make the EOU experience as friction free as possible, the system requirements for this package are higher than the stock OS-9 Level II, or even stock NitrOS-9.

We are also, for the first releases, limiting the hardware supported to the 4 basic configurations listed above, that we feel are the most common for people that have wanted to try NitrOS-9 out.

We will expand this in the future (including things like Drivewire), but for now it is easier for use to maintain/test/get feedback from less versions.

Because the 6309 version of NitrOS-9 has extra features and is faster, if you have the hardware to support it (or set your emulator to use 6309 versus 6809), we would highly recommend installing that version.

We should also mention that we have defaulted the initial boot screen to 32 columns, and the main window (called “/term”) is defaulted to 40 columns.

This is help users running on RF or composite screens, so they can read the text easily.

The GUI (called “Multi-Vue”, and the main program to start it called “GShell” (short for “Graphical Shell”)), also defaults to 320×200 resolution for the same reason.

Two other windows are currently fired up by default that are 80×25, so people with RGB monitors can choose those to start on if they wish.

The hard drive images (6809 and 6309) are common between real hardware and the two emulators; the emulators also include a floppy image (containing the main boot, with the emulated hard drive drivers), that will then kick into the hard drive image.

So, on an emulator, you must mount the file “63SDC.DSK” into floppy drive 0, and mount the file “63SDC.VHD” into hard drive 0 (for the 6809 version, use 68SDC.DSK and 68SDC.VHD, respectively).

Then, type DOS to boot.

(If you need help setting up the emulators, Steve Strowbridge, the main host of CocoTalk!, has some instructional videos on how to do that):
MAME part 1:
https://youtu.be/3NegztbUWM8
MAME part 2:
https://youtu.be/A9Arxa7JbsI

CocoPi3 (Raspberry Pi3 or Pi3B):
https://youtu.be/nQlnXzExOqQ

VCC:
https://youtu.be/RD1cexRPpT4

John Shawler from The Coco Show also has a video on setting up Coco emulation in MAME:
https://www.youtube.com/watch?v=Kacg-R-b3cs

For the CocoSDC, you need only copy the 63SDC.VHD (or 68SDC.VHD) file onto your SD card, and after you have fired up the Coco with that card in the CocoSDC, change to that drive image, and type DOS.

If you have Coco Explorer, you can use it's menu system to select the card as well.

If you plan to be using NitrOS-9 a lot, you can set up the CocoSDC to automatically mount that image when you turn the Coco on.

You may want to set up a separate SD card strictly for NitrOS-9 in this case, and set it up to autoboot NitrOS-9 when you turn the Coco on.

See MAKING AN AUTO-BOOTING NITROS-9 SD CARD at the end of this documentation for details.

New to Beta 5 are a couple of things: The VHD is a “skitzo” image that contains a very small partition that contains a BASIC program.

If you rename it to AUTOEXEC.BAS, and you have your CocoSDC config file set to do so, you can have NitrOS-9 automatically boot as soon as you turn the machine on.

Thanks to David Ladd for setting this feature up, for those that need/want it.

You can also directly launch the .VHD file from SDC Explorer, as normal.

Also new to Beta 5 is a second, blank hard drive image (giving you almost 128MB more storage).

This will work with the CocoSDC or MAME; unfortunately, VCC and OVCC do not currently support a second hard drive.

This is done for the programmers and tinkerers; you can put all of your own code, copies of files on the main drive that you have modified, etc.

With this, when we issue a new release of EOU, it won't overwrite any changes that you have backed up on this 2nd drive.

We will include the empty hard drive image in each release, but if you are already using it, just leave your image alone and ignore the blank one.

It comes with Beta 5 and later for people who are using NitrOS-9 for the first time.

Upon booting, you will first encounter the “NitrOS-9 BOOT” screen.

All of stuff that flies by on the screen is a listing of all of the system modules, as they are loaded, and is mainly meant for debugging, and you shouldn't need to pay much attention to them (and it does give you something to look at while the system is booting).

After the operating system is loaded, the screen will clear to black on white, 40 column text, and it will load in large library of graphical fonts (48 as of this writing), paint patterns, mouse cursors, etc.

that are used by the GUI and other programs.

It will then prompt you for the time (these first releases will use the software clock), fire up two more (80 column) windows in the background, display the current monitor type NitrOS-9 is defaulted to (currently RGB), and then give you instructions on how to change the monitor type, and how to start up Multi-Vue, for the point and click mouse interface.

NOTE FOR BETA 5: If you have a Smartwatch installed (a real time clock chip), you can edit the /dd/ startup file (using EDIT, MINTED, VED, etc.

- whichever text editor you prefer) and replace the line that has SETIME (etc.) on it with 'SWREAD'.

This will set the software clock time to your Smartwatch time, and you won't have to type it in any more.

Quick notes on special keys in NitrOS-9

I will group these into 3 sections:
Universal (keys that do special things no matter what program you are in),
SHELL (the main SHELL command prompt), and
MULTI-VUE (the GUI).

This is not a complete list (see the manuals, available online at the Coco Archive at http://www.colorcomputerarchive.com), but the most common ones that you will find yourself using a lot.

NOTE: I will be listing the keys from an actual Coco 3; consult your emulator documentation to see what equivalent key(s) will do the same thing (whether it be Windows, Mac or Linux).

Also, emulators like MAME allow you to change these, anyways.

UNIVERSAL

Key repeat is on by default, turned on (hold down a key, and after a short delay, it will start repeating).

You can change this in the Control Panel in GSHELL, both to change the delay length and the repeat speed, and even shut if completely off.

Programs can also do this themselves, if they wish.

<CLEAR> - Go forward to the next window.

These can be completely separate full screen windows, or multiple windows on the same screen.

<SHIFT-CLEAR> - Go backwards to the previous window.

<CTRL-CLEAR> - Toggles the “keyboard mouse” on or off (the system boots with it off).

This will change the normal function of the 4 arrow keys, and the F1/F2 keys, to simulate a mouse.

The four arrow keys move the mouse in the four directions (you can hold 2 down at once to move diagonally), and F1 and F2 are the left (red) mouse/joystick button and right (black) joystick/button respectively.

Most programs only need F1, as a lot of people back in the 1980's when OS-9 Level II was released, still had the older 1 button joysticks or mice.

While the keyboard mouse is on, the arrows jump 8 pixels each time you hit one.

If you hold <CTRL> and an arrow at the same time, the mouse cursor will jump to the far edge of the screen corresponding to which arrow you hit.

If you hold <SHIFT> and an arrow at the same time, you will move 1 pixel at a time.

Please note - if you are running on a graphic window, but just printing text, the keyboard mouse overrides the normal functions of the arrow keys (like backspacing, etc.).

If you find that you can't backspace, and you see the mouse cursor on the screen, hitting <CTRL>-<CLEAR> will switch back to normal keyboard mode.

<CTRL-0> (that is a zero, not the letter 'O').

This toggles the CAPSLOCK on and off (the system boots with it off).

This forces all text you type to uppercase.

<CTRL-W> - when listing text files to the screen, this will Pause the display (like <SHIFT>-<@> in Disk Basic).

Any other key un-pauses.

There are some other <CTRL> keys used to generate special symbols that the Coco keyboard doesn't directly support (an example is <CTRL-minus> to do an underscore); you can find those in the OS-9 Commands section of the OS-9 Level II manual, in Appendix D “OS-9 Keyboard Control Functions”, so I won't repeat all of them here.

SHELL

Shellplus 2.2A is the default shell we have installed.

It has some special features, like command history, that are incredibly useful as a time saver.

It also allows users to change the default prompts, and we have picked (as a default) one that give you a lot of info about the window you are looking at, without taking up too much room.

Each window with a shell on it will show you 1) the window name (like “/term”, the process # (like “02”), and the data directory you are currently in (like “/dd”).

By default, we have command line history enabled in the shell with full editing keys.

This means that you can bring up previous commands you have used on this particular window/shell, and re-use them (or edit them), without having to retype the whole thing.

You can see these by tapping the UP ARROW (to go backwards through your command history), or DOWN ARROW (to go forwards through your command history).

(this is similar to as you see on Linux, Windows and OSX command lines).

You can use the line verbatim again by hitting <SHIFT-RIGHT ARROW> to go the end of the line, and then hit <ENTER>.

You can also edit the line, using the following keys:
<LEFT ARROW> - move left one character
<RIGHT ARROW> - move right one character
<SHIFT-LEFT ARROW>- move to beginning of line
<SHIFT-RIGHT ARROW> - move to end of line
<CTRL-LEFT ARROW> - delete character at current character position; shift rest of line left.
<CTRL-RIGHT ARROW> - insert character at current character position; shift rest of line right.
<ENTER> - accept current line up to current position as is, and execute it.
<UP ARROW> - abort current line edit, go back up one line in command history
<DOWN ARROW> - abort current line edit, go forward one line in command history

Note: One difference with Windows command prompts - hitting <ENTER> in the middle of line will cut the command off at that position and execute it; Windows will take the whole line.

If have made edits but want to use the remaining part of the line verbatim, simply hit <SHIFT-RIGHT ARROW> first and then <ENTER>.

A further note: The editing keys listed above (but not the history keys) are actually universal to all programs that do the equivalent of an INPUT or LINE INPUT (ie asking for a line of input at a time, not just a single character).

So other programs, whether they are written in assembly, C, Pascal, BASIC-09, etc.

will all allow those editing keys - but they will be based on the last previous input ONLY.

Some programs can also “pre-load” the text buffer with default text, and display it, with you able to edit that using the keys above, as well.

SHELL also has a special “enable wildcards” character (:) that, if you put it as the beginning of the line, will enable SHELL wildcarding (?

for single character wildcard match, * for multi-character wildcard match, and [a-b] for a single character wildcard match within a certain ascii range ([a-b] would mean that the character has to be an 'a' or 'b'; [0-9] means it would have to be a numeric digit, etc.).

There are some limitations to SHELL wildcards that you should be aware of, though:
1) They only work for commands that accept multiple filenames as parameters on the command line
2) The internal buffer that SHELLPLUS uses to generate a wildcard file list is limited in size (I think around 2k)
3) If you send them to a program/utility that does it's own internal wildcarding, you may confuse that program.

Some commands that do use it well are DEL, CP, and TOUCH.

MULTI-VUE (GShell)

Most of the time, you will simply be using your mouse/joystick (or even keyboard mouse) to select menus, programs, folders, drives, etc.

But, there are some special keys you can use as well, while in GShell:
<Q> - Quit GShell.

This will ask you if you are sure; you can use the mouse to answer, or hit <Y> or <N>.

This is the same as File→Quit.

<S> - makes an overlay window with a shell in it, so that you can run a command line.

Type EX to quit the shell once you are done.

<$> - makes a resizable window shell on a different screen (same as File→Shell menu)

<?> - Calls HELP command for the currently selected file and displays it in an overlay window (same as selecting a file with a single click, and then clicking the question mark in the upper right part of GShell).

If there is no help for the file, it will say “No help available”

< = > - Refreshes currently selected directory.

Under NitrOS-9, vs. the original OS-9 Level II, it should do this automatically, if a file has been added/deleted/changed.

Sometimes it will miss if you have an overlay SHELL running on top of GShell at the exact moment a file has changed.

<SHIFT-UP ARROW> - will go up a page of icons (if there is a page up to go to).

Same as clicking the up arrow on the right.

<SHIFT-DOWN ARROW> - will go down a page of icons (if there is a page down to go to).

Same as clicking the down arrow on the right.

General notes on MultiVue (Gshell)

When you first fire GShell up, it reads it's environment file (which is a list of default settings, etc.), and then displays the floppy and/or hard drives it knows about on the left side.

(There is also a printer, and a trash can).

You select a drive (make sure that you have a disk in it, if it is a floppy!) by pointing the mouse cursor to it, and left clicking once.

You will then see a display of the files/folders/applications on it, which you can scroll through using the up and down arrows on the far right side.

To select a file/folder/ application, left click it once (it will highlight it), and then you can click on the Files menu and do various things to it (depending on the type, some selections will be non-bold and not accessible to you), such as list the file, copy it, get statistics on it, rename it, delete it, etc.

There is also a Sort option, to force a directory to permanently sort it alphabetically (it actually remakes the directory in alphabetical order).

If you follow the OS-9 “Standard” (not enforced), then directories will be all uppercase and will show up first, as well as AIF (Application Interface Files - these are used for apps, like the old PIF files from back in Windows 3.xx days) files, and then all other files.

There will be folders (also known as sub-directories) that contain more files, data files (which look like little pieces of paper with their corner folded), regular program files (which look like mini-GShell windows), and AIF program files (which will actually have unique icons).

Once again, left clicking once will then let you select the Files menu and perform actions on them; you can also click the < ? > (question mark) in the upper right corner to get help on a program file (if help is available in the help database - warning: this is a work in progress).

If you see a program icon (generic or AIF), you can double-Left click it to launch the program.

Some programs will then immediately run (like most of the game icons in the Games folder), others will prompt you for parameters to pass to the program first, in an overlay window.

A lot of programs will create their own full sized screen all to themselves.

A few, and most of the 'Tandy' Menu mini-applications (the funny looking 'X' type thingie left of the 'Files' menu - it is meant to look like a miniature version of the TC (Tandy Corporation) logo) will allow you to resize and/or put more than one program on the same screen.

These will show a box that you move around with the mouse (to position where you want the upper left corner to be), and at the same time shows you the minimum size the window has to be for that program.

Once you have the upper left corner where you want it, left click once to lock it in place, and then drag the mouse to resize it to the size you want.

Once you have the size you want, left click again to run the program in your new window.

Note: A few games support running in resizable windows; two I can mention are Rogue and Zone Runner.

If you get a circle with a slash through it as your mouse cursor, that means that you can't place the window at it's current location (NitrOS-9 does not currently allow overlapping windows), so you will have to pick a different spot/size.

It should be noted that, even with a 512K Coco 3, some games take a large amount of RAM, and you may not be able to run too many of those at the same time.

It should also be noted that some programs/ games are smart enough to know that they are not the currently active window, and will either pause or sleep until you make them the active window again…

but others will run full bore in the background while you are doing something else (for some games that may take awhile before requiring user input again - Flight Simulator II is one that comes to mind… this actually works out in your favour).

We are thinking of having this package automatically start up GShell on boot - if we do do that, would it be best to fire it up on the starting window, or one of the secondary windows that get fired up as it boots?

Tips and tricks

- When printing text on a graphics window - 8×8 fonts display a LOT faster than 6×8 fonts do - although they fit less text on each line.

A full screen window using an 8×8 font will show 40 columns for a 320 pixel wide screen, and 80 columns for a 640 pixel wide screen; you will get 53 and 106 columns respectively with 6×8 fonts.

Please be aware that not all programs check this properly, and those that don't will assume 8×8 fonts at all times.

- Hardware text screens are the fastest of all; especially on a 6309 based system.

Utilities like LIST (which lists text files) are much faster in these modes under NitrOS-9 than under Disk BASIC.

- For GSHELL - the default icons are all 4 color, so the two 4 color view modes (320×200 and 640×200) display and update much faster than the 16 color mode (which has to dynamically convert between 4 to 16 color on the fly).

- <CTRL-E> is usually used to abort a program (unless it has over rode that - kind of like ON BRK in Coco 3 BASIC), but if the program has done funky things like turn the cursor off, or shut off screen echo, or turned page pause on, etc., those weird settings will likely stay that way on the window you are on.

Try to quit a program through it's own quitting mechanism (Quit menu, CTRL-Q. etc). to avoid this.

If a program gets “stuck” and you can't get it stop no matter what, you can <CLEAR> to another shell window, then type PROC to get a list of processes.

Find the program name on the window that is running amok, and then type KILL <process #> to forcefully abort it.

The same problems with hitting <CTRL-E> listed above will apply, though.

- On a real Coco, hitting the RESET button once will immediately reload the NitrOS9 boot file and relaunch NitrOS9.

Hitting it twice will boot back to BASIC.

- If you want to change the defaults for Multi-Vue, you can use one of the text editors included (not all documentation is on for all of these yet).

Probably the easiest it use is called ED, and it uses a mouse.

To edit the Multi-Vue/GShell configuration file, you will need to go to a SHELL window, and type the following:

CD /dd/sys
ed env.file

Most of the settings are documented in the Multi-Vue manual on the Coco archive, and you should set them to how your system is set up (like whether your mouse/joystick is in the left or right port, whether you have a high-res mouse interface, your keyboard repeat delay/speed, and monitor type), but there are also some new ones that you may find useful:

GSHPAL0=r,g,b
GSHPAL1=r,g,b
GSHPAL2=r,g,b
GSHPAL3=r,g,b

The above 4 settings set the first four palettes that GShell itself uses, without changing the system wide default palettes.

The RGB settings are exactly the same as used by PALET0= from the manual, and elsewhere in the env.file.

NOTE: These should be set with color 0 as the darkest (usually black), and brightening as you go until color 3 is the brightest (usually white).

This is preserve the 3D look in the menu bars, and also for some graphics viewing programs coming soon that you can incorporate into your own programs.

As long as you go from dark to light for GSHPAL colors 0 to 3, you should be fine.

DEFTYPE=<window type>

Window type can be: 6 (320×200, 4 color), 7 (640×200, 4 color) or 8 (320×200, 16 color).

This tells GShell what mode to start in when you first fire it up.

Set this to your liking; we currently have it as type 6.

- While a lot of people just hit <ENTER> for the date and time, it is sometimes useful to enter them in, so any files you edit (even if you are unaware of it - like high score save files, etc.) are more easily findable by recent written to date/times.

- For viewing manuals in the /dd/docs directory, we highly recommend using the VU utility.

NOTE:

Two copies of this documentation are in /dd/docs as well, although they are slightly older versions.

NitrOS9-Beginner_docs.txt is the plain text version that you can load into a text editor, LIST, run MORE or VU on, etc.

NitrOS9-Beginner_docs.os9 is an experiment - native OS9 formatted documentation.

Use LIST on this one; it should automatically switch to an 80×25 graphics window, switch to a slightly shorter font (so the letters don't run together vertically) and then have bolding, underlining, and even an italic or two.

You can pause the listing either with <CTRL-W>, or by typing TMODE PAUSE before you LIST it.

MAKING AN AUTO-BOOTING NITROS-9 SD CARD

NOTE:

If you are a casual user, I would highly recommend dedicating an SD card for this purpose, and a second SD card for “regular” things, like SDC Explorer, etc.).

First, on your PC or Mac:

Step 1: Copy EOU_USER.VHD and either 68SDC.VHD or 63SDC.VHD (depending on whether your Coco 3 has a 6809 or 6309 CPU in it) to the root of your SD card.

Step 2: Create a text file called STARTUP.CFG in the root of your SD card, and enter the following lines into it:

If your CoCo has a 6809:

0=68SDC.VHD
1=EOU_USER.VHD

If your CoCo has a 6309:

0=63SDC.VHD
1=EOU_USER.VHD

Second, on your Coco 3:

Step 3: Insert the SD card into your CocoSDC, and power your Coco 3 on.

Type DRIVES <enter> and make sure that the two disk image names that you entered into STARTUP.CFG show up.

Step 4: Type:

RENAME "AUTO.BAS" TO "AUTOEXEC.BAS"

(this will enable the autoboot).

That's it!

When you turn your Coco 3 on with this SD card inserted, it should automatically launch NitrOS-9!

A big thanks to John Shawler and Aaron Dougherty from The Coco Show podcast (sadly, on hiatus for awhile), for helping add in documentation for beginners new to the Coco and OS9 both.

And thanks to Kevin Becker for the step by step directions to make NitrOS-9 EOU completely autoboot.

Well, that's it for quick and dirty notes for now.

Please let me know if you have any questions, need any clarification, any suggestions for me to make this easier to understand for beginners, etc.

L. Curtis Boyle curtisboyle at sasktel dot net

Beta 5 Beginners Documentation revision 1 05/24/2020

Return to NitrOS-9 Ease of Use :: Tandy Color Computer