Add docs, simplify template

flow3-rs-rt/src/flow3r.rs

@@ -14,17 +14,17 @@ use static_cell::StaticCell;
 
 use flow3_rs::{
     // badgelink::BadgeLink,
-    captouch::{Captouch, CaptouchRunner},
+    captouch::CaptouchRunner,
     display::Display,
     // imu::ImuHandler,
-    input::{Inputs, InputRunner},
+    input::InputRunner,
     leds::init_leds,
     Flow3r,
 };
 
 static CLOCKS: StaticCell<Clocks> = StaticCell::new();
 
-pub async fn init_flow3r() -> (Flow3r, InputRunner, CaptouchRunner)  {
+pub(crate) async fn init_flow3r() -> (Flow3r, InputRunner, CaptouchRunner)  {
     let peripherals = Peripherals::take();
     let mut system = peripherals.SYSTEM.split();
     let clocks = CLOCKS.init(ClockControl::boot_defaults(system.clock_control).freeze());
@@ -179,11 +179,9 @@ pub async fn init_flow3r() -> (Flow3r, InputRunner, CaptouchRunner)  {
 
     //let badgelink = BadgeLink::new(i2c_busmanager.acquire_i2c());
     //let imu = ImuHandler::new(i2c_busmanager.acquire_i2c());
-    let inputs = Inputs;
-    let captouch = Captouch;
     let leds = init_leds(rmt, io.pins.gpio14);
 
-    let flow3r = Flow3r::new(None, Some(captouch), Some(display), None, Some(inputs), Some(leds), Some(uart0), Some(uart1), Some(rng));
+    let flow3r = Flow3r::new(None, Some(display), None, Some(leds), Some(uart0), Some(uart1), Some(rng));
 
     (flow3r, input_runner, captouch_runner)
 }
\ No newline at end of file

flow3-rs-rt/src/lib.rs

 #![no_std]
 #![feature(type_alias_impl_trait)]
 
+//! This crate provides a runtime implementation for the [`Flow3r`] based on [`embassy`] as the async runtime.
+//! It takes care of initializing the hardware and starting the async runtime and all necessary background tasks.
+//! 
+//! If you want to get started quickly, use the [`flow3-rs-template`] to set up a minimal `flow3-rs-rt` project, by running:
+//! ```
+//! cargo generate --git https://git.flow3r.garden/flow3r/flow3-rs
+//! ```
+//! 
+//! [`Flow3r`]: https://flow3r.garden
+//! [`embassy`]: https://embassy.dev
+
 mod runtime;
 mod flow3r;
 pub use runtime::start_runtime;
\ No newline at end of file

flow3-rs-rt/src/runtime.rs

@@ -10,6 +10,21 @@ use crate::flow3r::init_flow3r;
 
 pub static EXECUTOR: StaticCell<Executor> = StaticCell::new();
 
+
+/// This function starts the async runtime, initializes the hardware and then starts the provided `main` function.
+/// The function passed as an argument must be an embassy-task.
+/// 
+/// ```rust
+/// #[entry]
+/// fn runtime() -> ! {
+///     start_runtime(main)
+/// }
+/// 
+/// #[embassy_runtime::task]
+/// async fn main(flow3r: Flow3r) {
+///     // do something
+/// }
+/// ```
 pub fn start_runtime<S>(main: fn(Flow3r) -> SpawnToken<S>) -> ! 
 {
     println!("starting runtime");
@@ -39,12 +54,12 @@ async fn init_runtime(main: fn(Flow3r) -> SpawnToken<*mut ()>) {
 }
 
 #[embassy_executor::task]
-pub async fn input_task(runner: InputRunner) -> ! {
+async fn input_task(runner: InputRunner) -> ! {
     runner.run().await
 }
 
 #[embassy_executor::task]
-pub async fn captouch_task(runner: CaptouchRunner) -> ! {
+async fn captouch_task(runner: CaptouchRunner) -> ! {
     runner.run().await
 }
 

flow3-rs-template/src/main.rs

 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
-#![feature(async_fn_in_trait)]
 
 use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
@@ -19,7 +18,7 @@ fn runtime() -> ! {
 }
 
 #[embassy_executor::task]
-async fn main(mut flow3r: Flow3r) {
+async fn main(_flow3r: Flow3r) {
     let spawner = Spawner::for_current_executor().await;
     spawner.spawn(task()).unwrap();
 }

flow3-rs/src/captouch.rs

+//! The Flow3r has a total of 10 captouch surfaces, five top petals on the upper pcb, and five bottom petals on the lower pcb.
+//! Those petals are each divided into three touch surfaces for the top petals, and two for the bottom petals, allowing for 2/1 axis position resolution.
+//! 
+//! The petals are numbered clockwise starting from petal 0 above the USB-C port, leading to even-numbered top petals 0,2,4,6,8 and odd-numbered bottom petals 1,3,5,7,9.
+//! 
+//! The captouch as a whole can be accessed via the [`Captouch`] struct, which can be split into individual top and bottom petals.
+//! 
+//! ```rust
+//! let captouch = Captouch;
+//! 
+//! // split into top and bottom petals;
+//! let top_petals = captouch.top_petals();
+//! let bottom_petals = captouch.bottom_petals();
+//! 
+//! // check if Petal 7 is pressed
+//! if bottom_petals.petal7.pressed() {
+//!     // do something
+//! }
+//! ```
+//! 
+//! ## Runner
+//! ### Usage with `flow3-rs-rt`
+//! If you use the `flow3-rs` runtime, the runner is automatically set up and started for you.
+//! ### Without `flow3-rs` runtime
+//! If you don't use the `flow3-rs-rt`, you have to start the captouch runner before you can recieve any captouch events.
+//! In a seperate async task, execute the `run` function of the `CaptouchRunner`.
+
 use ad7147::{
     device::DecimationFactor,
     stage::{CapInput, CdcInput, InputConnection, StageSensitivity, ThresholdSensitivity, PeakDetect},
@@ -31,6 +58,7 @@ static PETALS: Mutex<CriticalSectionRawMutex, [Flow3rPetal; 10]> = Mutex::new([
     Flow3rPetal::new(Flow3rCaptouchController::BOTTOM),
 ]);
 
+#[derive(Copy, Clone)]
 pub struct Captouch;
 
 impl Captouch {

flow3-rs/src/lib.rs

 #![no_std]
 #![feature(type_alias_impl_trait, async_fn_in_trait)]
 
+//! This crate contains the board support for the [`Flow3r`]. It provides higher-level
+//! abstractions for the hardware components of the flower.
+//! 
+//! This crate is written for an async runtime. There are some tasks that need to be running in the
+//! background for all functionality to work. It was tested with embassy and the flow3-rs-rt, however
+//! it _should_ be agnostic over the async runtime used.
+
+
 use hal::Rng;
 
 use self::badgelink::BadgeLink;
@@ -21,12 +29,14 @@ pub mod sdcard;
 
 unsafe impl Sync for Flow3r {}
 
+/// This struct contains all the high-level peripherals of the board.
+/// To use a peripheral, call the respective `take` or `get` function. This returns an owned version of that peripheral.
+/// Each `take` function can only be called once, and will panic if called twice. 
+/// The peripherals behind a `get` function can exist multiple times.
 pub struct Flow3r {
     badgelink: Option<BadgeLink>,
-    captouch: Option<Captouch>,
     display: Option<Display>,
     imu: Option<ImuHandler>,
-    inputs: Option<Inputs>,
     leds: Option<Leds>,
     uart0: Option<BadgenetUartLeft>,
     uart1: Option<BadgenetUartRight>,
@@ -36,10 +46,8 @@ pub struct Flow3r {
 impl Flow3r {
     pub fn new(
         badgelink: Option<BadgeLink>,
-        captouch: Option<Captouch>,
         display: Option<Display>,
         imu: Option<ImuHandler>,
-        inputs: Option<Inputs>,
         leds: Option<Leds>,
         uart0: Option<BadgenetUartLeft>,
         uart1: Option<BadgenetUartRight>,
@@ -47,10 +55,8 @@ impl Flow3r {
     ) -> Self {
         Self {
             badgelink,
-            captouch,
             display,
             imu,
-            inputs,
             leds,
             uart0,
             uart1,
@@ -62,16 +68,16 @@ impl Flow3r {
         self.badgelink.take().expect("can only take badgelink once!")
     }
 
-    pub fn take_captouch(&mut self) -> Captouch {
-        self.captouch.take().expect("can only take captouch once!")
+    pub fn get_captouch(&mut self) -> Captouch {
+        Captouch
     }
 
     pub fn take_display(&mut self) -> Display {
         self.display.take().expect("can only take display once!")
     }
 
-    pub fn take_inputs(&mut self) -> Inputs {
-        self.inputs.take().expect("can only take inputs once!")
+    pub fn get_inputs(&mut self) -> Inputs {
+        Inputs
     }
 
     pub fn take_imu(&mut self) -> ImuHandler {