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:

• Conduit version (n) is newer than the Auriga file (version m)
  
• Conduit version (n) is older than the Auriga file (version m)
  
  
  • The version of the conduit does not match the cave DB on your Palm: synchronization cannot be performed for this database. This can happen for two reasons:
    
    
    1. your version of Auriga is incompatible with the version of the conduit. Update one (or both) with the newest version.
    2. You have an old copy of a cave database on your Palm. Normally, Auriga should update all cave databases when it is started. Start Auriga on the Palm, and go the Main window (cave DB list), the data migration should automatically take place. If it does not, the database may be corrupted somehow.
  
  
• file needs to be re-organised with Auriga
  • (This message is always followed by: "-- Could not save the local database. Error Code 105"). The integrity of the Auriga file has been broken. You should open it with Auriga and it will be automatically repaired. If this were to fail, you can force reorganization of the file, using Auriga, in the "Cave / Maintenance" menu.
  
  
• Succeeded with errors. For details, see C:\Program Files\Auriga\Log\MyCave.log
  • Open the specified file in any text editor (like Notepad) to see a full list of errors.

Known limitations

• Parsing of depth slope is not handled and will abort parsing when a depth session is encountered. The sample file delivered with Visual Topo (Exemple.tro) includes 2 shots with depth reading; that file will therefore not be completely parsed.
• Parsing in format 4.4, with a separator which is not a standard Auriga separator (such as "_") does not work correctly.
• When parsing large files, the HotSync progress arrows may stop moving, thus giving the impression that the process is halted. It's not. Just wait longer. The speed of execution of the Conduit is mostly determined by the CPU speed of your desktop PC, and by the connection speed and type (USB is faster than serial for example).   If you're parsing a small file, this should not happen.
• Error handling is not as good as it should be: parsing may fail, but the conduit may not report any error, or may parse only part of the file without reporting it.
• Remember that Auriga has an 8-character limit on station names. If you use longer names, they will be truncated and it will result in invalid data.
• The size of imported caves is only limited by the memory in your Handheld, as far as the conduit is concerned. That being said, keep in mind that large systems may not be computable on small and older devices (and they may be slow to compute too).  Caves with 2500 shots seem to work on most devices.  You can get upwards of 10,000 shots on high-end Palms.  That being said, it may be wiser to separate large caves into sections for faster processing and display.
• Surveys with dates before 1970 get set to 1970 (because some functions on PCs don't allow dates before then).
• The sync process seems to go into an infinite loop if you try to syncronize several large caves during a single sync operation. If you're going to sync several caves with a total of tens of thousand shots, it is preferred to do a separate sync for each.

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

Troubleshooting

If you don't see all your data:

• Compass is very permisive as to the file format it accepts. The Auriga Conduit is unfortunately not quite as permisive when reading Compass files. If you're missing data, look at the last Session in the Session list. It's likely that the conduit found something odd in the Compass "survey" which comes right after the last successfully-read survey.
• Remember that Auriga sorts data in an order you may not be accustomed to. Are you sure it's missing?

The future

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

• Export to other cave survey file formats (Walls, Toporobot, etc...)
• Full (two-way) synchronization of data between PC and Palm
• Better error messages in the HotSync log
• A better version of this documentation file

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