User Tools

Site Tools


doc:lua_tutorial
no way to compare when less than two revisions

Differences

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


doc:lua_tutorial [2014/03/02 07:26] (current) – created admin
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 
 +  
doc/lua_tutorial.txt · Last modified: 2014/03/02 07:26 by admin