Crate esp_ward

source ·
Expand description

§esp-ward

esp-ward is a Rust crate designed as a higher-level abstraction over esp-hal to simplify the usage of ESP32, ESP32S2, ESP32C3, ESP32C6, ESP32S3, ESP32C2 and ESP32H2 chips with Rust. It provides common APIs, traits, and structs to interact with various peripherals such as GPIOs, I2C, and SPI devices.

This crate is targeted at developers new to the esp-rs ecosystem or those who prefer a simplified interface for common operations.

§Features

  • Traits and structs for common peripheral interactions.
  • Easy configuration of SPI and I2C.
  • Predefined macros for common operations and setup routines.
  • Compatible with various ESP32 family chips.
  • Simplified Wi-Fi and MQTT features

§Usage

To use esp-ward, include it as a dependency in your Cargo.toml and refer to the following examples to start interacting with your ESP device’s hardware features.

§Quick Start

Here’s how you might initialize the system peripherals and configure I2C and SPI with default settings:

use esp_ward::{init_chip, take_periph, take_system};

let peripherals = take_periph!();
let system = take_system!(peripherals);
let (clocks, pins) = init_chip!(peripherals, system);
// Now you can use `clocks` and `pins` to interact with the peripherals

§Example: Configuring I2C

use esp_ward::init_i2c_default;

let i2c = init_i2c_default!(peripherals, pins, clocks);
// Now `i2c` is ready to communicate with I2C devices

§Example: Configuring SPI

use esp_ward::init_spi_default;

let spi = init_spi_default!(peripherals, pins, clocks);
// Now `spi` is ready to transfer data with SPI devices

§Macros

This crate also provides several macros to ease the setup and usage of ESP peripherals.

§take_periph

Takes the peripherals from the ESP board. This is typically one of the first steps in a Rust-ESP application.

§take_system

Splits the SYSTEM peripheral into its constituent parts.

§init_chip

Initializes the system clocks and IO pins.

§init_i2c_default and init_i2c_custom

Initializes the I2C peripheral with either default or custom configurations.

§init_spi_default and init_spi_custom

Initializes the SPI peripheral with either default or custom configurations.

§init_wifi

Initializes Wi-Fi connection in async or non-async way - depending on your project

and more…

§Contributing

Contributions to esp-ward are welcome. Check out the repository on GitHub to report issues or submit pull requests.

§License

esp-ward is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.

Modules§

Macros§

  • create_joystick
    Macro for creating a Joystick instance.
  • create_stack
    Macro to create a network stack for WiFi communication.
  • get_ip
    Macro to retrieve the IP configuration from the network stack.
  • get_timer
    Macro to obtain a suitable timer based on the ESP device mod
  • get_x_adc_pin
  • get_y_adc_pin
  • init_chip
    Initializes the system clocks and IO pins, providing the base setup required for any operation with peripherals.
  • init_i2c_custom
    Initializes a custom I2C configuration, allowing for arbitrary SDA and SCL pins and frequency.
  • init_i2c_default
    Initializes the default I2C configuration for the ESP board. Assumes the use of the standard I2C0 peripheral and “default” pin configuration. The rest of “default” functions
  • init_spi_custom
    Initializes a custom SPI configuration, allowing for arbitrary CLK, MOSI, MISO, and CS pins and frequency.
  • init_spi_default
    Initializes the default SPI configuration for the chip. Assumes the use of the standard SPI2 peripheral and default pin configuration.
  • init_wifi
    Macro to initialize the WiFi interface with the given SSID and password in mqtt (or async) configuration. This macro configures the WiFi controller and initializes the WiFi interface. Example:
  • load_lp_code
    Load code to be run on the LP/ULP core.
  • make_gpio_enum_dispatch_macro
    Create an enum for erased GPIO pins, using the enum-dispatch pattern
  • prepare_alloc
    Sets up a global allocator for heap memory, required for the alloc crate functionalities. This is essential for using heap-allocated data structures which are used, for example, for max7219 display. ATTENTION: MAKE SURE to use this prepare_alloc as a first function in your program if you’re using module which utilizes alloc. Modules like this will have a warning that you should use the alloc feature
  • prepare_buffers
    Macro to prepare buffers with fixed sizes for MQTT communication.
  • take_periph
    Takes the ESP peripherals. This should be one of the first steps in an ESP application, ensuring that the peripherals are properly acquired before use.
  • take_system
    Splits the SYSTEM peripheral into its constituent parts. This macro is a convenience wrapper for quickly accessing system components.
  • wait
    Pauses the execution for a specified number of milliseconds using a delay provider.
  • wait_wifi
    Macro to wait until WiFi is connected in async variation Typically used after net_task async task call.

Structs§

Enums§

Traits§

Attribute Macros§

  • entry
    Attribute to declare the entry point of the program
  • interrupt
    Marks a function as an interrupt handler
  • main
    Creates a new executor instance and declares an application entry point spawning the corresponding function body as an async task.
  • ram
    This attribute allows placing statics and functions into ram.