Embassy async runtime and HAL for HT32F523xx microcontrollers

An in-development Embassy implementation for selected HT32F523xx peripherals, with async GPIO/UART/timer support and a USB Full-Speed device driver.

Version: 0.2.1 Status: 🟡 Active Development Hardware Testing: HT32F52352 on ESK32-30501; see the support matrix below

This is a unified crate providing Embassy async runtime and hardware abstraction for HT32F523xx microcontrollers:

• Embassy-native: Built from ground up for Embassy async runtime
• Hardware-validated core: clocks, GPIO/EXTI, Embassy time, BFTM, USART0 TX, Flash, USB CDC and vendor Raw HID on HT32F52352
• USB Ready: Full-Speed device mode with CDC-ACM and HID examples
• RMK integration example: pinned RMK 0.9 fixed-keymap target links within the HT32F52352 memory budget; keyboard semantics remain an upper-layer concern
• Probe-rs Ready: Complete development environment with examples

Install required tools:

# Install Rust target for Cortex-M0+
rustup target add thumbv6m-none-eabi

# Install probe-rs for flashing and debugging
cargo install probe-rs --locked
cargo install cargo-embed --locked

# Build all workspace members
cargo build --release

# Build specific example
cargo build --release -p blink

# Flash and run blink example
cargo run --release -p blink

# Or use probe-rs directly
cargo embed -p blink

# Flash and run serial echo example
cargo run --release -p serial-echo

# Flash and run USB HID keyboard example
cargo run --release -p usb-hid-keyboard

• HT32F52342 - Cortex-M0+, 48MHz, 64KB Flash, 8KB SRAM
• HT32F52352 - Cortex-M0+, 48MHz, 128KB Flash, 16KB SRAM (default)
• Uses the crates.io ht32f523x2 PAC version 0.6.0

• ESK32-30501 starter kit (default BSP configuration)
• BSP pin mappings: active-low LEDs (PC14/PC15), WAKEUP header signal (PB12), USART0 module connector (PA2/PA3)
• Compatible with any HT32F523xx development board

Host-visible USB tests and register/counter checks do not replace measurement of signals at the pins. Before a production-oriented release, run one final logic-analyzer acceptance pass using the public HAL APIs and real board pins:

A logic analyzer is sufficient for digital protocol and timing assertions, but not for GPIO drive-current compliance, rise/fall time under a specified load, analog ADC accuracy, or power integrity. Those require an oscilloscope and/or DMM with a defined electrical load. Flash erase/program verification is done by readback, while USB needs host/protocol tests rather than GPIO-channel capture. For later peripherals, I2S also needs protocol/timing capture, WDT reset timing can use a GPIO marker plus reset observation, and PDMA must be stressed through the peripheral it serves. RTC/LSE accuracy is better measured with a frequency counter or a long-window reference than with a short logic-analyzer capture.

embassy-ht32f523xx/           # Root crate (was: ht32-hal + embassy-ht32)
├── Cargo.toml               # Main crate configuration
├── build.rs                 # Chip selection build script
├── memory_ht32f52342.x      # Linker script for HT32F52342
├── memory_ht32f52352.x      # Linker script for HT32F52352
├── src/                     # Unified HAL + Embassy implementation
│   ├── lib.rs              # Crate entry point
│   ├── chip/               # Chip-specific definitions
│   │   ├── ht32f52342.rs   # HT32F52342 configuration
│   │   ├── ht32f52352.rs   # HT32F52352 configuration
│   │   └── mod.rs          # Chip selection logic
│   ├── gpio.rs             # GPIO with Embassy digital traits
│   ├── rcc.rs              # Clock management
│   ├── time.rs             # Time units (Hertz, Microseconds)
│   ├── time_driver.rs      # Embassy time driver
│   ├── timer.rs            # BFTM one-shot timers
│   ├── uart.rs             # USART with nb traits and inherent async methods
│   ├── usb.rs              # USB device driver
│   ├── flash.rs            # Asynchronous Flash erase/program
│   ├── exti.rs             # External interrupts
│   ├── interrupt.rs        # Interrupt handling
│   └── fmt.rs              # Formatting utilities
├── bsp/                     # Board Support Package
│   └── src/esk32_30501.rs  # ESK32-30501 development board
├── examples/                # Ready-to-run examples
│   ├── blink/              # LED blink (Embassy async)
│   ├── serial-echo/        # UART echo (Embassy async)
│   ├── usb-hid-keyboard/   # USB HID keyboard
│   ├── usb-raw-hid-speed-test/ # Vendor Raw HID throughput test
│   └── ht32-rmk-60key/     # Lean, pinned RMK integration example
├── IMPLEMENTATION_PROGRESS.md # Capability and acceptance roadmap
└── VALIDATION_REPORT.md    # Evidence-scoped hardware validation

• Single Crate: No more ht32-hal vs embassy-ht32 split
• Embassy-First: Built for async/await from the ground up
• Feature Flags: Select chip variant and peripherals at compile time
• Zero-Cost: Embassy async with no runtime overhead
• Evidence scoped: hardware-tested paths are distinguished from planned peripherals

See examples/ht32-rmk-60key/ for the fixed-keymap RMK integration and its automated Flash/static-RAM budget gate. It demonstrates framework compatibility; it does not make RMK matrix or complete HID semantics part of HAL acceptance.

• 📊 Implementation Progress - Capability and analyzer acceptance roadmap
• 🔍 Hardware Validation Report - Evidence-scoped source, board and measurement status
• 📋 OpenSpec changes - Approved and proposed implementation work

• 📖 HT32F523xx Datasheet - Official hardware documentation
• 🚀 Embassy Framework - Async runtime documentation
• 🦀 Embedded Rust Book - Rust embedded development guide
• 🎛️ RMK Keyboard Firmware - Advanced keyboard features

1. Close existing signal-level gates - GPIO/EXTI and USART analyzer tests
2. I2C Driver (src/i2c.rs) - High impact peripheral
3. SPI Driver (src/spi.rs) - Critical for displays/sensors
4. PWM Driver - GPTM/SCTM/MCTM output compare and Embassy-facing API
5. ADC / PDMA Drivers - Analog input and efficient transfers

• Embassy async patterns following existing implementations
• Hardware validation against PAC definitions
• Memory safety with documented unsafe usage
• Comprehensive error handling (no panics in production)

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.