diff --git a/HTTP-request-API.md b/HTTP-request-API.md index e5f6c4f..0b5cafe 100644 --- a/HTTP-request-API.md +++ b/HTTP-request-API.md @@ -1,167 +1,3 @@ -WLED's HTTP API allows you to set many properties of your lights, even more than the index page UI supports, via a simple GET web request. - -_Unsure how all this API stuff works? Check out [this amazing guide](https://tynick.com/blog/01-28-2020/controlling-wled-with-raspberry-pi-using-the-wled-api/) by tynick!_ - -**Notice: While this API is not deprecated, it is highly recommended to use the [JSON API](https://github.com/Aircoookie/WLED/wiki/JSON-API) instead of the HTTP API for new integrations, as it is structured in a better way and allows efficient use of newer features like segments, presets, and playlists.** - -The basic URL scheme is: `[ipadress]/win`. This will return an XML file with some current values (see bottom of page). -Parameters can be added to control some of the variables. -- Example (AP): `192.168.4.1/win&A=255` sets the brightness to maximum -- Example (mdns): `led.local/win&A=128&FX=0` sets the brightness to half and the effect to Solid - -In conjunction with a [router port forwarding](https://github.com/Aircoookie/WLED/wiki/Remote-Access-and-IFTTT) this can be used to automate WLED, for example via IFTTT. - -Add one or multiple of the following parameters after the base URL/IP to change values: -(if the parameter is unknown or the value illegal nothing will happen) - -## LED control - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&A= | 0 to 255 | Master brightness | 0.2 -&T= | 0, 1, or 2 | Master Off/On/Toggle | 0.3 -&R= | 0 to 255 | Primary Red value | 0.2 -&G= | 0 to 255 | Primary Green value | 0.2 -&B= | 0 to 255 | Primary Blue value | 0.2 -&W= | 0 to 255 | Primary White value | 0.4 -&FX= | 0 to 101 | LED Effect Index | 0.3 -&SX= | 0 to 255 | Effect Speed | 0.3 -&IX= | 0 to 255 | Effect Intensity | 0.5.0 -&FP= | 0 to 46 | FastLED Palette | 0.8.0 -&NL= | 0 to 255 | Nightlight active and duration in minutes | 0.3 -&ND | none | Toggles nightlight on but uses default duration | 0.6.3 -&NT= | 0 to 255 | Nightlight target brightness | 0.5.0 -&NF= | 0 to 2 | Fade Nightlight, 1 = fade brightness only,
2 = additionaly fade color from primary to secondary color | 0.5.0 - -## Advanced - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&CL= | HEX/DEC | Primary color | 0.8.0 -&C2= | HEX/DEC | Secondary color | 0.8.0 -&C3= | HEX/DEC | Third color | 0.8.0 -&R2= | 0 to 255 | Secondary Red value | 0.4 -&G2= | 0 to 255 | Secondary Green value | 0.4 -&B2= | 0 to 255 | Secondary Blue value | 0.4 -&W2= | 0 to 255 | Secondary White value | 0.4 -&HU= | 0 to 65535 | Hue | 0.5.1 -&SA= | 0 to 255 | Saturation (only in conjunction with Hue) | 0.5.1 -&H2 | none | Hue + Saturation will set secondary color | 0.5.1 -&SR= | 0 or 1 | Set Primary/Secondary color to random hue | 0.4 -&SC | none | Swap primary and secondary color | 0.4 - -### Use of hex values - -Hex values need to be prefaced with the character h or H. The normal format is `RRGGBB`. If the led strip is RGBW, the hex format is `WWRRGGBB`. Note: In the UI the format is `RRGGBBWW`, so the values cannot be copied without a transformation. - -### Loxone commands - -Loxone offers two commands. One for RGB values and one for brightness and color temperature. - -| Parameter | Syntax | Range | Description | Since Version | -|---|---|---|---|---| -&LX= | BBBGGGRRR | 0 - 100100100 | Loxone RGB value for primary color. Each color (`RRR`,`GGG`,`BBB`) is specified in the range from 0 to 100%. | 0.11 -&LX= | 20bbbtttt | 200002700 - 201006500 | Loxone brightness and color temperature values for primary color. Brightness `bbb` is specified in the range 0 to 100%. `tttt` defines the color temperature in the range from 2700 to 6500 Kelvin. | 0.11 -&LY= | BBBGGGRRR | 0 - 100100100 | Loxone RGB value for secondary color. Each color (`RRR`,`GGG`,`BBB`) is specified in the range from 0 to 100%. | 0.11 -&LY= | 20bbbtttt | 200002700 - 201006500 | Loxone brightness and color temperature values for secondary color. Brightness `bbb` is specified in the range 0 to 100%. `tttt` defines the color temperature in the range from 2700 to 6500 Kelvin. | 0.11 - -## Notifications - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&RN= | 0 or 1 | Receive UDP Notifications | 0.3 -&SN= | 0 or 1 | Send UDP Notifications | 0.3 -&NN | none | No notification for this request | 0.3 -&HP= | 0 to 99 | Sets Hue polling light ID (0 is off) | 0.5.1 - -## Presets - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&PS= | 1 to 16 | Saves current setup to preset | 0.4 -&PL= | 1 to 250 | Applies entire preset | 0.4 -&P1= | 1 to 249 | First cycle preset | 0.6.3 -&P2= | 2 to 250 | Last cycle preset | 0.6.3 -&TT= | 0 to 65000 | Set transition time (ms) | 0.6.3 - -## Macros - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&M= | 1 to 16 | Apply macro (deprecated, added for compatibility with pre-0.11 automations) | 0.5.0 - -## Segments -It is highly recommended to use the [JSON API](https://github.com/Aircoookie/WLED/wiki/JSON-API) when dealing with Segments. - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&SM= | 0 to 9 | Set the main segment (values are reported to XML) | 0.9.0 -&SS= | 0 to 9 | Select segment to apply THIS api call to | 0.9.0 -&SV= | 0, 1, or 2 | Set segment selected (2 unselects others) | 0.9.0 -&S= | 0 to ledcount-1 | Set segment start | 0.9.0 -&S2= | 0 to ledcount | Set segment stop | 0.9.0 -&GP= | 1 to 255 | Set segment grouping | 0.9.1 -&SP= | 0 to 255 | Set segment spacing | 0.9.1 -&RV= | 0 or 1 | Reverse/Flip Segment direction | 0.9.1 -&SB= | 0 to 255 | Segment brightness | 0.10.0 - -## General and Experimental - -Parameter | Value Range | Description | Since Version -| --- | --- | --- | --- | -&RB | none | Reboot WLED | 0.10.0 (?) -&ST= | 32bit | Current UTC time in Unix epoch | 0.4 -&CT= | 32bit | UTC time for countdown end | 0.4 -&MD= | 0 or 1 | Set slider mode to RGB/HSB | 0.3 -&AX= | 0 to 255 | Debug feature, can be configured for general IO | 0.3 -&IN | none | Server will not respond to this request (internal) | 0.3 -&OL= | 0 to 255 | Experimental overlays | 0.3 -&L= | 0 to 255 | Lock pixel | 0.4 -&L2= | 0 to 255 | Lock pixel range L to L2 | 0.4 -&UL | none | Unlock instead (used in conjunction with L and L2) | 0.4 -&NX= | String 1..6 | Cronixie clockface | 0.4 -&NM= | 0 or 1 | Cronixie Time or Countdown mode | 0.4 -&NB= | 0 or 1 | Cronixie Backlight | 0.4 -&IT | none | Include UI color theme in API response | 0.8.2 -&RD= | 0 or 1 | Toggle realtime UDP | 0.8.4 -&LO= | 0-2 | Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot | 0.10.2 - -## XML response -This is the XML file sent as response to every API call. - -Parameter | Value Range | Description -| --- | --- | --- | -\ | 0 to 255 | Master Brightness -\ | 3x 0..255 | Primary Color RGB -\ | 3x 0..255 | Secondary RGB -\ | 0 or 1 | Notification Sending on -\ | 0 or 1 | Notification Receive on -\ | 0 or 1 | Nightlight active -\ | 0 or 2 | Nightlight Fade type -\ | 0 to 255 | Nightlight delay -\ | 0 to 255 | Nightlight target brightness -\ | 0 to 73 | Effect index -\ | 0 to 255 | Effect speed -\ | 0 to 255 | Effect intensity -\ | 0 to 43 | FastLED palette -\ | -1 to 255 | Primary White value -\ | 0 to 255 | Secondary White -\ | 0 to 255 | Current Preset -\ | 0 or 1 | Preset Cycling enabled -\ | 0 or 1 | RGB or HSB UI mode -\ | String 0..32 | Server description -\ | 0 to 12 | Segment ID - -## In-/decrementing values - -You can use the `~` character to easily set values relative to their current value. -This is currently supported for the following parameters: -`A, R, G, B, W, R2, G2, B2, W2, FX, SX, IX, FP, PL` - -For example, use `PL=~` to go to the next preset. Using just `~` without a number will increase the value by 1, `~-` will decrease it by 1. The value will then wrap around, so using `A=~-` when A is 0 will set A to 255. - -You can also specify by how much to change the value. For example, using `A=~10` will increase the brightness by 10. In case of using a number behind `~`, the value will clip (so it will not wrap around, if the maximum brightness is set, `A=~10` will not have any effect) - -To setup a Macro for a Button to advance to the next Preset, use **win&P1=1&P2=30&PL=~** -P1 will equal the first Preset of the rotation while P2 will be the last Preset. +Please see https://kno.wled.ge/interfaces/http-api/ for this information. +This wiki is now deprecated. Please consider contributing to kno.wled.ge by making improvements as a pull request. Thank you! \ No newline at end of file