Infrared

You can create Homey apps that use Infrared signals to control devices. This allows you to automate devices such as TVs and speakers that don't have "smart" capabilities.

Infrared is a Signal similar to Radio (433Mhz & 868Mhz), this means that adding support for an Infrared device to your Homey App is done in much the same way as adding a 433Mhz device.

In order to use Infrared in your app will need the homey:wireless:irpermission. For more information about permissions read the permissions guide.

You can view a working example of a Homey App that uses Infrared at: https://github.com/athombv/com.lg.ir-example

Installation

The homey-rfdriver implements the basic functionality needed for all infrared apps and implements a higher level interface that you can use to control infrared devices. Install homey-rfdriver with the following command:

npm install homey-rfdriver

You will also need to copy the infrared pairing templates from node-homey-rfdriver.

Read the RFDriver documentation at https://athombv.github.io/node-homey-rfdriver.

Copy the pair/rf_ir_remote_add.html and pair/rf_ir_remote_learn.html files to the drivers/<driver_id>/pair/ folder of your app.

Usage

Now that you have homey-rfdriver installed and copied the pairing templates, you can add them to your driver's manifest:

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "TV" },
  "class": "tv",
  "capabilities": ["onoff", "channel_up", "channel_down"],
  "images": {
    "small": "/drivers/my_driver/assets/images/small.jpg",
    "large": "/drivers/my_driver/assets/images/large.jpg"
  },
  "infrared": {
    "satelliteMode": true
  },
  "pair": [
    {
      "id": "rf_ir_remote_learn",
      "navigation": {    "next": "rf_ir_remote_add" },
      "options": {
        "title": { "en": "Pair your IR remote" },
        "instruction": { "en": "Press next to pair your remote." }
      }
    },
    {
      "id": "rf_ir_remote_add"
    }
  ]
}

Signal definition

Next you need to add the signals you want to send to your manifest, you can define your signals by creating .homeycompose/signals/ir/my_signal.json. We will explain the basics next but if you want to know more about creating signal definitions your should read the RF 433Mhz/868Mhz guide.

First you need to configure the carrier frequency, number of repetitions for all commands and the signal characteristics. For example:

/.homeycompose/signals/ir/my_signal.json

{
  "carrier": 37900,
  "sof": [4535, 4465],
  "eof": [590],
  "words": [
    [590, 590],
    [590, 1690]
  ],
  "prefixData": [1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0],
  "interval": 1000,
  "sensitivity": 0.5,
  "repetitions": 5,
  "minimalLength": 32,
  "maximalLength": 32,
  "cmds": {}
}

The carrier frequencies for infrared are: min: 30000, default: 38000, max: 45000

Now that the signal characteristics are defined you can add commands, for example:

/.homeycompose/signals/ir/my_signal.json

  "cmds": {
    "POWER_ON": [1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0],
    "POWER_OFF": [0, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0],
    "CHANNEL_UP": [0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0, 1, 1, 1],
    "CHANNEL_DOWN": [0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 1, 1, 0, 1, 1, 1]
  }

Classes

The only things left to do is to define the right classes, starting with the signal which tells homey-rfdriver what signal to use (and allows you to override the signal functionality):

/drivers/<my_driver>/signal.js

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

class MySignal extends RFSignal {
  static FREQUENCY = 'ir';
  static ID = 'my_signal';
}

module.exports = MySignal;

Next you need to link create a Driver that extends RFDriver and the link your RFSignal class to it.

/drivers/<my_driver>/driver.js

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

class MyDriver extends RFDriver {
  static SIGNAL = MySignal;
}

module.exports = MyDriver;

And lastly you need to create a Device that extends RFDevice and create a mapping from Homey capabilities to the commands you defined for your signal.

/drivers/<my_driver>/device.js

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

class MyDevice extends RFDevice {
    static CAPABILITIES = {
    onoff: {
      'true': 'POWER_ON',
      'false': 'POWER_OFF',
    },
    channel_up: 'CHANNEL_UP',
    channel_down: 'CHANNEL_DOWN',
  }
}

module.exports = MyDevice;

Prontohex

Homey also supports Prontohex signal definitions for infrared devices.

Properties

The table below shows the encoding properties in the Prontohex signal definition.

Attribute	Description	Remark
cmds	Static commands	The Prontohex command string definition
type	Type of Signal	Set to prontohex to enable prontohex mode

Commands

Sometimes, devices have a static set of commands and do not include any dynamic data such as an address. This is the case for most infrared devices. In these cases, the cmds attribute can be used to predefine all commands. This property consists of an object that maps commands (specified as identifier string) to a prontohex payload (specified as String). The carrier in the prontohex String overrides the carrier in the signal radio specification.

/.homeycompose/signals/ir/my_signal.json

{
  "type": "prontohex",
  "cmds": {
    "ON": "0000 0073 0000 000D 0020 0020 0040 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0040 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0CA4",
    "OFF": "0000 0073 0000 000C 0020 0020 0040 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0040 0020 0020 0020 0020 0020 0020 0040 0040 0020 0CA4"
  }
}

/app.js

const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const philipsSignal = this.homey.rf.getSignalInfrared('philips');

    await philipsSignal.cmd('ON');
  }
}

module.exports = App;