MBARI OASIS3 Mooring Guide

Getting Started With OASIS3

Needed

(*) Items noted with an asterisk are available on the OASIS3 Distribution CD

Types of Users

There are 3 classes of users for the OASIS3 system.

  1. Software developers who want to write (or modify) new OASIS3 drivers or change functionality in the OASIS3 software.
  2. Technicians who want to configure the OASIS3 software or turn around an O3 can.
  3. Users who just want to talk to the OASIS3 controller.

Class 1 and users need to install the full development system and read this guide. Class 2 users don't need the full development system just to configure the can, but it's frequently helpful to be able to make small code changes. Users described as class 3 don't need this guide; they just need an O3 can, power and serial cables, power supply, PC, and any old terminal emulator; and can proceed to Connecting to OASIS. Developers and technicians should continue with this document.

Procedure

Note - OASIS3 requires PicoDOS version 2.28b1 or later; this is a beta release of PicoDOS. The instructions in the Persistor CF2 Getting Started Guide are based on PicoDOS 2.27, the latest released version as of this writing. Item 5 below is designed to upgrade you from PicoDOS 2.27 to 2.28b1. If Persistor subsequently releases 2.28 or later, you can ignore step 8 below.

  1. Assemble the items needed, as above. Note that the software is all available on the OASIS3 Distribution CD.
  2. Copy the /oasis directory from the OASIS3 Distribution CD to your PC. This is the OASIS3 source code, and can be copied to anywhere on your PC where you want to develop or configure OASIS3 software.
  3. Install CodeWarrior 8.0 for PalmOS, either from the CodeWarrior CD, or by clicking here. Note - Steps 3, 4, and 5 are taken directly from the Persistor CF2 Getting Started Guide. You may want to follow that document, as it has more illustrations. The current step, installing CodeWarrior, is on page 7:
    Your first step toward CF2 development requires installing Metrowerks CodeWarrior for Palm OS. The minimum requirements are:
    1. Windows 95, 98, ME, NT, 2000, XP
    2. Pentium (recommended), 80386, or 80486
    3. 64MB RAM,
    4. 220 MB available hard disk space
    5. CD-ROM for installation
      CF2 development requires that you install CodeWarrior using the Metrowerks CD installer. NOTE: If you have an existing CWPalm8 installation that compiles Palm OS 68K programs, you can skip right to the Install MotoCross section. If you're using CodeWarrior solely for CF2 development, you need only select the options indicated below, which will require about 40MB of disk space. Keep an eye on the dialog’s Space Required text. If it varies a lot from the screen snapshots, carefully review your selections. If you have trouble, it's perfectly safe to reinstall CodeWarrior in part or whole, and that generally will get you going.

      Start by inserting the CodeWarrior CD (O3 note - or here). Click your way through the first half-dozen or so introductory and license information dialogs. Begin to pay careful attention when you get to the Choose Destination Location dialog.

      For a painless introduction to CF2 development, you really do want to accept the default location offered by the installer:

      C:\Program Files\Metrowerks\CodeWarrior

      At the Setup Type screen, select the Custom Install option.

      At the Select Components screen, collapse all of the boxes to fit everything in the small window provided and uncheck everything except: “CodeWarrior IDE” and “CodeWarrior for Palm Support”

      Click your way through the remaining installer screens. After completing the installation the Programs selection in your Start Menu will now contain an option for Metrowerks CodeWarrior IDE.

      When done, CodeWarrior should prompt you to ask whether you want to check for updates. Click YES. This should update you to CodeWarrior 8.3

  4. Install PicoDEV with MotoCross. From CF2 Getting Started Guide, page 8:
    After you've installed CodeWarrior, insert the PicoDEV CD (O3 note - just click here). On most PCs, you will automatically be presented with the installation dialog. On some others, you will have to double click on the CD icon and setup.exe to get things started. Work your way through the setup screens accepting the default options until the installation is complete. The suggested directory for the software to be installed is C:\Program Files\Persistor. In order for everything to work properly we strongly suggest that you accept this path for the installation. (O3 note - I've seen some versions of Windows on which it will try to install to C:\Program Files\Metrowerks. If that happens, make sure you change it to C:\Program Files\Persistor).

    The Programs selection in your Start Menu will now contain an entry named Persistor containing the PicoDEV documentation index and the application; MotoCross for PicoDEV. (O3 note - you need to use MotoCross as your terminal emulator in order to load O3 code)

  5. Setup the Source Trees. From CF2 Getting Started Guide, page 8:
    MotoCross uses a powerful feature of CodeWarrior called Source Trees to steer projects to the proper directories for locating target components. The first time you use CodeWarrior with MotoCross, you must tell it where to look for the correct CF2 build model by importing one of the pre-configured XML Source Tree panels. After that, source tree operation becomes completely transparent.
    1. Start CodeWarrior from the Start / Programs menu.
    2. Select Preferences from the main CodeWarrior IDE Edit menu
    3. Click-select “Source Trees” from the IDE Preference Panels (left)
    4. Click the Import Panel… button from the Source Trees pane (lower right)
      Navigate to C:\Program Files\Persistor\MotoCross Support\CFX\XMLSettingsPanels\IDE You should see the four primary configurations:
      Source Trees_CF1+CWPalm8_IDEGlobalPref.xml
      Source Trees_CF1+CWPro6_IDEGlobalPref.xml
      Source Trees_CF2+CWPalm8_IDEGlobalPref.xml
      Source Trees_CF2+CWPro6_IDEGlobalPref.xml
    5. Choose Source Trees_CF2+CWPalm8_IDEGlobalPref.xml
    6. Click the OK button back in the Source Trees pane

  6. You can now exit CodeWarrior (File->Exit). You may want to continue reading the Persistor CF2 Getting Started Guide through page 12, but we're not doing those steps now.
  7. If, during installation of CodeWarrior in step 3, you didn't upgrade to CodeWarrior 8.3, you must do so now. The easiest way to do this is to go to the OASIS3 Distribution CD, cd to /support, and double-click on CW_for_Palm_V8.3_Update.exe. Alternatively, you can do it using the Metrowerks web site. On your PC, go to Start->Programs->Metrowerks CodeWarrior->CodeWarrior Updater, and follow the directions.
  8. Install PicoDOS version 2.28b1 by following the directions below, which are from CF2PicoDOSBeta228b1Notes.htm. (Note, Beta2 has how been released. If you want to update to Beta2 instead, follow the instructions in CF2PicoDOSBeta228b2Notes.htm instead; but you're on your own).
     For Beta 1:

You're now ready to recompile the OASIS3 source code.

  1. Go to your /oasis directory (or wherever you copied the source) and double-click on oasis.mcp. This will bring up the CodeWarrior compiler.
  2. You should see a window called "oasis.mcp" that lists all the source modules. Those that need recompiling have a check mark next to them. Place your mouse pointer to the left of the folder icon named "Oasis Src", and click. That should cause a check mark to be placed next to all source modules.
  3. Type the F7 key. This should cause the entire system to be rebuilt. Any errors (hopefully none!) will be shown in an additional error window. If you have errors, fix them and recompile.
  4. Exit the compiler, and navigate to /oasis/bin (if your source is /oasis). This is the output of the compiler, and consists of about 9 files. Many of these are symbol table, map, or hex files. There are two executable files produced:

How to Use the OASIS.xxx Files

To understand how to use OASIS.RUN and OASIS.APP, you need to understand that the CF2 has 3 potential boot modes:

  1. PBM is the Persistor Boot Monitor, and is the lowest-level software in the CF2. If you try to boot a CF2 card without a Compact Flash Memory card in it, it will boot into PBM.
  2. PicoDOS is the Persistor Disk Operating System. It looks a lot like MS-DOS, and has commands such as dir, copy, cd, date, time, prompt, etc. You can even create an autoexec.bat. It also has commands dedicated to using the CF2 hardware. Out of the box, if there's a CFM card, the CF2 will boot into PicoDOS.
  3. "APP" is the application that is burned into the on-board Flash memory on the CF2. This is normally where we store OASIS.APP.

If you're in PicoDOS, you can tell the CF2 which mode to boot into by using one of the PicoDOS commands boot PBM, boot PICO, or boot APP, for the 3 cases above. Notice the "if". If the OASIS3 system is already set to boot into OASIS ("boot APP"), then you need to get back into PicoDOS by issuing the OASIS3 command reset pico. This causes OASIS3 to quit and go into PicoDOS, regardless of the previous boot command. Once in PicoDOS, you can then issue one of the 3 boot commands.

Note that you also must be in PicoDOS to load new code via the MotoCross Transfer->Load command.

More details on PicoDOS commands, including boot, are in the CF1 Users Manual that came with the PicoDev Development CD, by clicking on "Persistor CF1 Users Manual" and then "PicoDOS Commands". (Yes CF1; the CF2 manual isn't out yet).

Debugging Mode

When debugging, it's usually convenient to run OASIS3 from RAM. (Note, this will decrease the amount of RAM available to the system by about 70K. See OASIS3 Memory).

If the system is booting into OASIS, issue the reset pico command. When you get to PicoDOS, issue the PicoDOS command boot pico to cause it to stay in PicoDOS through power cycles. Assuming you're already in Motocross, pull down the "Transfer" menu and click on "Load". In the File menu, navigate to /oasis/bin and choose OASIS.RUN. It will load into memory. When done, MotoCross should display the "G" command (note, doesn't always happen). Append an "S OASIS", so that it now reads "GS OASIS". This saves the file to OASIS.PXE. If you do a dir in PicoDOS, you should see this on the CFM card.

Whenever you want to run OASIS, simply type OASIS at the PicoDOS prompt. This will cause the OASIS3 code to run from init. This code will run forever as long as you don't lose power. When you power-cycle, the system will reboot into PicoDOS.

Release Mode

To load the release version of the code into flash, you must again start in PicoDOS. If the system is in OASIS, issue the reset pico command. Assuming you're already in Motocross, pull down the "Transfer" menu and click on "Load". In the File menu, navigate to /oasis/bin and choose OASIS.APP. This will cause the code to be burned into on board Flash memory. When done, get back to PicoDOS (note, it will sometimes go into PBM; if this happens, type pico). Then type boot app. This will cause the OASIS3 code to be executed whenever the system powers up.

Next

If you're turning around an existing OASIS3 can, see How to Turn Around an OASIS3 Can.

If you're preparing a newly constructed OASIS3 can, see Preparing a New OASIS3 Controller.