Wb-rules

https://github.com/wirenboard/wb-rules
Admin
Wb-rules is a rule engine designed for Wiren Board controllers, allowing users to program custom...
Tokens:67,471
Snippets:416
Trust Score:9.1
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### RuleEngine start and wait for readiness example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Go example showing how to create a RuleEngine, start it, defer its stop, and wait until the engine is ready (driver ready, cron set up, first retained MQTT values processed) before loading scripts. The ReadyCh() channel is closed when the engine is ready.

```go
engine := wbrules.NewRuleEngine(driver, mqttClient, wbrules.NewRuleEngineOptions())
engine.Start()
defer engine.Stop()

// wait until retained MQTT values are processed before loading scripts
<-engine.ReadyCh()
```

--------------------------------

### Creating and starting an ESEngine with persistent storage

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/03-esengine.md

Shows how to create an ESEngine with a persistent database file, module directories from the WB_RULES_MODULES environment variable, and cleanup on stop. It then starts the engine, defers its stop, and live-loads a rules file. The example assumes a driver and MQTT client are already available.

```go
opts := wbrules.NewESEngineOptions()
opts.SetPersistentDBFile("/var/lib/wirenboard/wbrules-persistent.db")
opts.SetModulesDirs(strings.Split(os.Getenv("WB_RULES_MODULES"), ":"))
opts.SetCleanupOnStop(true)

engine, err := wbrules.NewESEngine(driver, mqttClient, opts)
if err != nil {
	log.Fatalf("error creating engine: %v", err)
}
engine.Start()
defer engine.Stop()

if err := engine.LiveLoadFile("/etc/wb-rules/rules.js"); err != nil {
	log.Printf("error loading script: %s", err)
}
```

--------------------------------

### trackMqtt() example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Example that subscribes to '/devices/wb-adc/controls/+' and logs the topic and value of each incoming message.

```javascript
trackMqtt("/devices/wb-adc/controls/+", function (message) {
  log.info("{} = {}", message.topic, message.value);
});
```

--------------------------------

### Start

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/03-esengine.md

Starts the engine.

```APIDOC
## Start

### Description
Starts the engine. Must be called after construction and before use.

### Method
Method

### Signature
`func (engine *ESEngine) Start()`

### Parameters
None

### Returns
None

### Example
```go
engine.Start()
```

```

--------------------------------

### readConfig() example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Example that reads the configuration file '/etc/wb-rules/alarms.conf' and assigns the parsed object to variable conf.

```javascript
var conf = readConfig("/etc/wb-rules/alarms.conf");
```

--------------------------------

### publish() example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Example call to publish() that sends a message to topic '/abc/def/ghi' with payload '0', QoS 2, and retain flag true.

```javascript
publish("/abc/def/ghi", "0", 2, true);
```

--------------------------------

### Logging usage examples

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Shows how to use log and log.error with format placeholders. The first example logs a device value, the second logs an error message.

```javascript
log("value = {}", dev["wb-gpio/A1_OUT"]);
log.error("something failed: {}", err);
```

--------------------------------

### Example: Extending the Engine in Go

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/05-rule.md

An example showing how to create a rule condition and define a rule using the wb-rules engine in Go.

```APIDOC
## Example: Extending the Engine in Go

### Description
This example demonstrates how to create a rule condition and define a rule using the wb-rules engine in Go.

### Code
```go
cond := wbrules.NewCellChangedRuleCondition(wbrules.ControlSpec{
    DeviceId: "wb-gpio", ControlId: "A1_OUT",
})
rule := wbrules.NewRule(engine, 1, "example", cond, func(args objx.Map) any {
    log.Printf("fired: %v", args)
    return nil
})
id, err := engine.DefineRule(rule, ctx) // ctx *ESContext
```

### Related
- [rule-engine.md](02-rule-engine.md) — `RuleEngine.DefineRule`, `RunRules`, `Refresh`
- [js-global-api.md](07-js-global-api.md) — how these map to JS `defineRule` variants
```

--------------------------------

### NewRuleEngine constructor

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Creates a new RuleEngine instance. Requires a non-nil driver, MQTT client, and options. Panics with 'no options given to NewRuleEngine' if options is nil. The engine is not started until Start() is called.

```go
func NewRuleEngine(driver wbgong.Driver, mqtt wbgong.MQTTClient, options *RuleEngineOptions) (engine *RuleEngine)
```

--------------------------------

### dev access examples

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Shows reading a control value, publishing a value, reading a meta field, and writing a meta field on a virtual device. Comments indicate the MQTT topics involved.

```javascript
if (dev["wb-gpio/A1_OUT"]) {
  dev["buzzer/enabled"] = true;          // publish /devices/buzzer/controls/enabled/on
}
var err = dev["wb-mr3_48/K1#error"];     // meta read
dev["virtdev/cell#units"] = "V";         // meta write on a virtual device
```

--------------------------------

