Skip to content

Commit f0366fe

Browse files
jhodappjhodapp
authored
Merge pull request #59 from Jim-Hodapp-Coaching/38-publish-esp32-wroom-rp-crate-to-cratesio
Mature documentation and ready for publishing to crates.io
2 parents 47e7bc0 + a4b0cf5 commit f0366fe

File tree

8 files changed

+274
-117
lines changed

8 files changed

+274
-117
lines changed

‎cross/get_fw_version/src/main.rs‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@
88
#![no_std]
99
#![no_main]
1010

11-
extern crate esp32_wroom_rp;
12-
1311
// The macro for our start-up function
1412
use cortex_m_rt::entry;
1513

@@ -26,6 +24,9 @@ use fugit::RateExtU32;
2624
use hal::clocks::Clock;
2725
use hal::pac;
2826

27+
use esp32_wroom_rp::gpio::EspControlPins;
28+
use esp32_wroom_rp::wifi::Wifi;
29+
2930
/// The linker will place this boot block at the start of our program image. We
3031
/// need this to help the ROM bootloader get our code up and running.
3132
#[link_section = ".boot2"]
@@ -92,7 +93,7 @@ fn main() -> ! {
9293
&MODE_0,
9394
);
9495

95-
let esp_pins = esp32_wroom_rp::gpio::EspControlPins {
96+
let esp_pins = EspControlPins {
9697
// CS on pin x (GPIO7)
9798
cs: pins.gpio7.into_mode::<hal::gpio::PushPullOutput>(),
9899
// GPIO0 on pin x (GPIO2)
@@ -102,7 +103,7 @@ fn main() -> ! {
102103
// ACK on pin x (GPIO10)
103104
ack: pins.gpio10.into_mode::<hal::gpio::FloatingInput>(),
104105
};
105-
let mut wifi = esp32_wroom_rp::wifi::Wifi::init(spi, esp_pins, &mut delay).unwrap();
106+
let mut wifi = Wifi::init(spi, esp_pins, &mut delay).unwrap();
106107
let firmware_version = wifi.firmware_version();
107108
defmt::info!("NINA firmware version: {:?}", firmware_version);
108109

‎esp32-wroom-rp/src/gpio.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! GPIO pin control interface of a connected ESP32-WROOM target Wifi board.
1+
//! GPIO pin control interface of a connected ESP32-WROOM target WiFi board.
22
//!
33
//! ## Usage
44
//!

‎esp32-wroom-rp/src/lib.rs‎

Lines changed: 130 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,158 @@
11
//! esp32-wroom-rp
22
//!
3-
//! Rust-based Espressif ESP32-WROOM WiFi driver for RP2040 series microcontroller.
4-
//! Supports the [ESP32-WROOM-32E](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32e_esp32-wroom-32ue_datasheet_en.pdf), [ESP32-WROOM-32UE](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32e_esp32-wroom-32ue_datasheet_en.pdf) modules.
5-
//! Future implementations will support the [ESP32-WROOM-DA](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_en.pdf) module.
3+
//! This crate is an Espressif ESP32-WROOM WiFi module communications driver for RP2040 series microcontroller implemented in Rust.
4+
//! It currently supports the [ESP32-WROOM-32E](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32e_esp32-wroom-32ue_datasheet_en.pdf)
5+
//! and [ESP32-WROOM-32UE](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32e_esp32-wroom-32ue_datasheet_en.pdf) modules.
6+
//! Future implementations intend to add support for the [ESP32-WROOM-DA](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_en.pdf) module.
67
//!
7-
//! **NOTE:** This crate is still under active development. This API will remain volatile until 1.0.0
8+
//! It's intended to communicate with recent versions of most [Arduino-derived WiFiNINA firmwares](https://www.arduino.cc/reference/en/libraries/wifinina/)
9+
//! that run on an ESP32-WROOM-XX WiFi module. For example, Adafruit makes such WiFi hardware, referred to as the [Airlift](https://www.adafruit.com/product/4201), and maintains its [firmware](https://github.com/adafruit/nina-fw).
10+
//!
11+
//! This driver is implemented on top of [embedded-hal](https://github.com/rust-embedded/embedded-hal/), which makes it platform-independent, but is currently only intended
12+
//! to be used with [rp2040-hal](https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal) for your application.
13+
//!
14+
//! Please see the README.md for details on where to obtain and how to connect your RP2040-based device (e.g. Pico) to your ESP32-WROOM-XX WiFi board.
15+
//!
16+
//! Once connected, note that all communication with the WiFi board occurs via a SPI bus. As the example below (and all examples under the directory `cross/`)
17+
//! show, you first need to create an `embedded_hal::spi::Spi` instance. See the [rp2040-hal documentation](https://docs.rs/rp2040-hal/0.6.0/rp2040_hal/spi/index.html) along
18+
//! with the datasheet for your device on what specific SPI ports are available to you.
19+
//!
20+
//! You'll also need to reserve 4 important [GPIO pins](https://docs.rs/rp2040-hal/0.6.0/rp2040_hal/gpio/index.html) (3 output, 1 input) that are used to mediate communication between the two boards. The examples
21+
//! also demonstrate how to do this through instantiating an instance of `esp32_wroom_rp::gpio::EspControlPins`.
22+
//!
23+
//! **NOTE:** This crate is still under active development. This API will remain volatile until 1.0.0.
824
//!
925
//! ## Usage
1026
//!
1127
//! First add this to your Cargo.toml
1228
//!
1329
//! ```toml
1430
//! [dependencies]
15-
//! esp32_wroom_rp = 0.3
31+
//! esp32_wroom_rp = 0.3.0
32+
//! ...
1633
//! ```
1734
//!
1835
//! Next:
1936
//!
20-
//! ```no_run
21-
//! use esp32_wroom_rp::spi::*;
22-
//! use embedded_hal::blocking::delay::DelayMs;
23-
//!
24-
//! let mut pac = pac::Peripherals::take().unwrap();
25-
//! let core = pac::CorePeripherals::take().unwrap();
26-
//!
27-
//! let mut watchdog = hal::Watchdog::new(pac.WATCHDOG);
28-
//!
29-
//! // Configure the clocks
30-
//! let clocks = hal::clocks::init_clocks_and_plls(
31-
//! XTAL_FREQ_HZ,
32-
//! pac.XOSC,
33-
//! pac.CLOCKS,
34-
//! pac.PLL_SYS,
35-
//! pac.PLL_USB,
36-
//! &mut pac.RESETS,
37-
//! &mut watchdog,
38-
//! )
39-
//! .ok()
40-
//! .unwrap();
41-
//!
42-
//! // The single-cycle I/O block controls our GPIO pins
43-
//! let sio = hal::Sio::new(pac.SIO);
44-
//!
45-
//! // Set the pins to their default state
46-
//! let pins = hal::gpio::Pins::new(
47-
//! pac.IO_BANK0,
48-
//! pac.PADS_BANK0,
49-
//! sio.gpio_bank0,
50-
//! &mut pac.RESETS,
51-
//! );
52-
//!
53-
//! let spi_miso = pins.gpio16.into_mode::<hal::gpio::FunctionSpi>();
54-
//! let spi_sclk = pins.gpio18.into_mode::<hal::gpio::FunctionSpi>();
55-
//! let spi_mosi = pins.gpio19.into_mode::<hal::gpio::FunctionSpi>();
56-
//!
57-
//! let spi = hal::Spi::<_, _, 8>::new(pac.SPI0);
58-
//!
59-
//! // Exchange the uninitialized SPI driver for an initialized one
60-
//! let spi = spi.init(
61-
//! &mut pac.RESETS,
62-
//! clocks.peripheral_clock.freq(),
63-
//! 8.MHz(),
64-
//! &MODE_0,
65-
//! );
66-
//!
67-
//! let esp_pins = esp32_wroom_rp::gpio::EspControlPins {
68-
//! // CS on pin x (GPIO7)
69-
//! cs: pins.gpio7.into_mode::<hal::gpio::PushPullOutput>(),
70-
//! // GPIO0 on pin x (GPIO2)
71-
//! gpio0: pins.gpio2.into_mode::<hal::gpio::PushPullOutput>(),
72-
//! // RESETn on pin x (GPIO11)
73-
//! resetn: pins.gpio11.into_mode::<hal::gpio::PushPullOutput>(),
74-
//! // ACK on pin x (GPIO10)
75-
//! ack: pins.gpio10.into_mode::<hal::gpio::FloatingInput>(),
76-
//! };
77-
//!
78-
//! let mut wifi = esp32_wroom_rp::spi::Wifi::init(&mut spi, &mut esp_pins, &mut delay).unwrap();
79-
//! let version = wifi.firmware_version();
8037
//! ```
38+
//! // The macro for our start-up function
39+
//! use cortex_m_rt::entry;
40+
//!
41+
//! // Needed for debug output symbols to be linked in binary image
42+
//! use defmt_rtt as _;
43+
//!
44+
//! use panic_probe as _;
45+
//!
46+
//! // Alias for our HAL crate
47+
//! use rp2040_hal as hal;
48+
//!
49+
//! use embedded_hal::spi::MODE_0;
50+
//! use fugit::RateExtU32;
51+
//! use hal::clocks::Clock;
52+
//! use hal::pac;
53+
//!
54+
//! use esp32_wroom_rp::gpio::EspControlPins;
55+
//! use esp32_wroom_rp::wifi::Wifi;
56+
//!
57+
//! // The linker will place this boot block at the start of our program image. We
58+
//! // need this to help the ROM bootloader get our code up and running.
59+
//! #[link_section = ".boot2"]
60+
//! #[used]
61+
//! pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_W25Q080;
62+
//!
63+
//! // External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
64+
//! // if your board has a different frequency
65+
//! const XTAL_FREQ_HZ: u32 = 12_000_000u32;
66+
//!
67+
//! // Entry point to our bare-metal application.
68+
//! //
69+
//! // The `#[entry]` macro ensures the Cortex-M start-up code calls this function
70+
//! // as soon as all global variables are initialized.
71+
//! #[entry]
72+
//! fn main() -> ! {
73+
//! // Grab our singleton objects
74+
//! let mut pac = pac::Peripherals::take().unwrap();
75+
//! let core = pac::CorePeripherals::take().unwrap();
76+
//!
77+
//! // Set up the watchdog driver - needed by the clock setup code
78+
//! let mut watchdog = hal::Watchdog::new(pac.WATCHDOG);
79+
//!
80+
//! // Configure the clocks
81+
//! let clocks = hal::clocks::init_clocks_and_plls(
82+
//! XTAL_FREQ_HZ,
83+
//! pac.XOSC,
84+
//! pac.CLOCKS,
85+
//! pac.PLL_SYS,
86+
//! pac.PLL_USB,
87+
//! &mut pac.RESETS,
88+
//! &mut watchdog,
89+
//! )
90+
//! .ok()
91+
//! .unwrap();
92+
//!
93+
//! let mut delay = cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().to_Hz());
94+
//!
95+
//! // The single-cycle I/O block controls our GPIO pins
96+
//! let sio = hal::Sio::new(pac.SIO);
97+
//!
98+
//! // Set the pins to their default state
99+
//! let pins = hal::gpio::Pins::new(
100+
//! pac.IO_BANK0,
101+
//! pac.PADS_BANK0,
102+
//! sio.gpio_bank0,
103+
//! &mut pac.RESETS,
104+
//! );
105+
//!
106+
//! defmt::info!("ESP32-WROOM-RP get NINA firmware version example");
107+
//!
108+
//! // These are implicitly used by the spi driver if they are in the correct mode
109+
//! let _spi_miso = pins.gpio16.into_mode::<hal::gpio::FunctionSpi>();
110+
//! let _spi_sclk = pins.gpio18.into_mode::<hal::gpio::FunctionSpi>();
111+
//! let _spi_mosi = pins.gpio19.into_mode::<hal::gpio::FunctionSpi>();
112+
//!
113+
//! let spi = hal::Spi::<_, _, 8>::new(pac.SPI0);
114+
//!
115+
//! // Exchange the uninitialized SPI driver for an initialized one
116+
//! let spi = spi.init(
117+
//! &mut pac.RESETS,
118+
//! clocks.peripheral_clock.freq(),
119+
//! 8.MHz(),
120+
//! &MODE_0,
121+
//! );
122+
//!
123+
//! let esp_pins = EspControlPins {
124+
//! // CS on pin x (GPIO7)
125+
//! cs: pins.gpio7.into_mode::<hal::gpio::PushPullOutput>(),
126+
//! // GPIO0 on pin x (GPIO2)
127+
//! gpio0: pins.gpio2.into_mode::<hal::gpio::PushPullOutput>(),
128+
//! // RESETn on pin x (GPIO11)
129+
//! resetn: pins.gpio11.into_mode::<hal::gpio::PushPullOutput>(),
130+
//! // ACK on pin x (GPIO10)
131+
//! ack: pins.gpio10.into_mode::<hal::gpio::FloatingInput>(),
132+
//! };
133+
//! let mut wifi = Wifi::init(spi, esp_pins, &mut delay).unwrap();
134+
//! let firmware_version = wifi.firmware_version();
135+
//! defmt::info!("NINA firmware version: {:?}", firmware_version);
136+
//!
137+
//! // Infinitely sit in a main loop
138+
//! loop {}
139+
//! }
140+
//! ```
141+
//!
142+
//! ## More examples
143+
//!
144+
//! Please refer to the `cross/` directory in this crate's source for examples that demonstrate how to use every part of its public API.
145+
//!
81146
82147
#![doc(html_root_url = "https://docs.rs/esp32-wroom-rp")]
83148
#![doc(issue_tracker_base_url = "https://github.com/Jim-Hodapp-Coaching/esp32-wroom-rp/issues")]
84149
#![warn(missing_docs)]
85150
#![cfg_attr(not(test), no_std)]
86151

87152
pub mod gpio;
88-
/// Responsible for interactions over a WiFi network and also contains related types.
89153
pub mod network;
90-
/// Responsible for interactions with NINA firmware over a data bus.
91154
pub mod protocol;
92-
/// Fundamental interface for creating and send/receiving data to/from a TCP server.
93155
pub mod tcp_client;
94-
/// Fundamental interface for controlling a connected ESP32-WROOM NINA firmware-based Wifi board.
95156
pub mod wifi;
96157

97158
mod spi;

‎esp32-wroom-rp/src/network.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//! Defines common network functions, types and error definitions.
2+
//!
3+
14
use defmt::{write, Format, Formatter};
25

36
/// A four byte array type alias representing an IP address.

‎esp32-wroom-rp/src/protocol.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//! Defines functions, types and error definitions related to the WiFiNINA protocol communication specification.
2+
//!
3+
14
pub(crate) mod operation;
25

36
use core::cell::RefCell;

‎esp32-wroom-rp/src/spi.rs‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
//! Serial Peripheral Interface (SPI) for Wifi
1+
//! Serial Peripheral Interface (SPI)
2+
//!
3+
//! Contains all SPI bus related structs, types and errors. Also responsible for
4+
//! implementing WifiNINA protocol communication over a selected SPI interface.
5+
//!
6+
//! Note: Currently everything in this file is private and considered internal to the crate.
7+
//!
28
use core::convert::Infallible;
39

410
use embedded_hal::blocking::delay::DelayMs;

0 commit comments

Comments
 (0)