> ## Documentation Index > Fetch the complete documentation index at: https://docs.embedder.com/llms.txt > Use this file to discover all available pages before exploring further. # COMMON WORKFLOWS # Common Workflows Step-by-step guides for hardware development, firmware debugging, and everyday tasks with Embedder CLI. *** ## Start a new project ### Set up your project 1. **Create or select a project** ``` /project ``` Choose an existing project or create a new one. 2. **Select your chip/board** ``` /chip ``` Choose your microcontroller or development board. Embedder loads relevant documentation automatically. 3. **Add peripherals** ``` /peripheral ``` Select peripherals you're using (I2C sensors, SPI displays, UART modules, etc.). You can also add custom peripherals and upload their datasheets. 4. **Generate EMBEDDER.md** ``` /init ``` Creates an `EMBEDDER.md` file with your project context, pin mappings, and configuration. This file is updated throughout your project. **Tips:** * Upload datasheets via the web console (`/console`) before starting for best results * The AI understands your hardware context from the uploaded documentation * Update `EMBEDDER.md` as your project evolves *** ## Hardware interaction ### Use the serial monitor The serial terminal is integrated directly into Embedder. The AI reads serial output automatically. **Open the serial sidebar:** ``` /serial ``` Or use the keyboard shortcut: \`Ctrl+\`\` (backtick) **Auto-connect behavior:** * By default, Embedder auto-connects to your device after flashing * To disable auto-connect, update your `EMBEDDER.md` or prompt: ``` > don't auto-connect to serial after flashing ``` ### Configure peripherals Add or modify peripherals at any time: ``` /peripheral ``` Example prompts: ``` > add an SSD1306 OLED display on I2C ``` ``` > configure UART2 for GPS module at 9600 baud ``` ``` > what pins should I use for SPI on this board? ``` *** ## Firmware development ### Write peripheral drivers Embedder has context from your datasheets and documentation. ``` > write an I2C driver for the BME280 sensor ``` ``` > create a UART driver for the ESP32 ``` ``` > implement SPI communication for the SD card module ``` ### Build and flash Embedder knows the required toolchains and dependencies from the project catalogue. Ask for help getting started: ``` > help me install the dependencies for this project ``` ``` > build the project ``` ``` > flash the firmware to the device ``` ``` > build and flash, then show me the serial output ``` ### Work with HALs and SDKs Embedder understands vendor-specific HALs and SDKs: ``` > how do I configure the STM32 HAL for I2C? ``` ``` > show me how to use the ESP-IDF GPIO driver ``` ``` > what's the correct way to initialize DMA on this chip? ``` *** ## Debug with serial output The AI reads serial output directly and can analyze issues in real-time. ### Analyze errors ``` > what's causing this error in the serial output? ``` ``` > the device keeps resetting, analyze the crash dump ``` ``` > parse the debug logs and find the issue ``` ### Share screenshots Drag and drop images or paste with `Ctrl+V`: ``` > here's a screenshot of the error, what's wrong? ``` ``` > this is the oscilloscope output, is the signal correct? ``` ### Trace execution ``` > add debug prints to trace the initialization sequence ``` ``` > why isn't the interrupt handler being called? ``` *** ## Plan mode vs Act mode Embedder has two modes for different workflows. ### Act mode (default) Full tool access. Embedder can read, write, and execute. Use for: * Writing and modifying code * Building and flashing firmware * Making changes to your project ### Plan mode Read-only analysis. Embedder researches without making changes. Use for: * Exploring unfamiliar code * Planning complex refactors * Reviewing architecture before changes * Analyzing datasheets **Toggle between modes:** * Keyboard: `Shift+Tab` * Commands: `/plan` or `/act` **Start in plan mode:** ``` > /plan > analyze the power management implementation and suggest improvements ``` *** ## Documentation and context ### Leverage uploaded documentation Upload datasheets and manuals via the web console (`/console`). The `/console` command lets you upload additional documentation to existing platforms and peripherals in your project. Embedder uses them automatically: ``` > what's the maximum I2C clock speed for this sensor? ``` ``` > show me the register map for the accelerometer ``` ``` > what are the power consumption specs in sleep mode? ``` ### Hardware-aware assistance Embedder understands your specific hardware: ``` > which pins support PWM on this board? ``` ``` > what's the pin mapping for the Arduino header? ``` ``` > can I use DMA with this UART peripheral? ``` *** ## Bash mode Bypass the AI agent and execute terminal commands directly using the `!` prefix. ``` !ls -la ``` ``` !make clean ``` ``` !git status ``` This runs the command in your terminal without AI interpretation. Useful for quick commands when you don't need AI assistance. *** ## Serial send mode Send messages directly to your MCU over serial using the `~` prefix. ``` ~help ``` ``` ~reset ``` ``` ~get status ``` This sends the text directly to your device's serial console. Useful for: * Sending AT commands * Interacting with device CLI/REPL * Manual debugging commands *** ## Reference files and directories Use `@` to quickly include files or directories in your prompts. ### Reference a file ``` > explain the logic in @src/main.c ``` ``` > what does @drivers/i2c.h do? ``` ### Reference a directory ``` > what's in @src/drivers/? ``` ``` > show me the structure of @lib/ ``` ### Multiple references ``` > compare @src/old_driver.c and @src/new_driver.c ``` *** ## Session management ### Switch teams and projects ``` /team # Switch team (if you have multiple) /project # Switch to a different project ``` ### Resume previous sessions ``` /history # Browse and resume past conversations ``` Or use keyboard shortcut for quick access to history. ### Manage context For long conversations: ``` /compress # Compress conversation to save context ``` ### Track tasks View your current task list: ``` /tasks ``` *** ## Quick reference | Workflow | Command/Shortcut | | ------------------- | ---------------------------------------------- | | New project setup | `/project` → `/chip` → `/peripheral` → `/init` | | Serial monitor | `/serial` or \`Ctrl+\`\` | | Switch mode | `Shift+Tab` or `/plan` `/act` | | Switch model | `/model` or `Ctrl+Alt+B` | | Add peripheral | `/peripheral` | | Reference file | `@filename` in prompt | | Bash mode | `!command` (e.g., `!ls`) | | Serial send | `~message` (e.g., `~help`) | | Undo last message | `/undo` or `Ctrl+Z` | | Rewind conversation | `/rewind` or `Ctrl+Z (2x)` | | Resume session | `/history` | | Compress context | `/compress` | | View tasks | `/tasks` | | Web console | `/console` | | Get help | `/help` | *** ## Tips for best results * **Upload documentation first** - Add datasheets via the web console (`/console`) before starting * **Use /init early** - Generate `EMBEDDER.md` to give the AI full project context * **Be specific about hardware** - Mention exact part numbers and pin configurations * **Use plan mode for research** - Explore codebases without accidental changes * **Keep EMBEDDER.md updated** - Add notes about your project as it evolves