dcmd
—
download dive computer data
dcmd |
[ -alnv ]
[-d
device ]
[-f
fingerprint ]
[-i
ident ]
[-m
model ]
[-r
range ]
computer |
The
dcmd
utility downloads recent dives from
a dive
computer on a serial (or USB)
device (defaulting to
/dev/ttyU0) and converts them to a regular
XML output format on standard output. The arguments are as follows:
-
-
-a
- Ignore the last-seen fingerprint and fetch all dives.
-
-
-d
device
- The hardware device connected to the
computer.
-
-
-f
fingerprint
- Only show the given device-specific fingerprint, if found. Implies
-a
and
-n
and disables
-r
.
-
-
-i
ident
- Sets these dives to the diver identified as
ident, which is an opaque string.
-
-
-l
- Lists the dives in short format, one per line: time, type, and
fingerprint.
-
-
-m
model
- 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.
-
-
-n
- Do not set the last-seen dive fingerprint.
-
-
-r
range
- Process only dives within the given date
range. Implies
-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
YYYY-MM-DD[THH:MM:SS]
.
-
-
-s
- 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.
-
-
-v
- Increase verbosity. One more, emits informational messages. Twice,
debugging messages. Three times, inundation.
-
-
- computer
- 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
was not
specified), the dive computer connected to
device is opened and its contents downloaded
and formatted as XML.
Be careful: 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
~/.divecmd/DEVICE, 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 time
dcmd
is invoked. The
DEVICE file is a binary fingerprint. The
-a
and
-n
flags restrict usage of this file. If
~/.divecmd does not exist, it is created.
dcmd
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.
Note: 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="dcmd" version="0.0.1"
vendor="zzzz" product="zzzz" model="nnn"
[diver="zzzz"]>
<dives>
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.
<dive number="n"
[date="yyyy-mm-dd" time="hh:mm:ss"]
[duration="ss"] [mode="YYYY"]>
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
freedive
(obviously
free-diving),
gauge
(recorded directly from a tank
gauge),
opencircuit
(open-circuit standard diving), or
closedcircuit
(closed-circuit rebreathing).
<fingerprint>xxx-yyy-zzz</fingerprint>
A unique, alphanumeric fingerprint for the dive.
<gasmixes>
<gasmix num="NNN" [o2="xxx"] [n2="xxx"] [he="xxx"] />
</gasmixes>
Gas mixes used in this dive. Values are percents (0–100). This is only if
the dive profile features gases. (Not to be confused with tanks.) This number
may later be referenced in the samples when switching gases, or by the tanks.
<tanks>
<tank num="nnn" [gasmix="nnn"]
[volume="xxx" [workpressure="xxx"]]
beginpressure="xxx" endpressure="xxx" />
</tanks>
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. Dive samples may reference
unspecified tanks. If so, the tank is assumed to have all default values.
<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...
<samples>
<sample time="ss">
[<rbt value="ss" />]
[<vendor type="nnn">[value]</vendor>]
[<depth value="xxx" />]
[<temp value="xxx" />]
[<pressure value="xxx" tank="nnn" />]
[<deco [depth="xxx"] type="zzz" [duration="ss"] />]
[<gaschange mix="nnn" />]
[<cns value="xxx" />]
[<event type="event" [duration="ss"] [flags="ss"] />]
</sample>
</samples>
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
pressure
for different tanks.
-
-
rbt
- Remaining bottom time (“RBT”) (seconds) at sampling
time.
-
-
vendor
- 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
- Depth (metres) at sampling time.
-
-
temp
- Temperature (Celsius) at sampling time.
-
-
pressure
- Tank pressure (in bar). References a tank number in the
<tanks>
section. If there is no
<tanks>
section, the referenced tank
consists only of default values, e.g.,
<tanks><tank num="NNN"
/></tanks>
.
-
-
gaschange
- Change of gas mixture. This refers to the
mix
corresponding to the <gasmix
num="nnn">
in the
<gasmixes>
set for the dive. For historical
reasons, the identifier of the gas mixture is one
less than the <gasmix>
number.
-
-
cns
- CNS oxygen toxicity fraction in the unit interval.
-
-
deco
- A decompression notice. The
type
attribute may be
one of “ndl”, for non-decompression limit time remaining;
“safetystop”; “decostop”; or
“deepstop”. Duration is in seconds. Decompression notices
are suppressed when in freediving mode. The “ndl” type
ignores the depth attribute, if specified. All types may omit the
duration
and depth
, in
which case this is simply an indicator of state. While in a deco or deep
stop, the type
of deco (or deep) will be
continuously emitted for each sample. The end of the stop may be inferred
by a “ndl” or “safetystop”, or simply by the
non-existence of the prior deco type.
-
-
event
- A generic event. This should usually be ignored, as it uses opaque values
from libdivecomputer(3). This may have the
type
set to one of “none”,
“decostop”, “rbt”, “ascent”,
“ceiling”, “workload”,
“transmitter”, “violation”,
“bookmark”, “surface”,
“safetystop”, “gaschange”,
“safetystop_voluntary”,
“safetystop_mandatory”, “deepstop”,
“ceiling_safetystop”, “floor”,
“divetime”, “maxdepth”, “olf”,
“po2”, “airtime”, “rgbm”,
“heading”, “tissuelevel”, or
“gaschange2”.
The flags
may optionally be set to “1”
or “2”, meaning that the condition has begun or ended,
respectively. The exception to this is “gaschange2”, which
optionally sets flags
to the new mixture (starting
at zero).
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
<depth>
element is specified for all samples,
but of course this isn't guaranteed.)
</dive>
</dives>
</divelog>
The
dcmd
utility exits 0 on success,
and >0 if an error occurs.
The
dcmd
utility was forked by
Kristaps Dzonsons,
kristaps@bsd.lv,
from the exemplar utility bundled with
libdivecomputer(3), written by
Jef Driesen
jef@libdivecomputer.org.