One dive, two instruments: how Subsurface keeps both accounts

Imagine returning from a dive with two computers that recorded the same descent. You have one outing to describe, one buddy to name and two instrument records to keep. Subsurface accommodates that distinction: several computer profiles can belong to a single dive, and switching between them leaves the shared notes in place.[1] Its architecture becomes clear when we follow those records from the download cable into the saved logbook.

Subsurface is a free, open-source dive logger for Windows, macOS and Linux.[2] Its origin was a practical compatibility problem. Reporting from Open Source Summit North America in 2022, LWN's Jake Edge described how Linus Torvalds started the project because dive-computer manufacturers gave Linux little attention; Dirk Hohndel subsequently maintained it.[3] That history makes the data boundary worth examining. The software has to understand different instruments while giving the diver a coherent record of an experience.

Close photograph of an iDive DAN dive computer displaying readings during an underwater dive. — An iDive DAN computer during a dive, photographed by Peter Southwood on March 5, 2016.[10] The instrument supplies the physical context for the records discussed here; the photograph is not a Subsurface screen. Wikimedia Commons, CC BY-SA 4.0; resized.

The download is a translation

For supported computer downloads, an important component is libdivecomputer, a separate library that handles communication with instruments from different manufacturers. Its manual distinguishes retrieving dive data from parsing those bytes into typed values. A parser can deliver a sequence containing time, depth, pressure and events, with a time value marking the beginning of a new sample point.[4]

Subsurface's adapter makes that handoff concrete. In the source snapshot examined here, parse_samples() calls dc_parser_samples_foreach(), passing sample_cb as the callback. A DC_SAMPLE_TIME value creates a sample; subsequent depth or temperature values fill it. The adapter also converts units: depth arrives in meters and is stored in millimeters.[5]

This is where a manufacturer's record becomes something the rest of the application can handle. A profile viewer should not need to decode a different byte layout whenever the diver replaces a computer. It needs recognizable measurements attached to a timeline. The adapter supplies that representation, while device communication remains a separate problem.

A dive contains its instruments

The distinction is visible in two small C++ structures. In core/dive.h, the dive object holds notes, buddy and guide names, equipment, a dive-site reference and a collection called dcs. That collection is a std::vector<divecomputer>.[6]

Each divecomputer, defined in core/divecomputer.h, has its own model information, identifiers, timing, samples and events. The instrument record therefore has a home inside the larger dive. Shared context does not have to be copied into every set of sensor readings.[6]

The interface exposes the benefit. The manual describes importing profiles from multiple computers into one dive, then moving between those profiles with the left and right arrow keys. The notes remain shared.[1] For our illustrative diver, the recollection of a strong current can stay with the outing while either computer's profile is examined.

There is a limit to the identity mechanism. Comments in divecomputer.h explain that deviceid and diveid are hashes built from model-specific identifying information; zero means no identifier. They are not a universal serial-number system guaranteed by every instrument.[6] Keeping separate records creates room to inspect provenance, but the quality of that provenance still depends on what the device exposes.

A line between readings is an interpretation

Even a successful import cannot make all sampling schemes equivalent. Libdivecomputer's design note on sampling distinguishes a measurement at a point in time from a value summarizing an interval. An interval might contain several measurements but retain only a minimum, maximum or average. Drawing its stored value as a point changes how a reader sees the timeline.[7]

The note also examines missing surface samples. Adding an artificial endpoint may make a profile look complete while changing its apparent duration. These are representation choices with consequences, even when every downloaded byte has been read correctly.[7]

This helps explain the value of retaining two instrument records. If their traces disagree, there are more questions to ask than which line looks smoother: what was recorded, at what interval, and how was time assigned? Keeping both accounts makes those questions possible. It does not determine which instrument was more accurate.

For a developer, the distinction is useful beyond diving. Converting measurements into common units solves an interface problem. It does not establish that two sensors observed the same thing in the same way.

The separation survives saving

Subsurface's XML writer carries the same structure onto disk. save_one_dive_to_mb() writes the dive-level information and iterates through dive.dcs. For each entry, save_dc() emits a divecomputer element containing its identifying information, events and samples.[8]

The saved object consequently retains more than the curve currently selected on screen. The hierarchy gives another reader of the file a way to distinguish the shared outing from its individual computer records. This is a concrete advantage of an inspectable storage format: the boundary can be checked in the serializer itself.

The user manual identifies Subsurface XML as a native export format and also offers exchanges such as UDDF.[1] A useful preservation check follows from the architecture: reopen a saved copy and confirm that both profiles and the shared notes are present. Counting dives alone would miss the accidental loss of one instrument's account.

Where the boundary ends

The surrounding operating system can still obstruct the route into that file. Subsurface's FAQ explains that infrared support has disappeared from many systems and that the application does not provide its own IrDA stack. An open application cannot, by itself, restore a missing transport layer.[9]

Storage services have another boundary. The FAQ distinguishes the integrated Subsurface Cloud from keeping desktop XML files on a remote storage service. The former is the supported cloud backend; placing a file in another synchronized folder does not reproduce that integration.[9]

These limits sharpen the architectural achievement. Subsurface can let one dive retain several instrument accounts, preserve the diver's shared context and write that distinction into a portable file. The result is a logbook whose structure remains understandable after the equipment changes. For our diver with two computers, the important outcome is simple: one remembered outing, with both records still available to question.

cronfeed.work