sky_ili9341/
lib.rs

1#![no_std]
2
3//! # sky-ili9341
4//!
5//! Async-ready ILI9341 TFT display driver for embedded Rust.
6//!
7//! ## Features
8//!
9//! - **Blocking and async** SPI interfaces (`embedded-hal` 1.0 / `embedded-hal-async`)
10//! - **Builder pattern** for flexible configuration (orientation, color order, inversion, offsets)
11//! - **Correct MADCTL** implementation per ILI9341 datasheet — no hardcoded BGR
12//! - **Optimized drawing** with 512-byte buffered SPI writes and fast `fill_rect`
13//! - **`embedded-graphics-core`** `DrawTarget` support (optional `graphics` feature)
14//! - **`defmt`** logging support (optional `defmt` feature)
15//! - **Board presets** Made for SkyRizz E32
16//! - **`no_std`** — works on any embedded target
17//!
18//! ## Cargo Features
19//!
20//! | Feature    | Default | Description |
21//! |------------|---------|-------------|
22//! | `graphics` | ✅      | Enables `embedded-graphics-core` `DrawTarget` implementation |
23//! | `async`    | ❌      | Enables async interface, builder, and display types via `embedded-hal-async` |
24//! | `defmt`    | ❌      | Enables `defmt::Format` derives for error and option types |
25//!
26//! ## Quick Start (Blocking)
27//!
28//! ```ignore
29//! use sky_ili9341::{Builder, SpiInterface, Orientation, ColorOrder};
30//!
31//! let di = SpiInterface::new(spi, dc);
32//! let mut display = Builder::new(di)
33//!     .orientation(Orientation::Landscape)
34//!     .color_order(ColorOrder::Bgr)
35//!     .init(&mut reset_pin, &mut delay)
36//!     .unwrap();
37//!
38//! display.clear_screen(0x0000).unwrap(); // Black
39//! ```
40//!
41//! ## Quick Start (Async with Embassy on ESP32)
42//!
43//! ```ignore
44//! use sky_ili9341::{AsyncBuilder, AsyncSpiInterface, Orientation};
45//!
46//! let di = AsyncSpiInterface::new(spi, dc);
47//! let mut display = AsyncBuilder::new(di)
48//!     .orientation(Orientation::Landscape)
49//!     .init(&mut reset_pin, &mut delay)
50//!     .await
51//!     .unwrap();
52//!
53//! display.clear_screen(0xF800).await.unwrap(); // Red
54//! ```
55//!
56//! ## ESP32 Example (esp-hal + embassy)
57//!
58//! ```ignore
59//! use esp_hal::spi::master::{Config as SpiConfig, Spi};
60//! use esp_hal::spi::Mode;
61//! use esp_hal::gpio::{Level, Output};
62//! use esp_hal::delay::Delay;
63//! use sky_ili9341::{Builder, SpiInterface, presets};
64//! use embedded_graphics_core::prelude::*;
65//! use embedded_graphics_core::pixelcolor::Rgb565;
66//!
67//! // Configure SPI at 40 MHz (ILI9341 max for most boards)
68//! let spi = Spi::new(peripherals.SPI2, SpiConfig::default()
69//!     .with_frequency(40.MHz())
70//!     .with_mode(Mode::_0))
71//!     .with_sck(sclk)
72//!     .with_mosi(mosi)
73//!     .with_cs(cs);
74//!
75//! let dc = Output::new(dc_pin, Level::Low);
76//! let mut reset = Output::new(reset_pin, Level::High);
77//! let mut delay = Delay::new();
78//!
79//! // Use a board preset or configure manually
80//! let di = SpiInterface::new(spi, dc);
81//! let mut display = Builder::with_options(di, presets::skyrizz_e32())
82//!     .init(&mut reset, &mut delay)
83//!     .unwrap();
84//!
85//! display.clear_screen(0x001F).unwrap(); // Blue
86//! ```
87//!
88//! ## Using with `embedded-graphics`
89//!
90//! Enable the `graphics` feature (on by default) and use standard drawing primitives:
91//!
92//! ```ignore
93//! use embedded_graphics_core::prelude::*;
94//! use embedded_graphics_core::pixelcolor::Rgb565;
95//! use embedded_graphics_core::primitives::{Rectangle, PrimitiveStyle};
96//! use embedded_graphics_core::geometry::{Point, Size};
97//!
98//! // DrawTarget is automatically implemented
99//! display.clear(Rgb565::BLACK).unwrap();
100//!
101//! // Solid fills are optimized — no per-pixel overhead
102//! let rect = Rectangle::new(Point::new(10, 10), Size::new(100, 50));
103//! display.fill_solid(&rect, Rgb565::RED).unwrap();
104//! ```
105//!
106//! ## Architecture
107//!
108//! The driver is organized into focused modules:
109//!
110//! - [`interface`] / [`interface_async`] — Bus abstraction (own `Interface` trait, not `display-interface`)
111//! - [`builder`] / [`builder_async`] — Fluent configuration and initialization
112//! - [`display`] / [`display_async`] — Core driver with drawing and display control
113//! - [`options`] — Orientation, color order, inversion, and MADCTL encoding
114//! - [`commands`] — ILI9341 command opcodes
115//! - [`presets`] — Ready-to-use configs for popular boards
116//! - [`error`] — Typed errors preserving the underlying bus error
117
118pub mod commands;
119pub mod error;
120pub mod options;
121
122// -- Blocking --
123pub mod interface;
124pub mod builder;
125pub mod display;
126
127// -- Async (behind feature flag) --
128#[cfg(feature = "async")]
129pub mod interface_async;
130#[cfg(feature = "async")]
131pub mod builder_async;
132#[cfg(feature = "async")]
133pub mod display_async;
134
135// -- Board presets --
136pub mod presets;
137
138// -- embedded-graphics integration --
139#[cfg(feature = "graphics")]
140mod graphics;
141
142// Re-exports for convenience
143pub use builder::Builder;
144pub use display::Display;
145pub use error::Error;
146pub use interface::{Interface, SpiInterface};
147pub use options::{
148    ColorInversion, ColorOrder, DisplayOptions, HorizontalRefreshOrder, Orientation,
149    VerticalRefreshOrder,
150};
151
152#[cfg(feature = "async")]
153pub use builder_async::AsyncBuilder;
154#[cfg(feature = "async")]
155pub use display_async::AsyncDisplay;
156#[cfg(feature = "async")]
157pub use interface_async::{AsyncInterface, AsyncSpiInterface};
158
159/// SPI mode for ILI9341 (CPOL=0, CPHA=0).
160pub use embedded_hal::spi::MODE_0 as SPI_MODE;
sky_ili9341/lib.rs

sky_ili9341/
lib.rs
