LUA Environment object - sys.*

[JimB40]

PURPOSE

This proposal is to switch from pulling system data via function to read only object avalable to LUA scipts. It will allow to:

• depreciate various functions (when agreed) - saving memory.
• make LUA code more clear
• unify way to access system data via LUA
• simplify adding new system maintaining backward compatibility (LUA table vs function lists or returned variables)

Initial proposal

sys Global LUA table holding various system data ​ **sys.*** childeren tables holding data related to child type

• sys.os.* - operating system (EdgeTX) data

  • sys.os.version (string) - full os version number - ie 2.8.1
  • sys.os.major (number) - major version number - ie 2 if sys.os.version is 2.8.1
  • sys.os.minor (number) - minor version number - ie 8 if sys.os.version is 2.8.1
  • sys.os.revision (number) - revision version - ie 1 if sys.os.versionversion is 2.8.1
  • sys.os.name (string) - OS name - ie "EdgeTX"
  • sys.os.codename (string) - OS code name - ie "Flying Dutchman" in case sys.os.version is 2.8.X
  • sys.os.build_date (string) - OS build date - ie. "2023-09-20"
  • sys.os.build_time (string) - OS build time - ie "15:03:44"
  • sys.os.hash (string) - GH build hash - ie "cb34cf75"
  • sys.os.options (table) - holds all of build options
  • sys.os.build_type (string) - OS buld type - ie "release", "nightly", "PR 1234"

• sys.radio - physical radio used data

  • sys.radio.name (string) - radio name - ie "EL14"
  • sys.radio.target (string) - target symbol - ie "NV14" in case sys.radio.name is "EL14"
  • sys.radio.mfg_name (string) - manufacturer name - ie "FlySky"
  • sys.radio.mcu_uid (number) - unique MCU number (cpu_uid)
  • sys.radio.simu (boolean) - true if run via simulator otherwise false
  • sys.radio.inputs (table) - holds available hardware radio inputs
  • sys.radio.inputs.sticks (table) - holds available hardware radio sticks
  • sys.radio.inputs.switches (table) - holds available hardware radio switches
  • sys.radio.inputs.keys (table) - holds available hardware radio keys
  • sys.radio.lcd (table) - radio LCD data
  • sys.radio.lcd.w (number) - radio lcd height in pixels - ie 480 in case sys.radio.name is "tx16s"
  • sys.radio.lcd.h (number) - radio lcd height in pixels - ie 272 in case sys.radio.name is "tx16s"
  • sys.radio.lcd.color_depth (number) - number of bits to represent color - ie 12 in case sys.radio.name is "tx16s", 1 in case of sys.radio.name is "zorro", 4 in case of sys.radio.name is "x9d"
  • sys.radio.com - holds data about radio communication sytems
  • sys.radio.com.rf (table) - holds data about RF modules
    • sys.radio.com.rf.internal (table) - holds data about internal RF modules
    • sys.radio.com.rf.external (table) - holds data about external RF modules
  • sys.radio.com.serial (table) - holds data about radio serial ports
  • sys.radio.com.bt (table) - holds data about radio Bluetooth module
  • sys.radio.com.wifi (table) - holds data about radio WiFi module
  • sys.radio.com.gps (table) - i data
    • sys.radio.com.gps.present (boolean) - true if internal GPS module is installed otherwise false
    • sys.radio.com.gps.data (table) - representing the current radio position

• sys.fs - filesy system data

  • sys.fs.sd (boolean) - true if SD card present otherwise false
  • sys.fs.flash (boolean) - true if flash memory available present otherwise false

• sys.lua - LUA data

  • sys.lua.version (string) - current LUA interprester version - ie 5.2
  • sys.lua.memory_available (number) - available memory remaining in the Heap for Lua in bytes.
  • sys.lua.usaage (number) - percent of already used Lua instructions in current script execution cycle.

