CUCC Expedition Handbook - Your laptop

Cave survey software - beyond the basics

Phones and laptops

Your Android phone

Everyone has a phone pretty much, and everyone should have GPS enabled for safety. See the expo GPS configuration pages.

There are several cave survey apps which run on a phone. We don't yet have a well documented way of using these with the expo survey data workflow.

You can also use a phone to upload files and manage version control on the server. This is not the place to start, but if you are already doing this on your own laptop then these can be useful:

Your laptop

You will already have configured your laptop to do all the basic stuff using the basic Expo laptop guide.

This is an attempt at a complete set of optional software for using survex, tunnel, therion, photos and GPS tracks to document our caves: using the existing data archive and processing new survey data.

If you want to do software development instead, go to configuring a troggle development machine.

This page documents what else you might find useful if the basic laptop setup does not do what you need.

Windows, Macs, Chromebooks and Linux

Software

Long-standing Expo policy is to use open tools and protocols so we can retain control of our own data over the long term. And not to require expo-goers to sign up to external services or spend money on software. So we use FOSS software. You can use other software on your own machine if it is format-compatible and exports data in the formats we want, but all the recommended software here is open source (and please don't install proprietary software on the 'expo laptop').

The list of software:

Nearly all our Austrian surveys have beeen produced using Tunnel (or were hand-drawn) but many smaller caves and some areas of SMKsystem are done with Therion because Therion does elevations and Tunnel doesn't. Expo has a policy decision on which to use: if it is an entirely new disconnected cave, then use Therion. If it is a passage in a cave where previously we used Tunnel, then use Tunnel. See also Comparison of Tunnel to Other Cave Software.

For Linux users only:

Note that on a Debian/Ubuntu machine you should normally install the versions that come with the distro (i.e. install using 'apt install xxx', not be downloading things from the above sites. So installing everything you need should be as simple as:

For Windows users only:

None of this works until you set up the key-pair setup using PuTty/Pageant.

Visual Studio Code editor

If you use VS Code here are some relevant extras. Not really for beginners but here are instructions for configuring it for python. On Windows you run VS Code as a Windows app but it communicates directly ("remotely") with the WSL Linux environment.

You will definitely want the "Git History" extension and probably the "GitLens" extension too.

It is entirely feasible (and on a slow machine, recommended) to use VS Code only for git management, and using a faster Windows-native editor, such as Notepad++, for actually editing code and text.

Configuration

You will already have configured your machine as a 'basic laptop'. If you have not yet done this, do that now, before continuing with these instructions.

If you are using a Windows machine, go and skim read the Windows advanced configuration section before you actually start any of this simpler stuff.

Idiots guide to setting up git for expo - PDF - Brendan's guide. Uses PuTTy and GitKraken.

You need to register a key with the expo server to get upload (i.e. read/write) access. Do this first, Without it none of git, scp, ftp or rsync will work. You can do this entirely on your own if you have access to the expo laptop to upload and install the public key generated by your laptop.

On a Windows machine you will need to configure pageant (the putty authentication agent) to run at startup to load your key. Note that you are loading your private key, the .ppk file, into pageant and that this key never leaves your laptop.

Full illustrated instructions:

The above gets the command-line PuTTY tools (ssd, sftp, pscp) running, but doesn't get rsync working. You might like to try this (untested).

When using Windows please, please be excessively careful when naming files and survex names and be exceptionally careful when using rsync.

Learning how to use this software


Cheat lists and quick reminders

Logins to external systems

#expo - public. An open-access open-access IRC channel (ephemeral, not archived) for real-time discussions about everything but mostly software people. If you are having trouble using the software try here first.

Some expo survey stuff is tracked externally:

Complementary tools

When maintaining the HTML files in the expo handbook a link-checker is useful to report bad URLs (links to external sites go bad regularly) and to find orphaned pages with no in-links. The website has about 2,000 internal URLs in just the Tunnel wiki section alone.