### Example: user module and rule file

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/09-js-modules.md

Complete example of a user module that uses the shipped wb-notify module and a rule file that imports it. The module sends a Telegram message and stores the last text in module.static; the rule triggers on a cell change.

```javascript
// /etc/wb-rules-modules/notifier.js — user module
var Notify = require('wb-notify');
exports.notifyAll = function (text) {
  Notify.sendTelegramMessage(token, chatId, text);
  if (module.static.lastText !== text) {
    module.static.lastText = text;
  }
};
```

```javascript
// /etc/wb-rules/my-rules.js — rule file
var notifier = require('notifier');

defineRule("onAlarm", {
  whenChanged: "somedev/cell",
  then: function (newValue) {
    notifier.notifyAll("cell changed to " + newValue);
  }
});
```

--------------------------------

### Example invocation of wb-rules

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/01-cli.md

Shows a typical command-line invocation with -syslog, -editdir, -http, and rule directories.

```sh
/usr/bin/wb-rules -syslog -editdir /etc/wb-rules/ \
  -http 127.0.0.1:9090 \
  /usr/share/wb-rules-system/rules/ /etc/wb-rules/ /usr/share/wb-rules/
```

--------------------------------

### Go example: extending the engine with DefineRule

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/05-rule.md

Shows how to create a rule condition and define it on the engine. Uses NewCellChangedRuleCondition and NewRule, then calls DefineRule with a context.

```go
cond := wbrules.NewCellChangedRuleCondition(wbrules.ControlSpec{
	DeviceId: "wb-gpio", ControlId: "A1_OUT",
})
rule := wbrules.NewRule(engine, 1, "example", cond, func(args objx.Map) any {
	log.Printf("fired: %v", args)
	return nil
})
id, err := engine.DefineRule(rule, ctx) // ctx *ESContext
```

--------------------------------

### sendEmail usage example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/10-wb-notify.md

Example of sending an email using the wb-notify module. The callback logs an error if sending fails.

```javascript
var Notify = require('wb-notify');
Notify.sendEmail("admin@example.com", "Alarm: {}", "Temperature out of range", function (err) {
  if (err) log.error("send failed: {}", err.message);
});
```

--------------------------------

### normalizeWebhookMethod usage example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/10-wb-notify.md

Example call to normalizeWebhookMethod with a lowercase method string, returning the uppercased method.

```javascript
var m = Notify.normalizeWebhookMethod("post");   // "POST"
```

--------------------------------

### sendWebhook usage example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/10-wb-notify.md

Example call to sendWebhook with a JSON body, custom headers, and a callback. The body object is JSON-stringified and sent via --data-binary @-.

```js
Notify.sendWebhook({
  url: "https://hooks.example.com/abc",
  method: "POST",
  contentType: "application/json",
  headers: { Authorization: "Bearer x" },
  body: { text: "hello" },
}, function (err) { /* ... */ });
```

--------------------------------

### defineRule() usage examples with whenChanged, when, and asSoonAs triggers

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Three examples showing how to define rules using the whenChanged, when (with cron), and asSoonAs triggers.

```javascript
var ruleId = defineRule("example", {
  whenChanged: ["wb-gpio/A1_OUT", "wb-gpio/A2_OUT"],
  then: function (newValue, devName, cellName) {
    log("{}/{} = {}", devName, cellName, newValue);
  }
});

defineRule("hourly", {
  when: cron("@hourly"),
  then: function () { log("hourly"); }
});

defineRule("edge", {
  asSoonAs: function () { return dev["wb-gpio/A1_OUT"]; },
  then: function () { log("A1_OUT switched on"); }
});
```

--------------------------------

### runShellCommand() with captureOutput and exitCallback

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Example of running a shell command with output capture and a callback. The callback receives exit code and captured output; unknown option keys produce a 'spawn: unknown option: <k>' warning.

```javascript
runShellCommand("uname -a", {
  captureOutput: true,
  exitCallback: function (exitCode, capturedOutput) {
    if (exitCode === 0) log(capturedOutput);
  }
});
```

--------------------------------

### Timer usage example: setInterval and startTicker

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Shows how to use setInterval to toggle a device control every 500 ms and clearInterval to stop it. Also shows how to use startTicker to create a named timer and define a rule that triggers when the timer fires, toggling a relay.

```javascript
var id = setInterval(function () {
  dev["buzzer/enabled"] = !dev["buzzer/enabled"];
}, 500);
// ... later
clearInterval(id);

startTicker("clickTimer", 1000);
defineRule("doClick", {
  when: function () { return timers.clickTimer.firing; },
  then: function () { dev["uchm121rx/Relay 0"] = !dev["uchm121rx/Relay 0"]; }
});
```

--------------------------------

### Registering the editor RPC service

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/06-editor.md

Registers the editor RPC service with an MQTT-RPC server. Starts the server and defers its stop. Fatal error if registration fails.

