Author Topic: ALTUI: Workflows Tutorial & Examples  (Read 8928 times)

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
ALTUI: Workflows Tutorial & Examples
« on: May 17, 2016, 01:23:50 pm »
WORKFLOW INTRODUCTION

ON/OFF
The workflow mode is controlled by a button in the settings tab of ALTUI device to switch it on or off. you can allways switch it off if you run into trouble  ( which is possible if you create crazy workflow that keeps matching conditions and run in loops ).   you can switch off or switch on the workflow mode without requiring a lua restart

Display
You have a first page with is showing all your workflows ( you can have several ) , then when clicking on the wrench icon you can see a graphical representation of your workflow with the start state in green, the active state in red.

I have not found a way to use web sockets so I have to do polling from the GUI to know the workflow status, I do this every 3 sec to avoid overloading VERA ( small data ) and the workflow page shows the workflow graphically and displays, which state is active so you actually see how your workflow progresses

State have connection points, you can use any "In" for incoming transition and any "Out" for outgoing transitions, the fact there are several is purely for convenience

Double click on a state or transition , or clicking on the edit button first then the object you want to edit will open the propery windows for that object where you can set configuration

Workflows
you can have many workflows ( like custom pages ), but on a vera backend I suspect you can hit some limits. Each workflow is made of states and transitions. A State is active or inactive. A Transition is met or un met. When a State is active and one of its transition is met, the transition is executed and the end point of the transition becomes the new state. if several transitions are met, only the first met transition is executed.
Once arrived in the new state, if one of its transition is met, the process continues, until the workflow is blocked , pending on a state where no transition can be met and it puts itself in waiting mode

There is a workflow report screen to display all details of states and transitions of a worfklow

Variable Bags
a Bag is a associative array to store workflow specific variable that are visible in any state of the workflow and are persistent accross reboots/reloads.  a resetWorkflow action will reset the variables to null.
They are accessible in lua code like this and the lua code can just add variable as it wants simply by assigning a value to them:
Code: [Select]
Bag["my_variable"] = 2Be careful that variables starts with a null value if the workflow has been reset for instance so if you use operations that use the previous value of the variable, you must guard it with default values like this:
Code: [Select]
Bag["my_variable"] = (Bag["my_variable"] or 0)+12 workflows can have the same variable name in their Bag, their will not be name collision, each workflow has its own Bag.

States
States represent a logical state of your environment. Only one state in a workflow is active at a time. States are linked by transitions and transitions must be met for a state transition to happen. States have a set of n actions when we enter the state ( OnEnter ) and a set of n actions when we exit the state ( OnExit ). these are device UPNP actions.  There is also the ability to run scene ( both on Enter and on Exit ), as well as execute a piece of LUA code. that Lua code can call any luup.* functions ( in _G space ) and have access to a special "Bag" of variables that belong to this workflow.

  • State onEnter or onExit can call the UPNP action of a device and can use a Bag["xxx"] value in the parameters
  • Link condition expressions can make use of a Bag["xxx"] value in their expression

When the workflow starts it starts in the start state. You can create transitions from the start state to the state you want to be in. at least one transition from the start state should fire and put your workflow in a proper position. Start state is remembered accross reboots, so if it is still valid ( not deleted by the user , and user has not reseted the workflow on purpose ) the workflow will resume in that state
 
