Skip to content

Add command line compile instructions, remove Arduino IDE instructions #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcone wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add command line compile instructions, remove Arduino IDE instructions #253

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
58009c1
Add command line compile instructions, remove Arduino IDE instructions
marcone Mar 26, 2025
21ca8dc
Tweak flashing instructions
marcone Mar 27, 2025
512725f
Merge branch 'main' into pr/253
softhack007 May 1, 2026
23ecd1e
Merge branch 'main' into pr/253
softhack007 May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 40 additions & 49 deletions docs/advanced/compiling-wled.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ WLED has come to rely on so many dependencies in the latest versions that buildi

If you don't want to change the code but only add some compile options and/or usermods, you can use bot on discord or compile with just few clicks using [this inofficial web based wled compiler](https://wled-compile.github.io/). Using it you can download the resulting .bin file directly or install via USB using built-in web-based installer.

### Preparations
### Compiling using Visual Studio Code

@coderabbitai coderabbitai Bot May 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Heading level skips from h1 to h3.

The document structure jumps from the h1 title to h3 headings. Use h2 (##) for the main section "Compiling using Visual Studio Code" to maintain proper heading hierarchy.

-### Compiling using Visual Studio Code
+## Compiling using Visual Studio Code

Then update the "Linux command line" section similarly:

-### Compiling using the Linux command line
+## Compiling using the Linux command line
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### Compiling using Visual Studio Code
## Compiling using Visual Studio Code
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 14-14: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/advanced/compiling-wled.md` at line 14, Change the improperly-leveled
heading "Compiling using Visual Studio Code" from an h3 to h2 (use "## Compiling
using Visual Studio Code") to restore heading hierarchy, and make the same
change for the "Linux command line" section heading (convert its current h3 to
h2) so both sections follow the document's h1 -> h2 structure.


#### Preparations

1. Make sure Git client is installed on your system. If it isn't, you can get it [here](https://git-scm.com/downloads).
2. Also make sure that you have [Node.js](https://nodejs.org/en/download) 20 or higher installed.
Expand All @@ -25,7 +27,7 @@ Alternatively fork the WLED project first and download it from your fork.
npm install
```

### Installation guide (PlatformIO, recommended)
#### Installing Visual Studio Code and PlatformIO extension

1. Download and install the free [Visual Studio Code](https://code.visualstudio.com/) by Microsoft.
2. Open VS Code and go to the Extensions manager (the icon with the stacked blocks in the left bar)
Expand All @@ -36,10 +38,7 @@ Alternatively fork the WLED project first and download it from your fork.
![](https://i.ibb.co/10ykGxk/Screen-Shot-2020-11-03-at-5-27-17-PM.png)
---

### Compilation guide (PlatformIO)

!!! tip
Make sure Git Client is installed on your system. You can get it [here](https://git-scm.com/downloads).
#### Compiling

1. In VS Code, open the file `platformio.ini`.
2. Add a semicolon in front of the line that says `default_envs = travis_esp8266, travis_esp32` to comment it out.
Expand All @@ -57,7 +56,7 @@ If you get one of these two errors, hit the checkmark icon once again to compile
- `error: wled00\wled00.ino.cpp: No such file or directory`
- `FileNotFoundError: [WinError 2] The system cannot find the file specified: '[...].sconsign37.dblite'`

### Making a custom environment
#### Making a custom environment

Once you've confirmed VSCode with Platformio is set up correctly, you can add/define overrides to allow you to use non-default pins, add a usermod, or add other custom features.

Expand All @@ -75,7 +74,7 @@ Once you've confirmed VSCode with Platformio is set up correctly, you can add/de
7. Put your `-D` overrides on this new line, giving each `-D` it's own new line.
8. Compile your freshly customized WLED image!

### Flashing the compiled binary
#### Flashing the compiled binary

!!! tip
This step is optional and only recommended if you want to install the same binary to multiple boards. For testing, it is easiest to upload directly from PlatformIO
Expand All @@ -84,61 +83,53 @@ The .bin file is located in the subfolder `/build_output/firmware` in your WLED

All that's left to do is [flash this .bin file onto your ESP board](/basics/install-binary/#flashing-method-2-esptool) and then connect it to WiFi.

### Compilation guide (Arduino IDE, not recommended)

!!! warning
This method is outdated. The source is no longer officially checked to be buildable with the Arduino IDE. Using PlatformIO is strongly advised.
### Compiling using the Linux command line

- Follow a guide to setup your Arduino IDE (I am using version 1.8.9) with the ESP8266 libraries.
For current compiles I recommend the latest Arduino core version 2.7.4. If you do not wish to install all libraries manually it is recommended to download the PlatformIO extension for VS Code (see above).
To compile using the Linux command line, it is recommended to use a recent version of Linux, as older versions may have outdated versions of required packages. As of this writing, Ubuntu 24.04 LTS still has an old version of Node.js, but Ubuntu 24.10 has the right version. The following was tested with Ubuntu 24.10.

- Run the following command to build the Web UI files:
```
npm run build
```
!!! tip
If you don't have Ubuntu 24.10, use `multipass` or similar software to start a 24.10 container

- You will need to install a few libraries:
#### Installing required software

| Library Name | Platform |
| --- | --- |
[NeoPixelBus](https://github.com/Makuna/NeoPixelBus) (2.6.0) | All
[FastLED](https://github.com/FastLED/FastLED) | All
[ESPAsyncWebServer Aircoookie fork](https://github.com/Aircoookie/ESPAsyncWebServer) (2.0.0) | All
[IRRemoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) | All
[ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) | ESP8266 only
[ESPAsyncUDP](https://github.com/me-no-dev/ESPAsyncUDP) | ESP8266 only
[AsyncTCP for ESP32](https://github.com/me-no-dev/AsyncTCP) | ESP32 only
[LITTLEFS_esp32](https://github.com/lorol/LITTLEFS)* | ESP32 only
Install `git` if it isn't already: `sudo apt install git`

\* Please see [the installation guide](https://github.com/lorol/LITTLEFS#installation). You might need to enable a define in the library code.
Install the Node.js package manager: `sudo apt install npm`

All other dependencies are included with WLED for convenience.
Run `node --version` and make sure you have at least version 20. If your Linux distribution uses an older version, install Node.js directly from [Node.js](https://nodejs.org/en/download)

- Now compile and flash the software! Make sure you erase everything when you flash! (If your board config does not provide this option, you can `Sketch -> Export compiled Binary` and upload with [any ESP flashing tool](/basics/install-binary).)
Install PlatformIO:

### Compilation settings (Arduino IDE)
!!! warning
Do NOT install PlatformIO with `apt`

ESP8266:
```
curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py
python3 get-platformio.py # if this fails because of missing packages, install the packages it complains about, then retry
PATH=$PATH:$HOME/.platformio/penv/bin/

@coderabbitai coderabbitai Bot May 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

PATH modification is not persistent across sessions.

The PATH modification shown only applies to the current shell session. Users will need to re-run this command in each new terminal, or the pio command will not be found.

Consider adding a note to make it persistent by adding the PATH export to the user's shell profile (e.g., ~/.bashrc or ~/.zshrc):

echo 'export PATH=$PATH:$HOME/.platformio/penv/bin/' >> ~/.bashrc
source ~/.bashrc

Or instruct users to re-run the PATH command in each new terminal session.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/advanced/compiling-wled.md` at line 110, The documentation currently
shows a transient PATH change (the line
"PATH=$PATH:$HOME/.platformio/penv/bin/") which only affects the current shell
and will break the pio command in new terminals; update the docs to instruct
users how to make this persistent by exporting that PATH addition in their shell
profile (e.g., ~/.bashrc or ~/.zshrc) or, alternately, explicitly tell users
they must re-run the PATH command in each new session so the pio command remains
available.

```

- Arduino Core v2.7.4
- Board: NodeMCU 1.0 (ESP-12E module) (or select your ESP board)
- CPU frequency: 80 MHz
- Flash size : 4MB (1MB SPIFFS)
- LwIP variant: v1.4 Higher Bandwidth (try 2 if you experience issues)
- Upload speed: Any, 921600 recommended
Clone the WLED Git repository (or a different fork)
```
git clone https://github.com/wled/WLED.git
cd WLED
```
Optional: check out the branch or tag you want to build, e.g. `git checkout v0.15.0`

ESP8266-07 (External Antenna):
Run `npm ci` to do a clean install of all the required dependencies

- Variants have 512kB or 1MB flash
- Be sure to use DOUT mode when flashing
- Flash Size 1MB (128k SPIFFS)
- 512kB variant no longer compatible
#### Compiling

To build all environments, simply run `pio run`. More likely though you'll want to only build an image for the specific device you're using, which you can do with something like `pio run -e esp8266_2m_160`.
To see a list of available environments, run
```
pio project config --json-output | jq -cr '.[0][1][0][1]'
```
Comment on lines +126 to +128

@coderabbitai coderabbitai Bot May 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Missing jq installation instruction.

The command uses jq to parse JSON output, but the installation of jq is not documented in the "Installing required software" section. Users will encounter a "command not found" error when running this command.

Add jq to the software installation section:

sudo apt install jq
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 126-126: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/advanced/compiling-wled.md` around lines 126 - 128, Add installation
instructions for jq to the "Installing required software" section so the example
pio + jq command won't fail; specifically, include a line telling users to
install jq (e.g., sudo apt install jq) for Debian/Ubuntu and mention the
Homebrew equivalent for macOS (brew install jq). Update the
docs/advanced/compiling-wled.md Installing required software section and ensure
the new line appears before the example that runs `pio project config
--json-output | jq -cr '.[0][1][0][1]'`.


ESP-07s (External Antenna):
#### Flashing the compiled binary

- Variant has 4MB flash
- Settings as for NodeMCU or Wemos
The .bin and .bin.gz files are located in the subfolder `/build_output/release` in your WLED folder.

@blazoncek blazoncek Jun 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Files are only copied into release folder if their environment has WLED_RELEASE_NAME macro/constant set.


ESP32:
If you have an existing WLED install, you can flash the .bin.gz image using the Config -> Security & Updates -> Manual OTA Update option in the web interface. Otherwise, follow the instructions [here](/basics/install-binary/#flashing-method-2-esptool).

@netmindz netmindz Mar 27, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bin is more commonly used than bin.gz

@blazoncek blazoncek Mar 27, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.gz is only used for ESP02 (with limited flash size) though it can work on other ESP8266.

@marcone marcone Mar 27, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had to use .gz on my ESP8266 because the .bin wouldn't work. Does .gz not work for all devices? I figured it was sort of the lowest common denominator.

@blazoncek blazoncek Mar 27, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does not on ESP32

@marcone marcone Mar 27, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I assume this is explained elsewhere, so I just removed the reference to the .bin.gz file here.


- Arduino Core v1.0.6