```go
rpc := wbgong.NewMQTTRPCServer("wbrules", engineMqttClient)
err := rpc.Register(wbrules.NewEditor(engine))
if err != nil {
	wbgong.Error.Fatalf("error registering editor: %v", err)
}
rpc.Start()
defer rpc.Stop()
```

--------------------------------

### Print wb-rules version

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/01-cli.md

Prints the build version (set via the -X main.version=... ldflag, e.g. git describe --tags --always --dirty) and exits with status 0. Useful for verifying the installed binary version.

```sh
wb-rules version
```

--------------------------------

### Example request/reply for Save method

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/endpoints.md

Shows a JSON request and reply for the Save editor method. The request includes the file path and content; the reply echoes the saved path. The topic includes a clientId (truncated as 9f8c…).

```json
// request: /rpc/v1/wbrules/Editor/Save/9f8c…
{"id": 1, "params": {"path": "rules.js", "content": "defineRule({...});"}}
// reply: /rpc/v1/wbrules/Editor/Save/9f8c…/reply
{"id": 1, "result": {"path": "rules.js"}}
```

--------------------------------

### Using getDevice and getControl

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/08-js-vdev-api.md

Example usage of getDevice and getControl to obtain a device object and a control (cell) object. The control id must be in the form 'dev/ctrl'.

```javascript
var dev = getDevice("thermostat");
var ctrl = getControl("thermostat/setpoint");
```

--------------------------------

### sendSMS usage examples

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/10-wb-notify.md

Example calls to sendSMS. The first sends a simple SMS. The second uses a custom command with one placeholder for the number and text on stdin, and includes a callback that logs errors.

```js
Notify.sendSMS("+78122128506", "Temperature out of range");
// custom command with text on stdin:
Notify.sendSMS("+78122128506", "hello", "/path/to/sender.py --number {}", function (err) {
  if (err) log.error("{}", err.message);
});
```

--------------------------------

### RuleEngine lifecycle method signatures

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Go method signatures for the RuleEngine lifecycle: Start, Stop, IsActive, ReadyCh, WhenEngineReady, CallSync, MaybeCallSync, and CallHere. These methods manage the engine's startup, shutdown, readiness notification, and synchronous execution of thunks on the single-threaded sync queue.

```go
func (engine *RuleEngine) Start()
func (engine *RuleEngine) Stop()
func (engine *RuleEngine) IsActive() bool
func (engine *RuleEngine) ReadyCh() <-chan struct{}
func (engine *RuleEngine) WhenEngineReady(thunk func())
func (engine *RuleEngine) CallSync(thunk func())
func (engine *RuleEngine) MaybeCallSync(thunk func())
func (engine *RuleEngine) CallHere(thunk func())
```

--------------------------------

### startTicker(name, ms)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Starts a named ticker (repeating timer) without a callback. The ticker can be checked via the `timers` object.

```APIDOC
## startTicker(name, ms)

### Description
Starts a named ticker (repeating timer) without a callback. The ticker can be checked via the `timers` object.

### Method
Function

### Signature
```js
startTicker(name, ms)
```

### Parameters
- **name** (string) - Required - The name of the ticker.
- **ms** (number) - Required - The interval in milliseconds.

### Behavior
- Starts a repeating timer with the given name.
- The ticker's firing state can be checked via `timers.<name>.firing`.
- The ticker can be stopped via `timers.<name>.stop()`.

### Example
```js
startTicker("clickTimer", 1000);
```
```

--------------------------------

### RuleEngine Publish, Log, Logf, and EngineLogLevel constants

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Defines the RuleEngine methods for publishing MQTT messages and logging at various levels, along with the EngineLogLevel type and its constants. Publish starts the MQTT client on first use; Log writes to syslog and publishes to /wbrules/log/debug|info|warning|error, with debug messages only when the Rule debugging switch is enabled.

```go
func (engine *RuleEngine) Publish(topic, payload string, qos byte, retain bool)
func (engine *RuleEngine) Log(level EngineLogLevel, message string)
func (engine *RuleEngine) Logf(level EngineLogLevel, format string, v ...any)

type EngineLogLevel int
const (
	ENGINE_LOG_DEBUG = EngineLogLevel(iota)
	ENGINE_LOG_INFO
	ENGINE_LOG_WARNING
	ENGINE_LOG_ERROR
)
```

--------------------------------

### debian/wb-rules.service systemd unit configuration

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/configuration.md

Systemd unit file for wb-rules. Sets WB_RULES_MODULES, reads optional /etc/default/wb-rules, starts wb-rules with HTTP on 127.0.0.1:9090, syslog, and edit directory, and applies memory limits.

