MediaWiki:Sitenotice:
2024-03-02: The wiki ran out of disk space, so things were not working. This has been resolved by adding another 5GB of quota ;-) Thanks to Tim Lindner for reporting the issues. 2020-05-17: If a page gives you an error about some revision not being found, just EDIT the page and the old page should appear in the editor. If it does, just SAVE that and the page should be restored. OS-9 Al (talk) 12:22, 17 May 2020 (CDT)

DW4 Installation Guide

From CoCopedia - The Tandy/Radio Shack Color Computer Wiki
Jump to navigation Jump to search

by Bill Pierce

Please do not edit this page. This is a work in progress and I would like to finish it before anything is added or deleted.
If you see something in need of correction or would like to contribute to the page, please contact me
This page was created in 1440 x 900 Widescreen resolution, and is best viewed that way.
Thank you, B.P


Introduction to DriveWire4

I'm mean when I'm green... and plugged in!
I'm mean when I'm green... and plugged in!

--------------------------------------------------------------------------------------------------------------------I'm mean when I'm green... and plugged in!--------------------------------------------------------------------------------------------------------------------


NOTE: This tutorial is for the actual Coco 1, 2, or 3. It is not for use with the Coco emulators with Becker port support. Those programs need a
different version of HDBDOS an/or NitrOS9 than what is discussed here. If this tutorial becomes a useful tool for the Coco Community,
then I may add a section for the emulators and the Becker port.
Also, In this tutorial I will only be covering the installation of DriveWire4, NOT DriveWire3. The two program have different GUI formats and
capabilities. To cover them both here would take two sets of instructions for each operation and I want this document to be simple and not
confuse the new user. I may do a similar page for DriveWire3 soon.
 B.P.

The current DriveWire4 installation is a simple, easy way for the Coco 1, 2, & 3 user to access virtual disk and virtual hard drive images found in the Color Computer archive sites. These types of images were originally created for the Coco emulators as far back as 1995. With DriveWire, you can use your PC (Windows, Mac or Linux) as a “server” for these files and access them from the Coco as if they were real disks.

DriveWire has many capabilities that go far beyond just mounting disk images. Things such as “DW4Midi” for using DriveWire as a Midi synth for a Coco Midi player or sequencer such as Lester Hands’s “Lyra” and Mike Knudsen’s “Ultimuse 3”. DriveWire is a “serial communications” system as well allowing you to set a “Coco style” terminal on your PC to access your Coco from a remote location. There are features for “modem emulation” to allow DriveWire to act as a modem for the Coco to use for “Telnet” and similar communications systems. There are many other uses and you’ll have to visit the DriveWire documentation site to find out all the various things it can do.

This document will only deal with getting DriveWire set up and running and some of the “basic” functions of the system like mounting virtual disks. It is by no means the end of the story as the boundries of the DriveWire system seem to expand rapidly. So I will leave it up to the user to explore the internet and find out what other people are doing with DriveWire, I just want to get you up and running so you can do these things once you find them.

I have tried to be as complete and consise as possible in making the DriveWire installation simple and easy as well as fun, though it is quite an "involved" process. I have tried to include everything needed to get started. If you find any mistakes or inconsistencies in this document please leave me a message on the Coco Mailing List or on the Color Computer FaceBook page and I will try to make corrections and get it posted as soon as possible. Have fun!

I will try to explain what software and hardware is needed to get started with DriveWire4, HDBDOS, and NitrOS-9_dw on the Tandy Color Computer. This will not be a tutorial in operating these systems but a tutorial in installing them. I will be dividing most things into categories when I can to make it easier to grasp each concept as each system has it’s own requirements, setup and maintenance. Where applicable, I will be providing links to the websites of the developers and/or distributors of these systems and their supporting Wikis, documentation and downloads for further info and updates. I will try to provide the basic essentials to get you up and running as quick as possible.

This document is not to be considered an alternate to the development sites but as a starting point to those sites. Please take the time to check the links to sites with downloads and info as I will be listing quite a few of those throughout this document.

With all that said, let’s get on with the show. First, we need a list of the things required to get running.

Bill Pierce

