Welcome to the esp-ward
official repository!
esp-ward
is an extensible Rust crate created for simplified the development of embedded sensor applications on the ESP32 platform. This library provides simplified API for basic operations with various peripherals.
- User-friendly Sensor Management: Provides an intuitive interface for the effortless setup, activation, and tracking of sensors, ideal for smart home or automation processes.
- Modular and Extensible Architecture: Designed with flexibility in mind, allowing easy integration and expansion to accommodate diverse application requirements.
- Created for
Espressif
chips: Built on Rust's robust safety features and performance, this crate is built on top ofesp-hal
driver for variousesp
chips
Category | Devices |
---|---|
Connectivity | Wi-Fi, MQTT |
Temperature | AHT20, BME280 |
Humidity | AHT20, BME280 |
Pressure | BME280 |
Motion Sensors | PIR Sensor |
Distance Sensors | HC-SR04 Ultrasonic Sensor |
Light Sensors | TSL2591 |
Gas Sensors | SGP30 (CO2 and VOC) |
User Input | Generic Button, Joystick |
Displays | ILI9341, MAX7219, PCD8544 |
Before you begin, ensure you have the MSRV
and the necessary tools and environment for ESP32+Rust development installed on your system (check The Rust on ESP book from our esp-rs
team).
MSRV: 1.76.0.1
To include esp-ward
in your project, add the following to your Cargo.toml
file:
esp-ward = { git = "https://github.com/playfulFence/esp-ward.git", features = ["required", "features"]}
For features guide check this section
If you want to try some default examples, you need to fork this repo and from the root directory of this project execute this CLI command:
cargo espflash flash --example=<example-name> --features=<chip-feature> --target=<target> --monitor
Where:
example-name
- name of your example (display_data
,led_scrolling
)chip-feature
- depending on what chip and example you use, you need to set correct features, here's some minimalist guide:- Decide which chip are you using
- If chosen example utilizes
wifi
-related features - enable corresponding feature (example:esp32s2-wifi
), same works withmqtt
functionalities. In case you want to use something, which requiresallocator
(in this example list - if you want to usemax7219
display) - make sure to enablealloc
feature (example:--features=esp32s2,alloc
). In case you need just basic functionality - just write a name of required chip to a feature list (example:--features=esp32s2
)
- Target lets the
espflash
know, which architecture your chip is using:xtensa-<chip>-none-elf
- for Xtensa-based chipsriscv32imc-unknown-none-elf
- foresp32c3
riscv32imac-unknown-none-elf
- foresp32c6
andesp32h2
The library provides a straightforward approach to managing sensors:
// Example instantiation of a sensor
let peripherals = esp_ward::take_periph!();
let system = esp_ward::take_system!(peripherals);
let (clocks, pins, mut delay) = esp_ward::init_chip!(peripherals, system);
let bus = esp_ward::init_i2c_default!(peripherals, pins, clocks);
let mut sensor = Aht20Sensor::create_on_i2c(bus, delay).unwrap();
println!("Temperature {}", sensor.get_temperature().unwrap())
Detailed examples for various use cases can be found in the /examples
directory.
-
If something is wrong with a building process and
CI
is green after latest commit toesp-ward
- problem is on your side- Check if you correcty installed the toolchains and the rest of environment (check
The Rust on ESP Book
) - Make sure to use
espup
- Try to pass correct toolchain to
cargo
(esp
for Xtensa,nightly
forRISC
) -cargo +<toolchain> espflash flash...
- Check if you correcty installed the toolchains and the rest of environment (check
-
On Xtensa targets you might encounter issues with linker. Try to install and export the
esp-idf
-
Report an
issue
to this repo or open aPull Request
fixing it!
Comprehensive documentation in typical Rust docs
fomat is available web-page of a driver, in "Docs
" section
Contributions to esp-ward
are welcome and appreciated. Please refer to the CONTRIBUTING.md file for guidelines on how to submit issues, follow the pull request process, and code of conduct.
The ongoing development of esp-ward
seeks to introduce new features, optimizations, and broader sensor, display and connectivity features support.
This project is released under the Apache License 2.0, which allows for both personal and commercial use, modification, and distribution.