ESP HAL

https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/
Admin
ESP HAL is a bare-metal, no_std Hardware Abstraction Layer for Espressif's ESP32 microcontrollers...
Tokens:1,316,678
Snippets:13,586
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: Starting AesDmaBackend with start

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/aes/dma/struct.AesDmaBackend.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to start the DMA-driven AES backend using the start method, which returns a driver handle that stops the driver when dropped.

```rust
use esp_hal::aes::dma::AesDmaBackend;

let dma_channel = peripherals.DMA_CH0;
let mut aes = AesDmaBackend::new(peripherals.AES, dma_channel);
let _handle = aes.start();
```

--------------------------------

### Get started with xtask: cargo xtask help

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/index.html

Invoke this command in the root of the esp-hal repository to get started with the xtask automation tool for building, running, and testing code and examples.

```bash
cargo xtask help

```

--------------------------------

### Example: Start RsaBackend to process operations

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rsa/struct.RsaBackend.html?search=

Shows how to start the backend, which allows processing RSA operations. The driver stops when the returned object is dropped.

```rust
use esp_hal::rsa::RsaBackend;
let mut rsa = RsaBackend::new(peripherals.RSA);
// Start the backend, which allows processing RSA operations.
let _backend = rsa.start();
```

--------------------------------

### AesBackend::new example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/aes/struct.AesBackend.html

Creates a new AES backend. The backend must be started before it can execute AES operations.

```rust
use esp_hal::aes::AesBackend;
let mut aes = AesBackend::new(peripherals.AES);
```

--------------------------------

### Example: Create and start RsaBackend, perform 512-bit multiplication

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rsa/struct.RsaBackend.html?search=

Shows how to create a backend, start it, and use RsaContext to enqueue a 512-bit big number multiplication operation and await its completion.

```rust
use esp_hal::rsa::{RsaBackend, RsaContext, operand_sizes::Op512};
let mut rsa_backend = RsaBackend::new(peripherals.RSA);
let _driver = rsa_backend.start();

async fn perform_512bit_big_number_multiplication(
    operand_a: &[u32; 16],
    operand_b: &[u32; 16],
    result: &mut [u32; 32],
) {
    let mut rsa = RsaContext::new();

    let mut handle = rsa.multiply::<Op512>(operand_a, operand_b, result);
    handle.wait().await;
}
```

--------------------------------

### Install and run esp-generate for ESP32-C6

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/index.html

Installs the esp-generate project generation tool and runs it for the ESP32-C6 chip. This is recommended when starting new projects.

```bash
cargo install esp-generate
esp-generate --chip=esp32c6 your-project

```

--------------------------------

### Example: Using AesDmaBackend with AesContext for ECB encryption

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/aes/dma/struct.AesDmaBackend.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create an AesDmaBackend, start it, create an AesContext with ECB mode, and process a block of data. The output buffer is asserted to contain the expected ciphertext.

```rust
use esp_hal::aes::{AesContext, Operation, cipher_modes::Ecb, dma::AesDmaBackend};
let dma_channel = peripherals.DMA_CH0;
let mut aes = AesDmaBackend::new(peripherals.AES, dma_channel);
// Start the backend, which allows processing AES operations.
let _backend = aes.start();

// Create a new context with a 128-bit key. The context will use the ECB block cipher mode.
// The key length must be supported by the hardware.
let mut ecb_encrypt = AesContext::new(Ecb, Operation::Encrypt, *b"SUp4SeCp@sSw0rd\0");

// Process a block of data in this context. The ECB mode of operation requires that
// the length of the data is a multiple of the block (16 bytes) size.
let input_buffer: [u8; 16] = *b"message\0\0\0\0\0\0\0\0\0";
let mut output_buffer: [u8; 16] = [0; 16];

let operation_handle = ecb_encrypt
    .process(&input_buffer, &mut output_buffer)
    .unwrap();
operation_handle.wait_blocking();

// output_buffer now contains the ciphertext
assert_eq!(
    output_buffer,
    [
        0xb3, 0xc8, 0xd2, 0x3b, 0xa7, 0x36, 0x5f, 0x18, 0x61, 0x70, 0x0, 0x3e, 0xd9, 0x3a,
        0x31, 0x96,
    ]
);
```

--------------------------------

### Example: first

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Example usage of the first method on slices.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

--------------------------------