NOTE: Please keep in mind that most of my references to the PC refer to my Windows machine even though I will use the term PC to refer to any machine
running Windows, Linux, or a Mac operating system. If you are running a Mac or Linux system then you will have to find the equivalent term applicable
for your system as I have very limited knowledge of those systems. The Tandy Color Computer 1, 2, & 3 will be referred to as the Coco 1, Coco 2, and
Coco 3 respectively. Also, any references to OS-9 is usually referring to NitrOS-9, as standard vanilla MW OS-9 will not run the DriveWire drivers. B.P.

The DriveWire4 Hardware

To start with you will need the following hardware:

Hardware (Required)

  • Tandy Color Computer 1, 2, or 3 with at least 64k of memory
  • Coco Serial to DB-9 adapter cable. (more on this later)
  • A Windows, Mac or Linux PC system with Java 1.5 or better.
  • A Monitor/TV for the Coco
  • Also, if your PC does not have a DB-9 serial port, you will need have to purchase a USB-to-DB9 adapter. (more later)

That’s it! This is all the hardware it takes to run an efficient modern Coco system! For optional hardware, there are hundreds of things that could be listed, but I will only list the standards:


Hardware (Optional)

  • Coco Floppy disk controller (Any Coco compatible will do)
  • Coco Floppy disk drive(s) (35t, 40trk, 80trk)
  • Coco Hard drive controller
  • Coco Hard drive(s)
  • Coco Multipak interface

Software (Required)


Windows, Linux, Mac PC

  • Java 1.5 or better
  • DriveWire4 Server package

Coco 1

  • HDBDOS 1.4 DW Coco 1 or better (rom, wav, or bin)
  • For NitrOS-9 you will need a DW compatible version of NitrOS-9 L1 for Coco 1

Coco 2

  • HDBDOS 1.4 DW Coco 2 or better (rom, wav, or bin)
  • For NitrOS-9 you will need a DW compatible version of NitrOS-9 L1 for Coco 2

Coco 3

  • HDBDOS 1.4 DW Coco 3 or better (rom, wav, or bin)
  • For NitrOS-9 you will need a DW compatible version of NitrOS-9 L2 for Coco 3

And most of all, a big collection of your favorite RSDOS or OS-9 software on virtual disk or vhd (virtual hard drive).

For the record, as of the writing of this document (10/01/2013), the current stable software versions are:

  • HDBDOS v1.4 DW3 Coco 1, 2, and 3
  • DriveWire v04.03.3o (or v04.03.3p for Turbo mode)
  • NitrOS-9 v03.02.09 dw3 (Coco 1 & 2 Level 1, & Coco 3 Level 2)
NOTE:To update any of these systems to their current version, please visit the links provided in each section and in the “Resources Links”
section of this document. From these links you can download the latest version of the software as well as documentation on each system. B.P.

With those simple elements, there is a whole world of Color Computer at your finger tips (literally). From this point, depending on the Coco system you are running (1, 2, or 3), your DW4/HDBDOS/NitrOS-9 system can expand to unbelievable capabilities. The current list of new hardware seems to be growing. More on that later, right now let’s set up a simple, easy to use, basic Coco DW4 system.


The DriveWire Cable

This was also covered in Getting Started with DriveWire but I will include it here for posterity.

Before you can use DriveWire 3 or 4, you will need to connect your CoCo to a computer being used as a DriveWire server. You will need a Coco Serial (bit-banger) to DB-9 serial cable. Again, Cloud9 sells these cables.

Conversely, you may build your own based upon the following diagram:



Also, if you have a more modern PC, it's most likely not to have the needed DB-9 serial port. As an alternative, you can puchase USB to Serial (DB-9) converters. These range in price from about $10 - $20 and can be purchased from most any electronics supply house. If they don't have it on the shelf, ask someone and they can most likely order it for you. You will still need the cable above as this is just an adapter to be able to connect it to PC's with no DB-9 serial port.

Alternatively, you can also still purchase an add-on PCI or PCIx serial card. TigerDirect and NewEgg still stock a large selection of these cards. The internal serial cards tend to offer better data transfer rates than the USB to Serial adapters in testing.


