# OASIS3 Development Tools README # This document describes how to install OASIS3 development tools and build and install OASIS3 firmware images. ## Prerequisites - Windows 10 PC or VM - Code Warrior for PalmOS v9.0 or v9.3 ISO image or install media - PicoDOS Persistor Tools v4.03 ISO image or install media - git - OASIS3 source code [see below] It is possible to install previous versions of Code Warrior or PicoDOS (e.g. v2.27 or v2.28 beta); these use default installation paths that make them less straightforward. *It it strongly recommended to use CW 9.0 or 8.3 and PicoDOS 4.03* To use the older versions instead, see the Getting Started guide on the OASIS3 documentation site: ``` http://fangtooth2.shore.mbari.org/oasis3/overview/GettingStarted.htm ``` The bitbucket repository ``` https://bitbucket.org/mbari/oasis3g ``` Windows 7 and Windows XP may also be used. Other versions may also work, but are untested. ## Installing Development Tools Before starting, uninstall any previous versions of CodeWarrior and PicoDOS Tools using the Windows Control Panel, and delete any directories they leave behind, e.g. ``` C:\Program Files\Metroworks\CodeWarrior C:\Program Files\Persistor C:\Program Files (x86)\Metroworks\CodeWarrior C:\Program Files (x86)\Persistor C:\Program Files\Metroworks\CodeWarrior\MotoCross Support ``` Both Code Warrior (CW) and PicoDOS may be installed from CD ISO images if you don't have the media or a CD/DVD drive. _Mount ISO images in VMWare_ * Copy the ISO image to the Windows guest * In the VM settings, select the virtual CD ROM settings * Use the drop down box to browse and select the desired image The ISO image may be changed while the VM is running. The ISO image will appear as a CD drive on the VM guest. _Mount ISO images in Windows 10 Explorer_ * Copy the ISO image to the Windows guest * In Windows Explorer, navigate to the ISO image * Right click on the image and select Mount The ISO image will appear as a CD drive on the VM guest. To change images, use Windows Explorer to eject the disk image and repeat these steps to mount the next image. _Install Code Warrior_ * From the CodeWarrior CD, run the Setup or Launch application * Use the default install path [1] * When prompted, select Custom Install and un-select all components except * CodeWarrior IDE * CodeWarrior for Palm Support * When prompted, decline the opportunity to update or register CodeWarrior [1] For Windows 10, the default install path is C:\Program Files (x86)\Metroworks\CodeWarrior. In previous Windows versions, it may be C:\Program Files\... _Install PicoDOS_ * From the PicoDev Tools CD, run the setup.exe application * Use the default install path (C:\Program Files (x86)\Persistor\MotoCross Support) ## Get OASIS3 Source Code If you haven't already registered an SSH key for your bitbucket account, do so via your user settings. _Get the source code_ Clone the MBARI bitbucket oasis3g repository ``` git clone git@bitbucket.org:mbari/oasis3g.git ``` Note that the source code may reside on the Windows file system, or if using a VM, a shared volume on the VM host. ## Configure Code Warrior Start the CodeWarrior IDE. From the Menu Bar use Edit > Preferences... to open the IDE Preferences window. Select General > Source Trees in the navigation frame on the left Click the Import Panel... button and select the PicoDOS Tools source tree settings by navigating to ``` C:\Program Files (x86)\Persistor\MotoCross Support\CFX\XMLSettingsPanels\IDE ``` Click Apply. The XMLSettingsPanels in PicoDOS Tools assume that it is installed in ``` C:\Program Files ``` In newer Windows versions, it installs to ``` C:\Program Files (x86) ``` If the source tree path settings loaded from PicoDOS Tools don't match the actual install directory, they must be manually changed: For each source tree path in the IDE Preferences window: * In the Name and Path panel, select the path (e.g. MxTarget, MxSpecial, etc.) * Note the full path under the Persistor directory * In the Source Tree Info panel, click the Choose... button * Navigate to the corresponding directory in the actual PicoDOS install directory, e.g. C:\Program Files (x86)\Persistor... * Click the Change button (otherwise it will revert to the original setting) When all the source tree paths have been updated, press OK to close the IDE Preferences window. After installing Source Trees, refresh the OASIS3 project paths via CodeWarrior: Project > Re-search for Files ## Build OASIS3 Firmware In the Code Warrior IDE menu bar, select File > Open..., and navigate to the OASIS3 Code Warrior project file in the oasis3g git repository: ``` ...\oasis3g\src\controller\oasis.mcp ``` This should open the oasis project window tab. At the top of the tab, click the Make icon to build the Persistor application. The build output is stored in ``` ...\oasis3g\src\controller\bin ``` Note: in some oasis versions, the isfet_pH.c file is missing from the oasis.mcp project, but is referenced in the DrvTable, resulting in a linker error. Add the file to the project in the CW IDE and make the project again. Output files include: ``` bin/oasis bin/oasis.AHX bin/oasis.AMP bin/oasis.APP bin/oasis.bin bin/oasis.MAP bin/oasis.RHX bin/oasis.RMP bin/oasis.RUN bin/Resource.frk/ bin/Resource.frk/oasis ``` The oasis.APP file is the firmware binary used to program the Persistor. Note that these files are overwritten any time the source is rebuilt. ## Install OASIS Firmware This section describes updating OASIS on an existing system, and installing to new hardware. __Update OASIS Firmware__ Persistor firmware (oasis.APP) may be installed through the OASIS serial console using the MotoCross utility included in the PicoDOS tools. Start the MotoCross for PicoDev application from the Windows start menu. From the menu bar, use File > Communications Settings to configure for the OASIS console port and settings (9600N81, no flow control, Mx Download speed 115200). Wake up OASIS using the hardware reset button, if needed . The OASIS prompt should be displayed in the MotoCross terminal. Reset to PicoDOS using the OASIS reset pico command: ``` OASIS3> reset pico ``` From the PicoDOS prompt, delete existing OASIS data log files: ``` C:\del OA*.DAT C:\del OA*.IDX ``` From the MotoCross menu bar, use Transfer > Load... to open a file browser, and navigate to select the OASIS.APP file. MotoCross will upload the OASIS.APP file and reboot the Persistor. Note: after rebooting, the output may end with "G" if so, type "S OASIS" and press return: ``` GS OASIS ``` If it returns to the PBP, return to picoDOS ``` PBM>pico ---------------------------------------------------------------- Persistor CF2I5 SN 01335 PicoDOS V4.03r1 PBM V4.03 (C) 1998-2007 Persistor Instruments Inc. - www.persistor.com ---------------------------------------------------------------- The clock needs setting if it's not January 01, 1970! ``` Set the clock (to UTC) if needed. Now it should be possible to boot the application. Set picoDOS to boot the resident APP file in flash and reboot: ``` C:\boot app C:\reset ``` It should boot to OASIS. __Install OASIS To New Hardware__ Follow this procedure if you are starting with a blank CF Card. If the Persistor is _Prepare a CF card for Persistor_ Not all CF cards are compatible with CF2. The Persistor CF2 Getting Started Guide installed with the PicoDev Tools contains CF card compatibility information: ``` Persistor\MotoCross Support\CFX\Docs\pdf\CF2GSG.PDF ``` Install the CF card into an OASIS programming fixture. Boot to PicoDOS. Use the format command to format the CF card: ``` C:\format c: ``` Connect the programming fixture serial cable to a PC with the PicoDev tools (MotoCross) installed. Use the procedure described above to load the OASIS.APP file using MotoCross. Once OASIS is installed Reformat the CF card: * Put the CFM card to be formatted in Persistor CF2 card on theOASIS3 CPU board. * Connect the serial terminal cable. Run a terminal emulator program (e.g. Motocross). * Boot OASIS3 normally. * Execute the user command diag. ``` OASIS> diag ``` * Follow the instructions to repeat the magic word to go into diagnostic mode. * Choose option F, reformat Compact Flash Card. * For "New sectors/cluster:", type 32 [1] * For "New # Root Directory Entries:", use 4096 for larger CFM cards. [2] The program will print the new Boot Record parameters. Reboot OASIS3 by choosing option X. [1] 32 * 512 bytes = 16 KB [2] For cards < 32 MB, you might want to use 1024. ## Update Persistor Firmware This procedure applies to Persistor hardware with PicoDOS versions < 4.03. Most existing OASIS Persistor hardware has been updated, though some OASIS programming fixture hardware may have old Persistor firmware. If a system is out of date, trying to load OASIS firmware via MotoCross may fail with the error ``` <<<< SEVERE PROBLEM >>>> Incompatible BIOS <<<< SEVERE PROBLEM >>>> FLASHAPP.PXE expects 3.0x not 2.28 [repeats until pbm button pressed, which goes to PicoDOS (or PBM?)] ``` The firmware versions may be checked using the PicoDOS version command: ``` C:\>ver CF2I5 SN 01335 PicoDOS 4.03r1 BIOS 4.03r1 PBM 4.03 SPV 5.20-P TPU P.01 TLC 1.03 ``` If the PicoDOS, PBM, and SPV versions match those indicated, the firmware is up to date. Notes on updating firmware are also documented in the release notes on the PicoDev Tools CD and installed with the PicoDOS tools: ``` Persistor\MotoCross Support\CFX\Docs\Release Notes\UpdatingFirmware.htm ``` The following procedure details how to update the Persistor firmware: * Get a CF card (prepared for Persistor, see note below) or power off the persistor and eject the CF card * Mount the CF card on the machine hosting PicoDev tools (e.g. using a USB CF card reader) * Copy all of the files from C:\Program Files (x86)\Persistor\MotoCross Support\CFX\bin\CF2 to the CF Card * CF2R4031.APP * RESTORE2.RUN * SPV520R7.RUN * Unmount the CF card and re-install it on the CF2 Power up the CF2 Note: For instructions on formatting a CF card for Persistor, see the Getting Started guide on the OASIS3 documentation site: ``` http://fangtooth2.shore.mbari.org/oasis3/overview/GettingStarted.htm ``` It should boot to PicoDOS. If it boots to the Pico Boot Monitor (PBM), exit to picoDOS: ``` PBM> pico ``` If it boots to OASIS, reset to picoDOS ``` OASIS> reset pico ``` If there is are error messages, push the PBM button or follow the Persistor doc for using Pin 39 to force a reset to PicoDOS. At the PicoDOS prompt, install the firmware update ``` C:\>restore2 CF2 Restore to ROM Version 2.20 (using PicoDOS 4.02r1) Searching for *.APP files on C: ... Restore CF2R4031.APP [N] ? Y Checking file CRC ... .................. Ok Checking file CRC ... .................. Ok Erasing flash from E08000 to E4FFFF ... Writing flash ..................... Confirming flash CRC32 ... Ok Checking PBM, hit any key to stop ... Updating PBM 227 to 403 ... Complete, resetting ---------------------------------------------------------------- Persistor CF2I5 SN 99999 PicoDOS V4.03r1 PBM V4.03 (C) 1998-2007 Persistor Instruments Inc. - www.persistor.com ---------------------------------------------------------------- The clock needs setting if it's not May 14, 1908! Warning: You need to update your SPV firmware! To do this now, type: UPDSPV \ ``` at the PicoDOS prompt, install the supervisor update using ``` C:\>UPDSPV CF2 99999 Supervisor Firmware Updater Version 5.20r7 Build: SPVX520r7 Apr 15 2005 04:02:29 (C) 2004-2005 Persistor Instruments Inc. This program will verify, or update then verify, the 4.05 firmware that is currently installed with the latest version 5.20 firmware. ONCE BEGUN, UPDATING TAKES ABOUT A MINUTE AND MUST NOT BE ABORTED! Are you sure [N] ? Y Installing .......................... OK Verifying .....CRCX=CDFD...CRCM=249C.. OK Resetting... ``` Now use the version command and confirm Persistor firmware versions ``` ---------------------------------------------------------------- Persistor CF2I5 SN 01335 PicoDOS V4.03r1 PBM V4.03 (C) 1998-2007 Persistor Instruments Inc. - www.persistor.com ---------------------------------------------------------------- The clock needs setting if it's not January 01, 1970! C:\>ver CF2I5 SN 01335 PicoDOS 4.03r1 BIOS 4.03r1 PBM 4.03 SPV 5.20-P TPU P.01 TLC 1.03 C:\> ``` PicoDOS and PBM versions should be 4.03. SPV should be ver 5.20 Note: after rebooting, the output may end with "G" if so, type "S OASIS" and press return: ``` GS OASIS ``` At the PBM prompt, return to picoDOS ``` PBM>pico ---------------------------------------------------------------- Persistor CF2I5 SN 01335 PicoDOS V4.03r1 PBM V4.03 (C) 1998-2007 Persistor Instruments Inc. - www.persistor.com ---------------------------------------------------------------- The clock needs setting if it's not January 01, 1970! ``` Now it should be possible to boot the application. Set picoDOS to boot the resident APP file in flash and reboot: ``` C:\boot app C:\reset ``` Should now boot to the new app image: ``` Resetting... oasis.c: Aug 20 2021 16:00:54 Persistor CF2 SN:1335 BIOS:4.3 PicoDOS:4.3 Setting minvalidyear to: 2021 Setting maxvalidyear to: 2023 OASIS3 $Revision: 1.18 $ OASIS3 $Revision: 1.18 $ 2021M1 OASIS> ``` ## Resources OASIS3 Documentation ``` http://fangtooth2.shore.mbari.org/oasis3 ``` Persistor Documentation (PicoDev Tools CD) ``` CF2 Getting Started Guide Persistor\MotoCross Support\CFX\Docs\pdf\CF2GSG CF2 Programmers Manual Persistor\MotoCross Support\CFX\Docs\pdf\CF2PRG CF1 Users Manual Persistor\MotoCross Support\CFX\Docs\html\PersistorCF1UsersManual\index.html ``` OASIS Maintainers ``` kent headley headley@mbari.org kevin gomes kgomes@mbari.org ```