200

Firmware update for OBD2-Analyser NG. OBD2 software for OBD2-Analyser NG with Bluetooth module running on PC and Raspberry Pi with Bluetooth adapter.

This project improves the firmware of the OBD2-Analyser NG project published in the September 2009 issue of the Elektor magazine. If your OBD2-Analyser NG is equipped with the optional Bluetooth module published in the April 2010 issue of the Elektor magazine, you even do not need to flash the new firmware to try it out! Just use the OBD2-Analyser NG test software that has the new firmware built-in as OBD2 software. In that case you can view more data items or menu items at once, since the test software's display height is 64 simulated pixels (instead of the 32 pixels of the original LCD). The OBD2 software might work with other DXM based OBD2 testers, like the Wireless OBD2 project published in the April 2011 issue of the Elektor magazine, too.
Additionally, the test software can be used as OBD2-Analyser NG emulator. By using the emulator you can enter all menus and view all OBD2 services and all OBD2 data items that the OBD2-Analyser NG firmware has implemented. That is much more than you would see in a real vehicle.
Furthermore, the test software contains a DXM-simulator that provides changeable OBD2 data for the emulator or third party OBD2 software.
Currently, the software runs on PC and Raspberry Pi. To use the OBD2 software with your OBD2-Analyser NG, you need a PC or Raspberry Pi with Bluetooth adapter.

1. Firmware

Compared to the original firmware v1.2.1 the following main features have been implemented:
  • support for 8 OBD2 capable ECUs
  • pending DTCs, OBD2 service 0x07
  • permanent DTCs, OBD2 service 0x0A
  • support for numerous additional PIDs of OBD2 services 0x01 and 0x02 (these are displayed in current data menu and freeze frame data menu, if a vehicle supports them)
  • evaluation and display of location of oxygen sensors, OBD2 service 0x01 and 0x02, PID 0x13 or 0x1D (this affects displayed bank/oxygen sensor indices of some PIDs)
  • evaluation of tester configuration bytes, OBD2 service 0x01 and 0x02, PID 0x4F and PID 0x50 (this affects displayed maximum values and resolution of some PIDs)
  • Inspection/Maintenance Readiness Code / OBD2 monitor status since DTCs cleared, OBD2 service 0x01, PID 0x01
  • OBD2 monitor status of the current driving cycle, OBD2 service 0x01, PID 0x41
  • ECU name, OBD2 service 0x09, infotype 0x0A
  • in-use performance tracking counters for spark ignition engines and compression ignition engines prior MY2010, OBD2 service 0x09, infotype 0x08
  • in-use performance tracking counters for compression ignition engines for MY2010 and beyond, OBD2 service 0x09, infotype 0x0B
  • dynamic supported PIDs for OBD2 service 0x02 (each DTC that caused freeze frame storage can have its own supported PIDs)
  • CAN error retry handling (I highly recommend updating if you have troubles with vehicles that use CAN busses. Frequent or even permanent 'no data' messages will no longer occur.)

Check the updates for details and more features.

2. HHEmu - The OBD2-Analyser NG Test Software

HHEmu stands for Handheld Open Emulator, since the primary objective was to develop a PC test environment (emulator, sandbox) for the firmware. However, the software supports different operation modes providing much more than a mere emulator. It can be used as emulator containing a built-in DXM-simulator as OBD2 data source. It can be used as stand-alone DXM-simulator. It can be used as OBD2 software using the GUI of the firmware. And finally, two HHEmus, one runnning as DXM-simulator and one running as OBD2 software, can be connected via a (virtual) serial connection.

HHEmu is a multi-threaded application with 5-7 threads. It executes the firmware in a separate thread and simulates all inputs (key presses, timer interrupt, data from DXM module, data from optional Bluetooth module) and outputs (LCD, data to DXM module, data to optional Bluetooth module) to make the firmware believe it would run on the AT90CAN128.

