Controlling the device for the first time

Which state do I use to switch on and off, the whole device or just a segment?

This section is still being written.

How do I use brightness as a percentage (0 to 100), for example for Alexa?

In short: Like WLED itself, bri works with values from 0 to 255, not with percentages. For 0 to 100 % you create an alias on bri that divides by 2.55 when reading and multiplies by 2.55 when writing.

The adapter doesn't switch bri to percent, because 255 steps are finer and a switch would break existing scripts and visualisations. The state has the role level.brightness with a minimum of 0 and a maximum of 255. This applies to the overall brightness wled.0.<device>.bri and in the same way to the segment brightness wled.0.<device>.seg.<segment>.bri.

Do you need a conversion at all?

For Alexa and Google Home via the iot adapter, usually not: because bri comes with a minimum and a maximum, the iot adapter can convert a percentage to 0 to 255 by itself. You need the alias if you want to see or write percentages in VIS, in scripts or in another integration, or if the conversion in the iot adapter doesn't work for you.

How to create a percentage alias

1. In Admin, open the "Objects" tab and create a state under alias.0, for example alias.0.WLED.LivingRoom.brightness.
2. Give it the type number, the role level.dimmer, minimum 0, maximum 100 and the unit %.
3. Enter the WLED state as the alias target: wled.0.<device>.bri.
4. Enter the conversion. Read: Math.round(val / 2.55). Write: Math.ceil(val * 2.55).
5. Save, and set the alias to 50 as a test. bri should then jump to 128, and the strip lights up at half brightness.

In the object, the alias part looks like this:

"common": {
  "name": "Brightness living room",
  "type": "number",
  "role": "level.dimmer",
  "min": 0,
  "max": 100,
  "unit": "%",
  "read": true,
  "write": true,
  "alias": {
    "id": "wled.0.<device>.bri",
    "read": "Math.round(val / 2.55)",
    "write": "Math.ceil(val * 2.55)"
  }
}

TIP

Round up when writing (Math.ceil). Otherwise 1 % becomes the value 0 and the light turns off, even though you only wanted it very dim.

WARNING

Don't build the conversion with two scripts that trigger each other (the percentage state writes bri, bri writes the percentage state). Because of the rounding, the two values can jump back and forth. An alias doesn't have this problem, because there is only one real value.

See also: How do I connect WLED to the iot adapter and switch effects, presets and color via Alexa or Google Home?

Where do I choose the effect and the palette?

In short: You set the effect and the palette per segment: wled.0.<device>.seg.<segment>.fx for the effect and wled.0.<device>.seg.<segment>.pal for the palette. Both states have a drop-down list with the names your WLED device reports.

The first segment has the number 0. If you have created several segments in WLED, each one has its own fx and pal states. What gets stored is the number of the effect or palette; the drop-down list shows the matching name.

How to do it

1. In Admin, open the "Objects" tab and go to wled.0.<device>.seg.0.
2. Click the value of the fx state. A list with the effect names of your device opens. Pick one.
3. Do the same with pal for the palette.
4. The strip changes right away. The state then holds the number of the selected entry.

The effect also uses seg.<segment>.sx (speed) and seg.<segment>.ix (intensity).

In a script you write the number, for example setState('wled.0.<device>.seg.0.fx', 9). Which number belongs to which name is listed in the drop-down list in the object (common.states).

New effects are missing from the list after a firmware update

The adapter reads the names from the device, so the list depends on your WLED firmware.

Up to v0.9.2: The adapter sets the drop-down list only once per adapter run. Effects and palettes added by a firmware update only appear after you restart the adapter instance.

From v0.9.3: The adapter rewrites the lists every time it connects to the device. Because WLED restarts during a firmware update and then reconnects, new effects appear without restarting the adapter (#912).

TIP

If the drop-down list is missing completely or out of date, restart the wled.0 instance once. That helps in every version.

See also:

• Where do I find the numbers and names of effects and palettes for scripts?
• How do I choose the effect and the palette in VIS as a drop-down?