0.19.0

Please note that only changes to the esp-hal package are tracked in these release notes.

Migration Guide

Coming Soon™️ (sorry, I forgot to write it 😅)

Changelog

Added

• uart: Added with_cts/with_rtss methods to configure CTS, and RTS pins (#1592)
• uart: Constructors now require TX and RX pins (#1592)
• uart: Added Uart::new_with_default_pins constructor (#1592)
• uart: Added UartTx and UartRx constructors (#1592)
• Add Flex / AnyFlex GPIO pin driver (#1659)
• Add new DmaError::UnsupportedMemoryRegion - used memory regions are checked when preparing a transfer now (#1670)
• Add DmaTransactionTxOwned, DmaTransactionRxOwned, DmaTransactionTxRxOwned, functions to do owning transfers added to SPI half-duplex (#1672)
• uart: Implement embedded_io::ReadReady for Uart and UartRx (#1702)
• ESP32-S3: Expose optional HSYNC input in LCD_CAM (#1707)
• ESP32-C6: Support lp-core as wake-up source (#1723)
• Add support for GPIO wake-up source (#1724)
• gpio: add DummyPin (#1769)
• dma: add Mem2Mem to support memory to memory transfer (#1738)
• Add uart wake source (#1727)
• #[ram(persistent)] option to replace the unsound uninitialized option (#1677)
• uart: Make rx_timeout optional in Config struct (#1759)
• Add interrupt related functions to PeriodicTimer/OneShotTimer, added ErasedTimer (#1753)
• Added blocking read_bytes method to Uart and UartRx (#1784)

Fixed

• ESP32-S3: Fix DMA waiting check in LCD_CAM (#1707)
• TIMG: Fix interrupt handler setup (#1714)
• Fix sleep_light for ESP32-C6 (#1720)
• ROM Functions: Fix address of ets_update_cpu_frequency_rom (#1722)
• Fix regi2c_* functions for esp32h2 (#1737)
• Improved #[ram(zeroed)] soundness by adding a bytemuck::Zeroable type bound (#1677)
• EESP32-S2 / ESP32-S3: Fix UsbDm and UsbDp for Gpio19 and Gpio20
• Fix reading/writing small buffers via SPI master async dma (#1760)
• Remove unnecessary delay in rtc_ctnl (#1794)

Changed

• Refactor Dac1/Dac2 drivers into a single Dac driver (#1661)
• esp-hal-embassy: make executor code optional (but default) again
• Improved interrupt latency on RISC-V based chips (#1679)
• esp_wifi::initialize no longer requires running maximum CPU clock, instead check it runs above 80MHz. (#1688)
• Move DMA descriptors from DMA Channel to each individual peripheral driver. (#1719)
• Support DMA chunk sizes other than the default 4092 (#1758)
• Improved interrupt latency on Xtensa based chips (#1735)
• Improve PCNT api (#1765)

Removed

• uart: Removed configure_pins methods (#1592)
• Removed DmaError::Exhausted error by improving the implementation of the pop function (#1664)
• Unsound #[ram(uninitialized)] option in favor of the new persistent option (#1677)

0.18.0

Please note that only changes to the esp-hal package are tracked in these release notes.

Migration Guide

SystemControl

We have removed the SystemExt trait, meaning that the SYSTEM peripheral no longer has a split() method. Instead, we now instantiate a new SystemControl struct:

use esp_hal::{peripherals::Peripherals, system::SystemControl, clock::ClockControl};

let peripherals = Peripherals::take();
let system = SystemControl::new(peripherals.SYSTEM);
let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

Timers

There have been a number of changes to the various timer drivers in esp-hal, notable the reorganization of their modules. While previously we had systimer (SYSTIMER) and timer (TIMGx) modules, these have been combined into a common module, and are now available at timer::systimer and timer::timg0 respectively.

Additionally, there have been some minor changes in API relating to the introduction of the timer::Timer trait; these should be mostly straight forward to resolve, refer to the documentation.

GPIO

The GPIO system has been reworked to remove into_X methods, in favour of a concrete pin type.

Old into_X method	New type
output	Output
output open drain	OutputOpenDrain
input	Input

For example code such as io.pins.gpio18.into_push_pull_output() should be replaced with Output::new(io.pins.gpio18) for each respective case. To see more discussion and examples for this change, see the RFC and implementation PR.

esp-hal-embassy

As of this release, support for [Embassy] has been extracted from esp-hal into its own package, esp-hal-embassy. This is nearly a drop-in replacement, only a few small changes are required.

First, add the new dependency to your Cargo.toml:

[dependencies]
esp-hal-embassy = { version = "0.1.0", features = [
    "time-timg0",            # Compatible with all chips
    # "time-systimer-16mhz", # Compatible with all chips except ESP32 and ESP32-S2
    # "time-systimer-80mhz", # Compatible with ESP32-S2 only
] }

Note that in previous version, the time-systimer-* features were incorrectly named time-systick-*; this has now been rectified. Additionally, as of this release it is no longer required to select an executor via its Cargo feature; both the thread-mode and interrupt-mode executors are now available by default.

Next, simply replace any references to the esp_hal::embassy module and its children with the esp_hal_embassy package instead. This can likely be accomplished with a simple search-and-replace in your text editor.

Changelog

Added

• i2c: implement I2C:transaction for embedded-hal and embedded-hal-async (#1505)
• spi: implement with_bit_order (#1537)
• ESP32-PICO-V3-02: Initial support (#1155)
• time::current_time API (#1503)
• ESP32-S3: Add LCD_CAM Camera driver (#1483)
• embassy-usb support (#1517)
• SPI Slave support for ESP32-S2 (#1562)
• Add new generic OneShotTimer and PeriodicTimer drivers, plus new Timer trait which is implemented for TIMGx and SYSTIMER (#1570)

Fixed

• i2c: i2c1_handler used I2C0 register block by mistake (#1487)
• Removed ESP32 specific code for resolutions > 16 bit in ledc embedded_hal::pwm max_duty_cycle function. (#1441)
• Fixed division by zero in ledc embedded_hal::pwm set_duty_cycle function and converted to set_duty_hw instead of set_duty to eliminate loss of granularity. (#1441)
• Embassy examples now build on stable (#1485)
• Fix delay on esp32h2 (#1535)
• spi: fix dma wrong mode when using eh1 blocking api (#1541)
• uart: make uart::UartRx::read_byte public (#1547)
• Fix async serial-usb-jtag (#1561)
• Feeding RWDT now actually works (#1645)

Changed

• Removed unneeded generic parameters on Usb (#1469)
• Created virtual peripherals for CPU control and radio clocks, rather than splitting them from SYSTEM (#1428)
• IO, ADC, DAC, RTC*, LEDC, PWM and PCNT drivers have been converted to camel case format (#1473)
• RNG is no longer TRNG, the CryptoRng implementation has been removed. To track this being re-added see #1499 (#1498)
• Make software interrupts shareable (#1500)
• The SystemParts struct has been renamed to SystemControl, and now has a constructor which takes the SYSTEM peripheral (#1495)
• Timer abstraction: refactor systimer and timer modules into a common timer module (#1527)
• Removed the embassy-executor-thread and embassy-executor-interrupt features, they are now enabled by default when embassy is enabled. (#1485)
• Software interrupt 3 is now used instead of software interrupt 0 on the thread aware executor on multicore systems (#1485)
• Timer abstraction: refactor systimer and timer modules into a common timer module (#1527)
• Refactoring of GPIO module, have drivers for Input,Output,OutputOpenDrain, all drivers setup their GPIOs correctly (#1542)
• DMA transactions are now found in the dma module (#1550)
• Remove unnecessary generics from PARL_IO driver (#1545)
• Use Level enum in GPIO constructors instead of plain bools (#1574)
• rmt: make ChannelCreator public (#1597)

Removed

• Removed the SystemExt trait (#1495)
• Removed the GpioExt trait (#1496)
• Embassy support (and all related features) has been removed, now available in the esp-hal-embassy package instead (#1595)

0.17.0

Please note that only changes to the esp-hal package are tracked in these release notes. Read the full changelog entry for all the changes.

[email protected] Migration Guide

This release changes interrupt handler binding from link-time binding to runtime-binding. This increases flexibility of how interrupts can be used, but the main reason is two allow mixing mixing async and non-async drivers in the same application.

Key changes

The biggest change is the removal of the #[interrupt] macro. It has been replaced by the #[handler] macro which works differently slightly differently.

Now you have to bind the interrupt handler explicitly. The supported peripheral drivers either take a new optional parameter to their constructor or it will offer a set_interrupt_handler function. Don't worry, if you forget to do this, the compiler will emit an unused warning for the #[handler] function.

The second change is that most drivers will now have a MODE parameter with some new constructors to initialize a driver in Blocking or Async mode. You will need to account for this in your code.

Finally, most root level re-exports are now gone, instead, you should import from the specific module.

Below is a list of key changes you need to make to upgrade.

There is no longer a need to enable interrupts manually unless you are changing a priority later in the application. This change also means the interrupt is enabled once the interrupt is used, so please ensure that you have the proper ordering of initialization or critical sections to account for that.

- interrupt::enable(Interrupt::GPIO, Priority::Priority2).unwrap();

Use the new handler macro.

- #[interrupt]
+ #[handler]

Ensure you set the handler, depending on the peripheral this may be part of the constructor or a method such as the one below.

+ io.set_interrupt_handler(handler);

Interrupts are now tightly coupled to their priority, meaning you can pass a priority to the handler macro. The default unless specified is the lowest priority.

+ #[handler(priority = "Priority::max()")]

0.16.1

Please note that only changes to the esp-hal package are tracked in these release notes.

Fixed

• Resolved an issue with the defmt dependency/feature (#1264)

Changed

• Use ROM memcpy over compiler builtins (#1255)
• Do not ensure randomness or implement the CryptoRng trait for ESP32-P4/S2 (#1267)

0.16.0

Please note that only changes to the esp-hal package are tracked in these release notes.

[email protected] Migration Guide

This release consolidates the various chip-specific HAL packages into a single package, esp-hal. Projects which previously depended on the chip-specific packages (esp32-hal, esp32c3-hal, etc.) should be updated to use esp-hal instead.

We now have self-hosted documentation built for each supported chip! See https://docs.esp-rs.org/esp-hal/ for more details.

In order to migrate your project to the latest release, please follow the short guide below.

If you encounter any issues during the migration process, please open an issue, and we will do our best to resolve them as expediently as possible.

Migrating to esp-hal

In general, only two steps should be required for this migration:

• Update your dependencies in the Cargo manifest
• Update any references to the HAL in your project's source files

Depending on which features you are using, there may be some additional changes required. Please refer to the esp-hal documentation for a full list of features.

Updating Dependencies

First, update your dependencies in Cargo.toml and enable the appropriate feature for the chip being targeted.

For example, if your project previously depended on esp32c3-hal then open your project's Cargo.toml file and make the following change:

- esp32c3-hal = "0.15.0"
+ esp-hal = { version = "0.16.0", features = ["esp32c3"] }

Update Imports

Next, update any references to the chip-specific HAL package (e.g. esp32c3-hal) in your project's source files. This can likely be done with a global search-and-replace in your favourite text editor.

In general this will only affect imports, e.g.:

- use esp32c3_hal::*;
+ use esp_hal::*;

Changelog

Added

• Add initial support for the ESP32-P4 (#1101)
• Implement embedded_hal::pwm::SetDutyCycle trait for ledc::channel::Channel (#1097)
• ESP32-P4: Add initial GPIO support (#1109)
• ESP32-P4: Add initial support for interrupts (#1112)
• ESP32-P4: Add efuse reading support (#1114)
• ESP32-S3: Added LCD_CAM I8080 driver (#1086)
• Allow for splitting of the USB Serial JTAG peripheral into tx/rx components (#1024)
• RngCore trait is implemented (#1122)
• Support Rust's stack-protector feature (#1135)
• Adding clock support for ESP32-P4 (#1145)
• Implementation OutputPin and InputPin for AnyPin (#1067)
• Implement estimate_xtal_frequency for ESP32-C6 / ESP32-H2 (#1174)
• A way to push into I2S DMA buffer via a closure (#1189)
• Added basic LP-I2C driver for C6 (#1185)
• Ensuring that the random number generator is TRNG. (#1200)
• ESP32-C6: Add timer wakeup source for deepsleep (#1201)
• Introduce InterruptExecutor::spawner() (#1211)

Fixed

• Fix embassy-time tick rate not set when using systick as the embassy timebase (#1124)
• Fix get_raw_core on Xtensa (#1126)
• Fix docs.rs documentation builds (#1129)
• Fix circular DMA (#1144)
• Fix hello_rgb example for ESP32 (#1173)
• Fixed the multicore critical section on Xtensa (#1175)
• Fix timer now for esp32c3 and esp32c6 (#1178)
• Wait for registers to get synced before reading the timer count for all chips (#1183)
• Fix I2C error handling (#1184)
• Fix circular DMA (#1189)
• Fix esp32c3 uart initialization (#1156)
• Fix ESP32-S2 I2C read (#1214)
• Reset/init UART if it's not the console UART (#1213)

Changed

• DmaDescriptor struct to better model the hardware (#1054)
• DMA descriptor count no longer needs to be multiplied by 3 (#1054)
• RMT channels no longer take the channel number as a generic param (#959)
• The esp-hal-common package is now called esp-hal (#1131)
• Refactor the Trace driver to be generic around its peripheral (#1140)
• Auto detect crystal frequency based on RtcClock::estimate_xtal_frequency() (#1165)
• ESP32-S3: Configure 32k ICACHE (#1169)
• Lift the minimal buffer size requirement for I2S (#1189)

Removed

• Remove xtal-26mhz and xtal-40mhz features (#1165)
• All chip-specific HAL packages have been removed (#1196)

Breaking

• ADC and DAC drivers now take virtual peripherals in their constructors, instead of splitting APB_SARADC/SENS (#1100)
• The DAC driver's constructor is now new instead of dac, to be more consistent with other APIs (#1100)
• The DMA peripheral is now called Dma for devices with both PDMA and GDMA controllers (#1125)
• The ADC driver's constructor is now new instead of adc, to be more consistent with other APIs (#1133)
• embassy-executor's integrated-timers is no longer enabled by default.
• Renamed embassy-time-systick to embassy-time-systick-16mhz for use with all chips with a systimer, except esp32s2. Added embassy-time-systick-80mhz specifically for the esp32s2. (#1247)

0.15.0

Please note that only changes to the esp-hal-common package are tracked in these release notes.

Added

• ESP32-C6: Properly initialize PMU (#974)
• Implement overriding base mac address (#1044)
• Add rt-riscv and rt-xtensa features to enable/disable runtime support (#1057)
• ESP32-C6: Implement deep sleep (#918)
• Add embedded-io feature to each chip-specific HAL (#1072)
• Add embassy-time-driver to esp-hal-common due to updating embassy-time to v0.3.0 (#1075)
• ESP32-S3: Added support for 80Mhz PSRAM (#1069)

Changed

• Set up interrupts for the DMA and async enabled peripherals only when async feature is provided (#1042)
• Update to 1.0.0 releases of the embedded-hal-* packages (#1068)
• Update embassy-time to 0.3.0 and embassy-executor to 0.5.0 release due to the release of the embedded-hal-* packages (#1075)
• No longer depend on embassy-time (#1092)
• Update to latest smart-leds-trait and smart-leds packages (#1094)

Fixed

• ESP32: correct gpio 32/33 in errata36() (#1053)
• ESP32: make gpio 4 usable as analog pin (#1078)
• Fix double &mut for the SetDutyCycle impl on PwmPin (#1033)
• ESP32/ESP32-S3: Fix stack-top calculation for app-core (#1081)
• ESP32/ESP32-S2/ESP32-S3: Fix embassy-time-timg0 driver (#1091)
• ESP32: ADC readings are no longer inverted (#1093)

Breaking

• Unify the low-power peripheral names (RTC_CNTL and LP_CLKRST to LPWR) (#1064)

0.14.1

Please note that only changes to the esp-hal-common package are tracked in these release notes.

Fixed

• Fix SHA for all targets (#1021)

0.14.0

Please note that only changes to the esp-hal-common package are tracked in these release notes.

Added

• ESP32-C6: LP core clock is configurable (#907)
• Derive Clone and Copy for EspTwaiFrame (#914)
• A way to configure inverted pins (#912)
• Added API to check a GPIO-pin's interrupt status bit (#929)
• A embedded_io_async::Read implementation for UsbSerialJtag (#889)
• RtcClock::get_xtal_freq, RtcClock::get_slow_freq (#957)
• Added Rx Timeout functionality to async Uart (#911)
• RISC-V: Thread-mode and interrupt-mode executors, #[main] macro (#947)
• A macro to make it easier to create DMA buffers and descriptors (#935)
• I2C timeout is configurable (#1011)
• ESP32-C6/ESP32-H2: flip-link feature gives zero-cost stack overflow protection (#1008)

Changed

• Improve DMA documentation & clean up module (#915)
• Only allow a single version of esp-hal-common to be present in an application (#934)
• ESP32-C3/C6 and ESP32-H2 can now use the zero-rtc-bss feature to enable esp-hal-common/rv-zero-rtc-bss (#867)
• Reuse ieee802154_clock_enable/disable() functions for BLE and rename ble_ieee802154_clock_enable() (#953)
• The embedded-io trait implementations are now gated behind the embedded-io feature (#964)
• Simplifed RMT channels and channel creators (#958)
• Reworked construction of I2S driver instances (#983)
• ESP32-S2/S3: Don't require GPIO 18 to create a USB peripheral driver instance (#990)
• Updated to latest release candidate (1.0.0-rc.2) for embedded-hal{-async,-nb} (#994)
• Explicit panic when hitting the DefaultHandler (#1005)
• Relevant interrupts are now auto enabled in embassy::init (#1014).

Fixed

• ESP32-C2/C3 examples: fix build error (#899)
• ESP32-S3: Fix GPIO interrupt handler crashing when using GPIO48. (#898)
• Fixed short wait times in embassy causing hangs (#906)
• Make sure to clear LP/RTC RAM before loading code (#916)
• Async RMT channels can be used concurrently (#925)
• Xtensa: Allow using embassy-executor's thread-mode executor if neither embassy-executor-thread, nor embassy-executor-interrupt is enabled. (#937)
• Uart Async: Improve interrupt handling and irq <--> future communication (#977)
• RISC-V: Fix stack allocation (#988)
• ESP32-C6: Fix used RAM (#997)
• ESP32-H2: Fix used RAM (#1003)
• Fix SPI slave DMA dma_read and dma_write (#1013)

Removed

• Direct boot support has been removed (#903).
• Removed the mcu-boot feature from esp32c3-hal (#938)
• Removed SpiBusController and SpiBusDevice in favour of embedded-hal-bus and embassy-embedded-hal implementataions. (#978)

Breaking

• Spi::new/Spi::new_half_duplex takes no gpio pin now, instead you need to call with_pins to setup those (#901).
• ESP32-C2, ESP32-C3, ESP32-S2: atomic emulation trap has been removed. (#904) (#985)
  • When upgrading you must either remove these lines from your .cargo/config.toml.
  • Usage of core::sync::atomic::* in dependent crates should be replaced with portable-atomic.
• RSA driver now takes u32 words instead of u8 bytes. The expected slice length is now 4 times shorter. (#981)

0.13.1

Please note that only changes to the esp-hal-common package are tracked in these release notes.

Fixed

• ESP32-C3: Make sure BLE and WiFi are not powered down when esp-wifi needs them (#891)
• ESP32-C6/H2: Fix setting UART baud rate (#893)

0.13.0

Please note that only changes to the esp-hal-common package are tracked in these release notes.

Added

• Added embassy-time-systick to ESP32-S2 (#827)
• Implement enabling/disabling BLE clock on ESP32-C6 (#784)
• Async support for RMT (#787)
• Implement defmt::Format for more types (#786)
• Add new_no_miso to Spi FullDuplexMode (#794)
• Add UART support for splitting into TX and RX (#754)
• Async support for I2S (#801)
• Async support for PARL_IO (#807)
• ETM driver, GPIO ETM (#819)
• (G)DMA AES support (#821)
• SYSTIMER ETM functionality (#828)
• Adding async support for RSA peripheral(doesn't work properly for esp32 chip - issue will be created)(#790)
• Added sleep support for ESP32-C3 with timer and GPIO wakeups (#795)
• Support for ULP-RISCV including Delay and GPIO (#840, #845)
• Add bare-bones SPI slave support, DMA only (#580, #843)
• Embassy #[main] convenience macro (#841)
• Add a defmt feature to the esp-hal-smartled package (#846)
• Support 16MB octal PS-RAM for ESP32-S3 (#858)
• RISCV TRACE Encoder driver for ESP32-C6 / ESP32-H2 (#864)

Changed

• Bumped MSRV to 1.67 (#798)
• Optimised multi-core critical section implementation (#797)
• Changed linear- and curve-calibrated ADC to provide readings in mV (#836)

Fixed

• S3: Allow powering down RC_FAST_CLK (#796)
• UART/ESP32: fix calculating FIFO counter with get_rx_fifo_count() (#804)
• Xtensa targets: Use ESP32Reset - not Reset (#823)
• Examples should now work with the defmt feature (#810)
• Fixed a race condition causing SpiDma to stop working unexpectedly (#869)
• Fixed async uart serial, and updated the embassy_serial examples (#871).
• Fix ESP32-S3 direct-boot (#873)
• Fix ESP32-C6 ADC (#876)

Removed

• Pin::is_pcore_interrupt_set (#793)
• Pin::is_pcore_non_maskable_interrupt_set (#793)
• Pin::is_acore_interrupt_set (#793)
• Pin::is_acore_non_maskable_interrupt_set (#793)
• Pin::enable_hold (#793)
• Removed the generic return type for ADC reads (#792)

Breaking

• Uart::new now takes the &Clocks struct to ensure baudrate is correct for CPU/APB speed. (#808)
• Uart::new_with_config takes an Config instead of Option<Config>. (#808)
• Alarm::set_period takes a period (duration) instead of a frequency (#812)
• Alarm::interrupt_clear is now Alarm::clear_interrupt to be consistent (#812)
• The PeripheralClockControl struct is no longer public, drivers no longer take this as a parameter (#817)
• Unify the system peripheral, SYSTEM, DPORT and PCR are now all exposed as SYSTEM (#832).
• Unified the ESP32's and ESP32-C2's xtal frequency features (#831)
• Replace any underscores in feature names with dashes (#833)
• The spi and spi_slave modules have been refactored into the spi, spi::master, and spi::slave modules (#843)
• The WithDmaSpi2/WithDmaSpi3 structs are no longer generic around the inner peripheral type (#853)
• The SarAdcExt/SensExt traits are now collectively named AnalogExt instead (#857)
• Replace the radio module with peripheral singleton structs (#852)
• The SPI traits are no longer re-exported in the main prelude, but from preludes in spi::master/spi::slave instead (#860)
• The embedded-hal-1 and embedded-hal-async traits are no longer re-exported in the prelude (#860)