Start Here

Embedr is a desktop stack for embedded systems. Think of it the way you would think about a web framework: one project model that brings together the files, runtime, tools, and workflow you need to build real things.

In Embedr, one project can contain:

• firmware source,
• build and upload configuration,
• board targets and connected devices,
• datasheets and hardware notes,
• schematic and PCB source,
• generated KiCad board files,
• Git history,
• an autonomous agent that can inspect the project and use tools.

The point is not to hide embedded engineering. The point is to make the whole stack visible in one place so firmware, hardware, documentation, and automation do not drift away from each other.

The shortest useful definition

An Embedr project is a folder with an embedr.yaml file. That manifest tells Embedr what the project is, where the source lives, what firmware target it can build, and which hardware design capabilities are available.

For a normal firmware project, the folder usually looks like this:

my-project/
  embedr.yaml
  platformio.ini
  src/
    main.cpp
  lib/
  datasheets/
  pcb/

Not every project has every folder. datasheets/ appears when you import datasheets. pcb/ appears when you initialize schematic or board design for the project.

The four core nouns

If you are new to embedded development, learn these first.

Term	Meaning in Embedr	Practical example
Project	The repo or folder that contains firmware, config, docs, and optional hardware design files.	line-follower-robot/
Target	The board profile you compile for. It resolves to a PlatformIO platform, board id, and framework.	esp32, uno, pico-w
Environment	A named PlatformIO build profile inside platformio.ini. One project can have more than one.	env:esp32dev, env:test-board
Device	The physical serial or USB port used for upload and serial monitor.	/dev/cu.usbserial-0001, COM5

The common mistake is to treat "board" and "device" as the same thing. They are not. A target answers "what are we compiling for?" A device answers "where is the connected hardware right now?"

What happens when you compile

When you click Compile, Embedr asks the managed Embedr CLI runtime to run a PlatformIO build for the active project. PlatformIO reads platformio.ini, downloads or reuses the required platform packages, compiles the firmware, and writes build artifacts under .pio/.

Embedr streams that output into the Output tab. If compilation fails, the failure is usually in one of these layers:

• the source code has a syntax or type error,
• a library is missing or incompatible,
• the selected target does not match the board or framework,
• the project path or toolchain setup has a platform-specific problem.

The agent can help with all four. Use Ask agent to fix from the Output tab when the build fails; it can inspect the output and then read whatever project files are needed before editing.

What happens when you upload

Upload, also called flashing, writes compiled firmware to the connected board. Upload needs both:

• a target, because PlatformIO needs to know the upload protocol and board rules,
• a device, because the app needs to know which serial or USB port to use.

If upload fails after a successful compile, think in physical terms first: cable, port, driver, boot mode, board power, permissions, or another serial monitor holding the port.

What the agent actually sees

Embedr Agent is project-aware. It can read files, search text, use semantic search when indexing is enabled, inspect the project tree, run builds, install dependencies, use terminal commands, and operate hardware design tools when approved.

You can start with almost any prompt. The agent will try to understand the project as deeply as the task requires. A descriptive prompt is still useful because it saves tokens, reduces back-and-forth, and narrows the search path.

Useful context includes:

• a file mention with @,
• selected compiler output,
• selected code,
• the target board,
• imported datasheets,
• the desired end state.

Both of these can work:

Make it work.

Compile failed after I added the DHT11 library. Please inspect src/main.cpp and the Output tab error, fix the smallest thing, then compile again.

The second one usually costs less and converges faster. It is not a requirement.

Firmware and hardware design in one repo

Embedr treats firmware and board design as different layers of one embedded system.

Firmware lives in files such as .cpp, .c, .ino, and headers. Hardware design can live in pcb/ as .zen source files. The PCB workflow can build, check, place, route, and generate KiCad-compatible board files when the required runtime is available.

That means you can work like this:

1. Write firmware for a sensor.
2. Import the sensor datasheet.
3. Ask the agent to explain pins and wiring.
4. Create or update .zen schematic source.
5. Build, check, place, or route the board.
6. Continue firmware work with the same project context.

A good first session

Use this sequence the first time you open Embedr:

1. Install the app and sign in.
2. Create a blank project with target uno or esp32.
3. Open src/main.cpp.
4. Compile before editing. This checks the toolchain.
5. Select a device and upload only after compile passes.
6. Open Serial Monitor at the baud rate used by your code.
7. Ask the agent one focused question, such as "Explain this project structure."

That first compile is your baseline. It tells you the target and runtime are sane before you add complexity.