Homey RFDriver

This module helps developers create RF (433MHz, 868MHz, Infrared) apps for Homey.

This module requires Homey Apps SDK v3.

Documentation

Documentation is available at https://athombv.github.io/node-homey-rfdriver/.

Related Modules

• node-homey-zwavedriver — Module for Z-Wave drivers
• node-homey-zigbeedriver — Module for Zigbee drivers
• node-homey-oauth2app — Module for OAuth2 apps
• node-homey-log — Module to log unhandled errors to Sentry

Installation

$ npm install homey-rfdriver

Requirements

• This module requires Homey Apps SDK v3.
• Your app needs permission for either homey:wireless:433 or homey:wireless:ir.

Usage

Both your driver and device should extend RFDriver and RFDevice. RFDriver should then reference another class that extends RFSignal.

A typical app might have these files:

/.homeycompose/signals/433/my_signal.json
/lib/MySignal.js (extends RFSignal)
/drivers/my_driver/driver.js (extends RFDriver)
/drivers/my_driver/device.js (extends RFDevice)
/drivers/my_driver/pair/rf_receiver_learn.html
/drivers/my_driver/pair/rf_receiver_add.html
/drivers/my_driver/pair/image.svg

Your driver can be either a transmitter (e.g. a remote) or a receiver (e.g. a light or socket switch).

You should copy the corresponding files from this module's /pair folder to your driver's /pair folder.

RFSignal

Imagine we have a simple 433 MHz protocol that first sends the address (1 byte) and then the on/off state (1 byte, 0x00 for off, 0xFF for on).

Our signal definition must be added to /.homeycompose/signals/433/my_signal.json. Refer to the Signal Documentation for more information on how to create a signal.

Your JSON describes how to encode and decode the low & high signals into bits. The RFSignal you define here will parse these bits (or bytes) from and to JavaScript objects.

/lib/MySignal.js

'use strict';

const { RFSignal, RFError, RFUtil } = require('homey-rfdriver');

// Protocol:
// [ 0x00 - 0xFF, 0x00 | 0xFF ]
// [ address    , state       ]

module.exports = class MySignal extends RFSignal {

  static FREQUENCY = '433';
  static ID = 'my_signal';

  // This method converts a JavaScript object command
  // into a payload for our signal.
  static commandToPayload({ address, state }) {
    if( typeof address !== 'number' )
      throw new RFError('Invalid Address');

    if( typeof state !== 'boolean' )
      throw new RFError('Invalid State');
      
    return [ address, state ? 0x00 : 0xFF ];
  }

  // This method converts a received payload
  // into a JavaScript object command.
  static payloadToCommand(payload) {
    const address = Number(payload[0]);
    const state = Boolean(payload[1]);
    return { address, state };
  }

  // This method takes a command object
  // and returns a device-unique data object
  static commandToDeviceData(command) {
    return {
      address: command.address,
    };
  }

  // This method is invoked when a new receiver is added
  // We can generate a random address, as if someone pressed
  // the button on a remote.
  static createPairCommand() {
    return {
      address: Math.round(Math.random() * 255),
      state: true,
    };
  }

}

RFDriver

/drivers/my_driver/driver.js

const { RFDriver } = require('homey-rfdriver');
const MySignal = require('../../lib/MySignal');

module.exports = class MyDriver extends RFDriver {

  static SIGNAL = MySignal;

}

Transmitter

Copy /pair/rf_transmitter_learn.html to your driver's /pair folder.

Then add this to your /drivers/<driver_id>/driver.compose.json:

"rf433": { // Or `infrared`
  "satelliteMode": true
},
"pair": [
  {
    "id": "rf_transmitter_learn",
    "options": {
      "title": {
        "en": "Press any button"
      },
      "instruction": {
        "en": "Press any button on your device."
      }
    }
  }
]

Receiver

Copy /pair/rf_receiver_learn.html and /pair/rf_receiver_add.html to your driver's /pair folder.

Then add this to your /drivers/<driver_id>/driver.compose.json:

"pair": [
  {
    "id": "rf_receiver_learn",
    "navigation": {
      "next": "rf_receiver_add"
    },
    "options": {
      "title": {
        "en": "Press the button..."
      },
      "instruction": {
        "en": "Press the button on your device once."
      }
    }
  },
  {
    "id": "rf_receiver_add",
    "options": {
      "instruction": {
        "en": "Did the device turn off and on?"
      }
    }
  }
]

Receiver + Learn

Some devices, such as built-in modules, are hard to reach when pairing. For such devices, you can let the user choose whether to generate a new signal, or copy from an existing remote.

Follow the instructions for Receiver, but additionally copy /pair/rf_transmitter_learn.html to your driver's /pair folder.

Then, modify this to your /drivers/<driver_id>/driver.compose.json:

"pair": [
  {
    "id": "rf_receiver_learn",
    "navigation": {
      "next": "rf_receiver_add"
    },
    "options": {
      "title": {
        "en": "Press the button..."
      },
      "instruction": {
        "en": "Press the button on your device once."
      },
      "copyFromRemote": {
        "en": "Copy from Remote"
      }
    }
  },
  {
    "id": "rf_transmitter_learn",
    "options": {
      "instruction": {
        "en": "Press any button on your remote."
      }
    },
    "navigation": {
      "prev": "rf_receiver_learn"
    }
  },
  {
    "id": "rf_receiver_add",
    "navigation": {
      "prev": "rf_receiver_learn"
    },
    "options": {
      "instruction": {
        "en": "Did the device turn off and on?"
      }
    }
  }
]

IR Remote

Copy /pair/rf_ir_remote_learn.html and /pair/rf_ir_remote_add to your driver's /pair folder.

Then add this to your /drivers/<driver_id>/driver.compose.json:

"pair": [
  {
    "id": "rf_ir_remote_learn",
    "navigation": {
      "next": "rf_ir_remote_add"
    },
    "options": {
      "title": {
        "en": "Pair your IR remote",
        "nl": "Koppel je IR afstandsbediening"
      },
      "instruction": {
        "en": "Press next to pair your remote.",
        "nl": "Druk op volgende om je afstandsbediening te koppelen."
      }
    }
  },{
    "id": "rf_ir_remote_add"
  }
]

RFDevice

/drivers/my_driver/device.js

const { RFDevice } = require('homey-rfdriver');

module.exports = class MyDevice extends RFDevice {

  static RX_ENABLED = false; // Set to true for transmitter devices

  static CAPABILITIES = {

    // When the onoff capability is changed by the user,
    // you can assemble a command here.
    // 'data' is your device's data object
    onoff: ({ value, data }) => ({
      address: data.address,
      state: value === true,
    }),
  };

}