```ini
Environment="WB_RULES_MODULES=/etc/wb-rules-modules:/usr/share/wb-rules-modules"
EnvironmentFile=-/etc/default/wb-rules
ExecStart=/usr/bin/wb-rules $WB_RULES_OPTIONS -http 127.0.0.1:9090 -syslog -editdir '/etc/wb-rules/' \
  '/usr/share/wb-rules-system/rules/' '/etc/wb-rules/' '/usr/share/wb-rules/'
MemoryHigh=30%  MemoryMax=50%
```

--------------------------------

### spawn(cmd, args, options)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Spawns a child process with the given command and arguments. Options control output capture, stdin input, and an exit callback. Unknown option keys produce a warning.

```APIDOC
## spawn(cmd, args, options)

### Description
Spawns a child process with the given command and arguments. Options control output capture, stdin input, and an exit callback. Unknown option keys produce a warning.

### Method
N/A (JavaScript function)

### Endpoint
N/A

### Parameters
#### Parameters
- **cmd** (string) - Required - The command to execute.
- **args** (array) - Required - Array of command-line arguments.
- **options** (object) - Optional - An object with the following properties:
  - **captureOutput** (boolean) - Optional - Default `false` - Capture stdout, pass as string to `exitCallback`.
  - **captureErrorOutput** (boolean) - Optional - Default `false` - Capture stderr; when `false`, stderr goes to the wb-rules process stderr.
  - **input** (string) - Optional - Default `null` - Written to the child's stdin.
  - **exitCallback** (function) - Optional - Default `null` - `function(exitCode, capturedOutput, capturedErrorOutput)`.

### Request Example
```js
spawn("echo", ["hello"], {
  captureOutput: true,
  exitCallback: function (exitCode, capturedOutput) {
    if (exitCode === 0) log(capturedOutput);
  }
});
```

### Response
#### Success Response
No return value. The `exitCallback` is invoked with the exit code and captured output.

#### Error Handling
- Unknown option keys produce a `spawn: unknown option: <k>` warning.
- Callback errors are contained with `error running command callback for <cmd>: ...`.

```

--------------------------------

### sendTelegramMessage usage example

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/10-wb-notify.md

Example call to sendTelegramMessage with a token, chat ID, message text, and options. The options include parseMode and disableNotification.

```javascript
Notify.sendTelegramMessage(
  "1234567890:AAHG7MAKsUHLs-pBLhpIw1RU07Hmw9LyDac",
  "123456789",
  "Alarm: temperature out of range",
  { parseMode: "MarkdownV2", disableNotification: true }
);
```

--------------------------------

### runShellCommand(cmd, options)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Runs a shell command via `/bin/sh -c`. Equivalent to `spawn('/bin/sh', ['-c', cmd], options)`. Options are the same as `spawn`.

```APIDOC
## runShellCommand(cmd, options)

### Description
Runs a shell command via `/bin/sh -c`. Equivalent to `spawn('/bin/sh', ['-c', cmd], options)`. Options are the same as `spawn`.

### Method
N/A (JavaScript function)

### Endpoint
N/A

### Parameters
#### Parameters
- **cmd** (string) - Required - The shell command to execute.
- **options** (object) - Optional - An object with the following properties:
  - **captureOutput** (boolean) - Optional - Default `false` - Capture stdout, pass as string to `exitCallback`.
  - **captureErrorOutput** (boolean) - Optional - Default `false` - Capture stderr; when `false`, stderr goes to the wb-rules process stderr.
  - **input** (string) - Optional - Default `null` - Written to the child's stdin.
  - **exitCallback** (function) - Optional - Default `null` - `function(exitCode, capturedOutput, capturedErrorOutput)`.

### Request Example
```js
runShellCommand("uname -a", {
  captureOutput: true,
  exitCallback: function (exitCode, capturedOutput) {
    if (exitCode === 0) log(capturedOutput);
  }
});
```

### Response
#### Success Response
No return value. The `exitCallback` is invoked with the exit code and captured output.

#### Error Handling
- Unknown option keys produce a `spawn: unknown option: <k>` warning.
- Callback errors are contained with `error running command callback for <cmd>: ...`.

```

--------------------------------

### startTimer(name, ms)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Starts a named timer without a callback. The timer can be checked via the `timers` object.

```APIDOC
## startTimer(name, ms)

### Description
Starts a named timer without a callback. The timer can be checked via the `timers` object.

### Method
Function

### Signature
```js
startTimer(name, ms)
```

### Parameters
- **name** (string) - Required - The name of the timer.
- **ms** (number) - Required - The delay in milliseconds.

### Behavior
- Starts a timer with the given name.
- The timer's firing state can be checked via `timers.<name>.firing`.
- The timer can be stopped via `timers.<name>.stop()`.

### Example
```js
startTimer("myTimer", 1000);
```
```

--------------------------------

### DefineVirtualDevice and control management methods

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Methods for defining a virtual device and adding/removing controls. DefineVirtualDevice creates a local device from a description map; AddControl/RemoveControl only work on existing local devices and return wbgong.ExternalDeviceError otherwise. GetDevice returns wbgong.DeviceNotExistError if the device is missing.

