# Infrared

Infrared is a `Signal` similar to [Radio (433Mhz & 868Mhz)](https://apps.developer.homey.app/wireless/rf-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.

{% hint style="info" %}
In order to use Infrared in your app will need the `homey:wireless:ir`permission. For more information about permissions read the [permissions guide](https://apps.developer.homey.app/the-basics/app/permissions).
{% endhint %}

{% hint style="info" %}
You can view a working example of a Homey App that uses Infrared at: <https://github.com/athombv/com.lg.ir-example>
{% endhint %}

## Installation

The `homey-rfdriver` library for Node.js 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:

```bash
npm install homey-rfdriver
```

You will also need to copy the infrared pairing templates from [node-homey-rfdriver.](https://github.com/athombv/node-homey-rfdriver/tree/master/pair)

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

Copy the [`pair/rf_ir_remote_add.html`](https://github.com/athombv/node-homey-rfdriver/blob/master/pair/rf_ir_remote_add.html) and [`pair/rf_ir_remote_learn.html`](https://github.com/athombv/node-homey-rfdriver/blob/master/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:

{% code title="/drivers/\<driver\_id>/driver.compose.json" %}

```javascript
{
  "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"
    }
  ]
}
```

{% endcode %}

### 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](https://apps.developer.homey.app/wireless/rf-433mhz-868mhz).

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

{% code title="/.homeycompose/signals/ir/my\_signal.json" %}

```javascript
{
  "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": {}
}
```

{% endcode %}

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:

{% code title="/.homeycompose/signals/ir/my\_signal.json" %}

```javascript
  "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]
  }
```

{% endcode %}

### 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):

{% code title="/drivers/\<my\_driver>/signal.js" %}

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

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

module.exports = MySignal;
```

{% endcode %}

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

{% code title="/drivers/\<my\_driver>/driver.js" %}

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

class MyDriver extends RFDriver {
  static SIGNAL = MySignal;
}

module.exports = MyDriver;
```

{% endcode %}

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.

{% code title="/drivers/\<my\_driver>/device.js" %}

```javascript
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;
```

{% endcode %}

## 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.

{% code title="/.homeycompose/signals/ir/my\_signal.json" %}

```javascript
{
  "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"
  }
}
```

{% endcode %}

{% code title="/app.js" %}

```javascript
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;
```

{% endcode %}