### AesBackend full example with ECB encryption

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/aes/struct.AesBackend.html

Shows creating a backend, starting it, creating an AesContext with a 128-bit key in ECB mode, processing a 16-byte block, and verifying the ciphertext. The key length must be supported by hardware and data length must be a multiple of 16 bytes.

```rust
use esp_hal::aes::{AesBackend, AesContext, Operation, cipher_modes::Ecb};
let mut aes = AesBackend::new(peripherals.AES);
// Start the backend, which allows processing AES operations.
let _backend = aes.start();

// Create a new context with a 128-bit key. The context will use the ECB block cipher mode.
// The key length must be supported by the hardware.
let mut ecb_encrypt = AesContext::new(Ecb, Operation::Encrypt, *b"SUp4SeCp@sSw0rd\0");

// Process a block of data in this context. The ECB mode of operation requires that
// the length of the data is a multiple of the block (16 bytes) size.
let input_buffer: [u8; 16] = *b"message\0\0\0\0\0\0\0\0\0";
let mut output_buffer: [u8; 16] = [0; 16];

let operation_handle = ecb_encrypt
    .process(&input_buffer, &mut output_buffer)
    .unwrap();
operation_handle.wait_blocking();

// output_buffer now contains the ciphertext
assert_eq!(
    output_buffer,
    [
        0xb3, 0xc8, 0xd2, 0x3b, 0xa7, 0x36, 0x5f, 0x18, 0x61, 0x70, 0x0, 0x3e, 0xd9, 0x3a,
        0x31, 0x96,
    ]
);
```

--------------------------------

### starts_with example: check prefix

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to use starts_with to check if a slice starts with a given prefix. Returns true for empty needle.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

```rust
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```

--------------------------------

### Using the Sha driver

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/sha/index.html?search=std%3A%3Avec

Initializes the SHA peripheral with Sha::new, starts a SHA-256 hashing operation, updates it with input data in a loop, and finishes to retrieve the hash. The example uses block! for infallible operations and shows that finish can be called multiple times.

```rust
let mut source_data = "HELLO, ESPRESSIF!".as_bytes();
let mut sha = Sha::new(peripherals.SHA);
let mut hasher = sha.start::<Sha256>();
// Short hashes can be created by decreasing the output buffer to the
// desired length
let mut output = [0u8; 32];

while !source_data.is_empty() {
    // All the HW Sha functions are infallible so unwrap is fine to use if
    // you use block!
    source_data = block!(hasher.update(source_data))?;
}

// Finish can be called as many times as desired to get multiple copies of
// the output.
block!(hasher.finish(output.as_mut_slice()))?;
```

--------------------------------

### Using the ShaBackend driver

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/sha/index.html?search=std%3A%3Avec

Initializes the SHA peripheral with ShaBackend::new, starts the backend, creates a SHA-1 context, updates it with input data three times, and finalizes to get a 20-byte digest. The update and finalize calls use wait_blocking() to wait for completion.

```rust
use esp_hal::sha::{Sha1Context, ShaBackend};
let mut sha = ShaBackend::new(peripherals.SHA);
// Start the backend, which allows processing SHA operations.
let _backend = sha.start();

// Create a new context to hash data with SHA-1.
let mut sha1_ctx = Sha1Context::new();

// SHA-1 outputs a 20-byte digest.
let mut digest: [u8; 20] = [0; 20];

// Process data. The `update` function returns a handle which can be used to wait
// for the operation to finish.
sha1_ctx.update(b"input data").wait_blocking();
sha1_ctx.update(b"input data").wait_blocking();
sha1_ctx.update(b"input data").wait_blocking();

// Extract the final hash. This resets the context.
sha1_ctx.finalize(&mut digest).wait_blocking();

// digest now contains the SHA-1 hash of the input.
```

--------------------------------

### General-purpose Timer

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/timer/timg/index.html

Example showing how to create a TimerGroup, get a timer, read the current timestamp, load a timeout value, start the timer, and check/clear interrupts.

```APIDOC
## General-purpose Timer

### Description
Example usage of a general-purpose timer from the TIMG module.

### Code
```rust
use esp_hal::timer::{Timer, timg::TimerGroup};

let timg0 = TimerGroup::new(peripherals.TIMG0);
let timer0 = timg0.timer0;

// Get the current timestamp, in microseconds:
let now = timer0.now();