```go
func (engine *RuleEngine) DefineVirtualDevice(devId string, obj objx.Map) error
func (engine *RuleEngine) AddControl(devID, ctrlID string, ctrlDef objx.Map) error
func (engine *RuleEngine) RemoveControl(devID, ctrlID string) error
func (engine *RuleEngine) GetDevice(devId string) error
func (engine *RuleEngine) GetDeviceProxy(name string) *DeviceProxy
func (engine *RuleEngine) GetDeviceProxyCacheSize() int
func (engine *RuleEngine) Driver() wbgong.Driver
```

--------------------------------

### setInterval(callback, ms)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Starts a timer that calls the callback repeatedly at the specified interval. Returns a positive integer timer id.

```APIDOC
## setInterval(callback, ms)

### Description
Starts a timer that calls the callback repeatedly at the specified interval. Returns a positive integer timer id.

### Method
Function

### Signature
```js
setInterval(callback, ms)
```

### Parameters
- **callback** (function) - Required - The function to call each time the interval fires.
- **ms** (number) - Required - The interval in milliseconds.

### Returns
- **timerId** (number) - A positive integer timer id that can be used with `clearInterval`.

### Behavior
- The callback runs on the rule sync queue.
- Intervals below 1 ms are clamped to 1 ms.
- Periodic intervals ≤ 10 ms log a performance warning.

### Example
```js
var id = setInterval(function () {
  // do something repeatedly
}, 500);
```
```

--------------------------------

### setTimeout(callback, ms)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Starts a timer that calls the callback after the specified number of milliseconds. Returns a positive integer timer id.

```APIDOC
## setTimeout(callback, ms)

### Description
Starts a timer that calls the callback after the specified number of milliseconds. Returns a positive integer timer id.

### Method
Function

### Signature
```js
setTimeout(callback, ms)
```

### Parameters
- **callback** (function) - Required - The function to call when the timer fires.
- **ms** (number) - Required - The delay in milliseconds.

### Returns
- **timerId** (number) - A positive integer timer id that can be used with `clearTimeout`.

### Behavior
- The callback runs on the rule sync queue.
- Intervals below 1 ms are clamped to 1 ms.

### Example
```js
var id = setTimeout(function () {
  // do something
}, 1000);
```
```

--------------------------------

### RuleEngine Constructor and Options

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Documentation for the RuleEngine constructor and RuleEngineOptions type.

```APIDOC
## NewRuleEngine

### Description
Creates a new RuleEngine instance. The engine is not started until Start() is called.

### Signature
func NewRuleEngine(driver wbgong.Driver, mqtt wbgong.MQTTClient, options *RuleEngineOptions) (engine *RuleEngine)

### Parameters
- **driver** (wbgong.Driver) - Required - wbgong driver that owns the MQTT device topic tree (/devices/...)
- **mqtt** (wbgong.MQTTClient) - Required - MQTT client used for service topics (/wbrules/...), log publishing and MQTT trackers
- **options** (*RuleEngineOptions) - Required - must be non-nil, otherwise the function panics with "no options given to NewRuleEngine"

### Returns
- **engine** (*RuleEngine) - The new RuleEngine instance

### Source
wbrules/engine.go:700
```

```APIDOC
## RuleEngineOptions

### Description
Options for configuring a RuleEngine. Use the constructor and setters to create and modify options.

### Constructor
func NewRuleEngineOptions() *RuleEngineOptions

### Methods
- **SetTesting(v bool) *RuleEngineOptions** - Sets debugQueues. When true, disables internal event buffering/queueing (test mode). Default: false.
- **SetCleanupOnStop(v bool) *RuleEngineOptions** - Sets cleanupOnStop. When true, all registered cleanups are run on Stop() (removes devices defined by rules, unsubscribes MQTT trackers). Default: false.

### Source
wbrules/engine.go:612-632
```

--------------------------------

### Constants defined in main.go:18-33

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/01-cli.md

Defines client IDs, database file paths, module environment variable, and broker URL used by the wb-rules binary.

```go
DRIVER_CLIENT_ID = "rules"
DRIVER_CONV_ID   = "wb-rules"
ENGINE_CLIENT_ID = "wb-rules-engine"
RPC_DRIVER_NAME  = "wbrules"

PERSISTENT_DB_FILE      = "/var/lib/wirenboard/wbrules-persistent.db"
VIRTUAL_DEVICES_DB_FILE = "/var/lib/wirenboard/wbrules-vdev.db"
WBGO_FILE               = "/usr/lib/wb-rules/wbgo.so"

WBRULES_MODULES_ENV = "WB_RULES_MODULES"

MOSQUITTO_SOCK_FILE = "/var/run/mosquitto/mosquitto.sock"
DEFAULT_BROKER_URL  = "tcp://localhost:1883"
```

--------------------------------

### NewESEngine

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/03-esengine.md

