Being able to synchronize the dive computer clock with the host system
is a very useful feature. Add the infrastructure to support this feature
through the public api.
The vendor_product_parser_create() and vendor_product_device_open()
functions should be called indirectly, through the generic
dc_device_open() and dc_parser_new() functions. And the
vendor_product_extract_dives() functions are internal functions that
should never have been part of the public api in the first place.
The current algorithm always downloads a full memory dump, and extracts
the dives afterwards. For the typical scenario where only a few dives
are being downloaded, this is inefficient because most of the data isn't
needed. This can easily be avoided by downloading the data on the fly.
The low level serial and IrDA functions are modified to:
- Use the libdivecomputer namespace prefix.
- Return a more detailed status code instead of the zero on success and
negative on error return value. This will allow to return more
fine-grained error codes.
- The read and write functions have an additional output parameter to
return the actual number of bytes transferred. Since these functions
are not atomic, some data might still be transferred successfully if
an error occurs.
The dive computer backends are updated to use the new api.
Both the allocation and initialization of the object data structure is
now moved to a single function. The corresponding deallocation function
is intended to free objects that have been allocated, but are not fully
initialized yet. The public cleanup function shouldn't be used in such
case, because it may try to release resources that haven't been
initialized yet.
Instead of freeing the object data structure in the backend specific
cleanup function, the memory is now freed automatically in the base
class function. This reduces the amount of boilerplate code in the
backends. Backends that don't allocate any additional resources, do no
longer require a cleanup function at all.
When the close function returns, all resources should be freed,
regardless of whether an error has occured or not. The error code is
purely informative.
However, in order to return the first error code, which is usually the
most interesting one, the current implementation is unnecessary
complicated. If an error occurs, there is no need to exit immediately.
Simply store the error code unless there is already a previous one, and
then continue.
If the dive computer has not recorded any dives yet, the profile pointer
isn't valid and contains the default value 0xFFFFFFFF. There is no need
to return an error in this case.
The Mares Smart Apnea uses a different data format than the regular
Smart, because it records not only a summary of each freedive in the
session, but also a full depth profile.
Because both the regular Smart and the Smart Apnea have the same model
number (0x10), another way to distinguish the two variants is needed.
Therefore, the Smart Apnea gets a modified model number, with one of the
higher bit set. The actual type is detected from the contents of the
version packet.
The new Smart Apnea is also capable of recording multiple samples per
second (e.g. 2, 4 or 8). But since our smallest unit of time is one
second, we can't represent this, and the extra samples will get dropped
for now.
We received data from a Mares Smart where the existing heuristics to
detect the last dive are not sufficient. The very last check, where the
calculated and stored are compared results in a fatal error.
The Mares Smart supports not only scuba diving, but also freediving.
Because the freedive data format is fundamentally different from the
regular dives, being able to detect the type of dive in advance is very
important. For that reason, Mares moved the 4 bytes containing the dive
mode and number of samples from the beginning of the header to the end.
Except for this 4 byte shift, there are no changes for regular dives.
For the freedives, there is no real profile available, only a summary of
the entire freedive session. In an attempt to workaround this
limitation, we generate a pseudo profile in exactly the same (but ugly)
way as is done in the Mares Nemo backend.
The Mares Nemo Wide 2 appears to have a slightly larger profile
ringbuffer, which extends to the end of the internal memory. It remains
to be seen whether this is also true for some of the other models. The
Mares Matrix is currently the only model where this is definitely not
the case.
The switch from downloading the entire data with a single large packet
to multiple smaller 256 byte packets, resulted in a considerable
performance regression. In one particular case, the difference was a
factor 6.7 slower!
I performed a small tests (using an Icon HD Net Ready) with 256, 1024
and 4096 byte packets, and the total time was respectively 21.0, 11.3
and 6.5 seconds. For a single large packet, the total time is only 5.9
seconds. Thus the difference with a 4096 byte packet is negligible.
The model number stored in the main memory isn't always the most
reliable source of information, because there are devices where the
model number has not been filled in properly. Instead, we check the
product name in the version packet against the list with valid names,
and return the corresponding model number.
As an additional advantage, we no longer depend on the model number
supplied by the application for selecting the correct memory layout.
Nevertheless, the model parameter is kept for backwards compatibility.
The recommended packet size is 256 bytes, which matches the maximal
amount of data that can be read back from the internal memory chip.
Larger requests are split by the firmware into multiple blocks of
maximum 256 bytes.
Note that initially, we already used 256 byte packets for the newer
models, but it seems this was accidentally changed to only 64 bytes in
commit ad0e187c0c932121efa50763afc02771633cbd61.
The main benefit of this change is a simplification of the code, because
now there is no longer a difference between the Icon HD and Matrix
variant of the protocol.
The Mares Icon HD use a processor with integrated USB circuit, which
presents itself to the host system as a CDC-ACM device. Since there is
no external usb-serial chip involved, the baudrate and other serial
line parameters are irrelevant. By choosing the same settings as the
later models, which do use an usb-serial chip, we can completely avoid
the problem of unresponsive devices due to using the wrong baudrate.
The profile ringbuffer appears to be slightly smaller than expected for
some models. For the Mares Matrix (and all compatible devices) it ends
earlier, while for the Icon HD Net Ready it starts later.
This bug resulted in missing dives, because all remaining dives were
getting dropped once a dive that crossed the ringbuffer boundary was
reached.
This dive computer has the same enclosure as the Mares Puck, but the
wire protocol is that of the Puck Pro. The original software identifies
it as a "Mares Puck 2", and the handshake string also contains the
sequence "PUCK 2", so this string is used to identify the device.
The Mares Matrix, Puck Pro and Nemo Wide 2 have only 256K of memory,
which is 4 times less compared to the Icon HD. However for some unknown
reason, trying to download 1024K succeeds, and these devices just
repeat the same data 4 times. That's why we never noticed the
difference in memory capacity before.
A side effect is that the mares_iconhd_extract_dives function now
requires a valid device handle. This shouldn't cause any real problems
because this function will likely become private some day.
Currently, each backend has it's own function to verify whether the
object vtable pointer is the expected one. All these functions can be
removed in favor of a single isintance function in the base class,
which takes the expected vtable pointer as a parameter.
Functions which are called through the vtable, don't need to verify the
vtable pointer, and those checks are removed.
The term "backend" can be confusing because it can refer to both the
virtual function table and the device/parser backends. The use of the
term "vtable" avoids this.
Apparantly there are also two different type of serial numbers present,
and their interpretation depends on the application. The Windows Dive
Organizer application shows both a serial number (byte offset 0x04) and
a warranty number (byte offset 0x0C). However, the Mac OS X Divers'
Diary application shows the number at byte offset 0x0C as the serial
number. Very confusing. For now, we just stick to the number at byte
offset 0x0C, because that's the number that is shown by the device
itself.
The Matrix uses the same communication protocol as the Nemo Wide 2,
except that the sending the request packets with just a single write
operation doesn't seem to work. That's very surprising because it
caused no problems for the Nemo Wide 2 or the Icon HD!
The first two bytes of each request packet are probably some kind of
command type. These two bytes are answerred immediately with an ACK
byte (0xAA). Once this ACK byte has been received, the payload of the
command (if any) can be sent, and finally the response packet can be
received.
I suspect that when trying to send the entire command at once, the
device somehow doesn't receive the payload bytes correctly. Maybe it's
still busy processing those first two bytes, which causes the remainder
of the packet to get dropped? That might explain why the version
commands is not affected, because it doesn't have any payload bytes!
The new vendor event provides a mechanism to deliver auxiliary data,
which is automatically retrieved during the data transfer, but not
accessible through the library interface otherwise. Possible examples
include handshake data and/or device identification data.
This event is mainly intended for diagnostic purposes, in combination
with the memory dumping support. Very few applications will actually
need it for anything else.
The Nemo Wide 2 uses the same communication protocol as the Icon HD,
except for two differences:
The Nemo Wide 2 requires a different baudrate and parity setting.
Unfortunately it doesn't seem possible to autodetect the correct
protocol variant at runtime. Attempting to proceed with incorrect
settings will render the device unresponsive and requires a battery
reset to recover.Therefore the model code needs to be provided as an
extra parameter, when opening the connection.
The Nemo Wide 2 also appears to have trouble downloading the entire
memory with a single request. Therefore the single large request is
split into many smaller ones. The offical Mares application uses 256
byte packets, and so do we. The Icon HD keeps using the large packets
because they are significant faster.
The extra model parameter breaks backwards compatibility!
The version function requires device specific knowledge to use it (at
least the required buffer size), it is already called internally when
necessary, and only a few backends support it. Thus there is no good
reason to keep it in the high-level public api.
These macros are used internally and don't need to be exposed. In some
cases, the actual values are not even constant, but dependant on the
model and/or the firmware version.
I forgot to update the device and parser initialization functions to
store the context pointer into the objects. As a result, the internal
context pointers were always NULL.
The public api is changed to require a context object for all
operations. Because other library objects store the context pointer
internally, only the constructor functions need an explicit context
object as a parameter.
Adding the "dc_" namespace prefix (which is of course an abbreviation
for libdivecomputer) should avoid conflicts with other libraries. For
the time being, only the high-level device and parser layers are
changed.
The public header files are moved to a new subdirectory, to separate
the definition of the public interface from the actual implementation.
Using an identical directory layout as the final installation has the
advantage that the example code can be build outside the project tree
without any modifications to the #include statements.
It looks like the Icon HD erases old dives partially with 0xFF bytes
before overwriting them with new dives. If the head of the oldest dive
has been erased, the length field which is stored in the first 4 bytes
is erased as well, and we can use it to detect the last dive.
The linux USB CDC-ACM driver, which is used by the Mares Icon HD
interface, doesn't support the ioctl's to configure a custom baudrate.
But since the actual baudrate doesn't seem to matter at all, we revert
back to the nearest standard baudrate.
Because custom baudrates are confirmed to be supported on Windows and
Mac OS X, those platforms can keep using the non-standard baudrate.
