devel

devel@libdivecomputer.org

3 participants
290 discussions

Roadmap
by Jef Driesen 16 Dec '11

16 Dec '11

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

1 1

Oceanic ProPlus 2
by Steve Boyd 06 Dec '11

06 Dec '11

I am looking at this package with a view to making a better dive log for the ProPlus 2. In order to be able to do that I need to find some of the information that is not being parsed by the Oceanic parser now. By looking at the raw data for the sample data I have managed to find tissue loading, ascent warning and dive time remaining info. If I can find a couple of nitrox dives in my computer memory I should be able to find the nitrox related info with little trouble. One thing that is eluding me though is the starting and ending tank pressure. I'm assuming it must be in the dive header (since it isn't in the sample data) but I can't seem to find it. I am checking the first 40 bytes of the dive data. Is there someplace else I should be looking? Any help you can give me is appreciated.

2 3

Funny code in universal.c
by Steve Boyd 06 Dec '11

06 Dec '11

I got an error while compiling universal.c with Visual Studio. The compiler didn't like the following line: device_data_t devdata = {0}; in dowork(). I changed it to: device_data_t devdata; memchr(&devdata, 0, sizeof(devdata)); and now everything compiles cleanly. Thought you should know.

2 2

Suspicious code
by Steve Boyd 06 Dec '11

06 Dec '11

When building with Visual Studio I got a warning in zeagle_n2ition3.c. The following code looks a bit suspicious to me. static device_status_t zeagle_n2ition3_init (zeagle_n2ition3_device_t *device) { unsigned char answer[6 + 13] = {0}; unsigned char command[6] = {0x02, 0x01, 0x00, 0x41, 0xBF, 0x03}; command[11] = ~checksum_add_uint8 (command + 3, 8, 0x00) + 1; return zeagle_n2ition3_packet (device, command, sizeof (command), answer, sizeof (answer)); } You are setting command[11] to a value when there are only 6 elements in command.

2 1

Building with MSVC
by Steve Boyd 03 Dec '11

03 Dec '11

I am trying to build with Visual Studio 2010. I am getting the following error in libdivecomputer.rc. Error 1 error RC1015: cannot open include file 'revision.h'. If I comment out that line I then get a bunch of unresolved externals: Error 1 error LNK2001: unresolved external symbol cressi_edy_parser_create Error 2 error LNK2001: unresolved external symbol dc_version Error 3 error LNK2001: unresolved external symbol dc_version_check Error 4 error LNK2001: unresolved external symbol hw_ostc_parser_create Error 5 error LNK2001: unresolved external symbol mares_iconhd_device_open Error 6 error LNK2001: unresolved external symbol mares_iconhd_extract_dives Error 7 error LNK2001: unresolved external symbol mares_iconhd_parser_create Error 8 error LNK2001: unresolved external symbol zeagle_n2ition3_device_open Any help is appreciated.

2 1

Logging support
by Jef Driesen 31 Aug '11

31 Aug '11

