[ Home ] [ Download @Sourceforge ] [ Documentation ]
[ Source code @github [primary] ]

This manual applies to freediag version 1.08 and following.

Table of contents:

• OBDII Introduction
• Scantool Introduction
• 1) Building the scantool
• 2) Running Scantool
• 3) Using the Command Line Interface (CLI)
• 4) Commands
• 5) Hardware Interfaces

In the Mid 1990's the US introduced mandated diagnostics on all vehicles sold in the USA for certain emissions related information. The idea behind this is that cars would monitor for emissions related problems and when they occur to light a "Check Engine" lamp on the dashboard and log fault information that could be then read by a Scantool. Scantools would become cheap and available to the smallest of vehicle repairers. These diagnostic protocols were grouped under the term "OBD II".

Europe has recently introduced similar, compatible systems, which are known as EOBD (European OBD).

OBDII/EOBD requires a standardised physical connector to be present within a small distance of the vehicle’s steering wheel. OBDII allows 3 types of physical interface (ISO9141/14230, SAEJ1850 VPW and SAEJ1850-PWM) and the related software protocols that are used with those physical interfaces.

This manual assumes that you have some knowledge of vehicle systems and have probably used a scantool before.

This Scantool uses SAEJ1979 (ODB II) protocol on ISO9141, ISO14230, SAEJ1850 VPW and SAEJ1850-PWM interfaces depending on what hardware interface is attached to the PC. The scantool does not yet support any manufacturer specific protocols for talking to non OBDII vehicles.

It is configured by default to use a generic (dumb) serial to ISO9141 converter such as those used on the VAG-COM software, It also supports smart interfaces from Multiplex Engineering and from B.Roadman for SAEJ1850 vehicles (mainly Ford and GM). Support for ELMxxx devices is being added but should be considered inexistant as of early 2014.

Support for CANbus (ISO 15765) is incomplete and unusable.

Please refer to Supported Interfaces to determine which protocols are supported by each interface type.

Refer to most up-to-date instructions in doc/build_system.txt

Under Linux / unix variants, the scantool should not be run as superuser / root, for obvious security reasons. A regular user account should be sufficient, provided you setup the udev rules (or equivalent) to give access to the relevant hardware.

Start the Scantool CLI by running "./freediag", you will get a command prompt:

freediag>

The scantool will read commands from a startup file called .freediagrc in your home directory or freediag.ini in the program directory, depending on options set at compile time.

Many people will put the appropriate set interface <type> command (see section 4) in their .freediagrc file and will just want to use the scan, and the cleardtc commands.

The CLI is hierarchical, with normal commands at the top level. Some commands include:

scan : start a scan
monitor : loop repeatedly checking/displaying ECU values
set : access set submenu to modify settings
exit : exit scantool

Please refer to the complete list in the next section.

2nd level commands, such as commands to set the address used by the scantool, can be accessed as:

set testerid <value>

or by entering the set menu:

set

and then using the testerid command

testerid <value>

Note the cli prompt will change from

freediag>

to

freediag/set>

To leave a submenu and return to the main menu, type:

up

All numeric values can be entered as:

123	decimal 123
$27	hexadecimal 27
0x27	hexadecimal 27
012	octal 012

The help (or simply ?)command is available at every menu and gives you help for the commands available at that menu. Further information about a specific command can be obtained by typing help <command>.

The CLI supports shell like command line editing if supported by your OS.

The following commands are available. Other commands may be visible from the CLI but are not supported