Since HHEmu version 2.50 you can view more data items or menu items than in a real OBD2-Analyser NG. Now, HHEmu's display height is 64 simulated pixels (instead of the 32 pixels of the original LCD). That allows to display 8 menu lines at once.

The HHEmu program contains DXM OpenHandheld source code v1.2.1, (c) 2009 DIAMEX, written by Erwin Reuss, ER-Tronik. DIAMEX restricts the usage of the source code to non-commercial use. Therefore, HHEmu is subject to the same restrictions.

2.1 OBD2-Analyser NG Emulator

HHEmu in emulator mode enables you to enter all menus and to test all OBD2 features of the OBD2-Analyser NG with the latest firmware update on a PC or Raspberry Pi. That is much more than you would see in a real vehicle that just supports a subset of all OBD2 features. HHEmu comes with a built-in DXM-simulator that provides changeable OBD2 data for the emulator. See the command summary in chapter 2.5.4 for a list of commands accepted by the DXM-simulator.

2.2 OBD2 Software

In OBD2 software mode HHEmu connects either to a real OBD2-Analyser NG equipped with the Bluetooth module (normal user mode) or to a second HHEmu running in DXM-simulator mode (developer mode (a virtual serial port software like com0com can be used for that)).

So, that mode provides an interesting feature for users who have an OBD2-Analyser NG with the optional Bluetooth module: new firmware can be tested in the car with no need for flashing the firmware! Run HHEmu with the built-in new firmware and via Bluetooth connect to a real OBD2-Analyser NG with at least firmware v1.2.1. Then you see on the PC, how the new firmware would run on the OBD2-Analyser NG.

The OBD2 software might work with other DXM based OBD2 testers, too. That depends on the availability of some DXM commands that are undocumented in the official DXM documentation, but are used by the latest official firmware v1.2.1 and therefore, are used by the latest firmware update, too.

2.3 DXM-Simulator

The DXM-simulator can be used to develop your own OBD2 software.

Warning
Do not run HHEmu in DXM-simulator mode unattended if you run it on an overclocked PC or notebook!
If the Bluetooth Menu is entered in the DXM-simulator mode, HHEmu enters a busy-wait-loop. That is running at full speed on a PC consuming all CPU cycles of a single core, so the CPU will become hot.

In the DXM-simulator mode HHEmu connects either to a second HHEmu running in OBD2 software mode or a third party OBD PC software (a virtual serial port software like com0com can be used for that).
tested with:
  • moDiag 2.8.601 (DXM)
  • moDiagUltimate 4.0.1.0 (DXM)
  • CarPort 2.2.15 (DXM)
  • ScanTool.net v1.2.1 (ELM/STN, 1 ECU only, non-CAN protocols only) Since PWM is the default responding protocol, nothing needs to be configured for the responding protocol, but one ECU and responding controller ELM or STN must be set. To do that, type "1e1u" or "1e2u" while the HHEmu window is active.

See the command summary in chapter 2.5.4 for a list of commands accepted by the DXM-simulator.

2.4 HHEmu Installation

Unpack the hhemu_usr_xxx.zip archive of the latest project update to whatever path you want.

2.4.1 HHEmu Installation on PC

Unpack the gtk_xxx_runtime_libs.zip archive(s) of the latest project update to \hhemu_usr\gtk or install mingw32 GTK3+ V3.6.4 or higher.

2.4.2 HHEmu Installation on Raspberry Pi

Install GTK3+.

That is enough for the emulator mode.

The Raspberry Pi OBD2 software mode additionally needs the following steps. Of which some steps can be omitted if a Raspberry Pi 3 with built-in Bluetooth is used. I have tested HHEmu on a Raspberry Pi 2.
 
Plug in a Bluetooth/USB adapter.
Install Bluetooth.
Set the Bluetooth adapter to always visible.
Pair the adapter with the Bluetooth module of the OBD2-Analyser NG and trust it.
Configure a free rfcomm device like /dev/rfcomm0.
Bind the address of the OBD2-Analyser NG's Bluetooth module to the rfcomm device.

