------------
libcomm14cux
https://github.com/colinbourassa/libcomm14cux

Download latest release:
https://github.com/colinbourassa/libcomm14cux/releases/latest

Discussion:
https://groups.google.com/forum/#!forum/rovergauge
------------

libcomm14cux is a cross-platform library that is capable of communicating with
the Lucas 14CUX ECU via its diagnostic serial port. The library itself has no
user-interface and requires a front-end application to display data. Included
with this code is a simple command-line utility (named "read14cux") which uses
the library to read and display bytes from the 14CUX's memory.

The RoverGauge project provides a graphical front-end to this library. Special
hardware is required to match the ECU's signaling scheme; the hardware is beyond
the scope of this document and detailed in the README for RoverGauge project:

https://github.com/colinbourassa/rovergauge

To assist in the development of other front-ends, the source archive can be
used to generate HTML documentation of the API. This is done by running Doxygen
on the provided doxygen.conf file (in the src/ directory.)

Comments, questions, bug reports, and bugfixes should be directed to
colin.bourassa@gmail.com. Please include the version number of the library in
any correspondence.

-------
License
-------
libcomm14cux is licensed under the GPL v3. See the file "LICENSE" for details.

----------
Disclaimer
----------
While this software has been shown to be reliable and is provided in good
faith, it is provided with ABSOLUTELY NO WARRANTY.

---------
Changelog
---------
2.1.1: Switched to a lookup table for coolant and fuel temperature sensors.
       This should yield slightly more accurate results.
2.1.0: Modified getFuelMap() routine to also return the row scaler value for
       the specified map
2.0.2: Updated release URLs in README
2.0.1: Added better support for cross-compiling to Windows using MXE
2.0.0: Added support for nonstandard baud rates (i.e. other than 7812.5 bps)
       Added preliminary support for AC compressor and heated screen status
1.2.0: Added function to retrieve final fueling value
       Added sanity checking for several readings
       Changed functions that retrieve fuel map row/col to return weighting
       Changed function signature for getRoadSpeed to use a smaller type
       Fixed Unix/Linux bug that resulted in reads failing if one of the
        command bytes was CR or NL
       Changed algorithm to detect new vs. old data offsets
1.1.0: Fixed bug with left/right bank confusion
       Modified getTuneRevision() to also return Ident byte and checksum fixer
       Added function to retrieve MAF CO trim voltage
1.0.0: Converted the interface from C++ to pure C
0.5.5: Updated serial port setup for better cross-platform compatibility
       Added code for compatibility with Mac OS X >= 10.6
0.5.4: Added functions to retrieve the idle-mode status and MIL status;
       also miscellaneous cleanup
0.5.3: Fixed polarity of short-term lambda trim; it was previously reversed
0.5.2: Added switchable absolute/corrected throttle position readings
0.5.1: Support for old revision of ECU (fixing main voltage calculation)
0.5.0: Added more fault codes, as well as fault code numbers
       Added switchable short/long term lambda fuel trim
       Added switchable linearized/direct MAF readings
0.4.4: Improved main voltage reading accuracy further
       Improved throttle pot position accuracy
0.4.2: Added function to retrieve lambda fuel trim
       Improved main voltage reading accuracy
0.4.1: Added functions to control the fuel pump and the idle air control valve
       Added function to get target idle speed
0.3.2: Added function to get fuel pump relay state and function to clear
       fault codes
0.3.1: Cleanup of Doxygen comments
0.3.0: Changed MAF reading call to return a percentage rather than raw value
       Added support for fuel map 0
       Improved efficiency of consecutive read commands to nearby addresses
       Added support for cancelling long read operations
0.2.0: Added routines for retrieving a number of specific values, such as
        engine RPM, coolant and fuel temperatures, and road speed.
0.1.1: Cleanup of Doxygen comments
0.1.0: Initial version

-------------
Compatibility
-------------
libcomm14cux has been tested with the following operating systems at some
point in its history:

* Linux (Ubuntu 13.10, i386 / AMD64)
* OpenBSD 5.2 (AMD64)
* FreeBSD 9.0 (AMD64)
* Windows XP
* Windows 7
* Macintosh OS X 10.6

Note that installation packages are not available for some of the OSs listed
above, but it is possible to build from source for those platforms.

---------------
Using read14cux
---------------
The libcomm14cux library must be visible to the read14cux executable for it to
run. (In Windows, the most straightforward way to do this is to ensure that the
DLL and read14cux.exe are in the same directory.)

The read14cux utility reads a specified number of bytes from a specified memory
location in the ECU, and will either display those bytes at the console (16
bytes per line), or, if an output filename is given, write the bytes to a file.

The read14cux command line parameters are as follows:

  read14cux <serial-device> [-b baud-rate] <address> <length> [output-file]

  serial-device:
    The name of the serial port device, which is probably an FTDI USB converter.
    In recent Linux distributions, it's probably "/dev/ttyUSB0". In Windows,
    it's a COM port (such as "COM2") -- the specific COM port can be found by
    locating the serial device in the Windows Device Manager.

  baud-rate:
    Optional parameter, prefixed with '-b' if present. Sets the baud rate used
    when communicating with the ECU. This is only useful if your ECU is running
    customized firmware that supports a higher baud rate.

  address:
    Memory address at which to start reading data. This should be specified in
    hex (using the "0x" prefix, as in "0xC000".)

  length:
    Number of bytes to read.

  output-file:
    Optional. If given, the file to which the bytes will be written (rather than
    to the console.)

------------------------------------------
Issues with writing to memory in the 14CUX
------------------------------------------
Write operations are of limited usefulness; fuel maps cannot be changed in this
way because they are read from the ROM, and sensor readings are continually
updated by the ECU (meaning that any change to the memory location of a sensor
value would almost immediately be overwritten.)

Care should be taken when writing memory while the engine is running; it's
possible to affect the operation of the fuel pump or idle-control stepper motor
in this way.

----------------------------------------------------
Notes for those developing frontends to libcomm14cux
----------------------------------------------------
Because Windows still uses legacy DOS names for certain devices (such as COM
ports), there are restrictions on how such devices may be manipulated by code.
In order to open COM ports beyond COM9, Windows I/O calls (such as CreateFile())
require use of the prefix "\\.\" on the device name, as in "\\.\COM10". (Also
note that the backslashes must be properly escaped where appropriate.)

(EOF)