Sử dụng Trigger
Last updated
Last updated
State Triggers are used within a Savant system to automatically perform an action based on a change in the value of a system state. A system state can be anything that is monitored by the system, with a corresponding entry that is generated and tracked within Savant State Center (System Monitor > System State). System states include such variables as volume level, component power status (on/off), the current date and time, the status of a particular button, relay, or GPIO, and so on. A state trigger is programmed to monitor a particular state or set of states, and then automatically run action(s) if that state's value changes in a way that meets the set criteria.
Triggers are programmed to operate following If:Then:Else logic. The basic elements of any trigger include monitored state(s), target condition(s), and triggered action(s).
IF | the monitored state(s) changes , and the target condition(s) are met |
THEN | run these actions [any selected workflows or service requests] |
ELSE | if the monitored state changes but the target conditions are *not* met, run these actions [any selected workflows or service requests] |
Understanding this basic underlying logic can make programming even complex state triggers into a straightforward process. The RacePoint Blueprint state trigger engine is an extremely powerful tool, which allows for almost any functionality that can be imagined to be programmed and implemented within a Savant system.
State triggers, along with all other custom RacePoint Blueprint programming, should be configured during the final stages of system deployment after all standard services have been implemented and tested. When configuring any state triggers, it is best to begin planning while access to the live system is available, so that conditional state variables can be chosen after testing to confirm that they change reliably in the expected way. This will ensure a stable foundation on which to build the triggers.
To browse or search a list of available system states and observe their behavior in a live system, open System Monitor for the Savant Host and select System State under the Control heading in the left sidebar menu.
The search field at the upper right corner can be used to filter the states displayed. Observing states and their values in a live system to see how changes occur under different conditions is a key part of planning and programming a state trigger. This should always be done before beginning trigger programming in RacePoint Blueprint.
To view the states available to be used with a trigger within the Blueprint configuration for the system, or to add states to a trigger, open the Services Requests States (SRS) window by clicking the View SRS icon in the top toolbar menu, or clicking the SRS icon in the options menu at the bottom of the state triggers dialog window (see State Triggers Dialog Window section below).
For further specific details regarding the SRS Window, refer to the Services Requests States (SRS) Overview Application Note on the Savant Community Knowledge Base.
Once the relevant state variables have been identified, monitored, and chosen, all other custom programming elements needed for a state trigger should be configured before moving on to trigger programming. Other tools which may be used include:
User-defined State Variables (USV): States other than those generated by the system or a configured component by default. A USV can be of any state type, and can have any desired value written to it. See the User-defined State Variable section in this article below.
Scheduled Events: Used within a state trigger to set an action to run at a given time and/or date. A scheduled event functions as both a monitored state and a target condition, though others can be added in addition as well. See the Scheduled Events section of this article below.
Custom Workflows: Any action or sequence of actions not generated by default in RacePoint Blueprint which are configured manually under the General Programmable Service Requests service category for a Zone. For detailed information, see the article Custom Workflow Development: RacePoint Blueprint Programming Guide.
Once all of the necessary elements have been configured in Blueprint, Generate Services for the configuration, then save a copy of the configuration file before proceeding.
To open the State Triggers dialog window in a RacePoint Blueprint configuration, navigate to: Tools > Review > State Triggers or select the Review Triggers icon from the main toolbar.
The image below shows an example of the State Triggers dialogue for reference. For detailed descriptions of each field, its function, and how to populate it, refer to the subsections below.
Displays all state triggers added to the system, and allows for editing. Groups can be created to organize triggers by function, zone, service, or any other desired parameter.
Group/Trigger displays the name entered during creation. The following actions can be applied here:
Click once to select a trigger and view or edit its details
Double click a trigger or group to edit the name
Click and drag to arrange the order of a trigger or group in the list, or to move triggers in and out of groups.
Enable: The Enable checkbox can be toggled to enable or disable each trigger. This can be useful for system troubleshooting.
Add/Delete Group: Click the (plus) icon next to an existing group to add a new one, or the (minus) icon to delete the group. (Default group cannot be deleted.)
Add/Delete Trigger: Click the (plus) icon next to an existing trigger to add a new one to the same group, or the (minus) icon to delete the trigger.
Description: (Optional) Text can be added here to describe the details or functionality of each group or trigger, or to add any other relevant notes.
Monitored States (When any of these states change...)
This section of the dialog window is a list of the states that will be monitored for changes during operation of the system. Any change to one of the monitored states listed in this section will prompt the system to check current state values in State Center, (viewable by navigating to System Monitor > System State,) against the conditions defined in the If (rules) section.
To populate this field, drag and drop selected states from the Services Requests States (SRS) window. Note that states added to the If (rules) section will automatically populate in the Monitored States field as well, and should be removed if not needed (see section below).
State Name Name of the state as it would appear in a workflow and in System Monitor.
State Scope This field provides a brief identification of the state based on the type of state used. This can be as simple as the zone name or expanded to include the device name.
On Set By default, evaluation of a state only occurs when the value of the state changes. When the On Set checkbox is checked, evaluation of the state will occur when the value is set by a workflow or system action, even if the value does not change.
Delete State Click minus to delete the state.
Helpful Information! if (rules) and Monitored States (When any of these states change...) Interactions:
• States added to the if (rules) section will automatically populate in the Monitored States section as well.
• States deleted from the if (rules) section will NOT be automatically deleted from the Monitored States section.
• States added to the Monitored States section will NOT be automatically added to the if (rules) section.
• While it is often desirable to have the same states listed in both of these sections, there are many cases where they will need to be adjusted.
• States can be removed from any field or section of the State Triggers dialog using the icon in the far right column.
Note on the Use of Time/Date States When adding or removing states in the Monitored States section, extreme caution should be used when creating triggers that evaluate based on current time/date states of any kind. Monitoring based on current time for example will cause the system to review the trigger every second. This can quickly lead to overtaxing of Host resources and failures or undesirable system behaviors. Savant recommends the use of Scheduled Events in place of Date/Time states wherever possible. See the section on Scheduled Events below for more information.
Match [Any/All] of the Following Rules
This dropdown option only appears when multiple conditional states are added to the if (rules) section, and defines how the system will evaluate against those multiple conditional states.
All: The triggered action(s) should only run when all conditions described in the if (rules) section are met.
Any: The triggered action(s) should run if any one of the conditions described in the if (rules) section are met.
If (rules)
This field defines the conditions that will cause the triggered action(s) to be run. When the rules are evaluated, (based on the When any of these states change, evaluate the rules section above,) the system will check the current states against this field. If the conditions described in this section match the values held by the relevant states within the live system, the actions in the Then section will be run.
To populate this field, drag and drop selected states from the Services Requests States (SRS) window. Note that as mentioned above, states added to the If (rules) section will automatically be added to the monitored states as well. In some cases these should be removed from the section above depending on the trigger use case.
State Name: Name of the state as it appears within System Monitor, the SRS window, or as part of a workflow in Automator.
State Scope: Contextual information about the state; generally appears in System Monitor before the State Name. Depending on the particular state, the type of information will vary. Examples include the related zone, service, or component.
Data Type: (Non-selectable, defined by the chosen state) The type of value the system will look for the state to hold when evaluating the trigger:
String | Sequence of characters, (can contain numbers, letters, symbols, or a combination) |
Integer Number | Numbers that do not contain a fractional component. 1, 21, etc. No Decimals. |
Real Number | Numbers that may contain a fractional component. 1.5, 21.34, etc. |
Boolean | Binary variable having two possible values: true or false (1 or 0). |
Date | Date or time. Note that in most cases, Savant recommends using Scheduled Events (see below) in place of Date/Time states for triggers. |
Another State's Value | Relation or comparison to another system state's value |
Test Condition: The modifier defining how the system should compare the value in State Center with the value defined in the Rules. Different options are selectable from this dropdown depending on the state's Data Type:
For string values:
is equal | State value is equal to entered value. |
is not equal | State value is not equal to entered value. |
is less than | State value is less than the entered value.* |
is greater than | State value is greater than the entered value.* |
is less than or equal to | State value is less than or equal to the entered value.* |
is greater or equal to | State value is greater than or equal to the entered value.* |
begins with | State value begins with the entered value. |
does not begin with | State value does not begin with the entered value. |
ends with | State value ends with the entered value. |
does not end with | State value does not end with the entered value. |
contains | Entered value is contained in the states value. |
does not contain | Entered value is not contained in the states value. |
is true | String value evaluates to true.** |
is false | String value evaluates to false.** |
modulo | Finds the remainder of division of one number by another (sometimes called modulus).* |
changes | State value has changed to any value. |
For integer and real values:
is equal | State value is equal to entered value. |
is not equal | State value is not equal to entered value. |
is less than | State value is greater than the entered value. |
is greater than | State value is greater than the entered value. |
is less than or equal to | State value is less than or equal to the entered value. |
is greater or equal to | State value is greater than or equal to the entered value. |
modulo | Finds the remainder of division of one number by another (sometimes called modulus). |
in range | State between the two entered values. |
is true | String value evaluates to true (or 1).** |
is false | String value evaluates to false (or 0).** |
changes | State value has changed to any value. |
For date values:
is equal | State value is equal to entered value. |
is not equal | State value is not equal to entered value. |
is before | State Date is before entered date value. |
is after | State Date is after entered date value. |
in range | State date is between two entered dates. |
in the last | State has occurred in the last # of days. |
not in the last | State has not occurred in the last # of days. |
changes | State value has changed to any value. |
For boolean values:
is true | State value evaluates to true (or 1.) |
is false | State value evaluates to false (or 0.) |
changes | State value has changed to any value. |
*Can only be performed on numerical values. **Can only be performed on boolean values (true or false, 1 or 0.)
Value: The specific value that will be compared to the current system state value based on the Test Condition when the trigger is evaluated.
Offset: (Optional) Used to define a range by which the current state value can differ from the selected value and still satisfy the if (rules) conditions, triggering the Then action. For example, if an Integer state is configured with a Test Condition of equals and a Value of 10 with an Offset of 2, the Rule would be satisfied and trigger the action if the live state had a value anywhere from 8 through 12, (10 offset higher or lower by 2).
Minus button: Click to delete the state entry.
Complex Operators: And | Or | Not
These optional complex operators can be added to the if (rules) section of a trigger to group states together, relate two different values for the same state, and/or define how they will be evaluated when one of the monitored states changes.
Add between two states to run the trigger when both match the target conditions at the same time. | |
Add between two states to run the trigger when either one matches the target conditions. | |
Use to run a trigger when the state immediately following does not match the target conditions | |
Open parenthesis: Add before first state in group, or select more than 1 state and click to group states into a single complex state. | |
Close parenthesis: Add after last state in group to close group, or select a complex state and click to remove parenthesis and ungroup into individual states. |
HELPFUL INFORMATION!: The and, or, and not operator options here are intended to be used within a parenthetical complex, while the Match [Any/All] of the Following Rules dropdown can be used to apply similar logic to the entire section for triggers that don't require complex statements. |
Run the Following Actions
Defines how many times the triggered action(s) in the Then section below will be run:
Once | Action will be performed only once. |
Repeat Every / for # Times | Action repeats with entered number of seconds between intervals, for the entered number of times. |
Repeat Every / Until State | Action repeats with the entered number of seconds between intervals, until the entered state value condition is met. |
Repeat Every / Until false | Action repeats with the entered number of seconds between intervals, until the If (rules) evaluate to false. |
Then Actions
Actions added to this section will be run by the system whenever the monitored states change value and the if (rules) evaluate to true (target conditions are met). Multiple actions can be included here in the form of workflows or state values to be set, and will be run in the order they are listed.
MPORTANT NOTE: The data listed in each column within the Then section will vary based on the type of action (Request, State, or Scene). Headings will show all potential data types when there is no action selected (as shown in the image above). When an action is selected, the column headings will change to reflect its type. |
Request/State/Scene: Name of the added action in order they will execute. For certain request actions, a disclosure triangle will be displayed before the name; click to expand argument options. |
Service/Scope: Similar to the State Scope field of the if (rules) section, provides further information about the action, and will vary depending on its type. Examples include the related Zone, Service, or component. |
Arguments/Data Type: Will display Data Type for a state (set state value action). For requests with arguments, expand the disclosure triangle next to the argument's name to view/set argument info. |
Value: Double-click within this field to enter a value for a set state action or request argument (Expand the disclosure triangle in the name field to view arguments where available). |
After Delay: Double-click this field to add a delay in seconds. Note that any delay added is counted from the start of the trigger execution, not between actions. For example: to run 3 actions with a delay of approximately 5 seconds between each this field should be left at the default of 0 for the first action, and populated with 5, and 10 for the next 2 respectively. |
Override: When checked, the action will not be run. This can be useful for isolation troubleshooting, as it enables the removal of individual actions without the need to reconfigure them later. |
Edit: Click to open a window to edit the action.
|
Minus: Click to remove the action from the list. |
TIP: To send a command to a specific zone rather than a device, drag the action to the Then dialog window, right-click it, and select 'Zone Only'.
Else Actions
The optional Else section allows for the addition of secondary actions which will execute if one of the monitored states changes but the if (rules) evaluate to False, (target conditions are not met.) This is most often used when the if (rules) section contains a boolean state with only 2 possible values (true or false). While this is not a requirement for use of the Else section, often in cases where the conditions are more complex creating a separate trigger for the secondary action(s) is a more effective solution.
All field definitions and functions are the same as those described for the Then section above, except that the actions added will be run when the If (rules) conditions are evaluated as false rather than true.
Dialog Options
The main options which apply to the State Triggers dialog as a whole are available along the bottom of the window.
Programming View: When checked, service names are displayed using the truncated internal format as opposed the the more user-readable default format. For example, with the checkbox enabled, Lighting Control Service would be displayed as SVC_ENV_LIGHTING. This does not affect functionality in any way; it is simply a display preference option. | |
Import/Export Selection: Allows selected triggers or groups to be exported to to a .plist file. | |
Lighting Configuration: Opens the Lighting and Keypad Manager dialog window to allow configuration or editing of wireless lighting. | |
Services/Requests/States - SRS: Opens the Services/Requests/States (SRS) dialog window, for access to all services, states, and workflows generated in the configuration. To add elements to a trigger, click and drag from this window to the desired field of the state trigger dialog. | |
Cancel/Save: Click Cancel to exit the state triggers dialog. Any unsaved changes will be lost. Click Save to save changes and exit. |
Basic Trigger Programming
The following section will walk through the steps to basic trigger programming, using a simple projector lift trigger as an example. For further details and examples of alternate methods of projector lift trigger configuration, refer to Projector Lift Triggers - Blueprint Programming Guide.
In the example below, a trigger will be configured to bring a projector lift down when the Zone has an active video service, or raise the lift to retract the projector when all active video services in the zone are shut off. For the purpose of this example, it is assumed that custom workflows have been preconfigured to run the actions needed to bring the lift up and down. The exact actions required to do so will vary depending on the type of lift and its configuration within the system. For further information on creating custom workflows, refer to Custom Workflow Development: RacePoint Blueprint Programming Guide.
HELPFUL INFORMATION At this point, the trigger to lower the lift when ZoneHasVideo changes to a value of True is functional, however because the conditions are based on a boolean data type state, which can only have a value of True or False, the second function of raising the lift when ZoneHasVideo becomes false can be added using the Elsesection. For more complex triggers, it can be a better option to construct a separate trigger for other functionalities. Use of the Else section is entirely optional. |
Open the State Triggers dialog by navigating to Tools > Review > State Triggers, or by clicking the Review Triggers icon in the RacePoint Blueprint toolbar.
Define a description for the new trigger (optional).
Open the SRS dialog by clicking the SRS Icon at the bottom left of the State Trigger dialog.
In the SRS dialog, select a category, then browse the list or use the search fields to locate the desired state the trigger will operate based on. For this example, the Zone category, Upstairs Media Room zone, and ZoneHasVideo state will be selected.
Click and drag the state from the SRS window into the if (rules) section of the State Triggers dialog.
Set the Test Condition and Value for the state within the if (rules) section to match the conditions that should cause the triggered action to run. In this example, no adjustments are made, and the default Test Condition of equals True is accepted. In this case, no Value statement is required.
Note that the state added to the if (rules) section has also populated in the monitored states list (When any of these states change...). In this example, this is the desired configuration. In a more complex trigger, both fields might be adjusted by adding or removing states as needed.
Return to the SRS dialog to locate the action to populate in the Then section of the trigger. In this example, under the Service Category, General Programmable Service Requests for the Upstairs Media Room zone, and the custom workflow configured to lower the projector is selected.
Drag the selected action into the Then section of the trigger.
Return to the SRS dialog. Under the same Service category and General Programmable Service Requests for the Upstairs Media Room zone, select the custom workflow configured to raise the projector back up into the ceiling, then drag and drop it into the Else section of the state trigger.
In this example, the After Delay field should be populated with the time in seconds that the projector requires to cool down when powering off, to avoid raising it into the ceiling while hot.
Once complete, review the state trigger to check the logic. In the example trigger above:
The system will monitor the state ZoneHasVideo for the Upstairs Media Room zone.
Any time the value of that state changes, the system will check it against the conditions in the if (rules) section.
If ZoneHasVideo for the Upstairs Media Room zone has changed to a value of True, matching the if (rules)...
Then, the system will run the Projector Lift Down workflow.
(Else,) if the ZoneHasVideo state changes but its value has changed to False, meaning it does not match the if (rules) section, the Projector Lift Up workflow will be run after a delay of 300 seconds (5 minutes).
When complete, select Save at the bottom right of the State Triggers dialogue, then save the Blueprint configuration, and upload to the Savant Host to test.
Scheduled Events
The Scheduled Events feature can be utilized within a trigger to have the system evaluate the rules on a chosen schedule, at a particular day or time. To access the Scheduled Events dialog window in RacePoint Blueprint, navigate to Tools > Review > Scheduled Events. Alternatively open the SRS window, then Other > Schedules > (plus) sign.
IMPORTANT NOTE: Before the Scheduled Events dialog can be opened, a Time Zone must be set for the configuration under Tools > Customer and Provider Info. It is also recommended that latitude and longitude be configured, as they are needed for some features of Scheduled Events to function properly, (refer to the Timesubsection below). |
Scheduled Event: | |
Time:
*Note: All Celestial Events, (Dawn, Dusk, Sunrise, Sunset,) require latitude and longitude to be set for the configuration. | |
Frequency:
| |
Date Range: Enable (checkbox) and select a Start Date and End Date to have the set schedule run only within a chosen date range. Enable the Every Year checkbox to have this date range apply continually, ignoring the year in the selected start and end dates. | |
Import/Export: Allows the Import or Export the schedule to a plist file. |
HELPFUL INFORMATION!: In most cases, Scheduled Events can replace any use of Time & Date states, which served a similar function in da Vinci 6.x and below. |
Configuring Zip Code and Location Coordinates
Location data for the configuration is required for certain trigger-related functions, including Scheduled Events, and the use of celestial date/time states. To add the zip code and latitude/longitude coordinates for the site in RacePoint Blueprint, follow the steps below:
Zip Code: Required for configuration of Scheduled Events:
|
Location Coordinates (latitude/longitude): Required for Celestial Date/Time States. To auto-populate, configure zip code first, then:
|
NOTE: The method described above is one way of adding location data to RacePoint Blueprint. For other methods, or more information regarding the Channel Listings Editor or Customer and Provider Info settings, refer to Setting up TV and Radio Favorites: RacePoint Blueprint Programming Guide
User-Defined State Variables
The vast majority of states needed to program a trigger for a Savant System are available by default. However, with more advanced triggers, a User-Defined State Variable (USV) may be required. User-Defined State Variables are states that are not natively supplied by RacePoint Blueprint. Once created, these variables will be available for use in any trigger within that Blueprint configuration. USVs can be written to (given a value) using custom workflows, and used within a state trigger as a variable for a waide range of conditions not tracked by a default state. To create a User-Defined State Variable, go to: Tools > Review > User Defined Variables.
|
Name | The name of the User-State Variable that will appear in the SRS window. |
Type | What data type the User state variable will be. Choose between real, integer, string, boolean, or date. |
Initial Value | The value of the User State Variable the moment the blueprint configuration is uploaded to the host. |
Converts the User State Variable into an Advanced Variable. | |
Add or remove the User State Variable. User State Variables cannot be deleted if they are being used in any field of a trigger. |
Advanced User-Defined State Variables
An Advanced User-Defined State Variable is a state with its value is determined by performing an operation between two or more other states and returning the results as the advanced USV's value. This can be used to make complex triggers with multiple variables more manageable, as it will automatically compare desired states in real time. An example of an Advanced User-Defined State Variable would be a boolean that tracks whether or not the temperature of one zone is higher than the temperature of another.
+ | Adds the value of a state to the state beneath it together and returns the sum as the value of the User State Variable |
- | Subtracts the value of a state from the state beneath it and returns the difference as the value of the User State Variable |
* | Multiplies the value of the state by the state beneath it together and returns the sum as the value of the User State Variable |
/ | Divides a state by another state and returns the difference as the value of the User State Variable |
Min | Compares two states' values and returns the lesser value. |
Max | Compares two states' values and returns the greater value. |
Helpful Information!
|
State Trigger Use Cases:
Triggering a Lighting Scene
To use a Lighting Scene within a trigger, use the ActivateScene or DeactivateScene workflows. Refer to Triggering Lighting Scenes-State Trigger Programming Guide for details.
Triggering a Lift
The Basic Trigger Programming section of this article uses a simple projector lift trigger as an example, however there are a number of different variations and options to choose from for projector lift trigger programming. The same general principles can also be applied to similar configurations such as hidden/motorized display lifts etc. For a list of examples and more in-depth explanations, refer to Projector Lift Triggers - Blueprint Programming Guide.
Using Third-Party Keypads to Control Services
With the proper implementation of state triggers, third party keypads can be used to control services within a Savant System. See How to Control a Service Using a Lighting Controller's Keypad for more information.
Triggering a Switch Screen Action (TrueControl II Only)
Switch Screen actions allow the TrueControl UI to be swapped to specific screens when specific criteria are met. An example would be If a Security Zone has been triggered, swap the TrueControl Screen to the security page. Refer to Triggering a Switch Screen Action for TrueControl II for details.
Using global.SystemHasStarted within a Trigger
This variable can be used to trigger events to occur when the host initially starts up. To learn more about this, refer to the Using global.SystemHasStarted within a State Trigger: Application Note.
Sending an E-mail when a State Changes Value
In order to make a user aware of a change in circumstance or states, such as a security zone being faulted, or the temperature reading in a wine cellar being above a certain point, review the How to Send an Email/SMS Text Notification from a Triggered Workflow article.
Advanced USV Timers and State Persistence as a Trigger Conditional
To use a state trigger and User State Variable (USV) to set a countdown timer for reviewing whether or not a state change is maintained over time, refer to Setting a Countdown Timer with a User State Variable: Application Note. This can be especially useful in triggers for motion sensor activated lighting changes.
Click the to create a new trigger, then enter a name for it.
Advanced User-Defined Variable
