Creating smart rules


A core piece of nymea's functionality is to wire up your devices and services using rules. For instance, if you've added a remote control and a light, when pressing a button on the remote, nymea should toggle the light. This can be achieved with rules. In nymea:app rules are referred to as magic. In nymea's API and nymea-cli those are referred to by the proper name, which is "Rules". From the main menu, tap the "Magic" button to enter the rules configuration screen.

Magic


This screen will show all the rules added to the system. Initially this list will be empty. Tap the + button in the upper right to start creating a rule.

Actions, events and states

In nymea, each device or service is described by a set of states, actions and events. At the same time, a rule also contains a list of events, conditions on states and a list of actions. For instance, a smart light bulb will have the state "power" which can be either true or false. At the same time it also offers an action to change that state and an event which is triggered whenever the light is powered on or off. All three of those things can be used to create smart rules. A remote control on the other hand, might only have events for "button pressed" but no states or actions.

MagicMagic


How rules are triggered

A rule can contain a list of events and a set of states. There is an important difference between rules that have events and rules which have only states: If a rule contains events, nymea will "wake up" every time a device or service triggers one of the events in that list. As a next step, it will compare all the states in the rule with the actual states in the system. If all the conditions match, nymea will go ahead and execute all the actions in that rule. In nymea, such rules are referred to as event based rules.

If a rule does not have any events, nymea will "wake up" any time time a state in the state conditions is changed. If all the conditions are met, the rule be marked as active, if any of the conditions is not met, the rule will be marked as inactive. Similarly to event based rules getting their name because they contain events, such rules are referred to as state based rules.

Actions and exit actions

Unlike devices and services which only have actions, rules also have exit actions. The behavior of exit actions is a bit different whether they are in an event based rule or in a state based rule.

Event based rules are evaluated every time one of the described events happnes in the system. On that occation, the states are evaluated. If all the states match, the rule's actions are executed. If the states are not matching instead, the rule's exit actions will be executed. An example of a rule could be:

  • the event list contains "remote button pressed"
  • the states are described as "light is off"
  • the action list contains "turn on light"
  • the exit action list contains "turn off light"

This rule's states are evaluated whenever the remote's button is pressed. If the light is off, it will turn the light on. If the light is on already, it will turn it off.

State based rules on the other hand are active or inactive depending on the overall system's state. They don't have any events in their list. An example could be:

  • the states are described as "media player is playing"
  • the action list contains "turn off light"
  • the exit action "turn on light" and "dim light to 50%"

This rule's states are evaluated whenever the media player changes its state. If the media player changes its state to "playing" the action is executed and the light is turned off. If the media player's state is something else (e.g. "Stopped" or "Paused"), the exit actions will be executed and the light is turned on again as well as dimmed to 50%.

Scenes

There is one more form of rules which are rules without any event or states. Those rules only have actions. Such rules also won't have any exit actions. Scenes can be activated in nymea:app and provide a way to control many devices or services with just one click.

Editing a sceneScenes view


Removing rules

In order to remove a rule, open the "Magic" entry from the main menu and swipe on the rule you want to remove. A delete button will become visible allowing you to remove the rule.

Delete a rule