-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathindex.xml
416 lines (416 loc) · 16.2 KB
/
index.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<meta charset="utf-8" />
<title>divecmd | download and process dive computer data</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Alegreya+Sans:400,400italic,500,700" />
<link rel="stylesheet" href="index.css" />
<script src="slider.js"></script>
<script>
window.addEventListener('load', function() {
new Slider('divecmd2grap-figures', {
controlNext: 'divecmd2grap-next',
controlPrev: 'divecmd2grap-prev'
});
new Slider('divecmd2term-figures', {
controlNext: 'divecmd2term-next',
controlPrev: 'divecmd2term-prev'
});
});
</script>
</head>
<body itemscope="itemscope" itemtype="http://schema.org/SoftwareApplication">
<nav>
<span itemprop="softwareVersion">version @VERSION@</span>
<a href="https://github.com/kristapsdz/divecmd">github</a>,
<a itemprop="downloadURL" href="snapshots/divecmd.tar.gz">source</a>,
<a href="snapshots/">archive</a>
</nav>
<header>
<div class="title">
<h1 itemprop="name">divecmd</h1>
—
<div class="description" itemprop="description">download and process dive computer data</div>
</div>
<div class="cite">
Image from <a href="https://divelog.blue">divelog.blue</a>'s <a href="https://divelog.blue/article079.html">Kittiwake</a>.
</div>
</header>
<article>
<p>
<span class="nm">divecmd</span> is a suite of open source command-line <span
itemprop="operatingSystem">UNIX</span> tools to <span itemprop="applicationCategory">extract and
manipulate dives from dive computers</span>.
Why use it instead of, say, <a href="https://subsurface-divelog.org/">Subsurface</a>?
Because it's built to work in a command-line workflow with other command-line tools for processing, such as
<a href="http://www.lunabase.org/~faber/Vault/software/grap/">grap(1)</a> piped into <a
href="https://www.gnu.org/software/groff/">groff(1)</a> or <a
href="https://www.latex-project.org/">LaTeX</a>.
</p>
<p>
My workflow usually begins with <a href="dcmd.1.html">dcmd(1)</a> on the day of my dive.
First, I extract the dives from my Suunto D6i into an XML file for the day.
<a href="dcmd.1.html">dcmd(1)</a> keeps track of my last extracted dive, so it will only extract new dives
(presumably from the current day):
</p>
<blockquote>
<code>
dcmd d6i > <a href="daily.xml">daily.xml</a>
</code>
</blockquote>
<p>
In reality, I usually archive my dives after each day of diving to prevent me from overrunning the computer's
internal memory and losing dives.
</p>
<blockquote>
<code>
dcmd d6i > daily-`date +%F`.xml
</code>
</blockquote>
<p>
Following that, I'll analyse my dives by plotting them with <a href="dcmd2grap.1.html">dcmd2grap(1)</a> via
<a href="dcmd2pdf.1.html">dcmd2pdf(1)</a>.
In the case of free diving, for example, I might do this:
</p>
<blockquote>
<code>
dcmd2pdf -m summary <a href="daily.xml">daily.xml</a> > <a href="daily.summary.pdf">daily.summary.pdf</a>
</code>
<code>
dcmd2pdf -m restscatter <a href="daily.xml">daily.xml</a> > <a href="daily.restscatter.pdf">daily.restscatter.pdf</a>
</code>
</blockquote>
<p>
These graphs let me see my dive depths and times, and also see whether I'm following the surface-time rule of
thumb, where rest is twice the prior dive.
<strong>Note</strong>: if you're free diving and using a dive computer that lumps all free dives into one huge
dive without splitting them up by surface time, use <a href="dcmdfind.1.html">dcmdfind(1)</a> to
canonicalise the dives. My HW OSTC 2C does this.
Or I'll take a sneak peak only at the day's dives on my terminal:
</p>
<blockquote>
<code>
dcmdfind -ldate=today <a href="daily.xml">daily.xml</a> | dcmdls
</code>
<code>
dcmdfind -ldate=today <a href="daily.xml">daily.xml</a> | dcmdterm
</code>
</blockquote>
<p>
Want to see a full analysis of these dives in PDF?
</p>
<blockquote>
<code>
dcmdfind -ldate=today <a href="daily.xml">daily.xml</a> | dcmd2pdf -a -m all ><a href="daily.all.pdf">daily.pdf</a>
</code>
</blockquote>
<p>
To use <span class="nm">divecmd</span>, you'll need a reasonably up-to-date UNIX system (OpenBSD, Linux, Mac
OSX, etc.).
You'll also need the excellent <a href="http://www.libdivecomputer.org/">libdivecomputer</a>, which does
the heavy lifting to interface with your device.
Just run <code>./configure</code>, <code>sudo make install</code> (or <code>doas</code>).
</p>
<h2>
printable graphs
</h2>
<p>
The <a href="dcmd2grap.1.html">dcmd2grap(1)</a> utility converts from XML into the <a
href="http://www.lunabase.org/~faber/Vault/software/grap/">grap(1)</a> format.
<strong>Aside</strong>: why <a href="http://www.lunabase.org/~faber/Vault/software/grap/">grap(1)</a>? Because
it fits into the standard piped UNIX workflow.
I can send the output directly into <a href="https://www.gnu.org/software/groff/">groff(1)</a> without needing
to manage the intermediary files of <a href="http://www.gnuplot.info/">gnuplot</a> or <a
href="https://www.latex-project.org/">LaTeX</a>.
I use these other tools all of the time, but prefer to avoid them for that reason.
See also <a href="dcmd2pdf.1.html">dcmd2pdf(1)</a>, which manages the groff pipeline.
</p>
<p>
There are a number of graphing modes available to <a href="dcmd2grap.1.html">dcmd2grap(1)</a>.
In all of them, I use <a href="daily.xml">daily.xml</a>, <a href="multiday.xml">multiday.xml</a>, <a
href="day1.xml">day1.xml</a>, and/or <a href="day2.xml">day2.xml</a>, as input.
The graph names (e.g., <q>aggr</q>) are used in the <b>-m</b> argument.
</p>
<nav class="figures">
<a id="divecmd2grap-prev" href="#">Previous</a>
<a id="divecmd2grap-next" href="#">Next</a>
</nav>
<div class="figures" id="divecmd2grap-figures">
<section class="figures">
<div>
<figure id="mode-showcase">
<a class="img" href="short.stack.png"><img src="short.stack.png" alt="" /></a>
<figcaption>
<h4>stack</h4>
<p>
Stacked dives (multiple dives)
split by date with <b>-s</b><i>date</i> and showing ascent and descent
velocities with <b>-d</b>.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-aggr">
<a class="img" href="daily.aggr.png"><img src="daily.aggr.png" alt="" /></a>
<figcaption>
<h4>aggr</h4>
<p>
Line graph connecting (<q>aggregating</q>) subsequent dives with real time (relative to
the beginning of the first dive) on the x-axis and depth on the y-xais.
See <b>stack</b> for how this looks when dive profiles are
super-imposed instead of laid side-by-side.
</p>
<p>
<strong>Note</strong>: this also has a <q>derivative</q> mode for viewing descent and
ascent velocities.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-temp">
<a class="img" href="daily.aggrtemp.png"><img src="daily.aggrtemp.png" alt="" /></a>
<figcaption>
<h4>aggrtemp</h4>
<p>
Also available as <q>stacktemp</q>, for stacked dives.
This shows the temperature recorded by your dive computer, either as an
aggregate or stacked.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-rest">
<a class="img" href="daily.rest.png"><img src="daily.rest.png" alt="" /></a>
<figcaption>
<h4>rest</h4>
<p>
Impulse graph with each dive's rest time (surface interval) on the
positive y-axis and dive time on the negative y-axis.
The recommended rest time (twice the prior dive) is also shown when at least one dive
profile is in free dive mode.
See <b>restscatter</b> for how this looks in a scatter
graph.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-restscatter">
<a class="img" href="daily.restscatter.png"><img src="daily.restscatter.png" alt="" /></a>
<figcaption>
<h4>restscatter</h4>
<p>
Scatter graph with points corresponding to dive time and rest time.
A line with minimum suggested free diving interval is shown (twice the
dive time) if any of the dives are free dives.
See <b>rest</b> for how this looks in an impulse graph.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-multiday-restscatter">
<a class="img" href="multiday.restscatter.png"><img src="multiday.restscatter.png" alt="" /></a>
<figcaption>
<h4>restscatter</h4>
<p>
Same as <b>restscatter</b> but with <b>-s</b><i>date</i> specified.
Here we're looking at two dive dates coloured differently.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-scatter">
<a class="img" href="daily.scatter.png"><img src="daily.scatter.png" alt="" /></a>
<figcaption>
<h4>scatter</h4>
<p>
Scatter graph with points at the intersection of dives' maximum depth
and time.
See <b>summary</b> for how this looks in an impulse graph.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-stack">
<a class="img" href="daily.stack.png"><img src="daily.stack.png" alt="" /></a>
<figcaption>
<h4>stack</h4>
<p>
Default line graph with dives layered over one other, dive time on the
x-axis, depth on the y-axis.
See <b>aggr</b> for how this looks when dive profiles are
laid side-by-side instead of stacked.
</p>
<p>
<strong>Note</strong>: this also has a <q>derivative</q> mode for viewing descent and
ascent velocities.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-multistack">
<a class="img" href="multiday.stack.png"><img src="multiday.stack.png" alt="" /></a>
<figcaption>
<h4>stack</h4>
<p>
Version of stack split (with the <b>-s</b><i>date</i> argument) for
multiple days' diving.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-summary">
<a class="img" href="daily.summary.png"><img src="daily.summary.png" alt="" /></a>
<figcaption>
<h4>summary</h4>
<p>
Each independent dive is shown on the x-axis with the maximum depth and
time above and below, respectively, the y-axis.
See <b>scatter</b> for how this looks in a scatter graph.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-rsummary">
<a class="img" href="multiday.rsummary.png"><img src="multiday.rsummary.png" alt="" /></a>
<figcaption>
<h4>rsummary</h4>
<p>
Like <b>summary</b>, except dives are shown on an x-axis of their start
time relative to the first dive in a grouped sequence.
This example shows two dives sequences split by <b>-s</b><i>date</i>.
</p>
</figcaption>
</figure>
</div>
<div>
<figure id="mode-temp">
<a class="img" href="daily.temp.png"><img src="daily.temp.png" alt="" /></a>
<figcaption>
<h4>temp</h4>
<p>
Each independent dive is shown on the x-axis with the minimum
tepmerature and time above and below, respectively, the y-axis.
This is shown with <b>-a</b> to de-linearise the temperature values so
that they don't cluster.
</p>
</figcaption>
</figure>
</div>
</section>
</div>
<h2>
terminal graphs
</h2>
<p>
The <span class="nm">divecmd</span> suite also has
<a href="dcmdterm.1.html">dcmdterm(1)</a>, which formats graphs on a UNIX terminal.
This is useful for a <q>quick peek</q> at one's dives.
It was the first output mode I wrote, just to test that <a href="dcmd.1.html">dcmd(1)</a> was exporting
reasonable data.
</p>
<p>
<a href="dcmdterm.1.html">dcmdterm(1)</a> doesn't have as many fancy modes as
<a href="dcmd2grap.1.html">dcmd2grap(1)</a>, but it's still a quick and easy way to see one's dives.
Especially when setting up a <a href="https://www.gnu.org/software/groff/">groff(1)</a> pipeline takes too many
characters.
</p>
<nav class="figures">
<a id="divecmd2term-prev" href="#">Previous</a>
<a id="divecmd2term-next" href="#">Next</a>
</nav>
<div class="figures" id="divecmd2term-figures">
<section class="figures">
<div>
<figure>
<a class="img" href="screenshot1.png"><img src="screenshot1.png" alt="" /></a>
<figcaption>
<p>
Screenshot of the terminal mode.
The temperature of a longer dive is shown on the top frame; depth, in the lower frame.
</p>
</figcaption>
</figure>
</div>
<div>
<figure>
<a class="img" href="screenshot2.png"><img src="screenshot2.png" alt="" /></a>
<figcaption>
<p>
Three consecutive free dives in <b>-a</b> mode.
The temperature isn't particular granular with this dive computer…
</p>
</figcaption>
</figure>
</div>
</section>
</div>
<h2>
other utilities
</h2>
<p>
The arguably most-used output mode is also the simplest: <a href="dcmd2json.1.html">dcmd2json(1)</a>,
which converts graphs to JSON. I use it constantly for <a href="https://divelog.blue">divelog.blue</a>,
specifically to show the <a href="https://divelog.blue/article040.html">dive profiles</a>. Technically, I could
simply bundle the native <a href="dcmd.1.html">dcmd(1)</a> output directly and use an XML-to-JSON
formatter in the client, but this is easier.
</p>
<p>
As much as I use <a href="dcmd2grap.1.html">dcmd2grap(1)</a> and friends for my needs, others prefer using
tools like <a href="https://subsurface-divelog.org">Subsurface</a> To do so, one needs to be able to export into
a format used by Subsurface. The <span class="nm">divecmd</span> suite has <a
href="dcmd2csv.1.html">dcmd2csv(1)</a>, which exports a (for the time being minimal) set of
information in CSV format. This can then be imported into Subsurface using the import utility.
</p>
<p>
If you have lots of dive files and want to consolidate, you can use the
<a href="dcmdfind.1.html">dcmdfind(1)</a> utility, which is able to pull together a lot of files,
de-duplicate entries, and print them out again.
Some dive computers, like the HW OSTC 2c, put all free dives into a single dive sequence.
The <a href="dcmdedit.1.html">dcmdedit(1)</a> lets you split those apart for analysis.
(You can also merge them back together with the same tool.)
</p>
<p>
The helpful <a href="dcmdls.1.html">dcmdls(1)</a> tool accepts a set of files, groups them by dive
computer and diver, and lists their contents.
This makes browsing through a lot of dives much easier!
</p>
<p>
For integration with <a href="https://subsurface-divelog.org/">Subsurface</a>, I also provide
<a href="dcmd2ssrf.1.html">dcmd2ssrf(1)</a> and <a href="ssrf2dcmd.1.html">ssrf2dcmd(1)</a>, which convert into
and out of the Subsurface native XML format.
</p>
<h2>
version notes
</h2>
<nav data-sblg-nav="1" data-sblg-navcontent="1">
<section>
<header>${sblg-date}: Version ${sblg-titletext}</header>
<article>${sblg-aside}</article>
</section>
</nav>
</article>
<footer>
<div>
Built with <a href="https://kristaps.bsd.lv/sblg">sblg</a> on <a href="https://www.openbsd.org">OpenBSD</a>.
</div>
<div>
Copyright © 2017–2018,
<a rel="author" itemprop="author" itemscope="itemscope" itemtype="http://schema.org/Person" href="https://github.com/kristapsdz">
<span itemprop="name">Kristaps Dzonsons</span>
</a>
</div>
</footer>
</body>
</html>