// Wait for timeout:
timer0.load_value(Duration::from_secs(1));
timer0.start();

while !timer0.is_interrupt_set() {
    // Wait
}

timer0.clear_interrupt();
```
```

--------------------------------

### esp_hal::init usage example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/fn.init.html?search=std%3A%3Avec

Example showing how to call esp_hal::init with Config::default() to obtain the peripherals.

```rust
use esp_hal::{Config, init};
let peripherals = init(Config::default());
```

--------------------------------

### Example: Creating AesDmaBackend with new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/aes/dma/struct.AesDmaBackend.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a new AesDmaBackend instance using the new method with an AES peripheral and a DMA channel.

```rust
use esp_hal::aes::dma::AesDmaBackend;

let dma_channel = peripherals.DMA_CH0;
let mut aes = AesDmaBackend::new(peripherals.AES, dma_channel);
```

--------------------------------

### get example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a reference to an element or subslice by index or range, returning None if out of bounds.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Get current CPU core

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/system/enum.Cpu.html

Example usage of `Cpu::current()` to get the core the application is currently executing on.

```rust
use esp_hal::system::Cpu;
let current_cpu = Cpu::current();
```

--------------------------------

### Example usage of chip! macro

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/macro.chip.html?search=std%3A%3Avec

Example showing how to use the chip! macro to get the chip name and assert it equals 'esp32c3'.

```rust
use esp_hal::chip;
let chip_name = chip!();
assert_eq!(chip_name, esp32c3)
```

--------------------------------

### Example: Create RsaBackend with new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rsa/struct.RsaBackend.html?search=

Shows how to create a new RsaBackend instance using the RSA peripheral.

```rust
use esp_hal::rsa::RsaBackend;
let mut rsa = RsaBackend::new(peripherals.RSA);
```

--------------------------------

### Spi::new example with default config

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/spi/master/struct.Spi.html

Constructs an SPI instance with default configuration and assigns SCK, MOSI, and MISO pins.

```rust
use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2);
```

--------------------------------

### init(config: Config) -> Peripherals

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/fn.init.html?search=std%3A%3Avec

Initializes the system by setting up the CPU clock and watchdog, then returns the peripherals and clocks. This function is available only with the `rt` feature enabled.

```APIDOC
## init(config: Config) -> Peripherals

### Description
Initializes the system by setting up the CPU clock and watchdog, then returns the peripherals and clocks. This function is available only with the `rt` feature enabled.

### Function Signature
```rust
pub fn init(config: Config) -> Peripherals
```

### Parameters
- **config** (Config) - Required - Configuration for the system initialization.

### Return Value
- **Peripherals** - The peripherals and clocks after initialization.

### Example
```rust
use esp_hal::{Config, init};
let peripherals = init(Config::default());
```

### Availability
- **crate feature `rt`** - Required
```

--------------------------------

### twai::TwaiConfiguration::start

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/twai/index.html

Starts the TWAI peripheral and returns an active TWAI instance.

```APIDOC
## [Rust] twai::TwaiConfiguration::start

### Description
Starts the TWAI peripheral, locking the configuration settings and putting it into operation mode, allowing packets to be sent and received.

### Method
Method

### Parameters
None

### Request Example
```rust
let mut twai = twai_config.start();
```

### Response
Returns a `Twai` instance representing the active TWAI peripheral.

```

--------------------------------

### Example: split with subslice_range

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Example for the split method on slices, using subslice_range to get ranges of subslices. The iterator yields ranges for each non-zero segment.

```rust
let mut iter = nums
    .split(|t| *t == 0)
    .map(|n| nums.subslice_range(n).unwrap());

assert_eq!(iter.next(), Some(0..0));
assert_eq!(iter.next(), Some(1..3));
assert_eq!(iter.next(), Some(4..4));
assert_eq!(iter.next(), Some(5..6));
```

--------------------------------

### Get time in ms from the RTC Timer (alternative)

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rtc_cntl/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Similar to the first example but uses multiplication by 1000 instead of division to get milliseconds, which is likely a typo in the source.

```rust
let rtc = Rtc::new(peripherals.LPWR);
let delay = Delay::new();

loop {
    // Get the current RTC time in milliseconds
    let time_ms = rtc.current_time_us() * 1000;
    delay.delay_millis(1000);

    // Set the time to half a second in the past
    let new_time = rtc.current_time_us() - 500_000;
    rtc.set_current_time_us(new_time);
}
```