2.5 Usage

Change to the path where you have installed hhemu.exe (e.g. D:\hhemu_usr\gtk) and in the console type:

hhemu --help

HHEmu can be controlled via the mouse by clicking the OBD2-Analyser NG buttons if the background picture HHOpenBackgroundPic.png that shows the 4 OBD2-Analyser NG buttons is found on program startup. Additionally, HHEmu can be controlled via the cursor keys or the h,j,k,l-keys that are mapped to the Up/Down/Ok/ESC-buttons. See the command summary in chapter 2.5.4 for a list of additional keys and their meaning.

2.5.1 Emulator Usage

Change to the path where you have installed hhemu.exe (e.g. D:\hhemu_usr\gtk) and in the console type:

hhemu

Or double click hhemu.exe.

2.5.2 OBD2 Software Usage

Change to the path where you have installed hhemu.exe (e.g. D:\hhemu_usr\gtk) and in the console type:

PC: hhemu COMx

x is the number of the COM-port used by the Bluetooth adapter on your PC to communicate with the OBD2-Analyser NG. In the current implementation x must be less than 10.

Pi: ./hhemu /dev/rfcommx

x is the number you configured for the rfcomm device.

2.5.3 DXM-Simulator Usage

Change to the path where you have installed hhemu.exe (e.g. D:\hhemu_usr\gtk) and in the console type:

hhemu COMx sim

Replace x with the actual (virtual) serial port of your installation. However, port number must be less than 10.
Then enter the Bluetooth menu.
The DXM-simulator is ready now to accept AT commands or OBD requests from a HHEmu running in OBD2 software mode, third party OBD2 software or a terminal program.

2.5.4 HHEmu Command Summary

In OBD2-Analyser NG emulator mode or DXM-simulator mode keys 0-9 can be used to store an up to 2-digit number in the number memory. The number from the number memory will be used for subsequent commands that need a number as parameter.
Possible commands are:
a - set number of permanent DTCs (CAN-protocols only) for the active ECU, 0-16
b - set number of cylinder banks for PID 0x13, 1-2 (***)
c - set number of cylinder banks for PID 0x1D, 1-4 (***)
d - set number of confirmed DTCs for the active ECU, 0-16
e - set number of responding ECUs, 1-8
m - enable MIL in DXM simulation (also sets one confirmed DTC for the active ECU, if none is active, yet)
n - toggle visibility of number memory
p - set number of pending DTCs for the active ECU, 0-16
t - set responding protocol in DXM-simulator or emulator: PWM (1), VPWM (2), ISO 9141-2 (3), KWP2000 5 Baud Init (4), KWP2000 Fast Init (5), CAN 11/500 (6), CAN 29/500 (7), CAN 11/250 (8) and CAN 29/250 (9)
u - set diagnostic interface controller: DXM (0), ELM (1) or STN (2)
v - toggle between fixed current data and IPT data (default) or variable current data and IPT data
x - set negative response code for SID 0x04 (clear DTCs) or SID 0x09, InfoType 0x06 (CVN) either for the active ECU or, if no ECU filter in the current menu is active, for all ECUs.
    Possible codes are 10, 11, 12, 21, 22, 78 (value is interpreted as hex). Same code given twice toggles negative response code on/off. If 00 is given, negative response codes are switched off.
y - set No DATA response for next response from DXM
z - set CAN ERROR response for next response from DXM (CAN-protocols only)
q - quit HHEmu

(***) - The standard ISO 15031-5 requires that all ECUs in a vehicle that support the location of oxygen sensors support either PID 0x13 or PID 0x1D, but not both. If you select setting the number of cylinder banks for PID 0x13, the supported PID 0x1D will be cleared automatically for you for all ECUs and vice versa.

Note that for some of the commands to take effect, the Reload OBD2 Data menu item must be executed in the emulator. Further note that some commands only affect the currently active ECU. So, they might have to be entered several times with a change of ECU in between.

2.6 Supported HHEmu Versions