• sys.dt - OS date/time data

  • sys.dt.current (table) - current radio RTC date and time
  • sys.dt.current_stamp (number) - current RTC date as unix timstamp (in seconds since 1. Jan 1970)
  • sys.dt.os_run (number) - time since the radio was started in multiple of 10ms

Backward compatibility and depreciation

LUA functions to depreciate over time

• getAvailableMemory()
• getDateTime()
• getRtcTime()
• getTime()
• getGeneralSettings()
• getTxGPS()
• getUsage()
• getVersion()
• getRAS()

Providing backward compatibility should be quite easy for existing LUA scripts and it can be done during script initialization That will allow LUA dev to make smooth transition to new syntax.

  local newAPI = getOsVersion() -- function that checks if new API is available based on EdgeTX version
  local getSysData = function(variable) 
    return variable
   end

  getAvailableMemory = newAPI and getSysData(sys.lua.mem_available) or getAvailableMemory()
  getTime = newAPI and getSysData(sys.dt.os_run) or getTime()
  -- etc

[JimB40]

@lshems @jfrickmann @offer-shmuely @frankiearzu @yaapu @ feedback appreciated

[lshems]

Why not add the models table as well. The structure is already defined by the introduction of yaml storage format.

[lshems]

In that way you can get rid of all API function to manipulate data. Only 'real' functions should remain, as getting inputs from sources, and creating output on screen. The rest is LUA data manipulation ...

[jfrickmann]

AFAIK, a table will be stored in RAM, whereas functions are stored in ROM. Therefore I believe that the proposal would increase the RAM memory usage.

[JimB40]

Why not add the models table as well. The structure is already defined by the introduction of yaml storage format.

Might be good idea

AFAIK, a table will be stored in RAM, whereas functions are stored in ROM. Therefore I believe that the proposal would increase the RAM memory usage.

Very good point Jesper. I wonder how much RAM will it consume considerng that getting rid of those read-system-value functions will free memory for new C code. I think there might be workaround for low mem radio so accesing special global "sys" variable will actually invoke C function that returns proper values.

[gagarinlg]

Why not add the models table as well. The structure is already defined by the introduction of yaml storage format.

Might be good idea

What excatly do you want to do on the models? The model data structure is changing with every release, so the LUA scripts would have to adapt to those changes at every relase. This sounds problematic to me. Everything model related should be done in one place in the code and there there have to be APIs for UI and LUA to get and set model information. That way only one place in the code needs to know the data structures and those can be changed without breaking anything else.

[offer-shmuely]

Looks great, as long as it done for “read” operation only (not for changing data)

It will simplify the access to this information.

Is it possible in lua to make that information read only? or one script will be able to change it by mistake to other scripts?

[frankiearzu]

Robert, Looks good to me. A good amount of the sys table is static (don't change after power on), but others are constantly changing (like date/time). Not familiar how internally lua table fields works, but when you access a field on a table, it will need to do a call to C/C++ to get the real-time value. or instead of a field, could be a function?? For example: sys.dt.os_run or sys.dt.os_run() instead of getTime() ???

Otherwise, you will need to constantly update the table with up-to-date values, that might be expensive.

[lshems]

Why not add the models table as well. The structure is already defined by the introduction of yaml storage format.

Might be good idea

What excatly do you want to do on the models? The model data structure is changing with every release, so the LUA scripts would have to adapt to those changes at every relase. This sounds problematic to me. Everything model related should be done in one place in the code and there there have to be APIs for UI and LUA to get and set model information. That way only one place in the code needs to know the data structures and those can be changed without breaking anything else.

Well, I do see the yaml format as an already existing representation of the actual eeprom settings. I know lots of implementations where the API is simply allowing get, put, patch actions on every element in such a data structure. This would make life super simple, as you only need to have one Metafunction added to all elements that would allow for that

So model.name.get() would get the model name. Model.name.set('newname') would change it.

You could also allow entire structures to be read and set. Perhaps invert the syntax:

Set(model.name,'newname') Get(model) would then return model.name and all other elements in Yaml format (or XML, or lUA table, or ...

Just ideas