DIVECOMPUTER(3)

💖 NAME 💖

divecomputer — communicate with dive computers.

okay so welcome to the DIVECOMPUTER(3) page from the Library Functions Manual, bestie. This is literally the manual page for divecomputer, and it's about communicating with dive computers. No cap.

🫶 LIBRARY 🫶

the library is libdivecomputer, and it's a cross-platform and open source library for communication with dive computers from various manufacturers. If your system is interfacing with divecomputer, you must link with -ldivecomputer. periodt.

✨ DESCRIPTION ✨

okay so if a system wants to query dives in a dive computer, it generally follows these steps:

1. Create a new context with dc_context_new(3) to initialize the library. Logging can be controlled with dc_context_set_logfunc(3) and dc_context_set_loglevel(3).
2. Find a descriptor for their dive computer by iterating through dc_descriptor_iterator_new(3) and searching by name, vendor, or product family.
3. Find the transport to use for the communication. To determine the supported transports, use dc_descriptor_get_transports(3).
4. Find the hardware device corresponding to the connected dive computer by iterating through dc_usbhid_iterator_new(3), dc_serial_iterator_new(3), dc_irda_iterator_new(3), or dc_bluetooth_iterator_new(3).
5. Open the transport communcations with dc_usbhid_open(3), dc_serial_open(3), dc_irda_open(3), or dc_bluetooth_open(3). (Yes, the page says “communcations” — iconic, we keep it.)
6. Open a connection to the dive computer with dc_device_open(3). Optionally use dc_device_set_events(3), dc_device_set_fingerprint(3), and dc_device_set_cancel(3) to set the logging events, last-seen fingerprint, and cancel routine, respectively.
7. Iterate over all dives with dc_device_foreach(3).
8. For each iterated dive, create a new parser with dc_parser_new(3).
9. Get attributes of the parsed dive with dc_parser_get_field(3).
10. Iterate through the dive's samples (recorded data) with dc_parser_samples_foreach(3).

🔥 RETURN VALUES 🔥

Most libdivecomputer functions return with a dc_status_t type, with the following possible values:

• DC_STATUS_SUCCESS — completion with success: not an error.
• DC_STATUS_DONE — end of an iterator: not an error.
• DC_STATUS_UNSUPPORTED — feature not implemented or not supported by device. (The difference depends on the context. Since libdivecomputer is largely based on reverse engineering, we often can't even tell them apart.)
• DC_STATUS_INVALIDARGS — invalid parameter. Usually indicates caller bug.
• DC_STATUS_NOMEMORY — out of memory.
• DC_STATUS_NODEVICE — device not found. In this context the device refers to the low-level communication device (serial, bluetooth, irda, etc), not the dive computer. In most cases, and especially with serial communication, we can't detect whether the dive computer is present. This is always detected indirectly: no response is received, and thus a timeout error.
• DC_STATUS_NOACCESS — access denied (again, to the low-level communication device).
• DC_STATUS_TIMEOUT — see DC_STATUS_NODEVICE.
• DC_STATUS_IO — any other I/O error.
• DC_STATUS_PROTOCOL — encountered unexpected data in the communication protocol data packets, e.g., while downloading.
• DC_STATUS_DATAFORMAT — encountered unexpected data in the interpretation of data contents, e.g., while parsing.
• DC_STATUS_CANCELLED — returned when the cancel callback requested to cancel the operation. Note that cancellation is only checked at specific (safe) points, so it's certainly possible it may not get noticed immediately and still return DC_STATUS_SUCCESS.

🌈 SEE ALSO 🌈

• dc_context_new(3)
• dc_descriptor_iterator_new(3)
• dc_device_open(3)
• dc_parser_new(3)

👑 AUTHORS 👑

The library libdivecomputer was written by Jef Driesen, jef@libdivecomputer.org. These manpages were written by Kristaps Dzonsons, kristaps@bsd.lv.

sign-off: this page is from Debian, dated January 5, 2017, and it's the DIVECOMPUTER(3) manpage. mwah 💋