diff --git a/docs/basics/getting-started.md b/docs/basics/getting-started.md index ed847ac77..a6e55002b 100644 --- a/docs/basics/getting-started.md +++ b/docs/basics/getting-started.md @@ -1,5 +1,5 @@ --- -title: Getting Started +title: Quick Start hide: # - navigation # - toc @@ -7,98 +7,124 @@ hide: ## Welcome to the WLED Wiki! -!!! info "Version Info" - Unless noted otherwise, all information applies to the latest release. +Say hi to Akemi, the WLED mascot. She marks extra information throughout these docs. Click her any time you want to know more. (1) +{ .annotate } -!!! warning "ESP8266 End of Life" +1. For a new project, an ESP32 is the better pick. It's much more capable hardware, and ESP8266 support is coming to an end. - Do not install any new setups using ESP8266. While WLED currently still supports ESP8266, all new setups should be using the ESP32 as it's much better hardware and ESP8266 is coming to and end of support. +### Quick Start Guide -### Quick start guide +**1.** Connect your LED strip to your ESP board. A digital strip is three connections at its simplest: power, data, and ground. Analog strips need a channel per color instead. The diagrams below show the extras worth adding. -**1.** Connect a WS2812B-compatible RGB(W) led strip to you ESP board: +=== "Digital LED Strips" -- For ESP32 use `GPIO16` (or `IO16` or `G16`); GPIOs `4`, `13` and `16-33` can be used, other pins are not recommended. -- For ESP8266 use `GPIO2`, on most development boards this pin is labeled `D4`. + Also called addressable strips, for example WS2812B-compatible RGB(W) strips. Each LED can be controlled separately. -_If the connecting wire cannot be kept short, use a [level shifter/translator](/basics/compatible-hardware#levelshifters)._ Optionally, connect a normally open pushbutton to `GPIO0` (NodeMCU/Wemos pin `D3`, on ESP32 use `IO17`) and ground for [configurable actions](/features/macros). + For ESP32 use `GPIO16` (or `IO16` or `G16`); GPIOs `4`, `13` and `16-33` can be used, other pins are not recommended. -!!! warning - Board pin naming varies depending on the manufacturer. Please use the board pinout from the _specific_ board you purchased and use the GPIO pins to reference this guide. _Make sure to connect ESP and LED-strip grounds together!_ + For ESP8266 use `GPIO2`, on most development boards this pin is labeled `D4`. (1) + { .annotate } + + 1. `GPIO1` and `GPIO2` are the recommended LED data pins on ESP8266, and `GPIO3` works for up to 100 LEDs. Other pins need _bit-banging_, which can slow performance and cause problems elsewhere such as with IR decoding. For clock-and-data LEDs, hardware SPI uses `GPIO14` (SCLK) for clock and `GPIO13` (MOSI) for data, and software SPI works on any pins. All pins can be changed in the Hardware section of LED settings. -![DigitalWiring](../assets/images/content/WLED_5VdigitalWiring.png) -Check out the [Wiring Guides](/basics/wiring-guides) for more examples. + _If the connecting wire cannot be kept short, use a [level shifter](/basics/wiring-guides#levelshifter)._ -While using an ESP8266 and LEDs that have clock and data, you can either use hardware SPI (mostly faster) or software SPI. + ![DigitalWiring](../assets/images/content/WLED_5VdigitalWiring.png) - - hardware SPI: use `GPIO14` (SCLK) for clock and `GPIO13` (MOSI) for data. - - software SPI: since all pins can be changed in the Hardware section of LED settings, you can use any pins. Recommend is to use `GPIO1` (TxD) for clock and `GPIO2` (D4) for data. +=== "Analog LED Strips" -For safe operation, it is recommended to size your power wires correctly and to integrate fuses. -For reference, you may use this [LED power, wiring and fuse calculator](https://wled-calculator.github.io/). + Also called non-addressable strips. Every LED shows the same color, and each color channel needs its own GPIO and MOSFET. The IRLZ44N and STP55NF06L are good choices. -For analog LEDs, the MOSFETs IRLZ44N or STP55NF06L are good candidates. Example circuit: + ![AnalogWiring](../assets/images/content/12Vanalog_wiring.png) -![image](../assets/images/content/12Vanalog_wiring.png) -More analog wiring examples can be found [here](/basics/compatible-led-strips/#non-addressable-led-strips) +!!! warning + Board pin naming varies depending on the manufacturer. Please use the board pinout from the _specific_ board you purchased and use the GPIO pins to reference this guide. _Make sure to connect ESP and LED-strip grounds together!_ -**2.** Flash the software to your ESP module! There are two options for this step: +**2.** Flash the software to your ESP board. The web installer flashes it straight from the browser. -[I just want to use WLED! (install release binary)](/basics/install-binary) +[Install WLED](https://install.wled.me){ .md-button .md-button--primary } -[I want to modify WLED (compile from source code)](/advanced/compiling-wled) +Other flashing methods, including for boards with less than 4MB of flash, are on the [Install WLED Binary](/basics/install-binary) page. Advanced users who want to change WLED before flashing it can [compile it from source](/advanced/compiling-wled) instead. -If everything worked the first thirty LEDs will light up in bright orange to stimulate courage, friendliness and success! +!!! success "How to tell it worked" + The first 30 LEDs will light up in bright orange to stimulate courage, friendliness and success! On an analog strip the whole strip turns orange, since every LED shares the same channels. -**3.** Use a WiFi device to connect to the access point `WLED-AP` using the default password `wled1234`. +**3.** On your phone or computer, connect to the WiFi network `WLED-AP` using the default password `wled1234`. You can also just scan this QR code: -![QR-Code](../assets/images/content/getting-started-wled-ap-qr.png) +
+ ![QR-Code](../assets/images/content/getting-started-wled-ap-qr.png){ width="220" } +
Scan to join WLED-AP
+
!!! tip "WLED-AP is not showing up!" - If you do not see the `WLED-AP` SSID, the default SSID may have been changed at [compile time](/advanced/custom-ap). + If you do not see the `WLED-AP` network, its name may have been changed at [compile time](/advanced/custom-ap). + +Open `wled.me` in your browser to control your lights. The IP `4.3.2.1` works too while you're connected to WLED-AP. + +### WiFi Setup + +To connect your WLED device to your home WiFi: + +**1.** Click on the _Config_ (gear) icon to edit your WLED device settings and choose "WiFi Setup". + +**2.** Select **Scan** to find nearby networks, or type your network name. Enter your WiFi password, which is case-sensitive. + +**3.** Set an **mDNS address**, such as `wled-livingroom`. This becomes the name you use to reach your device from now on. Change the AP password here too, since `wled1234` is the same on every WLED device. + +**4.** Click Save & Connect at the bottom of the page. + +**5.** Reconnect your phone or computer to your home WiFi network. + +**6.** Open your mDNS address in a browser, for example `http://wled-livingroom.local`. If you didn't set one, or the `.local` name doesn't resolve on your device, use the WLED app to find it, or look up its IP in your router's device list. + +!!! tip "4.3.2.1 stops working" + Once your device joins your home network, `4.3.2.1` and `wled.me` stop working. Use your mDNS address or the device's IP instead. + +Once you're in, take a look at [The Web UI](/basics/web-ui) to find your way around the interface. + +### Find Your Device with the WLED App + +The WLED app discovers devices on your network for you, so you don't have to dig through your router. + +=== "iOS" -Go to the IP `4.3.2.1` in your browser to control your lights! You should also be able to connect to `wled.me` if in access point mode (embedded DNS server). + Install [WLED from the App Store](https://apps.apple.com/us/app/wled-official-app/id6446207239). -### Wifi Setup +=== "Android" -To connect your WLED module to your home Wifi: + Install [WLED from Google Play](https://play.google.com/store/apps/details?id=ca.cgagnier.wlednativeandroid). -**1.** Click on the _Config_ (gear) icon to edit your WLED module settings and choose "Wifi Setup". +1. Connect your phone to the same WiFi network as your WLED device. +2. Your device appears in the app automatically. Select it, then open the **Config** tab in the top right. +3. Choose **WiFi Setup**. At the bottom of that screen is a text box with your hostname, ending in `.local`, and the IP address directly below it. -**2.** For most home networks, enter your Wifi network's name and network password. You can also change the mDNS address for your WLED module here. +Either one works in a browser, as `http://your-hostname.local` or `http://your-ip-address`. -**3.** Click Save & Connect at the bottom of the page. +### Useful Links -**4.** Reconnect your device to your home's Wifi network. +- 12V strips, multiple strips, several supplies, level shifters: [Wiring Guides](/basics/wiring-guides) +- Wire and fuse sizing: [LED power, wiring and fuse calculator](https://wled-calculator.github.io/) +- Optional pushbutton for [configurable actions](/features/macros). The default is `GPIO0` (`D3` on NodeMCU/Wemos). On ESP32 use any free pin, such as `IO17`, that you are not already using for LED data -**5.** Check the device list in your router's user interface for the IP of the WLED device within your local network. For easy automatic discovery, use the WLED Native app! Have fun with the WLED software! +### Software Update Procedure -### Default GPIO Usage +=== "Reflash" -!!! info "These are only defaults" - All pins can be changed in the Hardware section of LED settings. These are GPIO numbers, so please consult a pinout for your board to find the labeled pin (e.g., `D4` = `GPIO2` on most ESP8266 boards). When using an ESP8266 board, it's recommended to use pins `GPIO1`, `GPIO2`, or `GPIO3` for LED Data; using other pins will require _bit-banging_ and may cause slow performance and/or issues elsewhere (such as with IR decoding). + Download the latest [release binary](https://github.com/wled/WLED/releases) and flash it exactly like the first install. The [Install WLED Binary](/basics/install-binary) page covers every flashing method. -| Function | GPIO | Suggested pin | -|---|---|---| -LED Data | 2 | ESP8266: 1, 2 (3 if <= 100 LEDs), ESP32: 1, 2, 3, 4, 16 -Button | 0 | -IR Remote| None | 4 -Relay | None | 12 +=== "OTA Update" -### Software update procedure + The software has an integrated _OTA software update_ capability. -**Method 1**: Reflashing the new update like a new install (see above). + 1. Type the correct OTA passphrase (default: "wledota") in the settings menu and remove the tick in the checkbox "OTA locked". + 2. Save settings and reboot your device. + 3. Select "Manual OTA update" in Security settings and upload a [release binary](https://github.com/wled/WLED/releases). + 4. When you are done, it is recommended to lock the OTA function again. Tick the checkbox and reboot. You can change the passphrase by typing in a new one first. -**Method 2**: The software has an integrated _OTA software update_ capability. -First you have to enable it by typing in the correct OTA passphrase (default: "wledota") in the settings menu. -Remove the tick in the checkbox "OTA locked". Then save settings and reboot the ESP. -Then you can select "Manual OTA update" in Security settings and upload a [release binary](https://github.com/wled/WLED/releases). -After you are done, it is recommended to lock the OTA function again. -To do so, tick the checkbox again (you can change the passphrase by typing in a new one now). Reboot. -If you try to access the update page now, you should see the message "OTA lock active". + If you try to access the update page while OTA is locked, you should see the message "OTA lock active". -**Method 3**: ArduinoOTA is also possible, but requires a custom build with `-D WLED_ENABLE_AOTA` added to `build_flags`. + ArduinoOTA is also possible, but requires a custom build with `-D WLED_ENABLE_AOTA` added to `build_flags`. !!! info "If you own multiple devices and want to update them" - WLED source code includes shell/command prompt scripts to update multiple devices with a single command. Please check `tools` subfolder for `multi-update` scripts (.cmd or .sh). You will need to modify them to include IP addresses of your WLED devices and assign firmware binary file for each device. If you are using Windows, make sure you install `curl` utility somewhere in your `PATH` (curl is included with Windows 10 since build 17063). This will only work if "OTA Lock" is disabled. + The WLED source code includes shell/command prompt scripts that let you update multiple devices with a single command. Please check the `tools` subfolder for the `multi-update` scripts (.cmd or .sh). You will need to modify them to include the IP addresses of your WLED devices and assign a firmware binary file for each device. If you are using Windows, make sure the `curl` utility is somewhere in your `PATH` (curl ships with Windows 10 build 17063 and later, and with Windows 11). This will only work if "OTA Lock" is disabled, so turn it back on and reboot once the batch is finished.