# LED Ring

{% hint style="warning" %}
The LED Ring can only be controlled on Homey Pro (Early 2019) and older models. Add `platformLocalRequiredFeatures` to the [App Manifest](https://apps.developer.homey.app/the-basics/app/manifest#platform-local-required-features) to make sure the app can not be installed on Homey Pros that do not have a controllable LED Ring.
{% endhint %}

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 [screensaver](#screensaver).

{% hint style="info" %}
In order to access the LED Ring your app will need the `homey:manager:ledring` permission. For more information about permissions read the [Permissions guide](/the-basics/app/permissions.md).
{% endhint %}

## Playing a LED Ring animation

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

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

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

{% endcode %}

## Creating your own LED Ring animation

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

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

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

{% endcode %}

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:

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

{% code title="/.homeycompose/screensavers/weather.json" %}

```javascript
{
  "title": {
    "en": "Weather",
    "nl": "Weer"
  }
}
```

{% endcode %}

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

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

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

{% endcode %}

For live animations, simply update your animation using [`LedringAnimation#updateFrames()`](https://apps-sdk-v3.developer.homey.app/LedringAnimation.html#updateFrames) when needed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apps.developer.homey.app/advanced/ledring.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.