Some webCoRE Basics for writing pistons - Using variables

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:

Screen Shot 2022-01-26 at 12.40.49 AM

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

Screen Shot 2022-01-26 at 12.42.12 AM

Now you can add new local variables:

Screen Shot 2022-01-26 at 12.42.48 AM

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 setVariable)


If you do not set an initial value

  • Your code needs to set values to the variable

  • These setVariable 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 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, ie when the piston exits 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)

    • Note that exit means sleep, wait, resume also, so anything which pauses or wakes the piston will have it reset on the next execution or wakeup.

    • 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, and takes away an important debugging tool to know what happened last time the piston ran.


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

  • 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:

Screen Shot 2022-01-07 at 11.54.30 PM


  • 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)


Further reading on hub variables in webCoRE


References:

Installation and Tips for webCoRE on HE:

7 Likes

Reserved

Download the Hubitat app