From d0cd890e51c16b61707f7cce16f21fa7478fbdcf Mon Sep 17 00:00:00 2001 From: Sergio Gasquez Arcos Date: Thu, 27 Jun 2024 18:50:30 +0200 Subject: [PATCH] Update some modules documentation (#1726) * docs: Add inverting documentation and examples * docs: Update I2C mod docs * docs: Update LEDC documentation * docs: FIx format * Fix a typo in docstring in `esp-hal/src/uart.rs` --------- Co-authored-by: Jesse Braham --- esp-hal/src/i2c.rs | 60 ++++++++++++++++++++++++++++++++--------- esp-hal/src/ledc/mod.rs | 25 ++++++++++++----- esp-hal/src/parl_io.rs | 1 - esp-hal/src/uart.rs | 37 ++++++++++++++++++++++--- hil-test/README.md | 3 ++- 5 files changed, 102 insertions(+), 24 deletions(-) diff --git a/esp-hal/src/i2c.rs b/esp-hal/src/i2c.rs index 208f3021ca6..e6e3142075a 100644 --- a/esp-hal/src/i2c.rs +++ b/esp-hal/src/i2c.rs @@ -1,26 +1,60 @@ -//! # I2C Driver +//! # Inter-Integrated Circuit (I2C) //! -//! ## Overview -//! The I2C Peripheral Driver for ESP chips is a software module that -//! facilitates communication with I2C devices using ESP microcontroller chips. -//! It provides an interface to initialize, configure, and perform read and -//! write operations over the I2C bus. +//! I2C is a serial, synchronous, multi-device, half-duplex communication +//! protocol that allows co-existence of multiple masters and slaves on the +//! same bus. I2C uses two bidirectional open-drain lines: serial data line +//! (SDA) and serial clock line (SCL), pulled up by resistors. //! -//! The driver supports features such as handling transmission errors, -//! asynchronous operations, and interrupt-based communication, also supports -//! multiple I2C peripheral instances on `ESP32`, `ESP32H2`, `ESP32S2`, and -//! `ESP32S3` chips +//! Espressif devices sometimes have more than one I2C controller (also called +//! port), responsible for handling communication on the I2C bus. A single I2C +//! controller can be a master or a slave. //! -//! ## Example -//! Following code shows how to read data from a BMP180 sensor using I2C. +//! Typically, an I2C slave device has a 7-bit address or 10-bit address. +//! Espressif devices supports both I2C Standard-mode (Sm) and Fast-mode +//! (Fm) which can go up to 100KHz and 400KHz respectively. //! +//! ## Configuration +//! +//! Each I2C controller is individually configurable, and the usual setting +//! such as frequency, timeout, and SDA/SCL pins can easily be configured. +//! +//! ```rust, no_run +#![doc = crate::before_snippet!()] +//! # use esp_hal::i2c::I2C; +//! # use esp_hal::gpio::Io; +//! # use core::option::Option::None; +//! # use crate::esp_hal::prelude::_fugit_RateExtU32; +//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); +//! // Create a new peripheral object with the described wiring +//! // and standard I2C clock speed +//! let mut i2c = I2C::new( +//! peripherals.I2C0, +//! io.pins.gpio1, +//! io.pins.gpio2, +//! 100.kHz(), +//! &clocks, +//! None, +//! ); +//! # } +//! ``` +//! +//! ## Usage +//! +//! The I2C driver implements a number of third-party traits, with the +//! intention of making the HAL inter-compatible with various device drivers +//! from the community. This includes the [embedded-hal] for both 0.2.x and +//! 1.x.x versions. +//! +//! ### Examples +//! +//! #### Read Data from a BMP180 Sensor //! ```rust, no_run #![doc = crate::before_snippet!()] //! # use esp_hal::i2c::I2C; //! # use esp_hal::gpio::Io; //! # use core::option::Option::None; //! # use crate::esp_hal::prelude::_fugit_RateExtU32; -//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); +//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); //! // Create a new peripheral object with the described wiring //! // and standard I2C clock speed //! let mut i2c = I2C::new( diff --git a/esp-hal/src/ledc/mod.rs b/esp-hal/src/ledc/mod.rs index 391027041a5..316bf648cc9 100644 --- a/esp-hal/src/ledc/mod.rs +++ b/esp-hal/src/ledc/mod.rs @@ -1,10 +1,22 @@ -//! # LEDC (LED PWM Controller) peripheral control +//! # LED Controller (LEDC) //! -//! Currently only supports fixed-frequency output. Interrupts are not currently -//! implemented. High Speed channels are available for the ESP32 only, while Low -//! Speed channels are available for all supported chips. +//! The LED control (LEDC) peripheral is primarily designed to control the +//! intensity of LEDs, although it can also be used to generate PWM signals for +//! other purposes. It has multiple channels which can generate independent +//! waveforms that can be used, for example, to drive RGB LED devices. //! -//! # LowSpeed Example: +//! The PWM controller can automatically increase or decrease the duty cycle +//! gradually, allowing for fades without any processor interference. +//! +//! ## Configuration +//! +//! Currently only supports fixed-frequency output. High Speed channels are +//! available for the ESP32 only, while Low Speed channels are available for all +//! supported chips. +//! +//! ### Examples +//! +//! #### Low Speed Channel //! //! The following will configure the Low Speed Channel0 to 24kHz output with //! 10% duty using the ABPClock @@ -47,7 +59,8 @@ //! # } //! ``` //! -//! # Unsupported +//! ## Unsupported +//! //! - Source clock selection //! - Interrupts diff --git a/esp-hal/src/parl_io.rs b/esp-hal/src/parl_io.rs index 9d9a0233844..a24d07d910b 100644 --- a/esp-hal/src/parl_io.rs +++ b/esp-hal/src/parl_io.rs @@ -1,6 +1,5 @@ //! # Parallel IO //! -//! ## Overview //! The Parallel IO peripheral is a general purpose parallel interface that can //! be used to connect to external devices such as LED matrix, LCD display, //! Printer and Camera. The peripheral has independent TX and RX units. Each diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs index 8fd21dfed81..535a82ea22a 100644 --- a/esp-hal/src/uart.rs +++ b/esp-hal/src/uart.rs @@ -1,4 +1,4 @@ -//! Universal Asynchronous Receiver/Transmitter (UART) +//! # Universal Asynchronous Receiver/Transmitter (UART) //! //! The UART is a hardware peripheral which handles communication using serial //! communication interfaces, such as RS232 and RS485. This peripheral provides @@ -15,8 +15,8 @@ //! //! Each UART controller is individually configurable, and the usual setting //! such as baud rate, data bits, parity, and stop bits can easily be -//! configured. Additionally, the transmit (TX) and receive (RX) pins can be -//! specified. +//! configured. Additionally, the transmit (TX) and receive (RX) pins need to +//! be specified. //! //! ```rust, no_run #![doc = crate::before_snippet!()] @@ -30,6 +30,10 @@ //! # } //! ``` //! +//! The UART controller can be configured to invert the polarity of the pins. +//! This is achived by inverting the desired pins, and then constucting the +//! UART instance using the inverted pins. +//! //! ## Usage //! //! The UART driver implements a number of third-party traits, with the @@ -86,6 +90,33 @@ //! # } //! ``` //! +//! #### Inverting TX and RX Pins +//! ```rust, no_run +#![doc = crate::before_snippet!()] +//! # use esp_hal::uart::{config::Config, Uart}; +//! use esp_hal::gpio::{Io, any_pin::AnyPin}; +//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); +//! +//! let tx = AnyPin::new_inverted(io.pins.gpio1); +//! let rx = AnyPin::new_inverted(io.pins.gpio2); +//! let mut uart1 = Uart::new(peripherals.UART1, &clocks, tx, rx).unwrap(); +//! # } +//! ``` +//! +//! #### Constructing TX and RX Components +//! ```rust, no_run +#![doc = crate::before_snippet!()] +//! # use esp_hal::uart::{config::Config, UartTx, UartRx}; +//! use esp_hal::gpio::{Io, any_pin::AnyPin}; +//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); +//! +//! let tx = UartTx::new(peripherals.UART0, &clocks, None, +//! io.pins.gpio1).unwrap(); +//! let rx = UartRx::new(peripherals.UART1, &clocks, None, +//! io.pins.gpio2).unwrap(); +//! # } +//! ``` +//! //! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/ //! [embedded-io]: https://docs.rs/embedded-io/latest/embedded_io/ //! [embedded-hal-async]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/ diff --git a/hil-test/README.md b/hil-test/README.md index 1742d13726b..bfc0c96b93a 100644 --- a/hil-test/README.md +++ b/hil-test/README.md @@ -92,7 +92,7 @@ Our self hosted runners have the following setup: [`hil.yml`]: https://github.com/esp-rs/esp-hal/blob/main/.github/workflows/hil.yml -#### VM Setup +#### RPi Setup ```bash # Install Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain stable -y --profile minimal @@ -123,4 +123,5 @@ sudo reboot //% CHIPS: esp32 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3 ``` If the test is supported by all the targets, you can omit the header. + 6. Write some documentation at the top of the `tests/$PERIPHERAL.rs` file with the pins being used and the required connections, if applicable.