cygwin ncurses
cygwin/X11 ncurses
cygwin/X11 GTK3+ (tested with GTK+ V3.6.4)
mingw32 PDcurses
mingw32 GTK3+ (tested with GTK+ V3.6.1 and V3.6.4)
Raspbian ncurses
Raspbian GTK3+ (tested with GTK+ V3.14.5)

2.7 Released HHEmu Versions

mingw32 GTK3+
Raspbian GTK3+

Other versions are available on request.

Notes:
GTK3+ for Windows is now available with MSYS2. Since that does no longer support XP and Vista and I do not want to drop support of XP, yet, I will not do an update of GTK3+ soon. However, since I also release the object files and the makefile with every release, you should be able to link the object files with newer GTK3+ libraries for yourself.

Using GTK3+ V3.7.x or higher brings support for Broadway. Broadway enables a GTK+ application, like HHEmu, to be run in the Firefox browser. Since the browser can be run on a different machine than the application, you can remotely control the OBD2 Analyser NG via the internet, then. So, a remote mechanic could take a look on live-data of your car. I have tried that with the experimental GTK+3.8.2 package from here http://www.tarnyko.net/en/?q=node/34 and it worked fine.

3. Description of (old) Files in the Attachments Section

Check the latest project update to download the latest version of the firmware and the latest version of HHEmu. The project main page just contains the old files for HHEmu V2.10 and firmware V1.3.0 (containing also the mingw PDcurses version). I keep them here as long as I do not make a new release with full source code.

HandheldOpen_130.zip contains the firmware update v1.3.0 including the new hex file needed for flashing the AT90CAN128. Directory structure and files are almost identical to the old firmware release v1.2.1. File ChangeLog.txt contains a list of changes (despite the filename German only).

The firmware update to version 1.3.0 contains one new feature, several bug fixes and a few changes mainly needed for the emulator. The new feature is support for OBD2 service 0x07 ("Pending Diagnostic Trouble Codes"). Pending trouble codes are failures detected in the current or last completed driving cycle that have not been confirmed in a second driving cycle, yet. Therefore, OBD2 service 0x03 ("Confirmed Diagnostic Trouble Codes") would still be showing an error free car. Service 0x07 helps you to see coming problems earlier. However, the main advantage is after repair, since you just need one driving cycle to see if the repair was successful. The base for the firmware update is the original version 1.2.1. That is the one with Bluetooth support, but you do not need to have the Bluetooth extension installed to use it in your OBD2-Analyser NG.

hhemu_usr.zip contains the HHEmu mingw32/PDcurses executable and the mingw32/GTK3+ executable. Both need additional shared libraries to run. File HHEmu_.txt contains a list of these libraries and the links where to download them (later updates have the runtime libs included in separate archive(s)).

hhemu_dev.zip contains the HHEmu source code with documentation in the code (English only).

hhemu_doc_preview.zip contains a preview of the full HHemu/OBD2-Analyser NG documentation covering installation aspects, emulator usage and emulator internals (German only). Most notably, it contains 2 block diagrammes showing the interaction between the different threads in the GTK+ and curses versions of HHEmu. Furthermore, the preview contains a description of all OBD2-Analyser NG menus/displays that have been changed due to the new feature OBD2 service 0x07 (Pending Diagnostic Trouble Codes).

Warning for HHEmu prior V2.32
Do not run HHEmu unattended if you run it on an overclocked PC or notebook! The emulation is an application that steals many CPU cycles, so the CPU will become hot. The main reason for that is the main-loop of the firmware that is a busy-wait-loop running at full speed on a PC consuming all CPU cycles of a single core. The hhemu_usr.zip archive contains a curses/patched folder and a gtk/patched folder with special versions of HHEmu. In these versions a short pause has been inserted into the busy-wait-loop of the firmware that reduces the strain inflicted on the CPU core significantly.

Warning for HHEmu V2.32 and beyond
See description under chapter 2.3 DXM-Simulator above.