m5stack_core/board/rmt.rs
1// SPDX-License-Identifier: MIT OR Apache-2.0
2//! RMT channels, handed out one consumer at a time.
3//!
4//! Two on-board peripherals are driven by the RMT: the DS18B20 1-Wire bus
5//! (`driver::ds18b20`, one TX + one RX channel) and the SK6812 light bars on
6//! the M5GO Battery Bottom (`driver::sk6812`, one TX channel). Both drivers
7//! used to take `RMT<'static>` **by value** and both configured channel 0, so
8//! an application could have temperature sensing or light bars and not both —
9//! on hardware whose RMT has eight channels.
10//!
11//! This splits the peripheral once and names which channel each consumer gets,
12//! so the conflict is resolved where the board knows the answer rather than in
13//! every application. esp-hal supports exactly this: a `ChannelCreator` taken
14//! out of the `Rmt` keeps the peripheral initialised even after the `Rmt`
15//! itself is dropped.
16//!
17//! Channel assignment is per chip, because neither RX capability nor channel
18//! RAM is uniform:
19//!
20//! | | 1-Wire TX | 1-Wire RX | LEDs TX | LED blocks |
21//! |---|---|---|---|---|
22//! | **fire27** (ESP32) | 0 | 2 | 4 | 4 (256 codes) |
23//! | **cores3** (ESP32-S3) | 0 | 4 | 1 | 3 (144 codes) |
24//!
25//! On the ESP32 every channel can transmit and receive; on the ESP32-S3
26//! channels 0-3 are TX-only and 4-7 RX-only, which is why the RX channel
27//! differs. The 1-Wire pair keeps the channels it always used, so that driver's
28//! timing behaviour is unchanged.
29//!
30//! ## Why the LED channel claims several blocks
31//!
32//! An SK6812 frame is one pulse code per bit, so ten LEDs are 242 codes while
33//! one RMT block holds 64 (ESP32) or 48 (S3). A frame longer than the channel's
34//! RAM is refilled by the CPU from the threshold interrupt mid-transmission,
35//! every ~40 µs — and this firmware has LVGL, BLE and SPI DMA competing for
36//! that latency. A late refill clocks out whatever is still in the block, which
37//! an SK6812 reads as colour: the strip shows a gradient down its length rather
38//! than failing.
39//!
40//! The RMT's block RAM is inside the peripheral (ESP32: 8 x 64 codes, S3:
41//! 4 TX + 4 RX x 48), so these blocks cost no DRAM and nothing but channels
42//! that are already unused. Four blocks hold a whole ten-LED frame on the
43//! ESP32, which removes the refill entirely; the S3 cannot reach 242 codes with
44//! four TX blocks total, so there three blocks only make the refill rarer.
45
46use esp_hal::{
47 Async,
48 peripherals::RMT,
49 rmt::{ChannelCreator, ConfigError, Rmt},
50 time::Rate,
51};
52
53/// The RMT clock the 1-Wire and SK6812 bit timings are both written against.
54const RMT_FREQ_MHZ: u32 = 80;
55
56/// 1-Wire RX channel: any channel on the ESP32, an RX-capable one on the S3.
57///
58/// Public because `io::ow_temp::OnewireChannels` names the channel in its type,
59/// and that number is the board's to decide.
60#[cfg(feature = "fire27")]
61pub const OW_RX: u8 = 2;
62#[cfg(feature = "cores3")]
63pub const OW_RX: u8 = 4;
64
65/// LED TX channel. Named for the same reason as [`OW_RX`].
66///
67/// On the ESP32 it is channel 4 so that its [`LED_BLOCKS`] claim (blocks 4-7)
68/// clears the 1-Wire pair; the S3 has only channels 0-3 to transmit on.
69#[cfg(feature = "fire27")]
70pub const LED_TX: u8 = 4;
71#[cfg(feature = "cores3")]
72pub const LED_TX: u8 = 1;
73
74/// Blocks a channel-0 owner may claim: every TX block the chip has.
75///
76/// For [`crate::driver::sk6812::Sk6812Driver::new`], which takes the whole
77/// peripheral and so has nothing to share with.
78#[cfg(feature = "fire27")]
79pub const ALL_TX_BLOCKS: u8 = 8;
80#[cfg(feature = "cores3")]
81pub const ALL_TX_BLOCKS: u8 = 4;
82
83/// RMT blocks the LED channel claims, as the module docs explain.
84///
85/// Both values are every block above the channel, which is all a board with
86/// two RMT consumers can use anyway.
87#[cfg(feature = "fire27")]
88pub const LED_BLOCKS: u8 = 4;
89#[cfg(feature = "cores3")]
90pub const LED_BLOCKS: u8 = 3;
91
92/// The peripheral's channels, split for the board's two RMT consumers.
93///
94/// Fields are moved out individually — take only what the application drives,
95/// and an unused one costs nothing.
96pub struct RmtChannels {
97 /// 1-Wire TX, for [`crate::driver::ds18b20::Ds18b20Driver::with_channels`].
98 pub onewire_tx: ChannelCreator<'static, Async, 0>,
99 /// 1-Wire RX, for the same call.
100 pub onewire_rx: ChannelCreator<'static, Async, OW_RX>,
101 /// SK6812 TX, for [`crate::driver::sk6812::Sk6812Driver::with_channel`].
102 pub leds_tx: ChannelCreator<'static, Async, LED_TX>,
103}
104
105impl RmtChannels {
106 /// Initialise the RMT at 80 MHz and split out the channels above.
107 ///
108 /// Call this once, in place of handing `RMT` to a single driver.
109 pub fn new(rmt: RMT<'static>) -> Result<Self, ConfigError> {
110 let rmt = Rmt::new(rmt, Rate::from_mhz(RMT_FREQ_MHZ))?.into_async();
111 Ok(Self {
112 onewire_tx: rmt.channel0,
113 #[cfg(feature = "fire27")]
114 onewire_rx: rmt.channel2,
115 #[cfg(feature = "cores3")]
116 onewire_rx: rmt.channel4,
117 #[cfg(feature = "fire27")]
118 leds_tx: rmt.channel4,
119 #[cfg(feature = "cores3")]
120 leds_tx: rmt.channel1,
121 })
122 }
123}