# Reading the Documentation You now have a mental model: **Create → Configure → Control**. Let's turn that into a practical skill — reading embedded Rust documentation efficiently. ## Anatomy of a docs.rs Page When you open a struct page on docs.rs (like `esp_hal::gpio::Output`), here's what you'll find: ### 1. Module Path (top of page) ``` esp_hal::gpio → Output ``` This tells you where you are in the crate's hierarchy. The module path is your navigation breadcrumb. ### 2. Struct Definition Shows the type parameters and fields (if public). Tells you what the struct *is*. ### 3. Implementations (`impl Output`) **This is where Create and Control live.** Look for: - `new()` or `builder()` — how to create an instance - Control methods — `set_high()`, `toggle()`, `get_level()`, etc. ### 4. Trait Implementations (`impl OutputPin for Output`) **These are the portable methods.** If a struct implements `embedded_hal::digital::OutputPin`, you know it has `set_high()` and `set_low()` — and you know those methods will exist on *any* HAL, not just `esp-hal`. ### 5. Associated Types and Enums Click through to `OutputConfig`, `DriveStrength`, `Pull`, etc. **This is where Configure lives.** --- ## HAL Docs vs. Driver Crate Docs They look the same on docs.rs, but the context is different: | | HAL Docs (esp-hal) | Driver Crate Docs (e.g., icm42670) | |---|---|---| | **Create** | Takes pins + peripheral instances | Takes an `I2c` or `Spi` bus (generic!) | | **Configure** | Chip-specific settings (pin mode, clock speed) | Device-specific settings (sample rate, range) | | **Control** | Low-level operations (write bytes, read registers) | High-level operations (read acceleration, read temperature) | | **Trait impls** | Implements `embedded-hal` traits | *Uses* `embedded-hal` traits as bounds | --- ## Finding Examples Examples are your starting point for every exercise. Here's where to find them: ### Workshop Repo (primary) All exercise starting points are in the `examples/` directory of this workshop's repository. These are tested, working code that you'll adapt. ### esp-hal Repo (side exploration) The [esp-hal GitHub repo](https://github.com/esp-rs/esp-hal) has examples organized by category: ``` examples/ ├── interrupt/gpio/ ← GPIO interrupt example ├── peripheral/spi/ ← SPI examples ├── async/embassy_*/ ← Async/Embassy examples └── ... ``` ### Driver Crate READMEs Most driver crates include usage examples in their README or docs.rs documentation. Check both. --- ## The Workshop Workflow Every hands-on module will follow this flow: ``` ┌─────────────────────┐ │ 1. READ the example │ ← Working code in the workshop repo │ in the repo │ ├─────────────────────┤ │ 2. UNDERSTAND it │ ← Map it to Create → Configure → Control │ using the docs │ ├─────────────────────┤ │ 3. ADAPT it │ ← Change config, try different controls, │ to do something │ use what you found in the docs │ different │ ├─────────────────────┤ │ 4. EXTEND it │ ← Stretch goals: navigate unfamiliar │ (stretch goal) │ documentation on your own └─────────────────────┘ ``` The example shows **one** way to use a peripheral. The docs show **all** of them. Your job is to explore. Ready? Let's get our hands dirty with GPIO.
The Embedded Rustacean · Rust Week 2026
The Embedded Rustacean · Rust Week 2026
The Embedded Rustacean · Rust Week 2026