--------------------------------

### Io::new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/gpio/struct.Io.html?search=std%3A%3Avec

Initializes the I/O driver. This method is unstable and requires the `unstable` crate feature.

```APIDOC
## Io::new

### Description
Initializes the I/O driver. This method is unstable and requires the `unstable` crate feature.

### Method
`pub fn new(_io_mux: IO_MUX<'d>) -> Self`

### Parameters
- `_io_mux` (IO_MUX<'d>) - Required - The IO_MUX instance to initialize the driver with.

### Stability
**This API is marked as unstable** and is only available when the `unstable` crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

### Returns
`Self` - The initialized `Io` instance.
```

--------------------------------

### get_mut example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a mutable reference to an element by index, modifying it in place.

```rust
let x = &mut [0, 1, 2];

if let Some(elem) = x.get_mut(1) {
    *elem = 42;
}
assert_eq!(x, &[0, 42, 2]);
```

--------------------------------

### Create I2C driver instance and apply configuration

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/i2c/master/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the I2C driver with SDA and SCL pins, and shows how to change the configuration later using apply_config.

```rust
use esp_hal::i2c::master::I2c;
// You need to configure the driver during initialization:
let mut i2c = I2c::new(peripherals.I2C0, config)?
    .with_sda(peripherals.GPIO2)
    .with_scl(peripherals.GPIO3);

// You can change the configuration later:
let new_config = config.with_frequency(Rate::from_khz(400));
i2c.apply_config(&new_config)?;
```

--------------------------------

### RsaContext::modular_exponentiate usage example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rsa/struct.RsaContext.html?search=u32+-%3E+bool

Starts modular exponentiation with the given inputs. The example shows the required arguments: x, y, m, r, m_prime, and result, with OP constrained by RsaMode. Returns an RsaHandle for the operation.

```rust
pub fn modular_exponentiate<'t, OP>(
    &'t mut self,
    x: &'t OP::InputType,
    y: &'t OP::InputType,
    m: &'t OP::InputType,
    r: &'t OP::InputType,
    m_prime: u32,
    result: &'t mut OP::InputType,
) -> RsaHandle<'t>
where
    OP: RsaMode,

```

--------------------------------

### iter example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to iterate over a slice using the iter method, yielding items from start to end.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### UHCI Usage Example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/uart/uhci/index.html

Demonstrates how to create a UHCI instance, configure it, split it into Rx and Tx parts, and perform DMA read/write operations.

```APIDOC
## UHCI Usage Example

### Description
This example shows how to initialize a UHCI peripheral, configure it with UART settings, split it into receive and transmit halves, and perform DMA transfers.

### Usage
```rust
#![no_std]
#![no_main]

#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! {
    loop {}
}

use esp_hal::{
    clock::CpuClock,
    dma::{DmaRxBuf, DmaTxBuf},
    dma_buffers,
    main,
    rom::software_reset,
    uart,
    uart::{RxConfig, Uart, uhci, uhci::Uhci},
};

#[main]
fn main() -> ! {
    let config = esp_hal::Config::default().with_cpu_clock(CpuClock::max());
    let peripherals = esp_hal::init(config);
    let config = esp_hal::Config::default().with_cpu_clock(CpuClock::max());
    let peripherals = esp_hal::init(config);

    let config = uart::Config::default()
        .with_rx(RxConfig::default().with_fifo_full_threshold(64))
        .with_baudrate(115200);

    let uart = Uart::new(peripherals.UART1, config)
        .unwrap()
        .with_tx(peripherals.GPIO2)
        .with_rx(peripherals.GPIO3);

    let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) = dma_buffers!(4092);
    let dma_rx = DmaRxBuf::new(rx_descriptors, rx_buffer).unwrap();
    let mut dma_tx = DmaTxBuf::new(tx_descriptors, tx_buffer).unwrap();

    let mut uhci = Uhci::new(uart, peripherals.UHCI0, peripherals.DMA_CH0);
    uhci.apply_rx_config(
        &uart::uhci::RxConfig::default().with_chunk_limit(dma_rx.len() as u16),
    )
    .unwrap();
    uhci.apply_tx_config(&uart::uhci::TxConfig::default())
        .unwrap();

    let config = uart::Config::default()
        .with_rx(RxConfig::default().with_fifo_full_threshold(64))
        .with_baudrate(9600);
    uhci.set_uart_config(&config).unwrap();

    let (uhci_rx, uhci_tx) = uhci.split();
    // Waiting for message
    let transfer = uhci_rx
        .read(dma_rx)
        .unwrap_or_else(|x| panic!("Something went horribly wrong: {:?}", x.0));
    let (err, _uhci_rx, dma_rx) = transfer.wait();
    err.unwrap();

    let received = dma_rx.number_of_received_bytes();
    // println!("Received dma bytes: {}", received);

    let rec_slice = &dma_rx.as_slice()[0..received];
    if received > 0 {
        match core::str::from_utf8(&rec_slice) {
            Ok(x) => {
                // println!("Received DMA message: \"{}\"", x);
                dma_tx.as_mut_slice()[0..received].copy_from_slice(&rec_slice);
                dma_tx.set_length(received);
                let transfer = uhci_tx
                    .write(dma_tx)
                    .unwrap_or_else(|x| panic!("Something went horribly wrong: {:?}", x.0));
                let (err, _uhci, _dma_tx) = transfer.wait();
                err.unwrap();
            }
            Err(x) => panic!("Error string: {}", x),
        }
    }
    software_reset()
}
```

### Structs
- **AnyUhci** - Type-erased version of a peripheral singleton.
- **RxConfig** - UHCI Rx Configuration.
- **TxConfig** - UHCI Tx Configuration.
- **Uhci** - UHCI (To use with UART over DMA).
- **UhciDmaRxTransfer** - A structure representing a DMA transfer for UHCI/UART.
- **UhciDmaTxTransfer** - A structure representing a DMA transfer for UHCI/UART.
- **UhciRx** - Splitted Uhci structs, Rx part for receiving data.
- **UhciTx** - Splitted Uhci structs, Tx part for sending data.

### Enums
- **ConfigError** - A configuration error.
- **Error** - Uhci specific errors.
```

--------------------------------

### Example: Calling software_reset

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/system/fn.software_reset.html

Shows how to import and call the software_reset function. This will reset the chip immediately.

```rust
use esp_hal::system::software_reset;
software_reset();
```

--------------------------------

### as_ptr example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a raw pointer to the slice's buffer and use it to access elements.

```rust
let x = &[1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
    }
}
```

--------------------------------

### Example: trim_ascii_start

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Example usage of the trim_ascii_start method on byte slices.

```rust
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
assert_eq!(b"  ".trim_ascii_start(), b"");
assert_eq!(b"".trim_ascii_start(), b"");
```

--------------------------------

### as_mut_ptr example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a mutable raw pointer to the slice's buffer and use it to modify elements.

```rust
let x = &mut [1, 2, 4];
let x_ptr = x.as_mut_ptr();

