MBARI OASIS3 Mooring Guide

Getting Started With OASIS3

Needed

• * Persistor CF2 Getting Started Guide from Persistor Corp.
• * PicoDev Development CD from Persistor Corp.
• * CF2228B1.exe file, originally from Persistor Corp.
• * CodeWarrior 8.0 for Palm OS Platform, Hosted on Windows, from Metrowerks Corp.
• * CW_for_Palm_V8.3_Update.exe file, originally from Metrowerks Corp.
• * OASIS3 source code
• PC running Windows 95/98/NT/2000/XP
• 12 Volt, 3 amp power supply
• EITHER
  • OASIS3 Can and OASIS serial and power cables OR
  • Persistor CF2 Card, RecipeCard, Persistor serial and power cables. All of these are included in the CF2 Development kit from Persistor Corp.
• You may also want to look at the CF2 Version 2.27r1 Release Notes

(*) 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.

Both class 1 and class 2 users need to install the full development system and read this guide. Users described as class 3 above 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 item 5.

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. Follow the directions on pages 1-12 of the Persistor CF2 Getting Started Guide. Note that these directions have you install CodeWarrior 8.0 and the PicoDev tools, including MotoCross.
   • If you want to install CodeWarrior 8.0 from the OASIS3 CD, go to /support/CodeWarrior8.0_CD and double-click on Launch.exe.
   • To install the PicoDev tools from the OASIS3 CD, go to /support/PicoDev2.27_CD and double-click on setup.exe.
   • MotoCross is the terminal emulator that must be used during development, as it has special menu items that facilitate downloading code to the CF2 CPU card.
   • Note - if you're using an OASIS3 can instead of the CF2 card and RecipeCard, you probably won't see the signon message indicated on page 12. If that's the case, send the OASIS3 command Reset Pico. This will return you to PicoDOS, and you can continue from there.
   • You are encouraged to read the remainder of the Getting Started Guide, but pages 1-12 are critical.
4. Update to CodeWarrior version 8.3. 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.
5. Install PicoDOS version 2.28b1 by following the directions in CF2PicoDOSBeta228b1Notes.htm. Notes, by section of this document:
   • "Installing the beta release onto your PC" - Always do this section
   • "Installing the 2.28b1 beta PicoDOS firmware into your CF2" and "Updating the SPV Firmware to 3.07" - Do these sections only if it's a fresh CF2 card, which has never been updated to PicoDOS 2.28b1. Normally you can skip this step. It is covered again in Preparing a New OASIS3 Controller, under "Upgrading to PicoDOS 2.28b1".
   • "Compiling with the beta tools" - Always do this section.
   • "CodeWarrior for Palm OS Platform v9" - Skip this section. If you're curious, it contains information on why we're staying with CodeWarrior 8.3.

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:
   • OASIS.APP is the version that is compiled for the Flash memory address of the CF2. This is the version that gets used for final release, that runs every power cycle.
   • OASIS.RUN is the version that is compiled for RAM on the CF2. This is the version that's normally used for debugging; it requires booting into PicoDOS and running OASIS from the command line. See page 17 of the Persistor CF2 Getting Started Guide, under "First.RUN" and "First.APP".

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.