DCMD(1)

NAME
dcmd - download dive computer data

SYNOPSIS
dcmd [-v] -s
dcmd [-alnv] [-d device] [-f fingerprint] [-i ident] [-m model] [-r range] computer

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

  Output
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,

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”. An opaque flags value is also exported.

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>

EXIT STATUS

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