unsafe {
    for i in 0..x.len() {
        *x_ptr.add(i) += 2;
    }
}
assert_eq!(x, &[3, 4, 6]);
```

--------------------------------

### last_chunk_mut example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a mutable array reference to the last N items of a slice, modifying them in place.

```rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_chunk_mut::<2>() {
    last[0] = 10;
    last[1] = 20;
}
assert_eq!(x, &[0, 10, 20]);

assert_eq!(None, x.last_chunk_mut::<4>());
```

--------------------------------

### I2S Read Example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/i2s/master/index.html

Example demonstrating how to configure and use the I2S peripheral in master mode to read audio data using DMA.

```APIDOC
## I2S Read Example

### Description
Example demonstrating how to configure and use the I2S peripheral in master mode to read audio data using DMA.

### Code
```rust
let dma_channel = peripherals.DMA_CH0;
let (mut rx_buffer, rx_descriptors, _, _) = dma_buffers!(4 * 4092, 0);

let i2s = I2s::new(
    peripherals.I2S0,
    dma_channel,
    Config::new_tdm_philips()
        .with_sample_rate(Rate::from_hz(44100))
        .with_data_format(DataFormat::Data16Channel16)
        .with_channels(Channels::STEREO),
)?;
let i2s = i2s.with_mclk(peripherals.GPIO0);
let mut i2s_rx = i2s
    .i2s_rx
    .with_bclk(peripherals.GPIO1)
    .with_ws(peripherals.GPIO2)
    .with_din(peripherals.GPIO5)
    .build(rx_descriptors);

let mut transfer = i2s_rx.read_dma_circular(&mut rx_buffer)?;

loop {
    let avail = transfer.available()?;

    if avail > 0 {
        let mut rcv = [0u8; 5000];
        transfer.pop(&mut rcv[..avail])?;
    }
}
```
```

--------------------------------

### Example: Get weekday in New York using jiff crate

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rtc_cntl/struct.Rtc.html

Shows how to get the weekday of the current time in New York using the jiff crate. Works in core-only environments without dynamic memory allocation.

```rust
use jiff::{
    Timestamp,
    tz::{self, TimeZone},
};

