m5stack_core/board/fire27.rs
1// SPDX-License-Identifier: MIT OR Apache-2.0
2//! M5Stack Fire v2.7 (ESP32) board-level pin wiring.
3
4use esp_hal::{
5 Blocking,
6 dma::SpiDmaChannel,
7 gpio::AnyPin,
8 i2c::master::{BusTimeout, Config as I2cConfig, I2c, SoftwareTimeout},
9 peripherals::{BT, PCNT0_UNIT1, Peripherals, RMT, UART0, WIFI},
10 spi::master::AnySpi,
11 time::Rate,
12 timer::{AnyTimer, timg::TimerGroup},
13};
14
15use crate::board::spi2::Spi2Resources;
16use crate::board::{SoftwareInterrupts, SystemResources};
17use crate::driver::ip5306::{IP5306_ADDR, Ip5306Driver, Ip5306Error};
18use crate::io::buttons::ButtonResources;
19use crate::io::shared_i2c::SharedI2cBus;
20
21/// External M5-Bus pins the BSP does not claim for on-board functions. What
22/// hangs off them (1-Wire sensors, RPM pickups, ...) is application wiring.
23/// Not exhaustive — extend as needed.
24pub struct M5Bus<'a> {
25 pub gpio5: AnyPin<'a>,
26 pub gpio26: AnyPin<'a>,
27}
28
29/// The Fire27's peripherals, split into board-fact groups. See
30/// [`Board::split`].
31pub struct Board {
32 /// Display + SD-card shared SPI2 bus (see [`super::spi2`]).
33 pub spi2: Spi2Resources<'static>,
34 /// Internal I2C bus (SDA=GPIO21, SCL=GPIO22) — IP5306 fuel gauge (0x75,
35 /// M5GO bottom) and any Grove/external I2C devices.
36 ///
37 /// Returned BLOCKING: defer `into_async()` to the core that runs the I2C
38 /// tasks — `into_async()` binds the I2C peripheral IRQ to the calling
39 /// core, and on a BLE app it must stay off the core running RWBLE's
40 /// level-1 IRQ (cumulative IRQ blocking otherwise desyncs the BLE
41 /// controller blob and wedges that core's executor).
42 pub i2c0: I2c<'static, Blocking>,
43 /// Front-panel buttons A/B/C (GPIO39/38/37, active-low). Use
44 /// [`ButtonResources::into_buttons`] (feature `buttons`).
45 pub buttons: ButtonResources<'static>,
46 pub bt: BT<'static>,
47 pub wifi: WIFI<'static>,
48 /// UART0 — console + serial-cmd
49 /// ([`crate::io::serial_cmd::SerialCmdResources`] +
50 /// [`crate::io::console`]).
51 pub uart0: UART0<'static>,
52 /// UART0 RX pin (GPIO3).
53 pub uart0_rx: AnyPin<'static>,
54 /// UART0 TX pin (GPIO1).
55 pub uart0_tx: AnyPin<'static>,
56 /// SK6812 LED bars data pin (M-Bus pin 23 → GPIO15), driven over RMT
57 /// ([`crate::driver::sk6812::Sk6812Driver`]).
58 pub sk6812: AnyPin<'static>,
59 /// RMT — SK6812 LED bars or the 1-Wire driver (one owner;
60 /// [`crate::io::ow_temp::OnewireResources`]).
61 pub rmt: RMT<'static>,
62 /// PCNT — e.g. pulse counting ([`crate::io::rpm::RpmResources`]).
63 pub pcnt: PCNT0_UNIT1<'static>,
64 /// Spare SPI3 unit — the BSP does not drive it, listed for the app to
65 /// claim (same idea as [`Self::rmt`]/[`Self::pcnt`]). Wiring (which
66 /// [`Self::m5bus`] pin is SCK/MOSI/MISO/CS) and the interrupt priority /
67 /// core allocation are application knowledge. Attach the CS pin as the
68 /// peripheral's **hardware** chip-select (`with_cs`), not a
69 /// software-toggled [`esp_hal::gpio::Output`] — some designs depend on a
70 /// sub-microsecond CS gap that software toggling cannot hold. See #27.
71 pub spi3: AnySpi<'static>,
72 /// PDMA channel for [`Self::spi3`] — SPI3's own dedicated PDMA unit, not
73 /// shared with `spi2` (`DMA_SPI2`).
74 pub spi3_dma: SpiDmaChannel<'static>,
75 /// External SPI PSRAM (~4 MB) — feed to `mem::psram_map` / `mem::psram_split`
76 /// (the ESP32 cannot DMA from PSRAM). [feature `psram`]
77 pub psram: esp_hal::peripherals::PSRAM<'static>,
78 pub m5bus: M5Bus<'static>,
79 pub system: SystemResources<'static>,
80}
81
82impl Board {
83 /// Wire the Fire27 pin map. Call once with the output of
84 /// [`crate::board::init`] (or `esp_hal::init`); heap setup stays with the
85 /// app (sizing is application policy).
86 pub fn split(peripherals: Peripherals) -> Self {
87 let spi2 = Spi2Resources {
88 spi2: AnySpi::from(peripherals.SPI2),
89 spi2_dma: SpiDmaChannel::from(peripherals.DMA_SPI2),
90 sck: AnyPin::from(peripherals.GPIO18),
91 mosi: AnyPin::from(peripherals.GPIO23),
92 miso: AnyPin::from(peripherals.GPIO19),
93 display_cs: AnyPin::from(peripherals.GPIO14),
94 display_dc: AnyPin::from(peripherals.GPIO27),
95 display_rst: AnyPin::from(peripherals.GPIO33),
96 display_bl: AnyPin::from(peripherals.GPIO32),
97 card_cs: AnyPin::from(peripherals.GPIO4),
98 };
99
100 let i2c0 = I2c::new(
101 peripherals.I2C0,
102 I2cConfig::default()
103 .with_frequency(Rate::from_khz(400))
104 // The PPS holds SCL 100-200 us while it copies its bank for a
105 // read (measured); 400 cycles = 1 ms, 5x that.
106 .with_timeout(BusTimeout::BusCycles(400))
107 // A transaction is <= ~1 ms; this caps how long the APP-core
108 // executor can spin on one that never completes.
109 .with_software_timeout(SoftwareTimeout::Transaction(
110 esp_hal::time::Duration::from_millis(3),
111 )),
112 )
113 .expect("I2C0 init failed")
114 .with_sda(AnyPin::from(peripherals.GPIO21))
115 .with_scl(AnyPin::from(peripherals.GPIO22));
116
117 let buttons = ButtonResources {
118 left: AnyPin::from(peripherals.GPIO39),
119 center: AnyPin::from(peripherals.GPIO38),
120 right: AnyPin::from(peripherals.GPIO37),
121 };
122
123 let tg0 = TimerGroup::new(peripherals.TIMG0);
124 let tg1 = TimerGroup::new(peripherals.TIMG1);
125 let system = SystemResources {
126 aes: peripherals.AES,
127 sw_int: SoftwareInterrupts {
128 intr2: peripherals.FROM_CPU_INTR2,
129 intr3: peripherals.FROM_CPU_INTR3,
130 },
131 timer0_0: AnyTimer::from(tg0.timer0),
132 timer0_1: AnyTimer::from(tg0.timer1),
133 timer1_0: AnyTimer::from(tg1.timer0),
134 timer1_1: AnyTimer::from(tg1.timer1),
135 cpu_ctrl: peripherals.CPU_CTRL,
136 lpwr: peripherals.LPWR,
137 flash: peripherals.FLASH,
138 rtc_timer: peripherals.RTC_TIMER,
139 };
140
141 Board {
142 spi2,
143 i2c0,
144 buttons,
145 bt: peripherals.BT,
146 wifi: peripherals.WIFI,
147 uart0: peripherals.UART0,
148 uart0_rx: AnyPin::from(peripherals.GPIO3),
149 uart0_tx: AnyPin::from(peripherals.GPIO1),
150 sk6812: AnyPin::from(peripherals.GPIO15),
151 rmt: peripherals.RMT,
152 pcnt: peripherals.PCNT0_UNIT1,
153 spi3: AnySpi::from(peripherals.SPI3),
154 spi3_dma: SpiDmaChannel::from(peripherals.DMA_SPI3),
155 psram: peripherals.PSRAM,
156 m5bus: M5Bus {
157 gpio5: AnyPin::from(peripherals.GPIO5),
158 gpio26: AnyPin::from(peripherals.GPIO26),
159 },
160 system,
161 }
162 }
163}
164
165/// Whether USB is powering the board: IP5306 READ0 bit 3, set while VBUS feeds
166/// the charger. Measured both ways on a Fire v2.7: set on USB without a
167/// battery, clear on M-Bus 5 V with USB pulled.
168pub async fn usb_powered(i2c: &'static SharedI2cBus) -> Result<bool, Ip5306Error> {
169 Ip5306Driver::new(i2c, IP5306_ADDR).is_charging().await
170}