Conduit for Auriga

Features

The latest version of the Auriga Conduit is 0.39. This version is no longer compatible with Auriga since its version 2.08 (May 2013).

Conduits are programs which enable the transfe r and synchronization of data between the Palm and the PC. At this point in time, the Auriga conduit is bi-directional: it can export data from the Palm to the PC; it can import data from the PC to the Palm, but it cannot do a "full" synchronization if the file has changed on both sides.

This version of the conduit can export and import files from two popular cave survey data formats: Compass and VisualTopo. Other cave survey software formats will be supported in the future.

This being a Beta version of a software, there are most likely still some bugs. The author (Chris Chénier ) is most interested in hearing about any defect (bug) you may find.

Conduits being PC software, this conduit is designed to run under Microsoft Windows. If you use a Mac, I may get around to port it to that platform some time in the future, but it's not my first priority. If you use anything else, you're out of luck, as Palm does not support other platforms for synchronization.

Installation

Please follow these instructions for first time installations or for updating an older version of the conduit.

Conduits are desktop (or laptop) programs. 100% of the conduit installation is on the PC: nothing needs to be done on the Palm, unless otherwise specified.

Before installing, you should make sure that:

  1. The HotSync Manager is installed on the PC (the HotSync manager is installed automatically when you install the Palm Desktop.)
  2. Auriga and its conduit go hand-in-hand. If in the future you upgrade to a new version of Auriga, it may be that the conduit also needs to be updated. To be sure, check-out the PDB format under "About Auriga" in the Options menu. This version of the conduit is compatible with PDB format 49.

To install the conduit, you just need to run the install program AurigaConduitInstaller.exe (click to download). This program will do a number of things (which one does not need to worry about, but they are listed here in case you are curious.)

  1. It prompts you for an installation directory
  2. It copies AurigaConduit.dll's in the PalmDesktop directory
  3. If the Palm Desktop is currently running, it asks to close it so that the conduit can be properly installed. (You may restart the Palm Desktop immediately after.)
  4. It saves the path to the installation directory in the Windows Registry.
  5. It copies some files to the installation directory and creates 3 subdirectories. One is called "system", which you should not need to go into. Another is called "intermediate" and is used to store XML versions of the Auriga cave files (there is no need for most users to go there). The last one is called "TargetFiles" and contains one subdirectory for each target software currently listed in Auriga. This is the default directory where you will find the exported files, but it can be changed.

Parameters

You control what the conduit does at each HotSync operation by going to the HotSync "Custom" window, from which you can select "Auriga".  This brings-up the main Auriga Conduit configuration window.  In the top section of this window is a list of caves which will be imported or exported.  Initially this list will be empty.  You can manually add entries to it, and after a HotSync operation, all caves on your Palm will automatically appear in that list.

If you do nothing else to configure the above-mentioned list, the operation which will be done on all caves is the one specified with the radio buttons below (PC overwrites handheld; Handheld overwrites PC; Do nothing). 

However, you may choose to have different behaviour for each cave.  If you select a specific cave from the list and click edit (or just double-click the cave name), you will see the "Auriga Sync Details" window.  In that window, you can specify the name of the file in Auriga (it must match exactly the name used on your handheld); you can select the action for this file (this will override the default action specified on the previous screen), you can specify the full path to the file on your PC (either by typing it in or clicking on "Browse").  Further down, you can specify the file format (at this time either Compass or Visual Topo) (notice that this overrides the selection done in Auriga on your handheld).  Finally, you can specify station naming conventions, namely if you use 8 characters (or less) for station names, or if you want to use series and therefore use the "4.4" format.  In the later case, you can specify a separator.  Once you are done, click OK to go back to the main configuration screen.

If you want to completely disable the Auriga Conduit, just check the box at the bottom right: "Disable Conduit".  Just selecting "Do nothing" may no be enough, as you may have overridden that default as explained in the paragraph above.

To get file onto Auriga, which currently only exists on the PC, click the "Add" button, where you will see the same window as described above.  You get to decide the name your file will have on the handheld, and you must specify a file name and format.

Notice that a single list of caves to be synchronized is saved on a given PC.  If you synchronize more than one Palm to the same PC, you will want to pay extra attention to this.

At this time, doing a full synchronization is not supported.

Synchronizing (how it works)

This conduit performs its job in two steps. The first step is to write to an intermediate XML database file. The second step is to convert from the intermediate database to a "target" (on the Palm or PC).

All Palm devices synchronized with the same PC share the same intermediate database directory. Make sure that cave names are unique across all Palms being used, or risk data being overwritten in the intermediate XML database.

If two (or more) teams update the data on their Palms, and a single PC is used to synchronize, changes should be beamed from one Palm to the other(s) before synchronizing, or risk the intermediate database and the target survey file being overwritten when the second synchronization is done. A future version of the conduit will handle this situation in a more user-friendly manner.

Unless you have selected "Do Nothing" for the conduit, the conduit will attempt to export every Auriga cave present on your Palm device, overwriting any previously exported data. If you don't want to lose the previously exported data, you may want to make a copy of the resulting file before starting the HotSync process.

The conduit will log its activity to the HotSync log. At this point, any cave whose target software is different from Compass or VisualTopo will fail and the log will reflect that.

Output

Once you have performed a HotSync, you can use Windows Explorer to go to your TargetFiles directory (C:\Program Files\Auriga\TargetFiles if you have accepted the default installation directory.) or to the path you specified in the parameters of the conduit to see the PC file.  You can open Auriga on your Palm to see the file there. 

Advanced users who know their way around XML may choose to look at the data in the intermediate database (in your Auriga\Intermediate directory), although this should normally not be necessary.

You should be aware that in addition to this export being done, whenever you perform a HotSync and the Palm DB has changed since the last HotSync, a copy of the PDB (Palm database) file is kept in the "Backup" directory. (e.g. c:\Palm\YourSyncName\Backup.) If your Palm were to lose its battery power for example, you could easily restore the file from that directory. Most Palm files (not just Auriga) get backed-up this way.

Error messages (HotSync log)

A number of messages get written into the sync log. The name of each cave being synchronized is written into the log, along with it's status (OK or failed.)

Not all errors are yet properly logged into the sync log. In some circumstances, you may get an error number without any explanation. Please report to the author error codes not explained below so that more descriptive messages be given in future versions.

The most common errors include:

Known limitations

Most of these shortcommings will be addressed in an upcoming version of the Auriga Conduit.

Troubleshooting

If you don't see all your data:

The future

Other than the usual bug fix, future versions of this conduit will have features selected from amongst the following:

Please contact the author, Chris Chénier, chenier@alumni.uottawa.ca with any bug report.
(Notice that the author of the conduit is not the same as the author of Auriga. We work closely together, but we are indeed two different persons.)