User Tools

Site Tools


doc:lua_tutorial

Differences

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

Link to this comparison view

doc:lua_tutorial [2014/03/02 07:26] (current)
admin created
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