Transitions
Transitions are basically condition ( device watches & lua expressions, like the watches ) , or timer ( transition is 'met' when the timer described in the transition is met. Transitions may have multiple conditions, and this is an "AND" of all of them to be valid.

Timer transitions can be a hard coded timer ( n seconds ) or a range ( min-max ) which will make ALTUI chose a random duration between min and max seconds for that timer ( and it will be different every time the timer is armed ) . The timer value can also be a Bag variable with the syntax : Bag["varname"] .

Transition can also be "scheduled" transition. this is the same scheduling capabilities as scene and will enable the transition to be considered as true on a planned schedule basis. When you associate a schedule to a transition, it will create a scene called " Workflow <altuiid> " with the programmed schedule. the scene will run and trigger the workflow transition.  House modes apply if you are on UI7.  the Logic remains so even if the transition is considered as "true" when this happens, it will only trigger a worfklow state transition if the active state of the workflow, was the source state of the transition.

Transition of a workflow (A) can also be fired when another workflow (B) is entering a particular state. you can choose that state from the transition editor screen. as soon as the other workflow (B) reaches that state, ALTUI will check this particular transition :  if the source state of the transition in workflow (A) is matching the actual state of workflow (A), the transition will fire. Otherwise it will be ignored

if you need "OR" , you create multiple transitions ( multiple arrows on your graph )

Logical expressions for Transitions
Blockly editor for Transition condition editor is enabled , otherwise Transitions obey to the same rule / syntax than watches , so you can use special variable like new and old , just remember device values are string typed so to express a condition for a tripped motion sensor for instance, you write   new == '1'. you can use luup functions so  new == '1' and luup.is_night() is a valid expression to have for a transition. You can use Bag["xxx"] variables so new == Bag["my_var"] is a valid expression

Implementation, details
it is based on watch and timers so it is fully asynchronous. inactive workflows do not use any resources on your vera. the only exception is the GUI refresh of active state which is a polling every 3 sec for a small packet of information and this is only hapening on the workflow display page

Workflows can trigger transitions in other worfklows using the method explained here:
http://forum.micasaverde.com/index.php/topic,33303.msg282392.html#msg282392
« Last Edit: January 26, 2018, 05:49:14 pm by amg0 »

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #1 on: May 17, 2016, 01:27:35 pm »
  • Workflow Reports : to see a complete description of a workflow
  • Edit expression : click and edit

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #2 on: May 17, 2016, 01:30:17 pm »
  • Example : Smart Motion Light - switch on a light when motion is detected and switch it off after some time, but prevent that whole logic if the light was lighten manually
  • Update thingspeak : send data to thingspeak every x min. replacement for a programmed scene which sometimes creates LUA global error on VERA when the scene is executed before the startup is finished. with this workflow, no more issues

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #3 on: May 17, 2016, 01:32:16 pm »
Example on using Bag["nnn"] variable syntax in workflows LUA code

Each workflow can have Bag of variable;  they are not shared accross workflows, so each workflow can have the same bag variable names without issues. workflow Bag are saved into ALTUI lua device variable WorkflowsVariableBag
« Last Edit: May 17, 2016, 01:43:50 pm by amg0 »

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #4 on: May 17, 2016, 01:34:01 pm »
a nice thermostat workflow from @ndoggac

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #5 on: May 17, 2016, 01:36:15 pm »
About the use of "trigger" only flag in transition expressions

Transitions conditions are a boolean expression based on a device variable value. this expression is evaluated true or false and depending the result , the transition link is valid and the state change.

With the new TriggerOnly flag, the expression is only considered true the first time ( when the device variable value changes ). in other terms, it is like the LUA watch, the variable changes and the watch callback happens, but then the watch callback does not happen again until the variable changes.

so, a condition like "new == '1' " which would be marked as TriggerOnly , would only be considered true once, when the variable just take the value "1",  but then, even if the variable stays at value "1", it is not considered true, until the time where it had change its value to something else like 0 and then comes back to 1

Typically can be used for the remote btn 1 example discussed earlier in that thread, it simplifies a lot the workflow.

here is an example of a stupid workflow with 2 states linked by 2 transitions, each of them pointing to the same device, variable with expression new == '1'

if both are ongoing conditions the workflow will keep flip flop between the 2 states.  if you set one of them as TriggerOnly, the workflow will stay stuck on that state until you change the device variable to 0, then to 1 again. at that point it will go to the S1 state, evaluate the next transition ( ongoing ) so goes to state S2 , then get stuck until the next trigger on new == 1 happens

The "Flash" icon in the workflow reports means a condition that is marked as "TriggerOnly"

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #6 on: May 17, 2016, 01:37:22 pm »
Example: a smart window cover

window cover, which goes up and down depending on the light in the room, but enables the user to override the mecanisms and force the window cover to be open or closed without letting the light level influence that. I attached workflow diagram & details report with a couple of "pay attention" tips
« Last Edit: May 17, 2016, 01:42:34 pm by amg0 »

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #7 on: May 17, 2016, 01:38:05 pm »
How to make a counter with workflows
« Last Edit: May 17, 2016, 01:42:16 pm by amg0 »

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #8 on: May 17, 2016, 01:40:00 pm »
Example: Manage the dimmer in a theater Room with a Nodon Octan remote

-   Pressing ?+? sign should start ramping up the dimmer level , up to a maximum of 60% by steps of 5% every 5 seconds
-   Pressing ?-? sign should start ramping down the dimmer level  down to 0% by steps of 5% every 5 seconds
-   While ramping up or down, we want the ability to take over the control and stop the ramp up/down. So for instance while ramping up, a press on either + or ? will simply block the ramp up/down and leave the dimmer level to where it is.
-   If the ?+? or ?-? is pressed then, the respective ramp up or down continues

Tutorial and detailled explanation in the PDF file

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #9 on: May 17, 2016, 01:41:05 pm »
Workflow editor new features

  • Auto complete list selection to clone an existing transition or state
  • zooming and rotation of states

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #10 on: May 22, 2016, 01:04:34 pm »
workflow : implementing a presence simulator with random transition timer duration

V 1.54.1672 brings a new enhancement to workflow transitions. cf http://forum.micasaverde.com/index.php/topic,33308.msg282489.html#msg282489

this basically enable to create transitions which are a timer, but instead of having a hard coded duration, you can specify a min-max for the duration will will turn out to be a random duration in seconds, between min and max, and calculated every time the timer is armed. ( so never the same in theory ). I see the random on os.time() so it should be reasonably random.

Typical use could be implementing a workflow for presence simulation.

Start => "Active" state could be a transition based on the House Mode becoming "away"
then a set of transitions, all leaving the "Active" state to a "Device Group On" state with a random timer transition and a set of switch-on actions in the OnEnter section of the state.

From that "Device Group On" state, again a random timer to switch it off and go back to the "Active" state,  switch off only some devices etc...

you can be fancy and simulate real presence with different states like "Dining" , "looking at TV", "preparing to go to bed" , "sleeping" etc... all with slightly randomed transitions times

your choice, but the fundamentals are there

« Last Edit: May 22, 2016, 01:07:22 pm by amg0 »

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #11 on: May 24, 2016, 01:48:51 am »
workflow: triggering another workflow from a workflow


ALTUI device has an action called "TriggerTransition" / service "urn:upnp-org:serviceId:altui1" with 2 parameters:
workflowAltuiid : which is a workflow altuiid with the form "0-xxx"
transitionId : which is ID of a transition

Calling this Action in one of your workflow OnEnter or OnExit actions will actually trigger that particular transition in that other workflow you specify

There is a screen shot where you can find this information here: http://forum.micasaverde.com/index.php/topic,33303.msg282392.html#msg282392


Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #12 on: May 29, 2016, 09:44:47 am »
workflow:  presence simulator

Demo of using random timer transition to simulate presence activity

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #13 on: June 22, 2016, 04:02:05 pm »
Workflow:  Smart Entry Door Bell Warning

Demo of using workflow to notify with a sound when somebody approaches the door ( but only under some circonstances )

Offline amg0

  • Moderator
  • Master Member
  • *****
  • Posts: 3057
  • Karma: +206/-8
Re: ALTUI: Workflows Tutorial & Examples
« Reply #14 on: September 27, 2016, 03:48:25 am »
if you are a workflow user, please read http://forum.micasaverde.com/index.php/topic,33308.msg294491.html#msg294491 before you update ALTUI to a version stricly higher than > 1838