Installing the JavaVM

NOTE:This is NOT a Java browser plug-in, It is a Java Virtual Machine to run Java based code such as DriveWire4. As far as I know, it in no
way affects your browser and only runs when called to run Java code.

First you will need Java 1.5 or better to run DriveWire 4 on your PC no matter if it’s a Windows, Mac, or Linux system. Most more modern machines will already have Java installed and if you use a web browser to view webpages with videos or audio, then you most likely have Java installed but may need to update the package. DriveWire will inform you if you need the Java app when it runs. If you find you need to obtain the Java app, there are packages available for all machines. Even old ones. I have provided the link for the Java download site here:

Java Downloads for All Operating Systems

Here you will find the latest Java downloads for most computer OS platforms. Just click the Java package that's right for your machine and follow the instructions on the site and throughout the installation process.

Once you have the Java app installed, you are ready to move on to DriveWire 4.


Installing DriveWire4

Note:At this point, you want your Coco to remain powered down. B.P.

To install DriveWire4, you will need the DriveWire4 installation package. You can go to the DW4 distribution site and download the latest incarnation yourself at:

CocoCoding / DriveWire4

While you’re there, please read the documentation Wiki and browse the CocoCoding site to see all the available utilities. Links for those are on the site linked above.

After you have downloaded DriveWire4, unzip the DriveWire4 zip file to a folder of your choice. Choose what is right for you and your system as I know Mac and Linux are a little different in this respect. This is the only installation method for dw4 as there is no “Auto-Installation Package”.

Once you have the DW4 folder set up, open the folder and you will see a file named

  • DW4UI.jar” for MS Windows

