itsscb/esp-hal
1
0
Fork 0
mirror of https://github.com/esp-rs/esp-hal.git synced 2025-09-30 05:40:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update some modules documentation (#1726)

Browse Source 
* 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 <jessebraham@users.noreply.github.com>
This commit is contained in:
Sergio Gasquez Arcos 2024-06-27 18:50:30 +02:00 committed by GitHub
parent 565faf723b
commit d0cd890e51
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 102 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
esp-hal/src/i2c.rs
View File

@ -1,18 +1,22 @@
//! # 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!()]
@ -20,7 +24,37 @@
//! # 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(
//! 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);
//! // Create a new peripheral object with the described wiring
//! // and standard I2C clock speed
//! let mut i2c = I2C::new(

25
esp-hal/src/ledc/mod.rs
View File

@ -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

1
esp-hal/src/parl_io.rs
View File

@ -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

37
esp-hal/src/uart.rs
View File

@ -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/

3
hil-test/README.md
View File

@ -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.