Some webCoRE Basics for writing pistons - Using variables

[nh.schottfam]

This is another example of writing a piston, utilizing variables.

When you create a piston, the webCoRE IDE may not initially show the variables section:

To see the variables section when in edit mode the ‘Show Variables’ icon:

Now you can add new local variables:

To define a variable select the + add a new variable

You must define a type and a name for the variable. Note the name cannot start with @ or $ as these are reserved for other classes of variables discussed below.

You have a choice whether to set it to an initial value.

I would suggest as a best practice to not set an initial value, unless the variable is really a constant (ie you will never change it via set Variable)

If you do not set an initial value

• Your code needs to set values to the variable

• These set Variable changes to the variable the code makes will persist across executions of the piston.

  • This can be very helpful as something that happened in an earlier piston execution will be available for the next piston execution

If you do set an initial value:

• every time the piston executes [from the beginning] the variables with initial values will effectively run setVariable operations to initialize the variables.

• During execution if you set a new value to the variable, this new value is only ‘stored’ for this execution of the piston (and its wakeups), ie when the piston starts from the top, any changes made will be lost to the initial value

  • This can make debugging a bit more difficult as variables with initial values appear to never change (even though they could change during execution). The latest webCoRE can show this in the IDE:

Note 'setandreset' in the define section, it shows an initial value assignment, and if changed, what it was last changed to. Again, note that if the piston runs from the beginning, the initial value will be assigned.

• This can also make it appear that changes to the variable appear to be lost because of during the piston execution the piston if a run from the top has happened. (Piston runs, Events, wakeups in webCoRE, Asynchronous task blocks)

  • webCoRE IDE will now warn if you perform set variable on a variable with an initial value

• Full logging on a piston can make this clear, but full logging can be verbose to read

• So while initial values seem helpful, in many cases:

  • it just adds more code to execute before piston execution

  • it takes away an important debugging tool to know what happened last time the piston ran.

  • it can cause confusion on why variable is not keeping updated value if you change it with set variable command

So what scopes of variables are available?

• Local – these are the variables in the define section within the piston
  • Scope
    • only this piston can see/manipulate them.
  • Persistence
    • If they are not initialized, they persist across piston executions (unless you cleared)
  • How to update
    • setVariable commands in your piston
    • you can do a set from the webCoRE IDE -> view the piston, scroll down to the list of variables and it the edit icon next to the variable
  • How to clear
    • Clear all local variables for a piston: in the HE piston page (HE console -> Apps -> select the piston -> “Clear all data”))
    • Uber cleanups for all pistons (HE console -> Apps -> “your main webcore” -> settings -> Child Uber Cleanups (labeled “Danger:”))
  • How to add / remove
    • Create in define section, or delete from define section
  • Can I receive events on these changing?
    • No
  • Where is it stored?
    • In the piston state data (total limit for everything in piston state is about 100KB)

• webCoRE Global – Variables that start with an initial @
  • Scope
    • webCoRE pistons on this node can see these variables
  • How are variables created?
    • In webCoRE IDE when editing a piston on right hand side “ + add a new global variable”
  • How are global variables removed?
    • In webCoRE IDE, when editing a piston, select a global variable, then select delete
  • When do they update?
    • If a piston makes a change that piston can read the change immediately
    • Other pistons will not see the change until the piston that did the change exits its current event processing. At this point change events will be sent to other pistons that requested change notifications if the variable changed.
  • Persistence
    • They persist until deleted
  • Can I receive events if they change?
    • Yes. (if @global changes …)
  • Where is it stored
    • In the webCoRE main process state (total limit for everything in webCoRE main state is 100KB)
  • There are logs of the changes (for short period of time) in HE console -> logs -> location events

• See what pistons use global variables

• HE Hub variables – in webCoRE you reference hub variable foo via @@foo (this is hub variable foo)
  • Scope
    • All apps on this HE node can see the hub variables on this node
  • How are variables created?
    • HE console -> Settings -> Hub Variables
  • How are global variables removed?
    • HE console -> Settings -> hub Variables
  • When do they update?
    • In real-time
  • Persistence
    • They persist until deleted
  • Can I receive events if they change?
    • Yes. (if @@foo changes …), these happen in real-time to the change
      • likely a good idea to not do this if @@foo value is really large (as in a long string for example) as tracking has to store the old value if using tracking comparison
  • Where is it stored
    • In the hub database.
      • There are limits to data types, size, count, etc of hub variables. For example a string can only be 255 characters.
  • There are logs of the changes (for short period of time) in HE console -> logs -> location events

Observations:

• Local variables provide the best isolation.

• Shared variables (@ or @@) can become more difficult to debug as multiple pistons or applications share the same variable.

  • Single writer and multiple readers is a good workflow to avoid some of these challenges
    
    

System Variables

These are pre-defined variables that start with $.

• they are predefined in webCoRE (you can see many but not all of them in the IDE and when selecting variables)

• they cannot be written to

• their value may change between and during piston runs

Other complexities

• if you change local variable definitions (editing piston, changing types, or adding/removing local variables), you may need to follow the 'clear' instructions above for local variables to ensure the piston state is clean (this is hygiene, not correctness).

• Using device variables can make it easier for yourself or others to reuse a piston – ie they only change a few variables to adjust the devices the piston controls / monitors

• device variables also make it easy to get the average, variance, least, most, median, stddev, max of several devices:

• When using a device variable, the webCoRE IDE cannot easily deal with custom attributes / commands (vs. if your statement directly used the device, these are easily done)

  • expressions and functions as a value can help you here

Error logging

• webCoRE will log errors for missing variables if you attempt to set them

• webCoRE will logs errors for missing variables if you attempt to read them, and logging is set to 'medium' or 'high'

  • this is done because some apps can handle themselves missing variables (ie getting not found in the return value).

Further reading on hub variables in webCoRE

References:

Installation and Tips for webCoRE on HE:

webCoRE for Hubitat Updates

So in the latest webCoRE there is a report for in use global variables. How it works as pistons run they update a list of global variables they use to see this report, you need on the main webCoRE application to have FULL logging enabled on the main webcore process, then you will see an option to dump global variables in use (HE console -> apps -> webcore (main) -> Settings) What if you don't see a piston listed that is using a global variable? this means the piston has not run or …

[nh.schottfam]

Reserved