rumcake Feature: Improve docs

Type of Feature Request

[X] Enhancement to an existing rumcake feature
[ ] New feature unrelated to existing rumcake features
[ ] New driver for existing rumcake features
[ ] Support for a new MCU

Description

First of all thanks for putting this project together. I've been looking for an option to get things working for my latest keyboard, and this looks like the closest I've got.

My current keyboard is a ferris/sweep with one half with an ELITE-pi (aka an RP2040), and the other half is a nice!nano board. Both of these boards are connected via a wired connection on a TRRS cable. The reason this project seems like a great option is;

I like rust and I typically do most my embedded development in rust
QMK doesn't support Bluetooth
ZMK supports Bluetooth but doesn't support a wired connection between split left/right.

This project seems to be the perfect fit, but after a few hours of reading through the source code I'm kind of stumped as to how all the pieces fit together. The documentation that is available it seems like it's very well written but there are some holes where docs could probably be better. I'm fully aware that writing docs can be quite dry and boring, so I'm just going to ask some questions and if you have time to respond I'll write them up into some docs as I go. Here are my questions;

Setting wired serial connection between split left/right

What are the parameters that I should be using with rumcake::hw::mcu::setup_buffered_uarte to implement the necessary settings for wired communication? Apart from the RX/TX pin args it's unclear what I should be using here. I've tried looking through the docs and source code in embassy, nrf-hal etc. But between all the macros and abstraction layer's I've kind of got a little lost. e.g. Here are one of the errors that I'm running into;

error: proc macro panicked
  --> src/right.rs:82:5
   |
82 |     setup_buffered_uarte!{UART0, TIMER1, PPI_CH1, PPI_CH2, PPI_GROUP0, P0_08, P0_06}
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: message: proc-macro-error API cannot be used outside of `entry_point` invocation, perhaps you forgot to annotate your #[proc_macro] function with `

TBH I'm not even sure if the arguments I've used here even make sense. So it could be that I'm just using the macro completely incorrectly.

Setting up non-matrix type keyboard pinouts

In the case that there is 1-gpio-pin per key, what should I be doing with the layouts? It's not entirely clear how to adapt the layout for non-diode-matrix keyboards.

Mar 16 '24 23:03 nathaniel-brough

Thanks for the issue!

I am aware the docs aren't totally complete, and I appreciate the pointers on where the docs need some work. I do plan on adding more information about setting up specific drivers to the user docs, along with adding doc comments for the macros (and improving the API reference in general). At the moment, the only information about drivers is just the "Available Drivers" section, which I know may not be enough information for a first-time user.

As for that macro error message you pasted, looks like I forgot to add the #[proc_macro_error] attribute to some of the macros, so the error message isn't really informative. setup_buffered_uarte is specific to nRF chips, and the arguments are in the following order: interrupt name, UARTE peripheral, timer peripheral, PPI channel 1, PPI channel 2, PPI group, RX pin and TX pin. If you want more information about, check embassy_nrf::buffered_uarte::BufferedUarte::new Here's the source for the macro:

https://github.com/Univa/rumcake/blob/30bdb70b164b71284f6c9679a286510b8057faae/rumcake-macros/src/hw/nrf.rs#L88-L141

setup_buffered_uart for RP2040 is simpler, and just needs the interrupt name, UART peripheral, RX pin and TX pin (in that order):

https://github.com/Univa/rumcake/blob/30bdb70b164b71284f6c9679a286510b8057faae/rumcake-macros/src/hw/rp.rs#L93-L126

For the diodeless matrix, this is something that is supported by keyberon via the DirectPinMatrix struct, but I haven't written a matrix polling task that works with it yet. I am currently working on implementing analog matrix support, so I'll probably tackle direct pin matrices alongside that. I'll probably add a macro to map a specific pin to a matrix position (like build_layout but pin identifiers instead of keycodes).

Mar 17 '24 15:03 Univa

Added support for direct pin / diodeless matrix: https://univa.github.io/rumcake/getting-started/matrix-and-layout/#direct-pin-matrix-diodeless-matrix

Let me know if you have any issues getting this to work.

Mar 19 '24 19:03 Univa