Skip to content

Commit fc2815b

Browse files
playfulFenceplayfulFence
authored
gpio, spi and i2c::master cleanup, smaller updates (#3010)
* `gpio` and `i2c::master` cleanup, smaller updates fmt * spi docs update * fmt * alter `split` doc example for different pin types * address reviews * adjust to changes after rebase
1 parent 16af010 commit fc2815b

File tree

4 files changed

+292
-63
lines changed

4 files changed

+292
-63
lines changed

‎esp-hal/src/gpio/mod.rs‎

Lines changed: 131 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,13 +44,8 @@
4444
//! an input and output signal. You can then pass these signals to the
4545
//! peripheral drivers similar to how you would pass a pin.
4646
//!
47-
//! ### GPIO interconnect example
48-
//!
49-
//! See the [Inverting TX and RX Pins] example of the UART documentation.
50-
//!
51-
//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
52-
//! [embedded-hal-async]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/index.html
53-
//! [Inverting TX and RX Pins]: crate::uart#inverting-rx-and-tx-pins
47+
//! [embedded-hal]: embedded_hal
48+
//! [embedded-hal-async]: embedded_hal_async
5449
5550
use core::fmt::Display;
5651

@@ -674,6 +669,12 @@ where
674669
///
675670
/// Peripheral signals allow connecting peripherals together without using
676671
/// external hardware.
672+
///
673+
/// ```rust, no_run
674+
#[doc = crate::before_snippet!()]
675+
/// let (rx, tx) = peripherals.GPIO2.split();
676+
/// # }
677+
/// ```
677678
#[instability::unstable]
678679
pub fn split(self) -> (interconnect::InputSignal, interconnect::OutputSignal) {
679680
// FIXME: we should implement this in the gpio macro for output pins, but we
@@ -1168,6 +1169,14 @@ impl<'d> Output<'d> {
11681169
///
11691170
/// Peripheral signals allow connecting peripherals together without using
11701171
/// external hardware.
1172+
/// ```rust, no_run
1173+
#[doc = crate::before_snippet!()]
1174+
/// # use esp_hal::gpio::{Output, OutputConfig, Level};
1175+
/// let config = OutputConfig::default().with_level(Level::High);
1176+
/// let pin1 = Output::new(peripherals.GPIO1, config).unwrap();
1177+
/// let (input, output) = pin1.split();
1178+
/// # }
1179+
/// ```
11711180
#[inline]
11721181
#[instability::unstable]
11731182
pub fn split(self) -> (interconnect::InputSignal, interconnect::OutputSignal) {
@@ -1178,6 +1187,15 @@ impl<'d> Output<'d> {
11781187
/// this pin.
11791188
///
11801189
/// The input signal can be passed to peripherals in place of an input pin.
1190+
/// ```rust, no_run
1191+
#[doc = crate::before_snippet!()]
1192+
/// # use esp_hal::gpio::{Output, OutputConfig, Level};
1193+
/// let config = OutputConfig::default().with_level(Level::High);
1194+
/// let pin1_gpio = Output::new(peripherals.GPIO1, config).unwrap();
1195+
/// // Can be passed as an input.
1196+
/// let pin1 = pin1_gpio.peripheral_input();
1197+
/// # }
1198+
/// ```
11811199
#[inline]
11821200
#[instability::unstable]
11831201
pub fn peripheral_input(&self) -> interconnect::InputSignal {
@@ -1189,6 +1207,14 @@ impl<'d> Output<'d> {
11891207
///
11901208
/// The output signal can be passed to peripherals in place of an output
11911209
/// pin.
1210+
/// ```rust, no_run
1211+
#[doc = crate::before_snippet!()]
1212+
/// # use esp_hal::gpio::{Output, OutputConfig, Level};
1213+
/// let config = OutputConfig::default().with_level(Level::High);
1214+
/// let pin1_gpio = Output::new(peripherals.GPIO1, config).unwrap();
1215+
/// let pin1 = pin1_gpio.into_peripheral_output();
1216+
/// # }
1217+
/// ```
11921218
#[inline]
11931219
#[instability::unstable]
11941220
pub fn into_peripheral_output(self) -> interconnect::OutputSignal {
@@ -1336,6 +1362,14 @@ impl<'d> Input<'d> {
13361362
/// this pin.
13371363
///
13381364
/// The input signal can be passed to peripherals in place of an input pin.
1365+
/// ```rust, no_run
1366+
#[doc = crate::before_snippet!()]
1367+
/// # use esp_hal::gpio::{Input, InputConfig, Pull};
1368+
/// let config = InputConfig::default().with_pull(Pull::Up);
1369+
/// let pin1_gpio = Input::new(peripherals.GPIO1, config).unwrap();
1370+
/// let pin1 = pin1_gpio.peripheral_input();
1371+
/// # }
1372+
/// ```
13391373
#[inline]
13401374
#[instability::unstable]
13411375
pub fn peripheral_input(&self) -> interconnect::InputSignal {
@@ -1378,8 +1412,9 @@ impl<'d> Input<'d> {
13781412
/// otherwise your program will be stuck in a loop as long as the pin is
13791413
/// reading the corresponding level.
13801414
///
1381-
/// ## Example: print something when a button is pressed.
1415+
/// ## Examples
13821416
///
1417+
/// ### Print something when a button is pressed.
13831418
/// ```rust, no_run
13841419
#[doc = crate::before_snippet!()]
13851420
/// use esp_hal::gpio::{Event, Input, InputConfig, Pull, Io};
@@ -1475,6 +1510,14 @@ impl<'d> Input<'d> {
14751510
///
14761511
/// Peripheral signals allow connecting peripherals together without using
14771512
/// external hardware.
1513+
/// ```rust, no_run
1514+
#[doc = crate::before_snippet!()]
1515+
/// # use esp_hal::gpio::{Input, InputConfig, Pull};
1516+
/// let config = InputConfig::default().with_pull(Pull::Up);
1517+
/// let pin1 = Input::new(peripherals.GPIO1, config).unwrap();
1518+
/// let (input, output) = pin1.split();
1519+
/// # }
1520+
/// ```
14781521
#[inline]
14791522
#[instability::unstable]
14801523
pub fn split(self) -> (interconnect::InputSignal, interconnect::OutputSignal) {
@@ -1486,6 +1529,15 @@ impl<'d> Input<'d> {
14861529
///
14871530
/// The output signal can be passed to peripherals in place of an output
14881531
/// pin.
1532+
/// ```rust, no_run
1533+
#[doc = crate::before_snippet!()]
1534+
/// # use esp_hal::gpio::{Input, InputConfig, Pull};
1535+
/// let config = InputConfig::default().with_pull(Pull::Up);
1536+
/// let pin1_gpio = Input::new(peripherals.GPIO1, config).unwrap();
1537+
/// // Can be passed as an output.
1538+
/// let pin1 = pin1_gpio.into_peripheral_output();
1539+
/// # }
1540+
/// ```
14891541
#[inline]
14901542
#[instability::unstable]
14911543
pub fn into_peripheral_output(self) -> interconnect::OutputSignal {
@@ -1594,6 +1646,19 @@ impl<'d> OutputOpenDrain<'d> {
15941646
///
15951647
/// Peripheral signals allow connecting peripherals together without using
15961648
/// external hardware.
1649+
/// ```rust, no_run
1650+
#[doc = crate::before_snippet!()]
1651+
/// # use esp_hal::gpio::{OutputOpenDrain, OutputOpenDrainConfig, Level, Pull};
1652+
/// let config = OutputOpenDrainConfig::default()
1653+
/// .with_level(Level::High)
1654+
/// .with_pull(Pull::Up);
1655+
/// let pin1 = OutputOpenDrain::new(
1656+
/// peripherals.GPIO1,
1657+
/// config,
1658+
/// ).unwrap();
1659+
/// let (input, output) = pin1.split();
1660+
/// # }
1661+
/// ```
15971662
#[inline]
15981663
#[instability::unstable]
15991664
pub fn split(self) -> (interconnect::InputSignal, interconnect::OutputSignal) {
@@ -1604,6 +1669,20 @@ impl<'d> OutputOpenDrain<'d> {
16041669
/// this pin.
16051670
///
16061671
/// The input signal can be passed to peripherals in place of an input pin.
1672+
/// ```rust, no_run
1673+
#[doc = crate::before_snippet!()]
1674+
/// # use esp_hal::gpio::{OutputOpenDrain, OutputOpenDrainConfig, Level, Pull};
1675+
/// let config = OutputOpenDrainConfig::default()
1676+
/// .with_level(Level::High)
1677+
/// .with_pull(Pull::Up);
1678+
/// let pin1_gpio = OutputOpenDrain::new(
1679+
/// peripherals.GPIO1,
1680+
/// config,
1681+
/// ).unwrap();
1682+
/// // Can be passed as an input.
1683+
/// let pin1 = pin1_gpio.peripheral_input();
1684+
/// # }
1685+
/// ```
16071686
#[inline]
16081687
#[instability::unstable]
16091688
pub fn peripheral_input(&self) -> interconnect::InputSignal {
@@ -1615,6 +1694,20 @@ impl<'d> OutputOpenDrain<'d> {
16151694
///
16161695
/// The output signal can be passed to peripherals in place of an output
16171696
/// pin.
1697+
/// ```rust, no_run
1698+
#[doc = crate::before_snippet!()]
1699+
/// # use esp_hal::gpio::{OutputOpenDrain, OutputOpenDrainConfig, Level, Pull};
1700+
/// let config = OutputOpenDrainConfig::default()
1701+
/// .with_level(Level::High)
1702+
/// .with_pull(Pull::Up);
1703+
/// let pin1_gpio = OutputOpenDrain::new(
1704+
/// peripherals.GPIO1,
1705+
/// config,
1706+
/// ).unwrap();
1707+
/// // Can be passed as an input.
1708+
/// let pin1 = pin1_gpio.into_peripheral_output();
1709+
/// # }
1710+
/// ```
16181711
#[inline]
16191712
#[instability::unstable]
16201713
pub fn into_peripheral_output(self) -> interconnect::OutputSignal {
@@ -1748,6 +1841,14 @@ impl<'d> Flex<'d> {
17481841
/// this pin.
17491842
///
17501843
/// The input signal can be passed to peripherals in place of an input pin.
1844+
/// ```rust, no_run
1845+
#[doc = crate::before_snippet!()]
1846+
/// # use esp_hal::gpio::Flex;
1847+
/// let pin1_gpio = Flex::new(peripherals.GPIO1);
1848+
/// // Can be passed as an input.
1849+
/// let pin1 = pin1_gpio.peripheral_input();
1850+
/// # }
1851+
/// ```
17511852
#[inline]
17521853
#[instability::unstable]
17531854
pub fn peripheral_input(&self) -> interconnect::InputSignal {
@@ -1936,6 +2037,13 @@ impl<'d> Flex<'d> {
19362037
///
19372038
/// Peripheral signals allow connecting peripherals together without using
19382039
/// external hardware.
2040+
/// ```rust, no_run
2041+
#[doc = crate::before_snippet!()]
2042+
/// # use esp_hal::gpio::Flex;
2043+
/// let pin1 = Flex::new(peripherals.GPIO1);
2044+
/// let (input, output) = pin1.split();
2045+
/// # }
2046+
/// ```
19392047
#[inline]
19402048
#[instability::unstable]
19412049
pub fn split(self) -> (interconnect::InputSignal, interconnect::OutputSignal) {
@@ -1948,6 +2056,14 @@ impl<'d> Flex<'d> {
19482056
///
19492057
/// The output signal can be passed to peripherals in place of an output
19502058
/// pin.
2059+
/// ```rust, no_run
2060+
#[doc = crate::before_snippet!()]
2061+
/// # use esp_hal::gpio::Flex;
2062+
/// let pin1_gpio = Flex::new(peripherals.GPIO1);
2063+
/// // Can be passed as an output.
2064+
/// let pin1 = pin1_gpio.into_peripheral_output();
2065+
/// # }
2066+
/// ```
19512067
#[inline]
19522068
#[instability::unstable]
19532069
pub fn into_peripheral_output(self) -> interconnect::OutputSignal {
@@ -1977,6 +2093,13 @@ impl AnyPin {
19772093
///
19782094
/// Peripheral signals allow connecting peripherals together without
19792095
/// using external hardware.
2096+
/// ```rust, no_run
2097+
#[doc = crate::before_snippet!()]
2098+
/// # use esp_hal::gpio::{AnyPin, Pin};
2099+
/// let pin1 = peripherals.GPIO1.degrade();
2100+
/// let (input, output) = pin1.split();
2101+
/// # }
2102+
/// ```
19802103
#[inline]
19812104
#[instability::unstable]
19822105
pub fn split(self) -> (interconnect::InputSignal, interconnect::OutputSignal) {

0 commit comments

Comments
 (0)