Constructor for ESEngine.

```APIDOC
## NewESEngine

### Description
Creates a new `ESEngine` instance with the given driver, MQTT client, and options. It initializes the global context, loads the runtime library, and prepares the engine for use.

### Method
Constructor

### Signature
`func NewESEngine(driver wbgong.Driver, logMqttClient wbgong.MQTTClient, options *ESEngineOptions) (engine *ESEngine, err error)`

### Parameters
- **driver** (wbgong.Driver) - Required - The driver to use for the engine.
- **logMqttClient** (wbgong.MQTTClient) - Required - The MQTT client for logging.
- **options** (*ESEngineOptions) - Required - The engine options. Must not be nil.

### Returns
- **engine** (*ESEngine) - The created engine.
- **err** (error) - An error if construction fails.

### Example
```go
engine, err := wbrules.NewESEngine(driver, mqttClient, opts)
if err != nil {
    log.Fatalf("error creating engine: %v", err)
}
```

```

--------------------------------

### spawn() and runShellCommand() signatures

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Shows the signatures for spawn() and runShellCommand(). runShellCommand is a wrapper for spawn('/bin/sh', ['-c', cmd], options).

```javascript
spawn(cmd, args, options)
runShellCommand(cmd, options)   // spawn('/bin/sh', ['-c', cmd], options)
```

--------------------------------

### defineAlias() function signature and usage

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/07-js-global-api.md

Shows the internal signature of defineAlias() and a usage example. Invalid arguments throw 'invalid alias definition'; malformed references throw 'invalid cell reference'.

```javascript
var defineAlias = _WbRules.defineAlias;   // lib.js:360
// _WbRules.defineAlias defined at lib.js:141
defineAlias(name, "device/param")
```

```javascript
defineAlias("heaterRelayOn", "Relays/Relay 1");
defineAlias("roomTemp", "Weather/Temp 1");
if (roomTemp < 20) heaterRelayOn = true;
```

--------------------------------

### ESEngine source management methods

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/03-esengine.md

Method signatures for managing rule source files in the ESEngine. Use these to set the source root, list editable files, load or reload scripts, write scripts atomically, and remove files. LiveLoadFile skips reload if content is unchanged; LiveWriteScript forces reload and errors if the path escapes the source root.

```go
func (engine *ESEngine) ScriptDir() string
func (engine *ESEngine) SetSourceRoot(sourceRoot string) (err error)
func (engine *ESEngine) ListSourceFiles() (entries []LocFileEntry, err error)
func (engine *ESEngine) LoadFile(path string) (err error)
func (engine *ESEngine) LiveLoadFile(path string) error
func (engine *ESEngine) LiveWriteScript(virtualPath, content string) error
func (engine *ESEngine) LiveRemoveFile(path string) error
```

--------------------------------

### Define virtual device 'thermostat' with cells

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/08-js-vdev-api.md

Example of defining a virtual device named 'thermostat' with a switch, a range control, and a value control with an enum. The title is localized in English and Russian. The range control has min, max, and precision set.

```javascript
defineVirtualDevice("thermostat", {
  title: { en: "Thermostat", ru: "Термостат" },
  cells: {
    enabled: { type: "switch", value: false },
    setpoint: { type: "range", value: 22, min: 5, max: 30, precision: 1 },
    state: {
      type: "value",
      value: 0,
      enum: { 0: { en: "Off", ru: "Выкл" }, 1: { en: "Heating", ru: "Нагрев" } },
    },
  },
});
```

--------------------------------

### NewESEngineOptions

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/03-esengine.md

Constructor for ESEngineOptions.

```APIDOC
## NewESEngineOptions

### Description
Creates a new `ESEngineOptions` struct with default values.

### Method
Constructor

### Signature
`func NewESEngineOptions() *ESEngineOptions`

### Parameters
None

### Returns
- **`*ESEngineOptions`** - A pointer to the newly created options struct.

### Example
```go
opts := wbrules.NewESEngineOptions()
```

```

--------------------------------

### EvalScript function for script evaluation

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/03-esengine.md

Evaluates code on the global context via the sync queue and returns the resulting ESError or ScriptError. Adopted by runJS internal tests; usable to execute setup code in the engine's global scope.

```go
func (engine *ESEngine) EvalScript(code string) error
```

--------------------------------

### sendWebhook function signature

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/10-wb-notify.md

Function signature for the sendWebhook API. The opts object requires a url; method defaults to POST and must be one of GET, POST, PUT, PATCH, DELETE. Executed via curl -sS --fail.

```js
exports.sendWebhook = function (opts, callback)
```

--------------------------------

### defineVirtualDevice(name, deviceDef)

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/08-js-vdev-api.md

Defines a new virtual device with the given name and device definition. The device definition includes title and cells/controls. Returns a device object. Throws an Error if the name is empty or definition fails.

