DOCSEARCHbyAlgolia
Submit Docs

Discovery: Learning Microcontrollers with Rust

repository·master·Indexed 23 days ago

https://github.com/rust-embedded/discovery

An educational project providing hands-on examples and documentation for learning microcontroller development using the Rust programming language. The material focuses on the STM32F3DISCOVERY board (STM32F303VCT6), covering hardware requirements, toolchain setup (including rustup, itmdump, and cargo-binutils), bare-metal Rust attributes like #![no_std] and #![no_main], and interacting with hardware components such as LEDs, buttons, and sensors.

Tokens
76.9K
Snippets
173
Records
353
Agent score
81%

What's inside rust-embedded-discovery

  1. Overview of the Discovery course

    master

    Discovery is an introductory course designed to teach microcontroller-based embedded systems using Rust. It is intended for beginners with no prior experience in microcontrollers or embedded systems. The course focuses on practical, hands-on learning using the micro:bit development board.

    Key learning areas include:

    • Embedded Workflow: Writing, building, flashing, and debugging Rust programs.
    • Peripherals: Digital I/O, PWM, ADC, and communication protocols (Serial, I2C, SPI).
    • Multitasking: Cooperative vs. preemptive multitasking, interrupts, and schedulers.
    • Control Systems: Sensors, calibration, digital filters, actuators, and open/closed loop control.

    Note: This course assumes familiarity with the Rust programming language, as it focuses on embedded systems rather than teaching Rust itself.

  2. Hardware Overview: micro:bit

    master

    The micro:bit is a development board used in this project. The core component is the microcontroller (MCU), which executes the code you write.

    Key hardware components include:

    • Microcontroller (MCU): The primary chip that runs your code (the larger of the two black squares near the USB port).
    • LED Matrix: A grid of LEDs on the back of the board.
    • User Buttons: Two buttons for user interaction.
    • Reset Button: Located next to the USB port.
    • USB Port: For connectivity.
    • Sensors: Includes both a magnetometer and an accelerometer.

  3. Hardware Overview: STM32F3DISCOVERY (the 'F3')

    master

    The STM32F3DISCOVERY (referred to as 'F3') is the development board used in this project. It contains several key components that can be interacted with via code:

    • Microcontroller (MCU): The central component (the large black square) that executes your code.
    • LEDs: Includes a set of eight LEDs arranged in a 'compass' formation.
    • Buttons: Two physical buttons for user input.
    • USB Ports: Two ports for connectivity.
    • Sensors: An accelerometer, a magnetometer, and a gyroscope.

  4. Identify the micro:bit v2 hardware (Nordic nRF52833)

    master

    The micro:bit v2 uses the Nordic nRF52833 microcontroller (MCU). This is a 'System on a Chip' (SoC) that includes Bluetooth Low Energy and 2.4 GHz radio frequency (RF) capabilities.

    Key hardware characteristics:

    • Package: aQFN73 (73 tiny metal pins sitting underneath the chip).
    • Memory: The AA variant code for this specific chip indicates 512 kilobyte flash and 128 kilobyte RAM.
    • Processor Core: It is based on the ARM® Cortex™-M4 32-bit processor.

    When working with this hardware, you will frequently use tools and documentation specifically designed for Cortex-M based chips, as the nRF52833 implements the Cortex-M design licensed from Arm.

  6. Required development tools overview

    master

    Developing for microcontrollers requires specific tools for cross-architecture debugging and serial communication. The following tools are recommended:

    • Rust Toolchain: Version 1.57.0 or newer.
    • Debugger: gdb-multiarch (tested version 10.2). Alternatively, arm-none-eabi-gdb or a multiarch-enabled gdb can be used.
    • Binary Utilities: cargo-binutils (version 0.3.3 or newer).
    • Embedded Debugging: cargo-embed (version 0.24.0 or newer).
    • Serial Terminal (Linux/macOS): minicom (tested version 2.7.1).
    • Serial Terminal (Windows): PuTTY.

  7. Use the accelerometer for motion sensing

    master

    The f3discovery board includes an accelerometer as part of the LSM303DLHC package. You can access it via the I2C bus to measure acceleration (e.g., for measuring the power of a punch). The accelerometer shares the same coordinate system as the magnetometer on the board.

    To simplify development, use the high-level API provided by the project to retrieve sensor readings directly in a structured struct format.

  8. Follow the Discovery learning path

    master

    The Discovery repository is organized into progressive challenges and modules designed to teach embedded Rust development. The curriculum covers:

    • Basics: Background, hardware requirements, and environment setup.
    • Hardware Interaction: LED control (led-roulette, leds-again), Clocks and timers, and Registers.
    • Communication Protocols: Serial communication (USART), Bluetooth setup, and I2C (e.g., interacting with the LSM303DLHC sensor).
    • Advanced Projects: LED compass and the Punch-o-meter.
    • Async IO: Exploring the future of asynchronous programming in embedded Rust.

    Each module typically includes a challenge, a discussion of the underlying hardware/abstractions, and a reference solution.

  9. What is I2C and how does it work

    master

    I2C (Inter-Integrated Circuit) is a synchronous serial communication protocol used to exchange data between devices. It is commonly used for digital sensors, such as the accelerometer and magnetometer found on the F3 board.

    Key Characteristics:

    • Two-Wire Interface: Uses a data line (SDA) and a clock line (SCL).
    • Synchronous: The clock line (SCL) synchronizes the communication.
    • Master-Slave Model: A master device initiates and drives communication with slave devices.
    • Addressing: A master communicates with a specific slave by broadcasting its address (either 7 bits or 10 bits long).
    • Bus Access: Multiple masters and slaves can be connected to the same bus. Once a master starts communication with a slave, the bus is occupied until the master stops the communication.
    • Clock Speeds: Typically operates in Standard mode (100 KHz) or Fast mode (400 KHz).

  11. How embedded-hal unifies hardware abstractions

    master

    [embedded-hal] is a central crate in the Rust embedded ecosystem that provides a set of traits defining common behaviors for peripherals.

    Instead of writing drivers for a specific chip, you can write platform agnostic drivers that rely only on embedded-hal traits. For example, a driver for a temperature sensor can be written to use traits for I2C communication. This allows the same driver to work on any microcontroller that has a HAL implementing those specific embedded-hal traits. Most drivers found on crates.io follow this pattern, making them portable across different hardware platforms.

  12. Understand the Rust Embedded abstraction layers

    master

    The Rust embedded ecosystem is organized into three primary layers of abstraction to manage the complexity of hardware interaction:

    1. Peripheral Access Crate (PAC): Provides a low-level, direct interface to the chip's peripherals. It allows for bit-level configuration of the hardware. You typically use a PAC only when higher-level abstractions are insufficient or when developing new HALs.
    2. Hardware Abstraction Layer (HAL): Built on top of the PAC, the HAL provides a more usable, high-level API. It abstracts complex peripheral behaviors into manageable structures (e.g., a struct for sending data via a serial peripheral).
    3. Board Support Crate (BSP): (Historically called a Board Support Package). This layer abstracts an entire development board (like the micro:bit). It provides abstractions for both the microcontroller and the specific components on the board, such as sensors and LEDs.

    When working with custom boards, you might use a HAL for the chip and then either write your own drivers or find existing drivers for specific sensors on crates.io.