(NOTE: This Windows file will be changing in a future update of DriveWire4 to "DW4UI.exe" for Windows use. There is a problem with the current "DW4UI.exe" and it's being fixed)

  • DW4UI.sh for Linux
  • DW4UI.command for Mac OS

First, for Windows users, “right click” this file and click the “Create Shortcut” option to create a shortcut to put on your desktop. Some systems will automatically place this shortcut on the desktop and some will make you do it manually. If you have to do it manually, just drag the shortcut over and drop it on your desktop.

On Mac and Linux, I do not know the equivalent methods for creating desktop shortcuts so you will have to consult your OS documentation.

Now, double-click this shortcut and the DW4 GUI (graphics user interface) should display. You should see something similar to this:



Of course there will be no disk images mounted in your drive slots yet.

The first thing you want to do in DW4 is to check for updates. Click the “Tools” tab at the top of the GUI, and at the bottom of the pull-down menu, you will see “Check for new version” as below:



To use this feature of DW4, your PC must be connected to the internet. Once clicked, DW4 will check the distribution site for the latest update and if available, will prompt you for permission to download. Once it downloads, it will shut itself down. You will then have to restart DW4 as I don’t think the developer has the restart feature worked out yet. Once you are satisfied the latest version is running correctly, we still have a bit of work to do yet before we can connect the Coco to DW4.

It is best not to do any other configuration at this point until you have the Coco ready to go. So now need to move to the Coco to set up HDBDOS and configure it for DriveWire.


Installing HDBDOS for DW4

Template:Font color Template:Font color

This part of the installation needs to be done before you try to actually run a DW4 system. You need to be familiar with the version and method you will use to load and run HDBDOS.

Note: At this point you may power up your Coco

The HDBDOS installation is basically the same for all models of the Coco with the exception of the version of HDBDOS that you will be using. You can select the right version for your system when you download the latest HDBDOS build here:

HDBDOS Snapshots : In the ToolShed Repository that is the home for the HDBDOS sources

Alternately, you can get the HDBDOS files at:

HDBDOS Roms at Cloud9's site (scroll to the bottom of the page).

The Cloud9 Roms are not quite as up to date as the Roms at the ToolShed site but proven stable over time. Which you choose is your decision. You can view a list of descriptions of the contents of this package at DRIVEWIRE.ZIP. You will have to compare the names and decipher the equivalent Roms from this package.

The ToolShed project has provided us with a nice selection of roms, bins and wav files for making real cassette and disk files as well as ROM images for burning an EPROM. If fact, too nice. Most of the Roms in this package deal with setups not related to DW4, but the ones we need are there.

NOTE:The Roms listed below are from the ToolShed snapshot zip file. These are the only Roms in that file that can be used with DriveWire4.
There are other Roms, bins, and wavs in that zip but those are NOT used for DriveWire4. Most are experimental and are not stable for use
and again, are NOT DriveWire compatable.""

The Roms we are interested in from this package are:


Coco 1 Rom Files

  • hdbdw3cc1.bin – The binary executable file for HDBDOS DW on a Coco 1.
  • hdbdw3cc1.rom – The ROM version of HDBDOS DW on a Coco 1 for burning an EPROM to put in your disk controller.
  • hdbdw3cc1.wav – The audio wave recording of the HDBDOS DW “.bin” file above for cassette on your Coco 1.

Coco 2 Rom Files

  • hdbdw3cc2.bin – The binary executable file for HDBDOS DW on a Coco 2.
  • hdbdw3cc2.rom – The ROM version of HDBDOS DW on a Coco 2 for burning an EPROM to put in your disk controller.
  • hdbdw3cc2.wav – The audio wave recording of the HDBDOS DW “.bin” file above for cassette on your Coco 2.

Coco 3 Rom Files

  • hdbdw3cc3.bin – The binary executable file for HDBDOS DW on a Coco 3.
  • hdbdw3cc3.rom – The ROM version of HDBDOS DW on a Coco 3 for burning an EPROM to put in your disk controller.
  • hdbdw3cc3.wav – The audio wave recording of the HDBDOS DW “.bin” file above for cassette on your Coco 3.

Rom File Extension Definitions

Now I feel there is a little more detailed explanation of the file extensions used here. I’ve had people tell me when they loaded the “.rom” file, it crashed their Coco… as well it should. I will explain why. Here is an explanation of the terms:


.bin

This file was saved to disk with start, end and execution addresses so it can be loaded as any other file This is the same as any binary executable program file used by DECB. The actual “rom” file is loaded into low memory, then a small machine language program is added to the beginning of the file. The small program, when executed, will put the Coco into all-ram mode, copy the rom into high memory ($C000-$DFFF) and then execute the rom. To use this file, you must save it to a floppy disk. I will not get into the methods of transferring disk images to real floppies here as I have no drives that will work with my PC and cannot vouch for this method. It can then be loaded with: LOADM”HDBDW3Cx/BIN”:EXEC (x being your Coco model 1, 2, or 3) The file is renamed to be compatible with DECB’s 8 character limit.


.wav

This is the recording of a cassette version of the same file as above. It operates in the same manner. To use this file you must use one of the utilities that will play wav files through your PC speakers. You then either plug the Coco’s cassette cable into the PC’s headphone jack or use a straight 1/8th inch mini plug cable to plug into the headphone jack of the PC and the Microphone input on your cassette recorder. Type “CLOADM” on your Coco or press Play and Record on your cassette recorder, then start the playback of the wave file on your PC. If you’re using a cassette recorder, don’t forget to let the tape roll a bit to get past the leader tape at the beginning of the tape then hit Play on the PC. If you use the direct to Coco method, the program will load directly into memory just as if you were using a cassette player. The 2nd method makes a cassette tape that you can load normally on the Coco. In both cases, you may have to adjust the volume level on your PC as it tends have an output that’s a little higher than the Coco likes. I’ve found with experimentation that somewhere between 50% and 75% seems to work best. It will vary on different PCs and soundcards. You’ll have to experiment.

Once you have the file loaded into the Coco (before execution), you may want to save it to something more convenient to use in the future. These files will have to be renamed to make them compatible with DECB’s 8 character name, 3 character extension limit.

Saving to disk

SAVEM”HDBDW3Cx/BIN”,&H4FD0,&H6FFF,&H4FD0 where “x” is your Coco model (1, 2, or 3)

Saving to tape

CSAVEM”HDBDW3Cx”,&H4FD0,&H6FFF,&H4FD0 (no file extension) where “x” is your Coco model (1, 2, or 3)

Once you have the file loaded (and/or saved), just type EXEC<ENTER> and HDBDOS will start.


.rom

This file is not a loadable or executable file. It is a raw binary dump of the actual HDBDOS rom for use with an EPROM burner. It has no start, end, or executing address. Do not try to load this file from tape or disk. If you do not have an EPROM burner and would like to have an a ROM version of HDBDOS to install in your disk controller, you’ll have to ask around on the Coco mailing list or the Coco FaceBook page to find someone who can do this for you. Most people will do it for the cost of the EPROM and s/h charges. Again, you can get premade ROMS from:

Cloud9's HDBDOS page.

Their ROMS are of HDB-DOS 1.2 but stable and that may be negotiable with Mark at Cloud9 as he does mention "custom" burning on the website. He may be willing to burn any version you may need, but I can’t speak for him so you will have to contact Cloud9 and find out.

The advantage of this method over the other two is that HDBDOS cannot be wiped out by a program that uses it's own disk routines or ROM/RAM switching in it’s operation. The disk and cassette versions load into ram and therefore are defenseless from such programs. The only exception being the Coco 3 which always runs in all ram mode due to the nature of the “Super Extended Color Basic” patch. It is actually defenseless from the start. This is one of the reasons a lot of old Coco 2 programs crash the Coco 3.



Now we get to see something run. First, power down the Coco. Then start DW4 on the PC if it’s not running already. At the top of the DW4 GUI you will see a “Config” selection. Click on this and a menu will pop up. Select the “Simple Config Wizard” at the top of the menu:



An info screen will appear. Click “Next” at the bottom of this window. Here you will see several options of machines to run:



Select the proper Coco you are running, 1, 2, or 3 and click that machine. It will then confirm your selection. Click “Next”. Here you should see a list of “Comm Ports”:



Click the port that your DW4 cable is connected to. Then Click “Next”. In the next few windows, just click “Next” for the defaults until it reaches the final screen in which “Next” will no longer be available. Click “Finish”:



Your DW4 server is now ready

Now power up the Coco. You should see some activity in the “Server” tab in the DW4 GUI on your PC. This is normal as the server has found the Coco and is initializing. If you’ve installed an HDBDOS rom, you should now be in HDBDOS 1.4 on the Coco. If you do not have an HDBDOS rom, then load HDBDOS from disk or cassette by one of the methods described earlier and type “EXEC”. Either way, you should see:



If you get the flashing OK prompt, then you are home free. If not and your system seems to “freeze” then something is wrong. Start from the beginning and review the various steps and make sure everything was done exactly as explained. If it still doesn’t work, check the DW4 GUI and see if it is reporting errors. If so, note these errors and leave a message on the Coco mailing list and we will try to figure out what went wrong or submit a bug report from the .DW4 GUI “Help” menu and the developer may be able to help you.

If HDBDOS has started successfully, you can now “insert” a virtual disk image into the Slot 0 in the DW4 GUI. Type DIR<ENTER> on the Coco. You should get a directory of the contents of the disk. If you get the listing then you have successfully gotten DW4 and HDBDOS installed and running.

But… we are not through yet.


Mounting and Using Virtual Disks and Drives

(WIP)



Installing NitrOS-9 for DW4

(WIP)



DW4 Resources Links

DriveWire Cables

  • Cloud9 sells Coco serial to DB-9 serial cables

JavaVM Links


DriveWire4 Links'

NOTE:Links to download DriveWire4 from any other sites may result in a DriveWire4 version no longer in developement as DW4 is continuously updated
Please refer to CocoCoding's distribution site above for all DriveWire4 downloads.

HDBDOS ROMs


That's Not All Folks...

This is not the end of the story. I hope to include a lot more information in the near future though it may lead to an "Advanced DriveWire4 Features" page because there is a lot of things that DriveWire4 can do that have not been covered here. I wanted this to be a "Beginner's Guide" so I have tried to keep it as simple as possible to get the new DW4 user up and running.

It's programs like DriveWire4 that keep our little Coco running in the future... and I'll see you there.

Bill Pierce