```APIDOC
## defineVirtualDevice(name, deviceDef)

### Description
Defines a new virtual device with the given name and device definition. The device definition includes title and cells/controls. Returns a device object. Throws an Error if the name is empty or definition fails.

### Method
N/A (JavaScript function)

### Endpoint
N/A

### Parameters
#### Parameters
- **name** (string) - Required - Device id used in MQTT topics (`/devices/<name>/...`). Device names are required (throws otherwise).
- **deviceDef** (object) - Required - Device description. Fields:
  - `title` (string | {lang: string}) - Device title (`/devices/<id>/meta/name`); string form maps to `"en"`.
  - `cells` (object) - Map control-name → control description (equivalent to `controls`).
  - `controls` (object) - Alias of `cells`, mutually exclusive usage.

Control description fields:
- `title` (string | {lang: string}) - Control title (`.../meta/title`).
- `type` (string) - **required** - Wiren Board control type (`switch`, `pushbutton`, `range`, `value`, `text`, `alarm`, `rgb`, ...).
- `value` (any) - Default value (`.../controls/<ctrl>`); required for all types except `pushbutton`.
- `readonly` (boolean) - Read-only flag (`.../meta/readonly`). Default: `false` for `switch`/`pushbutton`/`range`/`rgb`, `true` otherwise.
- `writeable` (boolean) - **deprecated** - Presence causes load failure: `writeable flag is deprecated, use readonly instead`.
- `forceDefault` (boolean) - When `true` the default value is always applied at startup; otherwise the last saved value (from the values DB) is restored. Default: `false`.
- `lazyInit` (boolean) - When `true` the control is created in MQTT only after the first write. Default: `false`.
- `max` / `min` (number) - Numeric bounds for `value`/`range`. Default: `255` / `0` for `range`.
- `precision` (number) - Decimal places for `value`/`range`.
- `units` (string) - Units for `value` (`.../meta/units`).
- `enum` (object) - Named values: `{value: string|{lang: string}}` for `value`/`text`; numeric keys must be decimal/hex strings.
- `description` (string) - Control description (`.../meta/description`).
- `order` (number) - Display order (non-negative integer).

### Request Example
```js
defineVirtualDevice("thermostat", {
  title: { en: "Thermostat", ru: "Термостат" },
  cells: {
    enabled: { type: "switch", value: false },
    setpoint: { type: "range", value: 22, min: 5, max: 30, precision: 1 },
    state: {
      type: "value",
      value: 0,
      enum: { 0: { en: "Off", ru: "Выкл" }, 1: { en: "Heating", ru: "Нагрев" } },
    },
  },
});
```

### Response
#### Success Response
- Returns a device object (prototype `__wbVdevPrototype`) with `__deviceId` set.

#### Response Example
N/A (function returns a device object, no JSON response)

```

--------------------------------

### RuleEngineOptions struct

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/types.md

Options for the rule engine. See configuration.md for details.

```go
type RuleEngineOptions struct {
	debugQueues   bool
	cleanupOnStop bool
}
```

--------------------------------

### ScriptError struct definition

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/errors.md

Defines the ScriptError type in Go, an ESError translated to virtual paths. Frames outside the source root are dropped; syntax errors get their line from the message pattern ^SyntaxError:.*?\(line\s+(\d+)\). Triggered by any JS error while loading a rule file in ESEngine.loadScript (wbrules/esengine.go:739, via trackESError :809). The error is stored on the file's LocFileEntry.Error and also returned by LiveLoadFile/LiveWriteScript.

```go
type ScriptError struct {
	Message   string    `json:"message"`
	Traceback []LocItem `json:"traceback"`
}
func NewScriptError(message string, traceback []LocItem) ScriptError
func (err ScriptError) Error() string
```

--------------------------------

### DeviceProxy and ControlProxy type definitions and methods

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Defines the DeviceProxy and ControlProxy types and their methods for interacting with controls. EnsureControlProxy returns a ControlProxy for a control ID; Value returns the typed cached value or nil for missing controls; SetValue writes to the control and never throws on failure; SetMeta writes meta fields only for local devices; IsComplete checks if value and meta/type have been received.

```go
type DeviceProxy struct { ... }
type ControlProxy struct { ... }

func (devProxy *DeviceProxy) EnsureControlProxy(ctrlId string) *ControlProxy
func (ctrlProxy *ControlProxy) Value() (v any)
func (ctrlProxy *ControlProxy) RawValue() (v string)
func (ctrlProxy *ControlProxy) SetValue(value any, notifySubs bool) error
func (ctrlProxy *ControlProxy) SetMeta(key, metaValue string) *ControlChangeEvent
func (ctrlProxy *ControlProxy) GetMeta() (m wbgong.MetaInfo)
func (ctrlProxy *ControlProxy) IsComplete() (v bool)
```

--------------------------------

### List

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/endpoints.md