Main Menu
scan	Does an OBDII Scan for all parameters
monitor [english/metric]	Loops requesting/displaying OBD - Mode 1/2/7 results
cleardtc	Clear stored Diagnostic Trouble Codes
dumpdata	Show received data for mode 1/2 tests
pids	Show supported PIDS/TESTs for mode 1/2/5/6/9
source <filename>	Read commands from <filename>
log [logfile]	Basic data logging to logfile specified
stoplog	Stops logging
watch [raw]	Watch the K line bus and attempt to decode data
test	SUBMENU, see later, perform various tests - mostly performed in scan process
set	SUBMENU, see later, set parameters for diagnostic functions
diag	SUBMENU, see later, extended diagnostic functions
debug	SUBMENU, see later, access some debugging facilities
help [command]	Help
quit	Quit/Exit
Test Sub-Menu
rvi	Do OBD Mode 9 requests for vehicle info (vin etc)
cms	Request/Display continuously monitored system results
ncms	Request/Display non continuously monitored system results [more verbose than in scan]
readiness	Do readiness tests [more verbose than in scan]
Set Sub-Menu
show	Show all "setable" values. Note : some L0 drivers add specific configurable items, see Supported Interfaces
interface [NAME]	Shows/Sets the interface type. Use set interface ? to get a list of names
display [english/metric]	Sets english or metric display
speed [speed]	Shows/Sets the speed to connect to the ECU (separate from the Host-to-interface speed when using a smart L0 interface)
testerid [testerid]	Shows/Sets the source ID for us to use
destaddr [destaddr]	Shows/Sets the destination ID to connect
addrtype [func/phys]	Shows/Sets the address type to use
l1protocol [protocolname]	Shows/Sets the hardware protocol to use. Use set l1protocol ? to get a list of protocols
l2protocol [protocolname]	Shows/Sets the software protocol to use. Use set l2protocol ? to get a list of protocols
initmode [modename]	Shows/Sets the initialisation mode to use. Use set initmode ? to get a list of protocols
Diag Sub-Menu
connect	Connect to an ECU, but do not run any tests. Uses the protocol/speed etc set, i.e does not try multiple protocols.
disconnect	Breaks connection with the ECU.
sendreq [data]	Send data on the bus using the active L2 or L3 (if available) connection.
sr	Same
read [timeout]	Read data from the bus, timeout after timeout seconds
rx	Same
addl3 [protocol]	Add an L3 layer on the current L2 connection.
reml3	Remove an active L3 layer, leaving the L2 connection intact.
probe start_addr [stop_addr]	Scan bus using ISO9141 5 baud (slow) init, using the global testerid and speed. Stops at the first succesful connection.
fastprobe start_addr [stop_addr [func]]	Scan bus using ISO14230 fast init with physical or functional addressing, using the global testerid and speed. Stops at the first succesful connection.
Debug Sub-Menu
show	Show debug levels
l0 [val]	Show/set layer 0 debug value
l1 [val]	Show/set layer 1 debug value
l2 [val]	Show/set layer 2 debug value
l3 [val]	Show/set layer 3 debug value
cli [val]	Show/set layer cli debug value
all [val]	Show/set debug values for all the layers
l0test [testnum]	Run low-level L0 tests with DUMBT driver. This is exclusively for debugging electrical interfaces ,by sending raw test signals on TXD, RTS and DTR. Use "l0test" without arguments to get a list of available tests. See also doc/dumb_interfaces.txt
[val]	Available debug levels (combine by adding values) : DIAG_DEBUG_OPEN 0x01 /* Open events */ DIAG_DEBUG_CLOSE 0x02 /* Close events */ DIAG_DEBUG_READ 0x04 /* Read events */ DIAG_DEBUG_WRITE 0x08 /* Write events */ DIAG_DEBUG_IOCTL 0x10 /* Ioctl stuff (setspeed etc) */ DIAG_DEBUG_PROTO 0x20 /* Other protocol stuff */ DIAG_DEBUG_INIT 0x40 /* Initialisation stuff */ DIAG_DEBUG_DATA 0x80 /* Dump data depending on other flags */ DIAG_DEBUG_TIMER 0x100 /* Timer stuff */
Dyno Sub-Menu
mass [mass]	Set the mass of the vehicle, including driver and passengers
loss	Dynamically determine power lost by aerodynamic and friction forces (follow the instructions)
setloss [d] [f]	Manually enter aerodynamic and friction forces parameters
run	Run dyno (follow the instructions)
result	Display run results
graph	Display run graphs
save [filename]	Save run measures and results to a file

Please refer to the Supported Interfaces document to determine which hardware interface is appropriate for your usage and which version of the interface you should purchase.

In order to use the appropriate driver for your hardware interface, the appropriate set interface [name] command needs to be run. The default interface driver is the dumb driver which works with most generic serial to ISO9141 interfaces. It is recommended that you put this command in your .freediagrc file.

Generic serial adaptors (opto-isolated or not):
set interface dumb

Andy Whittaker's OBD-II ISO9141 interface:
http://www.andywhittaker.com/ecu/obdii_hardware.htm
set interface dumb

Jeff's OBD-II ISO 9141 interface:
http://www.planetfall.com/~jeff/obdii
set interface dumb

Silicon Engines ISO 9141 interface:
http://www.siliconengines.net/
set interface dumb

B.Roadman ISO9141/VPW/PWM interface:
http://obddiagnostics.com/
set interface br1

Multiplex Engineering VPW, PWM, and ISO 9141-2 interface:
http://www.multiplex-engineering.com/products.htm
set interface met16

Note, if you have a Multiplex Engineering interface not purchased for the freediag software, it will have a different ID to that used in the freediag project. Freediag uses ID 0x38. If you know the ID of your interface you can change the INTERFACE_ADDRESS definition in diag_l0_me.c and recompile.