Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • Playing a LED Ring animation
  • Creating your own LED Ring animation
  • Screensaver

Was this helpful?

  1. Advanced

LED Ring

Homey's LED ring consists of 24 RGB LED's that apps can control and supply new animations for.

PreviousImagesNextHomey Compose

Last updated 1 year ago

Was this helpful?

The LED Ring can only be controlled on Homey Pro (Early 2019) and older models. Add platformLocalRequiredFeatures to the to make sure the app can not be installed on Homey Pros that do not have a controllable LED Ring.

Your app may control Homey's LED Ring to give visual feedback when your app is doing something. It is also possible to take control of the LED Ring when Homey is idling, this is called a .

In order to access the LED Ring your app will need the homey:manager:ledring permission. For more information about permissions read the .

Playing a LED Ring animation

To keep the user interaction of Homey consistent, you can play a system-provided animation.

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const pulseAnimation = await this.homey.ledring.createSystemAnimation("pulse");
    await pulseAnimation.start();
  }
}

module.exports = App;

Creating your own LED Ring animation

An animation is essentially a JavaScript object with frames and settings about the frame speed and rotation speed.

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myAnimation = await this.homey.ledring.createAnimation({
      options: {
        fps: 1, // real frames per second
        tfps: 60, // target frames per second. this means that every frame will be interpolated 60 times
        rpm: 0, // rotations per minute
      },
      frames: [],
      priority: "INFORMATIVE", // or FEEDBACK, or CRITICAL
      duration: 3000, // duration in ms, or keep empty for infinite
    });

    // register the animation with Homey
    myAnimation
      .on("start", () => {
        // The animation has started playing
      })
      .on("stop", () => {
        // The animation has stopped playing
      });

    await myAnimation.start();
  }
}

module.exports = App;

The animation object is an Array, which contains frames. A frame is an Array with 24 Object values, that represent the color of that pixel. The pixel object is contains the properties r, g and b, respectively red, green and blue on a scale of 0 - 255.

For example, to create a spinning red dot:

const frames = [];
const frame = [];

// for every pixel...
for (let pixelIndex = 0; pixelIndex < 24; pixelIndex++) {
  let colors = {
    r: 0,
    g: 0,
    b: 0,
  };

  // set the first pixel to red
  if (pixelIndex === 0) {
    colors.r = 255;
  }

  frame.push(colors);
}

// and finally, add the generated frame to the frames array
frames.push(frame);

Screensaver

Your app can register a screensaver, which can be chosen by going to Settings → LED Ring, and executed when Homey is idling.

Define your screensaver(s) in your App Manifest as follows:

/.homeycompose/screensavers/weather.json
{
  "title": {
    "en": "Weather",
    "nl": "Weer"
  }
}

And from within your app, register your animation instance as follows:

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myAnimation = await this.homey.ledring.createAnimation({
      // ...
    });

    // If this animation is also a screensaver, we must register it first.
    // 'weather' is the screensaver name defined in our app.json
    myAnimation.registerScreensaver("weather")
      .then(this.log)
      .catch(this.error);
  }
}

module.exports = App;

For live animations, simply update your animation using when needed.

App Manifest
screensaver
Permissions guide
LedringAnimation#updateFrames()