Lists all rule files in the editor source root. Returns an array of file entries with metadata such as path, enabled state, load errors, and defined rules/devices/timers.

```APIDOC
## MQTT-RPC List

### Description
Lists all rule files in the editor source root. Returns an array of file entries with metadata such as path, enabled state, load errors, and defined rules/devices/timers.

### Method
MQTT-RPC

### Topic
`/rpc/v1/wbrules/Editor/List/{clientId}`

### Parameters
#### Request Params
- (none) - empty object `{}`

### Request Example
```json
{"id": 1, "params": {}}
```

### Response
#### Success Response
- **result** (array of LocFileEntry) - Array of file entries
  - **virtualPath** (string) - Relative path under the source root
  - **enabled** (boolean) - `false` when the file has the `.disabled` suffix
  - **error** (object, optional) - `{ message: string, traceback: [{line, name}] }` - last load error
  - **rules** (array of {line, name}) - Items defined by the file with their source lines
  - **devices** (array of {line, name}) - Items defined by the file with their source lines
  - **timers** (array of {line, name}) - Items defined by the file with their source lines

#### Response Example
```json
{"id": 1, "result": [{"virtualPath": "rules.js", "enabled": true}]}
```
```

--------------------------------

### Load RPC handler with argument and response types

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/06-editor.md

Defines EditorPathArgs and EditorContentResponse types and the Load handler signature. Returns file content, enabled state, and last load error.

```go
type EditorPathArgs struct {
	Path string `json:"path"`
}

type EditorContentResponse struct {
	Content string       `json:"content"`
	Enabled bool         `json:"enabled"`
	Error   *ScriptError `json:"error,omitempty"`
}

func (editor *Editor) Load(args *EditorPathArgs, reply *EditorContentResponse) error
```

--------------------------------

### RuleEngine Lifecycle Methods

Source: https://github.com/wirenboard/wb-rules/blob/master/_autodocs/api-reference/02-rule-engine.md

Lifecycle methods for the RuleEngine, including start/stop, readiness, and synchronous execution helpers.

```APIDOC
## Start

### Description
Starts the internal sync loop (`syncLoop`) and the main loop (`mainLoop`). The main loop waits for the driver to become ready, then sets up cron, marks the deferred queues ready, closes `readyCh` and starts processing `ControlChangeEvent`s from the event buffer.

### Method
Start

### Signature
`func (engine *RuleEngine) Start()`

### Parameters
None

### Returns
None

### Example
```go
engine := wbrules.NewRuleEngine(driver, mqttClient, wbrules.NewRuleEngineOptions())
engine.Start()
```

## Stop

### Description
Stops timers/rules per `cleanupOnStop`, then shuts the loops down.

### Method
Stop

### Signature
`func (engine *RuleEngine) Stop()`

### Parameters
None

### Returns
None

### Example
```go
defer engine.Stop()
```

## IsActive

### Description
Returns whether the engine is active.

### Method
IsActive

### Signature
`func (engine *RuleEngine) IsActive() bool`

### Parameters
None

### Returns
- **bool** - `true` if the engine is active, `false` otherwise.

## ReadyCh

### Description
Returns a channel that is closed when the engine is ready (driver ready, cron set up, first retained MQTT values processed). Panics if called before `Start()`.

### Method
ReadyCh

### Signature
`func (engine *RuleEngine) ReadyCh() <-chan struct{}`

### Parameters
None

### Returns
- **<-chan struct{}** - A channel that is closed when the engine is ready.

### Example
```go
<-engine.ReadyCh()
```

## WhenEngineReady

### Description
Runs `thunk` synchronously if the engine is ready, otherwise defers it until readiness.

### Method
WhenEngineReady

### Signature
`func (engine *RuleEngine) WhenEngineReady(thunk func())`

### Parameters
- **thunk** (func()) - Required - The function to execute when the engine is ready.

### Returns
None

## CallSync

### Description
Queues `thunk` on the single-threaded sync queue; every JS/rule operation runs on this queue, so rules never race. When debug mode is enabled a 120 s timeout (`ENGINE_CALLSYNC_TIMEOUT`) guards against a stuck queue.

### Method
CallSync

### Signature
`func (engine *RuleEngine) CallSync(thunk func())`

### Parameters
- **thunk** (func()) - Required - The function to execute on the sync queue.

### Returns
None

## MaybeCallSync

### Description
`CallSync` when the sync queue is active, otherwise executes `thunk` immediately.

### Method
MaybeCallSync

### Signature
`func (engine *RuleEngine) MaybeCallSync(thunk func())`

### Parameters
- **thunk** (func()) - Required - The function to execute.

### Returns
None

## CallHere

### Description
Executes `thunk` immediately in the calling goroutine.

### Method
CallHere

### Signature
`func (engine *RuleEngine) CallHere(thunk func())`

### Parameters
- **thunk** (func()) - Required - The function to execute.

### Returns
None
```
Tokens:
Raw