Differences

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

--- doc:lua_make-your-own-scripts [2014/03/02 07:24] – created admin
+++ doc:lua_make-your-own-scripts [2019/04/08 18:43] (current) – [The IO Commands] admin
@@ Line 5: / Line 5: @@
-===== What is Lua? =====
-Simply said, [[http://www.lua.org|Lua]] is "something" (a so called script interpreter) which is made to allow a program to run another program internally. The trick in that is, that the internal program does not need to be there when the "outer" program is made, it can be loaded later, just when you need it.
-This allows to make a program now but change its behavior later as needed. This is widely used in the OOBD script engine: The script engine is there from the beginning, but what it does is defined by the script which is loaded at runtime. Another script, another functionality..
-Luckely Lua became quite popular in the last years, so it's available for all major platforms, like Desktop PCs, Smartphone and Mobile Phones.
-There are tons of documentation about Lua available in the internet, so we'll not explain the wheel here once more, we'll just focus on how Lua works inside OOBD.
@@ Line 112: / Line 101: @@
   * function: Each menu is assigned to a Lua function, where one function can be shared between several menu items. The name of this function is given here (please take care about correct upper/lower characters)
   * initialValue(String): This is what is shown as initial value when the menu is displayed the first time.
-  * Flagset(Integer): This is an integer value, where each bit represents a flag. The meanings of these flags are explained in the [[:dev:clientdesignguide|Client design guide]] (look for System Flags)
+  * Flagset(Integer): This is an integer value, where each bit represents a flag. The meanings of these flags are explained in the [[dev_clientdesignguide|Client design guide]] (look for System Flags)
   * id(String): The id is used to add an individual marker to a menu item. This is widely used when one single Lua function should support many menu items. This is descripted in detail in the [[#the_menu_function_call|Menu Function Calls]] below.
@@ Line 147: / Line 136: @@
-==== The Communication  Commands ====
+==== The Communication Commands ====
 OOBD uses (actual) serial communication to talk to the diagnostic device. To allow Lua to send and receive data from the serial port, a few extended Lua functions exists:
 === serFlush() ===
 It just clears the input buffer (from anything which was maybe received in the meantime and which is not needed anymore)
@@ Line 157: / Line 149: @@
 === serWrite(String) ===
-Sends //String// to the output (which is normally the serial port)
+Sends //String// to the output (which is normally the serial port)
 === serSleep(milliseconds) ===
-waits //milliseconds//
+waits //milliseconds//
 === serReadLn(msTimeout) ===
 reads from input until a LF (dez. 10 hex 0x0A) appears and returns that input as String
 === serWait(OptionString, msTimeout) ===
 In case you want to wait for some input strings, of which several could appear, you fill the //Optionstring// with string1|string2|..|stringN. If then one of this string appears at the input, the index of the found string is returned (first string=1). If the string does not appear within //msTimeout//, the function returns 0.
-====  Miscellaneous  Commands ====
+==== The IO  Commands ====
-=== serDisplayWrite(String) ===
+FIXME the whole IO command section is in pure experimental state. There's no guarantee that these functions are even exist, are implemented as described or not subject to change.
+OOBD uses its own scheme for file IO, mainly driven by the restriction of a remote user and the need of complex data buffer handling.
+Similar to the LUA simple IO model, OOBD has always only just input and output file handle. As long as not redirected, these are stdin and stdout.
+As OOBD knows more as only one type of data sources, the parameter ''message'' is misused to control the behaviour.
+.
+=== ioInput(file_name ,file_extension,message) ===
+Tries to open the file accourding to the following parameter combinations:
+^  filename  ^  message  ^  Effect  |
+|/unix-path/.. |any message |Open a file Open dialog with preselected path (and file). At success returns the file path, otherwise null |
+|/unix-path/.. |'direct' |Open the given file without Dialog, At success returns the file path, otherwise null  \\ actual either complete path are supported, relative paths or filenames only. Filenames and relative paths are relative to the actual script directory |
+|URL like ''HTTP:<nowiki>//</nowiki>''.. |'html' |Reads the URL as input.At  success returns the URL, otherwise null |
+|URL like ''HTTP:<nowiki>//</nowiki>''.. or ''file:<nowiki>//</nowiki>''..|'json' |JSON-RFC call: The parameter ''file_extension'' can be a lua table or a JSON string, in case of a lua table, it's translated into a JSON string and send as POST to the given URL. In case of a file:<nowiki>//</nowiki>- URL, the local file is read as a JSON file |
+After opening the file with IOInput(), it can be read with ioRead()
+=== ioRead("%%*%%line") ===
+Read one line of the input file ending with either<nowiki> \</nowiki>r<nowiki>\</nowiki>n or<nowiki> \</nowiki>n as string without the EOL. In case of input EOF or read errors the function returns nil. By this the whole file can be read line per line
+=== ioRead ("%%*%%all") ===
+Read the whole file as string
+=== ioRead ("%%*%%json") ===
+Here it's assumed that the input file consists of a JSON string containing data. This string is translated into a lua table structure and returned
+=== ioRead ("%%*%%sha256") ===
+This mainly for testing purposes. It returns the sha256 checksum of that file
+\\
+==== The Buffer Commands ====
+FIXME this whole Buffer section is not implemented and actual just here as a reference for discussion
+=== loadbuffer ===
+  len, newfilename= loadbuffer(start , filelen , file_name , file_extension , message)
+Reads the file "file_name" into the telegram buffer starting at position "start" by reading "filelen" number of bytes.
+The data source can be defined as explained for the ioInput command.
+The number of bytes read will be returned in "len", a negative value means a load error
+The following conditions apply:
+  * The selected filename will be returned in "filename".
+  * If filename is 0, the whole file will be read. If the length exceeds the telegram length, an error will be raised.
+=== savebuffer ===
+  len, newfilename = savebuffer(start , filelen , file_name , file_extension , message)
+Writes the telegram buffer starting at position "start" by reading "filelen" number of bytes into the file "filename".
+The number of bytes written will be returned in "len", a negative value means a load error
+The following conditions apply:
+  * The selected file name will be returned in "filename".
+  * If len is 0, the whole telegram buffer will be written.
+=== setbuffer ===
+  setBuffer(bufferNr , newSize )
+Changes the actual buffer used to buffer number "buffernr". OOBD supports 10 buffers, counted from 0 to 9. The startup buffer is nr. 0.
+If newsize is <> 0, the old buffer is deleted and new memory with size newmem is allocated
+=== copyBuffer ===
+  copyBuffer(bufferNr )
+Copies the content of buffer  "bufferNr" into the actual buffer.
+=== BlitBuffer ===
+  BlitBuffer(frombuffer , startpos , topos , blocklen  )
+Copies a memory block  from the buffer "frombuffer" starting at position "startpos" to the actual buffer to position "topos" with the length of "blocklen" bytes.
+In case the buffer len needs to be bigger, the buffer len is increased accourdingly.
+=== SetBufferLen ===
+ newSize= SetBufferLen( newSize)
+All other buffer commands can increase the 'len' of a buffer, but none of them can make a buffer shorter, except SetBufferLen.
+SetBufferLen sets the 'len' of the current Buffer to 'newSize'.
+The success of the SetBufferLen - operation is returned as function result as follows:
+^  input value of newSize  ^  return value   ^
+|  < = 0                    | available size of the buffer in bytes. This can be used to read the real allocated memory size of that buffer  |
+|  1.. available size      | new available size (= requested size)  |
+|  > available size        | available size of the buffer as **negative value ** . This is a fault condition |
+As seen, a negative value given back indicates a fault condition, all other returned values are positive.
+=== SendBuffer ===
+Sends the actual buffer
+==== WriteString Command Syntax ====
+As default the command
+  serDisplayWrite(String)
+writes //String// to the build in output console. But with an optional secound parameter as command this behavior can be changed:
+  serDisplayWrite(parameter, command)
+The different commands have the following effects:
+^ parameter  ^ command  ^ Function  ^
+| buffername  | setbuffer  | redirects the following DisplayWrite()'s output into buffer "bufferName". If the buffer does not exists, it's automatically generated \\ The default output window buffername, which is also active at start, is //display// To write some output there after using some other buffers before, set buffer back to //display// |
+| -           | clear      | clears actual buffer content |
+| -           | clearall   | clears all buffers. Senseful at start of scripts, if wanted, as the buffers contain their contents between scripts runs |
+| filename    | save       | saves actual buffer to filename without further asking  |
+| filename    | saveas       | saves actual buffer to filename by let the user first confirm the filename  |
+| filename    | append       | appends actual buffer to filename without further asking  |
+| filename    | appendas       | appends actual buffer to filename by let the user first confirm the filename  |
+==== Miscellaneous  Commands ====
-Writes //String// to the build in output console.
 === dbLookup(db-File , searchstring) ===
-Searches in the //db-file// for all entries with index //searchstring//. The //db-file// needs to be in the same directory as the Lua- script itself. The //db-file// itself is made by [[doc:oodbcreate|oodbCreate]].
+Searches in the //db-file// for all entries with index //searchstring//. The //db-file// needs to be in the same directory as the Lua- script itself. The //db-file// itself is made by [[:doc:tools_oodbcreate|oodbCreate]].
 dbLookup() returns a Lua table
-  myTable = dbLookup("dtc.oodb", "0815")
+<code>
+myTable = dbLookup("dtc.oodb", "0815")
+</code>
 //myTable.len// tells the success status:
-  * if //myTable.len// < 0 then an error has occured
-  * if //myTable.len// = 0 then //searchstring// has not been found
-  * if //myTable.len// > 0 then //myTable.len// tells the number of entries found
-When something has been found, than //myTable// contains two sections, //header// and //data//.
+    * if //myTable.len//  < 0 then an error has occured
+    * if //myTable.len//  = 0 then //searchstring//  has not been found
+    * if //myTable.len//  > 0 then //myTable.len//  tells the number of entries found
+When something has been found, than //myTable//  contains two sections, //header//  and //data//.
 The header section is needed in case you don't know in which column your wanted result is stored; you can identify the column by its column header name instead:
-   col= myTable.header["DTC-Text"]
-   print (col)
- //myTable.header.size// tells the number of colums in total **without** the first index column, which is always surpressed.
+<code>
+ col= myTable.header["DTC-Text"]
+ print (col)
+</code>
-The //data// section then contains the found data itself, arranged as a two dimensional array, sorted by rows and columns.
-    result=myTable.data[row][column]
+//myTable.header.size//  tells the number of colums in total **without**  the first index column, which is always surpressed.
-**ATTENTION**: Although the row and column indexes are expressed as numbers (1,2,3,4..), they are internally represented as string values ("1","2","3","4"...), so to read the result correctly, numeric row and column counters need to be converted to strings first to address the array correctly
+The //data//  section then contains the found data itself, arranged as a two dimensional array, sorted by rows and columns.
+<code>
+  result=myTable.data[row][column]
+</code>
+**ATTENTION**: Although the row and column indexes are expressed as numbers (1,2,3,4..), they are internally represented as string values (“1”,”2”,”3”,”4”…), so to read the result correctly, numeric row and column counters need to be converted to strings first to address the array correctly
+<code>
+  column=3
+  row=2
+  result=myTable.data[tostring(row)][tostring(column)])
+</code>
+Here after all a piece of sample code
-    column=3
-    row=2
-    result=myTable.data[tostring(row)][tostring(column)])
- Here after all a piece of sample code
 <code lua>
 myTable= dbLookupCall("dtc.oodb","005")
 print ("header")
 for k,v in pairs (myTable.header) do
     print (k,"=",v)
 end
 nrOfColumns = myTable.header.size
 nrOfRows = myTable.len
 print ("Rows x Columns:" ,nrOfRows, nrOfColumns)
 for row = 1 , nrOfRows , 1 do
   for column = 1 , nrOfColumns, 1 do
 	  print (cy, cx, myTable.data[tostring(row)][tostring(column)])
   end
 end
 </code>
+=== openXCVehicleData(lua table) ===
+OOBD can work as VehicleDatasource for [[http://openxcplatform.com/|openXC]], which means OOBD can send datasets to the openXC system (which needs to be installed on the same android device too, obviously).
+To do so, a lua table is filled with the right indentifiers and correct formated values accourding to the [[https://github.com/openxc/openxc-message-format|OpenXC Message Format Specification]], one value per call.
+With that table openXCVehicleData() is called and the data are been transferred to the openXC backbone task for further handling.
+<code>
+openXCVehicleData({timestamp= 1332794087.675514, name= "longitude", value= -83.237427})
+</code>
+So everything which is understood by openXC can be generated out of a OOBD lua script.
 ===== Some Programming Tricks =====