Signals

Homey is capable of sending and receiving Infrared, 433 MHz and 868 MHz radio-signals for controlling remote appliances like wireless switches and thermostats. For transmitting and receiving radio-signals the developer has to define a signal-definition. This signal-definition contains all elements necessary for Homey to properly receive and transmit radio signals.

Developing apps for radio controlled devices requires knowledge of data-encoding and signalling

What are signals?

Signals are block-wave datasignals carried over the air using a electromagnetic carrier on a given frequency. Homey communicates on 433 MHz, 868 MHz and Infrared frequencies.

Radio modulation

An electromagnetic field has the ability to change in amplitude (signal strength) and frequency. These characteristics can be used to modulate a datasignal. When the amplitude of a electromagnetic field is used to represent a high or low state it is called 'amplitude shift keying' (ASK). When a change in frequency is used to modulate a signal it is called 'frequency shift keying' (FSK).

There is also a variation on ASK modulation used by most 433 MHz devices called 'on-off keying' (OOK). Instead of defining two amplitude levels for the high and low states, OOK modulation only uses a high state amplitude level. The low state amplitude level is represented by the absence of the carrier. This is a very easy and cheap way of modulating radio signals as it only requires a few hardware components that can generate and toggle an electromagnetic carrier.

Receiving

Receiving electromagnetic waves depends on the antenna and filtering that is used. Antennae are designed to operate at a certain frequency, this prevents the reception of noisy and unwanted signals. In our case we only want to receive on the 433 MHz and 868 MHz bands, for which Homey contains two different antennae. Unfortunately using two separate antennae is not enough to prevent the reception of noise and unwanted signals. To ensure that a device only receives signals within a specific frequency band, it is important to filter out incoming signals at other frequencies.

However, in practice devices often use a somewhat deviated carrier-frequency (e.g. 433.89MHz). To ensure that Homey is able to listen to these deviating frequecies, it's receiving frequency band has been broadened by 325Khz. This results to a frequency band ranging from 433.76MHz to 434.08MHz for 433 MHz signals and 868.14MHz to 868.46MHz for 868 MHz signals.

Homey can only listen to devices with radio-frequencies that are within its frequency band

Data encoding

To convert a received block-wave into usable data, we have to decode this wave. To do this, we have to define how the data is represented in the wave. This depends on the encoding mechanism a device uses. Some device manufacturers develop their own encoding mechanisms, while others use pre-defined standards. These encodings can be edge-based (eg manchester) or duration based (eg X10). Homey can be configured to operate in both modes.

Signal-definition

In order to do this, Homey requires a way to describe the protocol. This description is called a signal-definition. All signal definitions consist of two kind of properties, encoding-specific properties, and radio-specific configuration properties. Homey apps register their signal-definition with the Homey Signal Manager. The Homey Signal Manager receives all incoming raw transmissions and attempts to match these block-waves to a registered signal-definition. When an incoming signal matches a registered signal-definition, the signal is automatically decoded and the contained data is routed to the corresponding app. To send, data travels the reverse path which means the data is encoded using the same signal-definition and then transmitted.

The signal-definition contains al the necessary attributes for sending and receiving signals.

Homey supports two types of signal definitions:

• Signals-Homey - This is the recommended way to define a protocol, as it supports sending and receiving.
• Prontohex - This format is mostly used by Infrared databases, and supports sending only.

Both of these signal types support the same radio configuration parameters.

Obtaining a signal

It is possible to make Homey record raw data for a short period of time. More information about this topic can be found here.

Using signals in your App

Signals should be defined in your app.json, under signals.<frequency>.<your_signal_id>, where frequency is either 433, 868 or ir .

/app.json

{
  "id": "com.athom.weather",
  ...,
  "signals": {
    "433": {
      "my_signal": {
        "sof": [],
        ...
      }
    },
    "868": {
      "another_signal": {
        ...
      }
      },
    "ir": {
      "yet_another_signal": {
        ...
      }
    }
  }
}

Before your app can use the signal, it must be registered:

/app.js

const Homey = require('homey');

// create & register a signal using the id from your app.json
let mySignal = new Homey.Signal433('my_signal');
mySignal.register()
  .then(() => {

    // on a payload event
    mySignal.on('payload', function( payload, first ){
      console.log('received from a device:', payload, 'isRepetition:', !first);
    });

    // on a command event
    mySignal.on('cmd', function( cmdId, first ){
      console.log('received a command from a device:', cmdId, 'isRepetition:', !first);
    });

    // transmit the bits 01011001
    mySignal.tx([ 0, 1, 0, 1, 1, 0, 0, 1 ], console.log);

    // transmit predefined command
    mySignal.cmd('ONOFF', this.log);

    // unregister the signal
    mySignal.unregister( this.log );

  })
  .catch( this.error );

Please only register a signal if there are devices any paired, because receiving signals is quite performance intensive.

Signal requirements

A signal has to meet certain requirements in order to guarantee a proper flow of sending and receiving signals. For example, if a signal is to long, it could block other apps from sending their signals. The table below shows the signal requirements.

Transmitting

After a signal-definition has been made it can be used to transmit or receive data. Data is encoded based on a signal-definition which at the end is nothing more than an array of time-intervals. The Homey Signal Service receives the array with time-intervals, configures the radio with the appropriate settings and generates the signal.

Receive-after-transmit

Sometimes data only needs to be requested from a device. A request message is sent to the device and the device immediately response with the requested data. In order to receive these responses properly the radio has to switch to receive mode immediately after sending the request. With the rxTimeout attribute a receive timeout can be configured. The radio stays in receive mode for the configured time in milliseconds.

The Radio-controller cannot handle time-interval arrays larger then 256 intervals

Receiver configuration

The table below shows the radio configuration used by the 433 MHz and 868 MHz receivers. The receiver's filter bandwidth in listening mode for both 433 MHz and 868 MHz can not be changed by a developer since it is shared by other Homey apps. Changing the filter bandwidth could lead to an unstable reception of these other signals.

433 MHz configuration

868 MHz configuration

Infrared configuration

Child Topics

• Creating a Signal
• Prontohex
• Radio Configuration