Hi, I'm currently polishing the public API to prepare for a first release. Please don't ask for a date, because I won't be able to give one. Anyway, since some of these changes requires breaking backwards compatibility, I want to take this opportunity to reconsider a few other items as well. And one of these things is the logging support. Currently, the libdivecomputer API exposes the message() and message_set_logfile() functions. The first one is a simple printf() style logging function sending its output to stderr, and the second one allows to duplicate the output to a logfile. The main purpose of these functions is to allow non-technical people to easily email the output of the test applications, without having to redirect the output manually to a file. Running a command line application is already difficult enough. Originally, these functions were intended for internal use only. They where never supposed to be part of the public api. Applications are supposed to rely on the status code that are returned. The logfile should be used at most for troubleshooting and diagnostics purposes. The only reason why they are included in the public api today, is because of the test applications. To make the output easier to interpret, the test applications write some additional info (e.g. the name of the functions being called). Since the test applications are no different from other applications, these functions had to be public. But there are a number of potential problems: 1. Thread-safety. The logging functions use a number of global variables without any locking, and are therefore not thread-safe. This is not ideal considered the remainder of the library was designed to be used safely in a multi-threaded application (under a number of conditions). In practice it's not that bad because the global variables used for the logging or not that critical (e.g. timestamps), and most C stdio libraries implementations are thread-safe by default (thus the actual file writing should be fine, and in case two threads want to log at the same time, the output might be interleaved.). I believe the only real solution is either to implement proper locking (which is a heavyweight solution considered we don't require any explicit locking elsewhere in the code) or disable all logging by default. Disabling the logging could be done at build time (e.g. logging in debug builds only) or at runtime (see next item). Note that disabling at runtime wouldn't be truly thread-safe either. 2. Verbosity. By default only errors are logged. However, for troubleshooting this minimal info is almost useless and a much more verbose logfile is required. For this reason, the test applications are using a special patched version of the library, which is not ideal. This could be solved by adding a new function to let the application specify the loglevel (e.g. None, Errors, Warnings, Debug), with a default setting of "None". If anyone has ideas to improve this situation, you're welcome to share them! My personal preference is to allow to disable the logging at build time (e.g. the easiest solution), to avoid the entire thread-safety issues, and build with logging when necessary (e.g. in the single threaded test applications). But on the other hand, it would be great if those verbose diagnostics logs could be generated directly from within the applications, so users are not forced to use the very user unfriendly commandline based test applications. Jef

1 0

Backwards compatibility
by Jef Driesen 20 Jan '11

20 Jan '11

Hi, I try to maintain backwards compatibility as much as possible, especially in the core API (e.g. the non-device specific parts). But once in a while, I have to break backwards compatibility to fix a bug. If that happens, I'll send a reply to this message with further info. In the last couple of days, backwards compatibility has been broken for this function: * cressi_edy_parser_create: An extra "model" parameter was added to be able to tell the difference between the cressi edy and the zeagle n2ition3. Jef

1 0

Parsing header and profile data
by Jef Driesen 13 Jan '11

13 Jan '11

Hi, I have a couple of questions and proposals regarding the parsing of the header and profile data. 1. HEADER DATA Currently, there is no way to retrieve the dive header data (except for the date/time). Usually there is lots of additional information present that might be useful for an application. As usual, the problem is that there is a lot of variation in the information that is stored in this header data. There are only a few fields that are always available (or can be calculated from the sample data): divetime maxdepth avgdepth gasmix {helium, oxygen, nitrogen} Are there any fields missing in this list? The motivation for divetime and maxdepth are obvious, avgdepth is necessary to calculate surface air consumption (SAC), and for every dive you'll have at least one gasmix. I'm aware that this list is quite short, but I think that this will already suffice for the majority of use cases. For example a device independent logbook application is most likely limited to the least common denominator anyway, because it's nearly impossible to support every single piece of information that is present on each device. For the api, I have been experimenting with an ioctl() style api: parser_status_t parser_get_field (parser_t *parser, parser_field_type_t type, unsigned int flags, void *value); which you would use as follows: double maxdepth = 0; unsigned int divetime = 0; unsigned int ngasmix = 0; parser_get_field (parser, FIELD_TYPE_DIVETIME, 0, &divetime); parser_get_field (parser, FIELD_TYPE_MAXDEPTH, 0, &maxdepth); parser_get_field (parser, FIELD_TYPE_GASMIX_COUNT, 0, &ngasmix); for (unsigned int i = 0; i < ngasmix; ++i) { gasmix_t gasmix = {0}; parser_get_field (parser, FIELD_TYPE_GASMIX, i, &gasmix); } It's not the most elegant api, but I haven't found a better one. + Easily extensible to other field types. + Supports fields with multiple values (like the gas mixtures above). - No type safety (void pointer), which means you have to be very careful to use the appropriate data type for each field type. Another option would be to add a separate function for each field (like the current parser_get_datetime function), or a single struct to get all the fields at once. Although that last one may need a few more structs for those fields that can have a variable number of values (gas mixtures). 2. PROFILE DATA There are more or less two categories of sample data, based on how the device obtains the data. The first category, which I believe is also the most important one, is the type of data that a device can measure with one of its sensors. The typical examples are: * Depth * Temperature * Tank pressure * Compass bearing * Heart rate And probably a few we more that we haven't seen yet (for example a rebreather equipped with ppO2 sensors). Since this type of data is always associated with a sensor that measures some physical quantity, there is always a standard format (with a difference in units only). That makes supporting this type of data very straightforward. Of course a dive computer does a little more than measuring some data, and that's where it starts to get tricky. The main difference with the previous category is that this type of data is calculated by the dive computer. Because every device is different, there is also a lot of variation and no standard format. Typical examples are: * Air time remaining * Dive time remaining (or no decompression time if you prefer) * Decompression stops (time and depth) * Oxygen and nitrogen loading * Ascent rate * Alarms * ... I you look at the ascent rate for example, it may seem easy to come up with a standard format, but it's not. There are device that store the ascent rate as a numerical value (e.g. expressed in m/min), or lookup tables with speed ranges, or only warnings when exceeding some limit, etc. In the past, I have tried to support some of these sample types, but it's quite difficult to do that correctly and easily ends up in a mess. Take for example a look at the long list of events. There are many events that have a very similar meaning, but not exactly the same. There are events that also have an equivalent real sample type, and so on. Therefore, I'm considering to keep only some of them (e.g. the more general ones), and leave everything else as a vendor specific binary format. Instead of trying to fit everything into a common format, we could document each vendor format. An applications that wants to use some of this data, will probably need some device specific code anyway. Does that sounds reasonable? The next question is of course which sample type do we want to keep or not? Note that since this data is usually calculated from the measurements in the previous category, it is often possible to recalculate this data manually, although you'll not always get exactly the same results. For example if you implement a decompression algorithm you can recalculate decostops, N2/O2 loadings, etc. Since you can do that also for devices that do not store this kind of information, that could even be considered as an advantage! As usual, all comments and feedback are welcome! Jef

1 1

Migration to sourceforge git
by Jef Driesen 07 May '10

07 May '10

Hi, I have migrated our source repository to sourceforge, and switched from subversion to git. http://sourceforge.net/scm/?type=git&group_id=244020 Jef

1 0

New features
by Jef Driesen 18 Feb '10

18 Feb '10

Hi, I made some important changes to the libdivecomputer api, to support a number of new features. Some of them break backwards compatibility. The remainder of this email is an overview of the changes. I believe we are now reaching a status where all must-have functionality for downloading is available, but maybe not yet in the best possible way. Anyway, the current version is definitely the one you should be using! 1. CLOCK EVENT A new clock event was added to solve the clock synchronization problem for the reefnet and uwatec devices. As soon as the device and system timestamps to adjust the internal clock become available, you'll receive them in this event. 2. FINGERPRINTS In the foreach callback function, not only the dive data but also its fingerprint is provided. You should store the fingerprint (of the most recent dive) somewhere and pass it to the device_set_fingerprint() function during the next download to retrieve only the new dives. You could already do that before, but until now there was no way to get at the fingerprint of each dive. Note: The legacy xxx_device_set_timestamp() functions of the uwatec and reefnet backends are deprecated and might be removed at some time later. 3. CANCELLATION You can now cancel an operation by registering a cancellation callback function. This callback function should return a non-zero value whenever the active operaton should be cancelled, and zero when it should continue. A backend can invoke this callback function to query the application for a pending cancellation request. Note that there is NO guarantee that the operation will actually be cancelled. Not all backends support safe cancellation, and those that do may not always notice a cancellation request in time. 4. OTHER The Uwatec Smart backend breaks backwards compatibility by removing the uwatec_smart_device_handshake and uwatec_smart_device_version functions. The first one is done automatically during initialization and the second one is replaced with the device_version function. The format of the version data has changed too (the content remains the same, but the order of the fields has changed into: model number, serial number, timestamp). But you shouldn't need this info anymore because the same info is delivered in the devinfo and clock events. For systems without IrDA support (e.g. Mac OS X), a dummy IrDa backend is used, which will always return an error at runtime. The universal example application was update to use the new features. One of the major additions is that it can now also parse the downloaded dives and export them into a very simple xml file. You may find it useful for testing. Jef

1 0

Jump to page:

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

devel