While the page Lua scripts in OOBD tells you the basics about how Lua works inside OOBD, this tutorial will show you how to use Lua to realize your own ideas.

In this tutorial we'll read the VIN number from a vehicle. While doing that, we'll create a menu, identify the hardware, use the OOBD Lua function library, talk to the vehicle and show the result.

First we'll need a Menu on the screen to be able to start anything at all. That we'll do with the following code sequence

function Start(oldvalue,id)
	identifyOOBDInterface()
	openPage("VIN Test")
	addElement("VIN Number", "vin","-",0x2, "")
	pageDone()
	return oldvalue
end
 
 
----------------- Do the initial settings --------------
 
Start("","")
return

So what happens here? When the Lua interpreter runs through the script, it finally finds the

 Start("","")
 

command at the end. This is one of the naming conventions in OOBD: The function, which initializes everything, must be called “Start”.

When we looking into the Start function, we'll find

identifyOOBDInterface()

This a function out of the serial_dxm.lua support library. In there you can find several needful functions, which are used by more or less all OOBD scripts, so we've put these functions into a common file.

identifyOOBDInterface evaluates, which OBD hardware dongle is connected to make the further dongle commands inside the library more hardware independent.

The command sequence openPage(“VIN Test”), addElement(“VIN Number”, “vin”,“-”,0x2, “”) and pageDone() create and show a menu, containing the only list entry “VIN Number”. The addElement() command assigns the lua function vin to this menu entry:

function vin(oldvalue,id)
	echoWrite("0902\r")
	udsLen=receive()
	if udsLen>0 then
		if udsBuffer[1]==73 then
			local pos=4
			local res=""
			while pos <= udsLen and pos < 36 do
				if udsBuffer[pos]>31 then
					res=res..string.char(udsBuffer[pos])
				end
				pos= pos +1
			end
			return res
		else
			return "Error"
		end
	else
		return "NO DATA"
	end
end

This function is called when the user selects the Menu entry “VIN Number”. Inside this function first the command

echoWrite("0902\r")

sends the text “0902” as hexadecimal data string to the OBD dongle, which is the OBD standard command to request the vehicle Identification Number (VIN) from a vehicle. The dongle itself forwards this data sequence as binary telegram onto the vehicle diagnostics bus and waits for an answer from the vehicle module.

The command

udsLen=receive()

picks up the module answer from the OBD dongle. When udsLen is greater than 0, it means that something is received. The received bytes themself are stored in the byte array udsBuffer[].

As we are expect an ASCII VIN number in the received data, we run through the udsBuffer[] and join all bytes found as their ASCII values together to the string res. This string res we than finally return

return res

as the result of this function.

This is also important to know: All Lua functions which are called from a menu entry must return a string value, as this string is than displayed in the menu as actual value, so it represents the result of the call as feedback to the user.

And that's already the whole magic… Based on this scheme all wanted functionality can be realized in OOBD with Lua

• create a menu entry
• link a function to it
• do the wanted stuff inside the function
• return the result as string