static TZ: TimeZone = tz::get!("America/New_York");

let rtc = Rtc::new(peripherals.LPWR);
let now = Timestamp::from_microsecond(rtc.current_time_us() as i64)?;
let weekday_in_new_york = now.to_zoned(TZ.clone()).weekday();
```

--------------------------------

### start

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/twai/struct.TwaiConfiguration.html?search=

Puts the peripheral into Operation Mode, allowing transmission and reception of packets.

```APIDOC
## start

### Description
Puts the peripheral into Operation Mode, allowing the transmission and reception of packets using the new object.

### Method
start

### Signature
`pub fn start(self) -> Twai<'d, Dm>`

### Returns
- **Twai<'d, Dm>** - The active TWAI peripheral.
```

--------------------------------

### transmit_continuously

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rmt/struct.Channel.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts transmitting a pulse code sequence continuously. Returns a ContinuousTxTransaction to stop the transmission and get the channel back.

```APIDOC
## transmit_continuously

### Description
Start transmitting the given pulse code continuously. This returns a `ContinuousTxTransaction` which can be used to stop the ongoing transmission and get back the channel for further use. The `mode` argument determines whether transmission will continue until explicitly stopped or for a fixed number of iterations; see `LoopMode` for more details. When using a loop `mode` other than `LoopMode::Infinite`, `ContinuousTxTransaction::is_loopcount_interrupt_set` can be used to check if the loop count is reached. The length of `data` cannot exceed the size of the allocated RMT RAM.

### Method
pub fn transmit_continuously<T>(self, data: &[T], mode: LoopMode) -> Result<ContinuousTxTransaction<'ch>, Error>
where T: Into<PulseCode> + Copy

### Parameters
- **data** (&[T]) - The pulse code sequence to transmit. Each element must implement `Into<PulseCode>` and `Copy`.
- **mode** (LoopMode) - The loop mode for continuous transmission.

### Returns
- **Result<ContinuousTxTransaction<'ch>, Error>** - A result containing a `ContinuousTxTransaction` on success, or an `Error` on failure.

```

--------------------------------

### I2C Driver Initialization and Configuration

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/i2c/master/index.html

Shows how to create an I2C master driver instance with I2c::new, set SDA/SCL pins, and apply configuration changes.

```APIDOC
## I2c::new

### Description
Creates a new I2C master driver instance.

### Method
`I2c::new(peripheral: impl Peripheral<P = impl Instance>, config: Config) -> Result<Self, ConfigError>`

### Parameters
- **peripheral** (impl Peripheral) - Required - The I2C peripheral instance (e.g., `peripherals.I2C0`).
- **config** (Config) - Required - The I2C configuration.

### Returns
`Result<Self, ConfigError>` - The I2C driver instance or a configuration error.

### Example
```rust
use esp_hal::i2c::master::I2c;
let mut i2c = I2c::new(peripherals.I2C0, config)?
    .with_sda(peripherals.GPIO2)
    .with_scl(peripherals.GPIO3);
```

## I2c::with_sda

### Description
Sets the SDA pin for the I2C driver.

### Method
`with_sda(self, sda: impl Peripheral<P = impl OutputPin>) -> Self`

### Parameters
- **sda** (impl Peripheral) - Required - The GPIO pin to use for SDA.

### Returns
`Self` - The I2C driver with the SDA pin set.

## I2c::with_scl

### Description
Sets the SCL pin for the I2C driver.

### Method
`with_scl(self, scl: impl Peripheral<P = impl OutputPin>) -> Self`

### Parameters
- **scl** (impl Peripheral) - Required - The GPIO pin to use for SCL.

### Returns
`Self` - The I2C driver with the SCL pin set.

## I2c::apply_config

### Description
Applies a new configuration to the I2C driver.

### Method
`apply_config(&mut self, config: &Config) -> Result<(), ConfigError>`

