Skip to main content

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}