download dive computer data
utility downloads recent dives from a
on a serial (or USB)
) and converts them to a regular XML
output format on standard output. The arguments are as follows:
- Ignore the last-seen fingerprint and fetch all dives.
- The hardware device connected to the
- Only show the given device-specific fingerprint, if found.
Implies -a and
-n and disables
- Sets these dives to the diver identified as
ident, which is an opaque string.
- Lists the dives in short format, one per line: time, type,
- When looking up the
computer, use this as the model number.
Sometimes different dive computers share the same product name and need to
be differentiated by model, e.g., the Oceanic OC1.
- Do not set the last-seen dive fingerprint.
- Process only dives within the given date
-a and -n. The
range is in the format of
[start[/end]]. If empty,
shows only the current day. If just the start, shows the full start day.
If the start is empty (and just the range end), shows from the beginning
of time to the end. The start and end format is
- Shows all known device computers instead of trying to
download data. This lists the vendor, then the product. If there are
multiple vendor/product pairs of the same name, the model number is also
printed in parenthesis.
- Increase verbosity. One more, emits informational messages.
Twice, debugging messages. Three times, inundation.
- The case-insensitive full vendor and product, e.g.,
“suunto d6i” or “cressi leonardo”. You can
also just specify the product, e.g., “d6i”, but if there are
multiple vendors with the same product, they may conflict. You may need to
specify a model with -m if there are multiple
vendor/product pairs with the same name.
In the default behaviour (i.e., -s
specified), the dive computer connected to
is opened and its contents downloaded
and formatted as XML.
: many dive computers don't charge when
connected to a computer. Plug it in, suck down your data, and unplug it as
soon as possible.
The last-seen fingerprint is stored in
, where “DEVICE”
is the dive computer device name and diver identifier rendered as a filename,
for example, ~/.divecmd/suunto_d6i-26_kristaps
(vendor, product, model, diver). It is used to get (and/or initialise) and set
the last known dive. This suppresses old dives from being re-downloaded every
is invoked. The
file is a binary fingerprint. The
restrict usage of this file. If ~/.divecmd
not exist, it is created.
outputs an XML file describing the dive. In
this description, attributes offset by brackets (“[” and
“]”) are optional. Optional elements are specifically marked as
such. Values with “xxx” are floating-point, “nnn”
are integral, “ss” are integral seconds, and “uuu”
are unit-interval floating point. All units are metric.
: this format may change as the tool
progresses, my diving progresses, and I acquire more dive computers. If you
want good support, send me diving with a new computer!
The XML output is arranged as follows, with comments inline:
<?xml version="1.0" encoding="UTF-8" ?>
<divelog program="divecmd" version="0.0.1"
vendor="zzzz" product="zzzz" model="nnn"
The values to this element relate to the dive computer hardware, the diver (if
given by -i
) and the software version. Now begins
the dives. There may be multiple dives, which is often the case with
free-diving or any time multiple dives have been exported.
Each dive is numbered in a device-specific way. The time, if supported by the
device, is in local time. The dive time, also if supported, is always shown in
seconds. The mode is one of
(recorded directly from a tank
(open-circuit standard diving), or
A unique, alphanumeric fingerprint for the dive.
<gasmix num="NNN" [o2="xxx" n2="xxx" he="xxx"] />
Gas mixes (in percent) used in this dive (optional element). (Not to be confused
with tanks.) A gas mix should have its mix value, but that's not guaranteed:
it will at least show the mix number. This number may later be referenced in
the samples when switching gases, or by the tanks.
<tank num="nnn" [gasmix="nnn"]
beginpressure="xxx" endpressure="xxx" />
Tanks (optional element). A tank defines the tank parameters itself, including
the referenced gasmix (also if applicable), volume and work pressure, and the
start and end pressure over the course of the dive.
<depth [max="xxx"] [mean="xxx"] />
The depth field (optional). This sets either (or both) the maximum and average
non-zero depth. And now, the samples...
[<rbt value="ss" />]
[<depth value="xxx" />]
[<temp value="xxx" />]
[<pressure value="xxx" tank="nnn" />]
[<deco depth="xxx" type="zzz" duration="ss" />]
[<gaschange mix="nnn" />]
[<event type="event" />]
The sample time is in seconds from the dive start and is always specified. The
remaining optional sub-elements are as follows. Note that sub-elements may be
repeated or have multiple invocations, such as multiple values of
for different tanks.
- Remaining bottom time (“RBT”) (seconds) at
- Vendor-specific information of
type. If the given event consists of no data, it
will simply be a self-closed XML tag. Otherwise, it will consist of rows
of 16 bytes of hexadecimally encoded byte values, e.g.,
“hello” in ASCII being “68656C6C6F”.
- Depth (metres) at sampling time.
- Temperature (Celsius) at sampling time.
- Tank pressure (in bar). References a tank number in the
- Change of gas mixture. This refers to the
mix corresponding to the
<gasmix num="nnn"> in the
<gasmixes> set for the dive.
- A decompression notice. The
attribute may be one of “ndl”, “safetystop”,
“decostop”, or “deepstop”. Duration is in
- A generic event. This may have the
type set to one of “none”,
“decostop”, “rbt”, “ascent”,
“divetime”, “maxdepth”, “olf”,
“po2”, “airtime”, “rgbm”,
“heading”, “tissuelevel”, or
“gaschange2”. No additional information is provided at this
In theory, it's possible for a sample to have no inner elements at all, but in
all cases I've observed, there is at least one. (Usually the
element is specified for all samples,
but of course this isn't guaranteed.)
utility exits 0 on success,
and >0 if an error occurs.
utility was forked by
from the exemplar utility bundled with
, written by