Build, Upload, Serial

Compile and Flash sit on the right of the bottom toolbar. Build output goes to the Output tab, and the Serial Monitor tab connects to the board once it is running.

Before you build

Check the three pickers on the left of the toolbar:

Picker	What to choose
Target	The board to build for, for example ESP32 DevKit.
Device	The serial port your board is plugged into. Only needed for Flash.
Environment (layers icon)	Which build environment ([env:...] section of platformio.ini) to use. An amber dot means you are not on the default one.

See Targets and environments for how targets, environments and devices are set up.

Compile

Click Compile. Embedr:

1. Saves every open file.
2. Opens the Output tab.
3. Builds the selected target and environment, streaming the build log.
4. Ends with Build Succeeded or Build Failed in the Output tab's status bar.

When a build fails, the lines with errors are marked in the code editor.

Compile needs a board connected only when you flash; you can build without any hardware.

If Compile is greyed out, hover it for the reason:

Tooltip	Fix
Select a target to compile	Pick a target in the toolbar.
Add capabilities.firmware.actions.build to embedr.yaml to enable compiling	The project uses its own firmware tool and has no build action. See Project manifest.
Open a project to compile	Open a project first.

The first build takes longer

The first build of an environment downloads the board's platform, compiler and framework. For ESP32 this is hundreds of megabytes, so the first build can take several minutes. Later builds reuse the download and are much faster.

A first build is allowed up to 20 minutes and later builds up to 10. If a build hits that limit, the Output tab says Build timed out after … and shows the last part of the log. Run it again; downloads that already finished are kept.

If a download was interrupted and left an incomplete package behind, the next build removes that package and installs it again.

Arduino builds on Apple Silicon

The compilers for some boards, such as AVR boards like the Arduino Uno, are Intel builds. On an Apple Silicon Mac they need Rosetta 2. Without it the build fails, and Embedr explains that Rosetta is needed and gives the command to install it:

softwareupdate --install-rosetta --agree-to-license

Run it in Terminal (or the Embedr Terminal tab), then build again.

The Output tab

The Output tab holds the log of the last Compile or Flash. Its bottom bar shows the status on the left and these actions on the right:

Control	What it does
Fix with Agent	Appears after a failed build. Sends the build output to the agent and asks it to find the cause and fix it.
Migrate Project	Replaces Fix with Agent when the failure is because the project needs migrating to embedr.yaml.
Firmware file buttons	In the browser, download the built firmware files.
Auto-scroll	Keeps the newest output in view. Click to turn it off while you read.
Copy	Copies the whole log.
Clear	Empties the log.

Select part of the log to get an Add to Chat button, so the agent sees only the lines that matter.

When you read a failed build yourself, look for the first error: line, not the last line. It names the file and line number. A missing header, such as fatal error: DHT.h: No such file or directory, usually means a library is missing. See Dependencies and libraries.

Flash

Click Flash to build and upload in one step. Embedr saves your files, compiles, and then uploads to the selected device. The log in the Output tab shows each stage:

Build & Upload: main.cpp
════════════════════════════════════════

▸ Compiling...
  ✓ Compilation successful

▸ Uploading to cu.usbserial-0001...
────────────────────────────────────────
✓ Upload Successful

If compilation fails, nothing is uploaded.

Flash is disabled until both a target and a device are selected. If the selected port looks like a Bluetooth port, the log warns you before uploading.

Projects that use their own firmware tool flash with the project's flash action instead, and pass the selected device's port to it. See Project manifest.

When upload fails

If the build succeeds but the upload fails, start with the hardware:

• the wrong port is selected,
• the USB cable only charges and has no data lines,
• the USB serial driver is not installed,
• another program, including the Serial Monitor, has the port open,
• the board needs its BOOT button held while the upload starts (common on ESP32 boards),
• the selected target does not match the board you plugged in.

The device menu lists ports under Connected Devices. Use the refresh button (Scan for USB devices) or Rescan after plugging a board in, and Deselect Device to clear the choice.

Serial Monitor

Open Serial Monitor from the + menu in the tab strip. It uses the device selected in the toolbar.

1. Select a device in the toolbar.
2. Choose the Baud Rate: 300 to 115200. It starts at the monitor_speed of the active environment, or 9600 if none is set.
3. Click Connect.
4. Type in Send data... and press Enter or Send. Each message is sent with a newline at the end.
5. Click Disconnect when you are done, and always before flashing.

The baud rate must match your firmware. If your sketch calls Serial.begin(115200), choose 115200; a mismatch shows garbled characters.

The toolbar over the output has Auto-scroll (switch to Manual to stop following new lines), Copy and Clear. Select lines to add them to chat.

Descriptive log lines make debugging faster for you and the agent:

boot
sensor init ok
raw=512 voltage=1.65V
threshold crossed

Ask the agent to build, flash and watch

The agent can compile, flash, and connect to the Serial Monitor itself. A request like this lets it run the whole loop:

Build the firmware for the selected target, fix any errors, flash it to the connected board, then read the serial output for ten seconds and tell me whether the sensor initialised.

Flashing and serial access are blocked in Plan Mode. See The Embedr agent and Plan Mode.

In the browser

Embedr in the browser builds firmware in the cloud and talks to boards through Web Serial.

• Compile runs in the cloud. When it succeeds, the Output tab offers the firmware files for download.
• Web Serial needs a Chromium-based browser (such as Chrome or Edge) and an HTTPS page. Other browsers cannot reach serial devices.
• Open the device menu and choose Pair Browser Serial... to grant the page access to a port. Only paired ports are listed; No paired devices means none has been granted yet.
• Flash in the browser supports ESP32 Dev Module and ESP32-S3 DevKitC-1 targets. Embedr checks that the connected chip matches the build before writing. For other targets, download the firmware and flash it with the desktop app.
• The Serial Monitor works the same way as on desktop, over the paired port.

Clean builds

If a build keeps failing after a fix that should work, or after switching frameworks or target families, clean the build output and build again. From the Terminal:

embedr clean
embedr compile

Or build cleanly in one step with embedr compile --clean. See CLI reference.