### Parameters
- **config** (&Config) - Required - The new configuration to apply.

### Returns
`Result<(), ConfigError>` - Ok if successful, or a configuration error.

### Example
```rust
let new_config = config.with_frequency(Rate::from_khz(400));
i2c.apply_config(&new_config)?;
```
```

--------------------------------

### Spi::new example with frequency and mode

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/spi/master/struct.Spi.html

Constructs an SPI instance with a custom frequency and mode, then assigns SCK, MOSI, and MISO pins.

```rust
use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(
    peripherals.SPI2,
    Config::default()
        .with_frequency(Rate::from_khz(100))
        .with_mode(Mode::_0),
)?
.with_sck(peripherals.GPIO0)
.with_mosi(peripherals.GPIO1)
.with_miso(peripherals.GPIO2);
```

--------------------------------

### split_off_last example: remove last element

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to use split_off_last to remove the last element of a slice and get a reference to it.

```rust
let mut slice: &[_] = &['a', 'b', 'c'];
let last = slice.split_off_last().unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(last, &'c');
```

--------------------------------

### split_off_first example: remove first element

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to use split_off_first to remove the first element of a slice and get a reference to it.

```rust
let mut slice: &[_] = &['a', 'b', 'c'];
let first = slice.split_off_first().unwrap();

assert_eq!(slice, &['b', 'c']);
assert_eq!(first, &'a');
```

--------------------------------

### Io::new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/gpio/struct.Io.html

Initializes the I/O driver. This method is marked as unstable and requires the 'unstable' crate feature.

```APIDOC
## Io::new

### Description
Initializes the I/O driver.

### Method
new

