System

Overview

System is a global table providing information about the system, versions, debugging information and debugging controls.

System.

System.BuildVersion

String representing the Cognio version number in "X.X.X" format. On a Smart Device this is the device's firmware version; in Cognio DesignOps it is the version of DesignOps. This is a read only variable so any changes made to it will not have an effect.

print(System.BuildVersion)                >> 1.1.1

System.MajorVersion

Integer representing the Cognio major version number. This is the first number in the version, "X.x.x". This is a read only variable so any changes made to it will not have an effect.

print(System.MajorVersion)                >> 1

System.MinorVersion

Integer representing the Cognio minor version number. This is the second number in the version, "x.X.x". This is a read only variable so any changes made to it will not have an effect.

print(System.MinorVersion)                >> 1

System.PatchVersion

Integer representing the Cognio patch version number. This is the third number in the version, "x.x.X". This is a read only variable so any changes made to it will not have an effect.

print(System.PatchVersion)                >> 1

System.Build

Always 0 in Cognio. Cognio versions have three numbers, so there is no build number. It is kept so that scripts written for Composer still run.

print(System.Build)                       >> 0

System.IsEmulating

Always "true" in Cognio, whether the script runs in Cognio DesignOps or on a Smart Device. It is kept so that scripts written for Composer still run. To check where the script is running, use Device.Offline.

print(System.IsEmulating)                 >> true

System.IsDebugging

Always "true" in Cognio. Whether print output is saved to the Lua Script Debug Output File depends on where the script runs: in Cognio DesignOps it is always written, and on a Smart Device it is copied back only while Enable Synced Debugging is on in the Control Panel Group properties. This is a read only variable so any changes made to it will not have an effect.

print(System.IsDebugging)                 >> true

System.ClearDebugging()

Function to clear the Lua Script Debug Output File.

System.ClearDebugging()             -- Lua Script Debug Output File will be cleared

System.GetTime()

Returns the time in milliseconds since 1/1/1970.

print(System.GetTime())             >> -903260332

lowPortion, highPortion = System.GetTime()
print(lowPortion)                   >>  371
print(highPortion)                  >> 903095174 --

The high portion is Negative because we are beyond halfway through the epoch so it wraps around. This doesn't matter because the value returned is generally not especially useful in and of itself. But when compared with previous values, it can be used to determine how much time has passed between the two times. See the example below.

System.GetTime() is calculated the same way whether the script runs in Cognio DesignOps or on a Smart Device, although you may see a shift due to differences in time zone handling between a Windows computer and the Smart Device.

If you want to get the actual date and time for display, os.date() is better for this purpose because of its flexibility.

System.GetExecutionTime()

This API can tell you more about how much CPU processing time your script is consuming. This may be needed for optimizing complex and intensive scripts and should only be necessary if errors indicate your scripts are consuming too much CPU time.

It returns the number of ms which have passed since processing started on the current 4 Hz pass. This includes all timers, and other callbacks that happened on the current pass. This is the key thing that must be controlled to ensure processing doesn't exceed 1/8 second (125 ms) on each pass to prevent starving other routines.

print(System.GetExecutionTime())          >> 1

If you are seeing Skipped script passes or Load Factor over 100%, you may want to use this to profile your script. You can insert this into various sections of your code, usually in your Timer callback, to determine which parts are taking excessively long to execute. Then hopefully you can use this information to optimize.

Usage Examples

The following examples illustrate how these can be used:

Example 1 - Check Version Number

There may be some functionality that is only available in a certain version of Cognio or newer. The following code shows how this can be checked before doing some operation.

if (System.MajorVersion > 1) or (System.MajorVersion == 1 and System.MinorVersion >= 1) then
      -- Do Something
else
      -- Do Something Else
end

Example 2 - Check Where the Script Is Running

There may be some behavior you need to do differently in Cognio DesignOps and on the Smart Device. Because System.IsEmulating is always true in Cognio, use Device.Offline to create separate code paths.

if (Device.Offline) then
      --do something when running in Cognio DesignOps (not synced)
else
      --do something else when running on the Smart Device (synced)
end

Example 3 - Simulate Control Pins When Not Synced

While the Control Panel Group is not synced, you can use Device.Offline to supply test data in place of control pin inputs.

offline = Device.Offline
data = 0

if (offline) then
      data = 0.5
else
      data = Controls.Inputs[1].Value
end

--Use the "data"

Note if this code block is called repeatedly, it is good practice to set Device.Offline to a variable since its status won't be changing during the script execution.

Example 4 - Comparing Elapsed Time

Using a timer, System.GetTime() can be used to determine the elapsed time since starting a process.

startTime = System.GetTime()

function TimerClick ()
      elapsedTime = System.GetTime() - startTime
      --Do something with elapsed time
end

MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(1)