Scenarios

Other languages:

English
русский

General information

If the package did not install on the controller after an update, try updating it as follows:

apt update && apt full-upgrade

Scenarios (wb-scenarios) is a firmware package for the Wiren Board controller, comprising modules on top of the wb-rules engine and a visual configurator for connecting and configuring these modules in the graphical interface. The source code is open and available in our repository. There you can also find more details about how the package works and how to configure the ready-made templates.

Topics used in scenarios must follow the Wiren Board MQTT Conventions.

How to create a scenario in the web interface

Go to Rules → Scenarios.
Click + Scenario.
Choose and configure a scenario template.
Click Save.

Creating a scenario
Scenarios menu location
Empty scenarios window
Scenarios

A virtual device is created for each scenario, which lets you enable or disable the scenario.

Scenario virtual devices
Device control
Light control
Thermostat

When working with scenarios you can enable debug mode. It is enabled the same way as when writing wb-rules scripts.

Built-in scenarios

«If-Then» Automation

«If-Then» virtual device

The scenario template creates automation following the "Event — Action" pattern; suitable for most simple tasks. Use cases:

controlling outputs of one module from inputs of another;
master switch — turning off all lights in the rooms with a single tap;
two-way switch — controlling one light fixture from several different switches.

«If-Then» configurator

Light control

Light control virtual device

This scenario automatically turns on the light in transit rooms (for example, a hallway, bathroom, or storage room). The light comes on by itself when you open the door, walk in (the motion sensor triggers), or press the switch.

Light control configurator

Thermostat

Thermostat virtual device

The scenario reads data from a temperature sensor and manages heating or cooling on its own. It only works with discrete outputs — devices that can only be switched on and off (for example, ordinary relays or two-position valves on radiators).

Two operating modes are available:

Hysteresis (simple) — classic on/off switching. You set the bounds yourself: for example, turn the heater on at 20 °C and off at 22 °C.
PID Controller (smart) — the most precise temperature control without overshoots. The system calculates how quickly the room heats up or cools down and delivers heat in measured amounts. This helps avoid temperature swings and saves the equipment from constant relay chattering.

Thermostat configurator (Hysteresis)
Thermostat configurator (PID)

Schedule

Schedule virtual device

This scenario performs the configured actions on a schedule: on the specified days of the week and at exact times.

Important: before configuring, make sure that the timezone and current time are set correctly on the controller.

Schedule configurator

Astronomical Timer

Astronomical Timer virtual device

This scenario triggers actions depending on the position of the sun. You can bind your automation to any of the available astronomical events:

Main: Sunrise and Sunset;
Dawns (morning): Civil (-6°), Nautical (-12°), Astronomical (-18°);
Dusks (evening): Civil (-6°), Nautical (-12°), Astronomical (-18°);
Cinematic light: Golden Hour (evening, +6°) and End of Golden Hour (morning, +6°);
Peak points: Solar Noon and Nadir (the darkest moment of the night).

You can configure the trigger to fire exactly at the moment of an event or add an offset (for example, close the curtains 30 minutes before sunset). It is the perfect solution for controlling outdoor lighting, blinds, and other seasonal automation. The calculations happen locally on the controller — no internet connection is required.

Important: for everything to work accurately, set the geographic coordinates of your home and make sure that the time and timezone are set correctly on the controller.

Astronomical Timer configurator

Periodic Timer

Periodic Timer virtual device

This scenario periodically turns devices on and off. You set the overall operating "window" (for example, from 8:00 to 20:00), and you also specify how often and for how long the devices should run (for example, "turn on every 2 hours for 15 minutes"). After each run the devices turn off automatically.

It is a great fit for automatic watering, periodic ventilation, and any other tasks that require cyclic operation.

Important: before configuring, make sure that the current time and timezone are set correctly on the controller.

Periodic Timer configurator

Channel Mapping

Channel Mapping virtual device

The scenario links two parameters (MQTT channels) to each other. When the value changes in one channel, the system instantly copies it to the other.

If the channel types differ, the value is converted to the type of the target channel:

Numeric (range, value, temperature, etc.). The string "3.14" is converted to the number 3.14. A non-numeric string becomes 0. The values true and false are converted to 1 and 0 respectively;
Boolean (switch, alarm). Becomes false if the input is 0, an empty string, or the string "false" or "0" (in any case). Any other value is converted to true;
String (text, rgb). Any data (numbers or booleans) is converted to its text equivalent. The number 3.14 is converted to the string "3.14", and true becomes "true".

Channel Mapping configurator

PID controller (analog outputs)

PID controller virtual device

The scenario implements a PID controller for precise maintenance of a target value (setpoint) using analog outputs.

Use cases:

controlling a valve for underfloor heating or radiator heating;
adjusting the position of an air damper in a ventilation system;
controlling any analog actuator (0–10 V, 0–100 %).

The scenario computes the PID output (0–100 %) from sensor readings and the setpoint, then rescales it into actuator units according to the configured minimum and maximum. Both direct and reverse (inverted) operation modes are supported. Several actuators can be connected simultaneously.

PID controller configurator

Using scenario modules in wb-rules

Each scenario is implemented as a wb-rules module — this lets you include the modules in your rules and use scenarios as a JS library.

Every scenario has its own README.md file on GitHub with detailed usage examples and code templates:

General algorithm for using any scenario:

Import the module: var CustomTypeSc = require('thermostat.mod').ThermostatScenario;
Create a new instance of the scenario class var scenario = new CustomTypeSc()
Create a configuration object for the future scenario var cfg = {...required fields here...}
Initialize the scenario scenario.init(scenarioName, cfg);

Example code for creating a thermostat scenario:

/**
 * @file: init-heating.js
 */

// Step 1: import module
var CustomTypeSc = require('thermostat.mod').ThermostatScenario;

function main() {
  var scenarioName = 'Bathroom: heat floor';
  log.debug('Start init logic for: "{}"', scenarioName);

  // Step 2: Create new instance with scenario class
  var scenario = new CustomTypeSc();

  // Step 3: Configure algorithm
  var cfg = {
    idPrefix: 'bathroom_floor', // Optional parameter, can be omitted
    targetTemp: 22,
    tempLimitsMin: 16,
    tempLimitsMax: 29,
    hysteresis: 2,
    tempSensor: 'wb-msw-v4_34/Temperature',
    actuator: 'wb-mr6cv3_127/K6',
  };

  // Step 4: init algorithm
  try {
    var isInitSuccess = scenario.init(scenarioName, cfg);

    if (!isInitSuccess) {
      log.error('Init operation aborted for scenario: "{}"', scenarioName);
      return;
    }

    log.debug('Initialization successful for: "{}"', scenarioName);
  } catch (error) {
    log.error(
      'Exception during scenario initialization: "{}" for scenario: "{}"',
      error.message || error,
      scenarioName
    );
  }
}

main();

Known issues

Errata and caveats encountered during use.

Navigation menu