NAME

divecomputercommunicate with dive computers

LIBRARY

library “libdivecomputer”

DESCRIPTION

The divecomputer library is a cross-platform and open source library for communication with dive computers from various manufacturers. Systems interfacing with divecomputer must link with -ldivecomputer.
A system wishing to query dives in a dive computer generally follows these steps:
  1. Create a new context with dc_context_new(3). This supplies a parse context: logging, error handling, etc. Override the values 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(3) and searching by name, vendor, or product family.
  3. Open the hardware device to which the dive computer is connected with dc_device_open(3), then invoke 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.
  4. Iterate over all dives with dc_device_foreach(3).
  5. For each iterated dive, create a new parser with dc_parser_new(3) and set the parsed data with dc_parser_set_data(3).
  6. Get attributes of the parsed dive with dc_parser_get_field(3), then 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_buffer_new(3)

AUTHORS

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