CUCC Expedition Handbook - Your laptop
Setting up an Expo laptop
Operating Systems
- The quickest way to get a complete setup is to use a Debian Linux laptop.
The expo laptop uses Debian with the Cinnamon interface, but pretty much any Linux system works fine. This handbook does assume that you are using apt - the Debian package manager - which is good for all Debian-derived Linuxes such as Ubuntu. Old, slow machines without much memory can be very effective with Xubuntu/xfce.
- Windows machines can do almost everything needed (rsync is a problem), but some useful software has no Windows version and you will need to find your own equivalents. There are also dangerous 'gotchas' to look out for because the file-naming system is different. Do use Linux if you can.
- WSL: the Windows Subsystem for Linux. The first release of this didn't do the ssh key exchange process easily. The 2019 WSL2 release includes a complete Linux kernel. If you want to use this, then please do - and then write the handbook documentation too. But beware that it has two different modes which behave differently.
- Mac users will need to use the Linux documentation as a guide and work it all out for themselves.
- Android phone apps can be invaluable too.
Software
Long-standing Expo policy is to retain absolute control of all software and all data. So we use FOSS software and we store data in text files not in a database. 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:
- git - distributed version control system - already installed on Linux probably
- TortoiseHg - GUI to mercurial (to be deprecated during 2020)
- mercurial - distributed version control system (to be deprecated during 2020)
- Filezilla - ftp GUI software with a configuration file to get to the expo server
- Survex, including the Aven visualisation tool.
- Tunnel: a Java 2.5D cave drawing program surveys based on Survex-compatible data which can also read PocketTopo files. (Generally called 'tunnel' even though the project and executable is actually 'tunnelx'.)
- Therion - Therion processes survey data and generates maps or 3D models of caves.
- TopParser - to convert PocketTopo .top files from a DistoX into Therion.
- QGIS - A Free and Open Source Geographic Information System
- GPSprune - to edit GPS tracks in GPX files. Just download the .jar file.
- Viking - an alternative to GPSprune. The code is on github.
- python, if you are extending troggle or the scripts in expoweb/noinfo/ - already installed on Linux
- python packages you will want to install: [not yet documented]
Nearly all our Austrian surveys have beeen produced using Tunnel but we are moving to Therion for new caves because Therion does elevations properly and Tunnel never will.
For Linux users only:
- GUI for git - There is a choice on Linux but many people just use the command line.
- Your favourite syntax-highlighting code editor. gedit is installed on the expo laptop has syntax highlighting for .svx files too. This works with all GtkSourceView-based editors (thanks to Phil Withnall).
For Windows users only:
- PuTTY including pagent. Version 0.73 was released on 2019-09-29. You need this to generate and to use ssh keys on Windows. Otherwise none of git, mercurial, scp, ftp or rsync will work. It includes command line tools ssh, scp (pscp) and sFTP (psftp).
- Git for Windows
- TortoiseGit - GUI interface to git
- python for windows. We are using python 2.7 not 3.8.
- WinScp can be used as an alternative to Filezilla if you like.
- java - needed for GPSprune. Has to be installed separately on a Windows machine.
- Notepad++ or any other syntax-highlighting code editor for HTML and python such as Aptana Studio. Configuring these to syntax-highlight .svx files has yet to be done.
- Cygwin rsync - not installed as standard on Windows so you need to get Cygwin or use WSL. But getting WSL to work with ssh keys has been tricky and pagent-managed ssh keys are apparently not visible to ssh and rsync in WSL. If you find a good solution for Windows please edit this documentation.
For Android phones:
Logins to external systems
Bug lists and open issues are discussed on the github CaveSurveying/CUCCexposurveyissues/issues issue list so you will need to subscribe to the Cave Surveying Group on github to participate.
github.com/CaveSurveying/CUCCexposurveyissues/wiki/Expo-tunnel-workflows is a wiki on github discussing workflows to generate centerlines, GEOTIFF and QGIS integration.
launchpad.net/survex - the main Survex development system.
Configuration
You need to do the
key exchange procedure - which you can only do entirely on your own if
you have access to the expo laptop to upload and install the public key generated by your laptop. Do this first, Without it none of git, mercurial, scp, ftp or rsync will work.
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.
The above gets TortoiseHg and the command-line PuTTY tools (ssd, sftp, pscp) running, but doesn't get Cygwin rsync working. You might like to try this (untested).
Full illustrated instructions:
When using Windows please, please be excessively careful when naming files and survex names and be exceptionally careful when using rsync.
The handbook has documents where it is necessary to use scp or sftp to manage large files in 'expofiles'. See Experts: Uploading files, Uploading files and Uploading GPS tracks. Only machines which have done the key exchange process can do scp, sftp or rsync.
Learning how to use this software
For Survex, Tunnel and Therion, see the Expo Surveying Handbook.
For installing Survex, Tunnel etc. see this page which will be merged in here eventually.
The Tunnel tutorial - installation notes and a wiki of examples and tutorials
bitbucket.org/goatchurch/tunnelx - documentation and source code in the bitbucket repository system.
Cheat lists and quick reminders
Quick reminders for using mercurial at the command line.
Quick reminders for using rsync and mercurial at the command line.
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.
