Most build mistakes in embedded projects come from mixing up targets, environments, and devices. This page slows those ideas down.
Target
A target is the board profile you want to build for. In Embedr, targets are shown in the Target dropdown.
A target resolves to three PlatformIO values:
| Field | Meaning | Example |
|---|---|---|
platform |
The PlatformIO platform package. | espressif32, atmelavr, ststm32 |
board |
The board id inside that platform. | esp32dev, uno, bluepill_f103c8 |
framework |
The firmware framework. | arduino, espidf, stm32cube, mbed, zephyr |
The preset esp32 means "use the ESP32 DevKit profile", not "find any ESP32 plugged into USB".
Device
A device is a physical serial-capable port. It appears in the Device dropdown.
Examples:
/dev/cu.usbserial-0001,/dev/ttyUSB0,COM5.
Upload needs a device. Compile does not. You can compile for a target with no board plugged in.
Framework
The framework determines the entry point and APIs your firmware uses.
Arduino projects usually have setup() and loop(). ESP-IDF projects use app_main(). Mbed and Zephyr have their own entry points and libraries.
Embedr chooses a source template based on the framework when it creates a new project.
Environment
An environment is a named PlatformIO build profile in platformio.ini.
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
[env:esp32-idf]
platform = espressif32
board = esp32dev
framework = espidf
The compact environment picker in the toolbar lets you switch profiles when a project exposes more than one. The amber dot marks a non-default environment.
Use environments when one folder must support multiple boards, frameworks, or build options.
Target settings
The gear button next to the Target dropdown opens target settings. Supported settings include:
- upload protocol,
- upload speed,
- serial monitor speed,
- debug tool.
For manifest v1 projects, these values are persisted into the project configuration or the active PlatformIO environment. They are not just UI preferences.
Registry targets
Embedr ships with popular board presets and can use a remote board index. The registry includes common Arduino, ESP32, ESP8266, RP2040, STM32, Teensy, Nordic, Mbed, Zephyr, and other PlatformIO-supported targets.
If a board is not visible:
- Open the Target dropdown.
- Search by board family, vendor, MCU, or preset id.
- Try the CLI with
embedr boards --all. - Create a custom target if you know the PlatformIO platform, board id, and framework.
Custom targets
Use Create custom target when your board exists in PlatformIO but Embedr's registry does not show the exact preset you need.
You need:
- a name you recognize,
- PlatformIO platform,
- PlatformIO board id,
- framework.
Example custom target:
name: My ESP32-S3 Module
platform: espressif32
board: esp32-s3-devkitc-1
framework: arduino
Custom targets are useful for lab boards, clones, classroom kits, and newly released boards.
Setup & Diagnostics
The wrench button opens Setup & Diagnostics. Use it when the target list, build tools, or devices are confusing.
It shows:
- active toolchain,
- runtime resolution mode,
- PlatformIO version from the bundled runtime,
- connected serial devices,
- target defaults,
- troubleshooting hints.
Use Copy Diagnostics only when another developer needs the exact runtime context.
Choosing a target for a class or workshop
For beginners, choose a stable target with a common USB serial chip and simple upload flow:
- Arduino Uno: easy first compile and upload,
- ESP32 DevKit: useful for Wi-Fi projects,
- Raspberry Pi Pico: good low-cost microcontroller work,
- Seeed XIAO family: compact but sometimes less forgiving for first-time serial setup.
Avoid mixing several board families in the first lesson. Teach target, device, compile, upload, and serial monitor with one board first.