no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+====== The OOBD Lua Tutorial ======
+While the page [[doc:lua_make-your-own-scripts|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
+<code lua>
+function Start(oldvalue,id)
+	identifyOOBDInterface()
+	openPage("VIN Test")
+	addElement("VIN Number", "vin","-",0x2, "")
+	pageDone()
+	return oldvalue
+end
+----------------- Do the initial settings --------------
+Start("","")
+return
+</code>
+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:
+<code lua>
+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
+</code>
+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