### Signature
pub fn new(_io_mux: IO_MUX<'d>) -> Self

### Parameters
- **io_mux** (IO_MUX<'d>) - Required - The IO_MUX instance.

### Stability
This API is marked as unstable and is only available when the `unstable` crate feature is enabled.

```

--------------------------------

### get_unchecked example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a reference to an element without bounds checking, which is unsafe and can lead to undefined behavior if out of bounds.

```rust
let x = &[1, 2, 4];

unsafe {
    assert_eq!(x.get_unchecked(1), &2);
}
```

--------------------------------

### Io::new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/gpio/struct.Io.html?search=

Initializes the I/O driver. This method is marked as unstable and requires the 'unstable' crate feature.

```APIDOC
## Io::new

### Description
Initializes the I/O driver. This method is marked as unstable and requires the 'unstable' crate feature.

### Method
new

### Signature
pub fn new(_io_mux: IO_MUX<'d>) -> Self

### Parameters
- **io_mux** (IO_MUX<'d>) - Required - The IO_MUX instance to initialize the driver with.

### Stability
**This API is marked as unstable** and is only available when the `unstable` crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

```

--------------------------------

### last_chunk example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get an array reference to the last N items of a slice, returning None if the slice is too short.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());
```

--------------------------------

### Io::new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/gpio/struct.Io.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the I/O driver. This method is marked as unstable and requires the 'unstable' crate feature.

```APIDOC
## Io::new

### Description
Initializes the I/O driver.

### Method
new

### Signature
pub fn new(_io_mux: IO_MUX<'d>) -> Self

### Parameters
- **_io_mux** (IO_MUX<'d>) - Required - The IO_MUX instance.

### Returns
Self - The initialized Io driver.

### Stability
This API is marked as unstable and is only available when the `unstable` crate feature is enabled.
```

--------------------------------

### Periodic timer example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/timer/index.html

Creates a periodic timer using TimerGroup and PeriodicTimer, starts it with a 1-second period, and waits for each period in a loop.

```rust
let timg0 = TimerGroup::new(peripherals.TIMG0);
let mut periodic = PeriodicTimer::new(timg0.timer0);

periodic.start(Duration::from_secs(1));
loop {
    periodic.wait();
}
```

--------------------------------

### Io::new

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/gpio/struct.Io.html?search=u32+-%3E+bool

Initializes the I/O driver. This method is marked as unstable and requires the 'unstable' crate feature.

```APIDOC
## Io::new

### Description
Initializes the I/O driver. This method is marked as unstable and requires the 'unstable' crate feature.

### Method
`pub fn new(_io_mux: IO_MUX<'d>) -> Self`

### Parameters
- `_io_mux` (IO_MUX<'d>) - Required - The IO_MUX instance used to initialize the driver.

### Returns
- `Self` - The initialized Io instance.

### Stability
**This API is marked as unstable** and is only available when the `unstable` crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.
```

--------------------------------

### Rtc::current_time_us

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rtc_cntl/struct.Rtc.html

Returns the current time in microseconds. Includes an example using the jiff crate to get the weekday in New York.

```APIDOC
## Rtc::current_time_us

### Description
Returns the current time in microseconds. Includes an example using the jiff crate to get the weekday in New York.

### Method
`pub fn current_time_us(&self) -> u64`

### Parameters
- `self` (&self) - Required - The Rtc instance.

### Returns
- `u64` - The current time in microseconds.

### Example
```rust
use jiff::{
    Timestamp,
    tz::{self, TimeZone},
};

static TZ: TimeZone = tz::get!("America/New_York");

let rtc = Rtc::new(peripherals.LPWR);
let now = Timestamp::from_microsecond(rtc.current_time_us() as i64)?;
let weekday_in_new_york = now.to_zoned(TZ.clone()).weekday();
```

```

--------------------------------

### transmit_continuously

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/rmt/struct.Channel.html?search=

Starts transmitting the given pulse code continuously. Returns a ContinuousTxTransaction that can be used to stop the transmission and get back the channel.

```APIDOC
## transmit_continuously

### Description
Start transmitting the given pulse code continuously. This returns a `ContinuousTxTransaction` which can be used to stop the ongoing transmission and get back the channel for further use. The `mode` argument determines whether transmission will continue until explicitly stopped or for a fixed number of iterations; see `LoopMode` for more details. When using a loop `mode` other than `LoopMode::Infinite`, `ContinuousTxTransaction::is_loopcount_interrupt_set` can be used to check if the loop count is reached. The length of `data` cannot exceed the size of the allocated RMT RAM.

### Method
transmit_continuously

### Signature
pub fn transmit_continuously<T>(self, data: &[T], mode: LoopMode) -> Result<ContinuousTxTransaction<'ch>, Error>
where T: Into<PulseCode> + Copy

### Parameters
- `self` - Required - The channel to use for transmission.
- `data` (`&[T]`) - Required - The pulse code sequence to transmit.
- `mode` (`LoopMode`) - Required - Determines whether transmission continues until explicitly stopped or for a fixed number of iterations.

### Returns
- `Result<ContinuousTxTransaction<'ch>, Error>` - A result containing the transaction or an error.

```

--------------------------------

### Using CpuClock::max() to configure CPU clock

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/clock/enum.CpuClock.html?search=u32+-%3E+bool

Example from the documentation for CpuClock::max(). It shows how to create a default config with the highest possible CPU clock and initialize the HAL.

```rust
use esp_hal::clock::CpuClock;
let config = esp_hal::Config::default().with_cpu_clock(CpuClock::max());
let peripherals = esp_hal::init(config);
```

--------------------------------

### get_unchecked_mut example

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to get a mutable reference to an element without bounds checking, which is unsafe and can lead to undefined behavior if out of bounds.

```rust
let x = &mut [1, 2, 4];

unsafe {
    let elem = x.get_unchecked_mut(1);
    *elem = 13;
}
assert_eq!(x, &[1, 13, 4]);
```

--------------------------------

### partition_point example: find range of matching items

Source: https://docs.espressif.com/projects/rust/esp-hal/1.0.0/esp32c3/esp_hal/dma/struct.DmaLoopBuf.html?search=

Shows how to use partition_point to find the whole range of matching items, rather than an arbitrary matching one. The example also demonstrates that for a not-found element, the range is empty.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

let low = s.partition_point(|x| x < &1);
assert_eq!(low, 1);
let high = s.partition_point(|x| x <= &1);
assert_eq!(high, 5);
let r = s.binary_search(&1);
assert!((low..high).contains(&r.unwrap()));

assert!(s[..low].iter().all(|&x| x < 1));
assert!(s[low..high].iter().all(|&x| x == 1));
assert!(s[high..].iter().all(|&x| x > 1));

// For something not found, the "range" of equal items is empty
assert_eq!(s.partition_point(|x| x < &11), 9);
assert_eq!(s.partition_point(|x| x <= &11), 9);
assert_eq!(s.binary_search(&11), Err(9));
```
Tokens:
Raw