Class ZBus

Examples

zBus.dim(1, 0.0); // Fade to 0% brightness - off
zBus.dim(1, 0.5); // Fade to 50% brightness - off
zBus.dim(1, 1.0); // Fade 100% brightness - on

zBus.dim(1, 0.0, 0.04); // Instant off
zBus.dim(1, 1.0, 160); // Slow "sunrise" fade on within 160 s

zBus.dim([1, 2, 3], 0.5); // Dim multiple lights

This is useful for general Z-Bus system monitoring.

Example

Notifies of all received Z-Bus events:

zBus.receive((event) => {
   //This triggers for any reception
   console.log('Received', event.address, event.event);
});

This is useful for triggering central automations or scenes from a button.

Example

Both variations notify of any Z-Bus receptions of devices set to address 80:

zBus.receive(80, (event) => {
   //This triggers for a reception of any event on the address 80
   //Address and event are passed via the event
   console.log('Received on address', event.address, event.event);
});
zBus.receive(80, () => {
   //This triggers for a reception of any event on the address 80
   console.log('Triggered on address 80');
});

This is useful for triggering similar scenes from different buttons, and for grouping single devices together.

Example

zBus.receive([79, 80], (event) => {
   //This triggers for a reception of any event on either address 79 or 80
   console.log('Received on address', event.address);
});

This is useful for triggering automations with hardware buttons (e.g., for triggering a scene on top of a 'toggle' button press) or for piggybacking automation on top of devices which are individually switched by single device control Commands (e.g. implementing a staircase light group)

Example

Notifies of received combinations of address 1 in combination with the event toggle (or its numeric equivalent 0)

zBus.receive(80, 'toggle', () => {
   //This triggers for a reception of 'toggle' on address 80
   console.log('Central control button pressed');
   zBus.transmit([1, 2, 3], 'on');
});
zBus.receive(15, 0, () => {
   //This triggers for a reception of event 0 == 'toggle' on address 15
   console.log('Individual button pressed, switching entire group on');
   zBus.transmit([15, 16, 17], 'on');
});

This is useful for forwarding a specific set of commands to specific devices

Example

zBus.receive([79, 80], ['toggle', 'on', 'off'], (event) => {
   //This triggers for a reception of the commands 'toggle', 'on', or 'off'
   //on the "central" addresses 79 or 80
   console.log('Received on address', event.address);
});

Forwarding commands to a range of addresses:

function forwardCommand(event) {
    zBus.transmit([0, 1, 2, 3, 4, 5, 6, 7, 8], event.event);
}
zBus.receive(99, ['on', 'off'], forwardCommand);

This is useful for triggering scenes from the app.

Example

zBus.scene('Movie', () => {
   //This scene is triggered when pressing the button named "Movie" in the app
   zBus.transmit(4, 'off'); //Switch the main light off
   zBus.dim([5, 6], 0.2); //Dim both ambient lights to 20%
});

This is useful for triggering scenes both from the app and from a wall switch.

Example

zBus.scene('Movie', 3, () => {
   //This scene is triggered
   // * when pressing the button named "Movie" in the app
   // * when pushing the physical button attached to the sender address 3, event 'toggle'
   zBus.transmit(4, 'off'); //Switch the main light off
   zBus.dim([5, 6], 0.2); //Dim both ambient lights to 20%
});

This is useful for triggering scenes both from the app and from a wall switch.

Example

zBus.scene('Movie', 3, 'toggle', () => {
   //This scene is triggered
   // * when pressing the button named "Movie" in the app
   // * when pushing the physical button attached to the sender address 3, event 'toggle'
   zBus.transmit(4, 'off'); //Switch the main light off
   zBus.dim([5, 6], 0.2); //Dim both ambient lights to 20%
});

Cron-style scheduling

The cron format allows to create complex schedules in a single string, 0 8 * * mon-fri for example defines "Every weekday at 08:00h". Such expressions are parsed by cron-parser and consists of:

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, optional)

Field names	Allowed values
second	0-59 (optional)
minute	0-59
hour	0-23
day of month	1-31
month	1-12 where 1 is January, 2 is February, and so on, or jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, or dec as three-character strings based on the English name of the month
day of week	0-7 where 0 or 7 is Sunday, 1 is Monday, and so on, or mon, tue, wed, thu, fri, sat, or sun as three-character strings based on the English name of the day

For example, the schedule 30 16 1 1 0 runs on 16:30h on the 1st of January, plus on every Sunday in January.

Ranges and lists

Ranges are two numbers separated with a -. For example, the range 8-11 for an hour field executes at hours 8, 9, 10 and 11.

A list is a set of numbers or ranges separated by ,. For example: 1,3,5,7,9 or 8-12,14-18

Unrestricted range

A field can contain an asterisk *, which represents all possible values.

For example, the schedule 30 16 1,15 * * executes at 16:30 on the 1st and 15th of each month.

Step values

Step values can be defined by first-last/step and define a range and an execution interval. For example, to specify event execution every other hour, use 0-23/2. This is equivalent to 0,2,4,6,8,10,12,14,16,18,20,22.

If you specify *∕step the schedule will receive at any step interval. For example, the expression *∕2 will also receive every other hour.

Cron examples

Schedule	Expression
14:10 every Monday	10 14 * * 1
Every day at midnight	0 0 * * *
Every weekday at midnight	0 0 * * 1-5
Midnight on 1st and 15th day of the month	0 0 1,15 * *
18.32 on the 17th, 21st and 29th of November plus each Monday and Wednesday in November each year	32 18 17,21,29 11 mon,wed

Example

zBus.schedule('0 8 * * mon-fri', () => {
  //Blinds up every weekday morning at 08:00h
  zBus.transmit([10, 11, 12, 13, 14, 15], 'up');
});

zBus.transmit(99, 'on');
zBus.transmit(99, 3);

Send address 5, event 'down' (e.g. for blinds)

zBus.transmit(5, 'down');

Send address 1, 2, 3, 4, 5 event 'down' (e.g. for centrally controlling multiple blinds)

zBus.transmit([1, 2, 3, 4, 5], 'down');

Send a data packet:

zBus.transmit(5, 'on', [0x03, 0xFF]);