Roadmap

Hi,

I'm planning a major cleanup of the public api before making a first official release. Because some of those changes require breaking backwards compatibility, I'm going to take this opportunity to introduce many changes that have been on my todo list for a long while, but have been postponed forever to avoid breaking backwards compatibility as much as possible.

The remainder of this (long) email is an overview of the planned changes. There are a couple of questions as well.

1. Decide on a version scheme

The current plan is to use a typical major.minor.micro scheme. The infrastructure to support this scheme is already in place for a long time, but it's just not being used.

The main question is then how to increment these numbers? Either based on features or binary compatibility? I have a personal preference for the last method. It might also be a good idea to be able to distinguish between release and development versions. For example using a "-dev" suffix.

Worth reading: http://apr.apache.org/versioning.html

2. Separate public and private headers

All public header files are moved to the include/libdivecomputer subdirectory. The main benefit is that the example applications can use the recommended include style (e.g. #include <libdivecomputer/header.h>), regardless of whether they are build inside the build tree, or standalone. And as a bonus, it becomes very clear which header is considered public or private.

3. Improved error codes

The device and parser error codes will be merged to a single set. At the same time a few extra error codes are introduced:

* DC_STATUS_SUCCESS /* Success */ * DC_STATUS_UNSUPPORTED /* Unsupported operation */ * DC_STATUS_INVALIDARGS /* Invalid arguments */ * DC_STATUS_NOMEMORY /* Out of memory */ * DC_STATUS_NODEVICE /* Device not found */ * DC_STATUS_NOACCESS /* Access denied */ * DC_STATUS_IO /* Input/output error */ * DC_STATUS_TIMEOUT /* Timeout */ * DC_STATUS_PROTOCOL /* Protocol error */ * DC_STATUS_DATAFORMAT /* Data format error */ * DC_STATUS_CANCELLED /* Operation cancelled */

These are roughly identical to the current error codes, with a few modifications. The old TYPE_MISMATCH code is changed into the more general INVALIDARGS. The old ERROR is changed into the new DATAFORMAT or INVALIDARGS, depending on the context. The NODEVICE and NOACCESS codes have been added to return more fine grained error information when opening a connection to the low-level hardware (e.g. serial/irda/usb). Note that these two new error codes are not intended to report the status of the communication with the actual dive computer!

Are there any error codes missing?

4. Namespacing the public api

All public API (functions, structs, enums, etc) should be prefixed with "dc_" (which is short for libdivecomputer of course) to reduce the chances of conflicts with other libraries.

In recent additions this prefix is already used (e.g. dc_datetime_t and dc_buffer_t), but in older code it needs to be added. Note that this will break backwards compatibility everywhere!

5. Improved naming consistency

In a few places the naming of the typedef's is inconsistent. For example there is a callback named device_event_callback_t and dive_callback_t (missing "device" in its name), an enum named device_type_t and device_event_t (missing "type" in its name).

I intend to introduce a more consistent naming scheme:

dc_event_type_t; /* An enum listing all possible types. */ dc_event_progress_t; /* A struct corresponding to one specific type. */ dc_event_devinfo_t; dc_event_clock_t; dc_event_callback_t; /* A callback function. */

Related to this issue is the question whether the callback function should return the object pointer for which it is called or not (e.g. the this or self pointer)? Currently the event callback has this pointer (because you need this pointer for the fingerprint feature), while all others don't. I want to make this consistent by either adding it to all callbacks or removing it. Technically, you can always pass the object pointer by means of the userdata parameter, but it can be convenient to have it for free (at the expense of needing an extra parameter in the callback function signature).

Does anyone have a particular preference regarding adding/removing this object pointer?

6. Cleanup the parser api

The parser api needs some major improvement.

The biggest issue here is that the parser_sample_value_t union is passed by value in the sample callback. This means we can't introduce new sample types in the future without breaking backwards compatibility (because extending the union may change its size). This can be avoided by breaking the union into individual structs and pass them by reference with a pointer. This is similar to the current event callback, so it will improve consistency too.

The downside is the application will have to cast the pointer to the correct data type manually. It might be possible to keep the union (but still passed as a pointer of course), to eliminate the need for a manual cast, but this might not be entirely portable. I'll need to investigate this further.

Another concern are the sample events. Currently we have a large list with all possible event types supported by the many dive computers. But this starts to become a big mess because the data associated with each type varies greatly between different dive computers, so it's nearly impossible to map this into a single data structure. Therefore, I propose the remove the event sample type, and use the vendor type for this purpose. Then we can just document the format and pass the complete data to the application.

Note that in a later stage, we can always add back the more general purpose events (e.g. gas switches, etc), but then with an appropriate data structure for each event and not the single catch-all data structure we have now. This will need further discussion.

7. Re-order structures to eliminate padding

A few structures have unnecessary padding bytes inserted by the compiler due to alignment requirements (e.g. device_clock_t). These useless padding bytes can easily eliminated by re-ordering the fields in the structure. This breaks backwards compatibility, but since some of the other changes will break compatibility anyway, it's a good opportunity to get rid of the padding too.

8. Drop deprecated functionality

There are a few functions that have a better alternative, and can be removed.

For example the *_set_timestamp() functions in the reefnet and uwatec backends can be replaced with the more general device_set_fingerprint() function. You can still use an integer timestamp with the correct serialization to the binary fingerprint.

Another candidate for removal are the *_set_maxretries() functions. I think it's better to just handle this completely internally. In the end, the backend should know best how many attempts should be made to retry a failed command.

The device_version() function is also obsolete. All backends that have a mandatory version/handshake sequence during the communication perform this already internally. Only when you need the data returned by these commands for some reason, you can call the function explicitly. But although this functions looks device independent, it is not because you need to know the buffer length in advance. And then we could equally well turn it into a backend specific function. In cases such as the sensusultra handshake, where you wouldn't be able to call the function at any time, there is already a backend specific function to retrieve the cached handshake packet. We could even go one step further and introduce a special vendor event to pass the raw version/handshake packet to the application.

Would this cause trouble for anyone?

9. Improved tools

I plan to create a new "dctool" commandline application that is more flexible than the current universal application. the idea is to have a tool supports a number of actions:

dctool [<options>] action [<args>]

Planned actions are dump, dives, parse, extract, read and write. The major difference with the universal application is that the new tool will only perform a single action, but the output can be piped to the next action. This will require defining a common data format to pass the data through the pipe.

Note that this isn't a high priority item because it doesn't have any impact on the public api, and hence can be completed later on.

10. Stable numbers for the backend types (and merging device and parser)

To maintain backwards compatibility, the existing enum values shouldn't change when new backends are added. To achieve this, and at the same time keep backends from the same manufacturer grouped together, I propose to introduce two numbers to identify each backend: one for the vendor, and one for the device itself. This is similar to the USB VID/PID numbers. Both the VID and PID numbers can then be encoded into a single 16 or 32-bit number to make up the enum value.

Additionally, I would like to merge both the device_type_t and parser_type_t enums into a single enum. Right now every device backend has a corresponding parser backend (with a few exception where a parser can be shared by several device backends), and there is no good reason to keep just a single enum. I'm still looking for a good name for the new enum.

11. Return dc_buffer_t pointer instead of integer

I plan to make all dc_buffer_*() functions return the dc_buffer_t pointer to indicate success or failure, instead of an integer. These functions can only fail due to out-of-memory errors, so returning NULL makes more sense, and additionally it allows to chain calls.

12. Units: hydrostatic vs density

A few backends (e.g reefnet, cobalt, ostc) store the depth values (d) as pressure values (P). This makes a lot of sense considered the fact that a depth sensor is actually a pressure sensor. But it also means a conversion is necessary, and that requires knowledge of the atmospheric pressure (Patm) and the water density (rho):

P = rho * g * d + Patm

or if you prefer:

d = (P - Patm) / rho * g

Since those values are not always provided by the device (atmospheric pressure can be measured, but water density can't and is thus typically a user configurable setting or simply unknown), the calibration constants have to be provided by the user.

Note that this conversion has no influence on the decompression calculations, because those are done with the pressure values. The conversion to depths is strictly for displaying to humans, who prefer to see depths :-)

The use of the atmospheric pressure is straightforward, but for the water density their are many possibilities (density, salinity ratio, etc). In the current implementation a "hydrostatic" value is used, which is nothing more than the multiplication of the density with the standard gravity (and thus is equivalent to the pressure of 1m of seawater). The mean reason why this was chosen is simplicity in the implementation, and the nice correspondence with the simplified formula used by divers in the field:

PRESSURE(bar) = DEPTH(m) / 10 + 1 PRESSURE(atm) = DEPTH(ft) / 33 + 1

by defining the parameters (see units.h for the constants) as:

atmospheric = BAR hydrostatic = MSW

However I'm not convinced the use of this "hydrostatic" parameter is very intuitive, compared to using the more well-known density value. Using the density directly would basically hide the gravity constant from the public api. Do you have any preference towards using hydrostatic vs density?

Note that you can still obtain the same results as with the simplified formula, by defining the parameters as:

atmospheric = BAR density = MSW / GRAVITY ~= 1019.7 kg/m^3

The math for imperial units is similar, resulting in these parameters:

atmospheric = ATM hydrostatic = FSW / FEET density = (FSW / FEET) / GRAVITY ~= 1027.2 kg/m^3

13. Documentation

I should take some time to write proper documentation (e.g. doxygen or something similar). But since my time is pretty limited, this has the lowest priority.

That's it for now. Feedback is welcome as usual.

Jef