Feature: Improve docs

[nathaniel-brough]

Type of Feature Request

• 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;

1. I like rust and I typically do most my embedded development in rust
2. QMK doesn't support Bluetooth
3. 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.

[Univa]

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:

rumcake/rumcake-macros/src/hw/nrf.rs

Lines 88 to 141 in 30bdb70

	fn setup_buffered_uarte_inner(args: Punctuated<Ident, Token![,]>) -> TokenStream {
	let mut args = args.iter();
	let interrupt = args.next().expect_or_abort("Missing interrupt argument.");
	let uarte = args
	.next()
	.expect_or_abort("Missing UARTE peripheral argument.");
	let timer = args
	.next()
	.expect_or_abort("Missing timer peripheral argument.");
	let ppi_ch1 = args
	.next()
	.expect_or_abort("Missing PPI CH1 peripheral argument.");
	let ppi_ch2 = args
	.next()
	.expect_or_abort("Missing PPI CH2 peripheral argument.");
	let ppi_group = args
	.next()
	.expect_or_abort("Missing PPI Group peripheral argument.");
	let rx_pin = args.next().expect_or_abort("Missing RX pin argument.");
	let tx_pin = args.next().expect_or_abort("Missing TX pin argument.");
	quote! {
	unsafe {
	static mut RBUF: [u8; 4096] = [0; 4096];
	static mut TBUF: [u8; 4096] = [0; 4096];
	::rumcake::hw::mcu::embassy_nrf::bind_interrupts! {
	struct Irqs {
	#interrupt => ::rumcake::hw::mcu::embassy_nrf::buffered_uarte::InterruptHandler<::rumcake::hw::mcu::embassy_nrf::peripherals::#uarte>;
	}
	};
	let uarte = ::rumcake::hw::mcu::embassy_nrf::peripherals::#uarte::steal();
	let timer = ::rumcake::hw::mcu::embassy_nrf::peripherals::#timer::steal();
	let ppi_ch1 = ::rumcake::hw::mcu::embassy_nrf::peripherals::#ppi_ch1::steal();
	let ppi_ch2 = ::rumcake::hw::mcu::embassy_nrf::peripherals::#ppi_ch2::steal();
	let ppi_group = ::rumcake::hw::mcu::embassy_nrf::peripherals::#ppi_group::steal();
	let rx_pin = ::rumcake::hw::mcu::embassy_nrf::peripherals::#rx_pin::steal();
	let tx_pin = ::rumcake::hw::mcu::embassy_nrf::peripherals::#tx_pin::steal();
	::rumcake::hw::mcu::embassy_nrf::buffered_uarte::BufferedUarte::new(
	uarte,
	timer,
	ppi_ch1,
	ppi_ch2,
	ppi_group,
	Irqs,
	rx_pin,
	tx_pin,
	Default::default(),
	&mut RBUF,
	&mut TBUF,
	)
	}
	}
	}

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

rumcake/rumcake-macros/src/hw/rp.rs

Lines 93 to 126 in 30bdb70

	fn setup_buffered_uart_inner(args: Punctuated<Ident, Token![,]>) -> TokenStream {
	let mut args = args.iter();
	let interrupt = args.next().expect_or_abort("Missing interrupt argument.");
	let uart = args
	.next()
	.expect_or_abort("Missing UART peripheral argument.");
	let rx_pin = args.next().expect_or_abort("Missing RX pin argument.");
	let tx_pin = args.next().expect_or_abort("Missing TX pin argument.");
	quote! {
	unsafe {
	static mut RBUF: [u8; 64] = [0; 64];
	static mut TBUF: [u8; 64] = [0; 64];
	::rumcake::hw::mcu::embassy_rp::bind_interrupts! {
	struct Irqs {
	#interrupt => ::rumcake::hw::mcu::embassy_rp::uart::BufferedInterruptHandler<::rumcake::hw::mcu::embassy_rp::peripherals::#uart>;
	}
	};
	let uart = ::rumcake::hw::mcu::embassy_rp::peripherals::#uart::steal();
	let rx = ::rumcake::hw::mcu::embassy_rp::peripherals::#rx_pin::steal();
	let tx = ::rumcake::hw::mcu::embassy_rp::peripherals::#tx_pin::steal();
	::rumcake::hw::mcu::embassy_rp::uart::BufferedUart::new(
	uart,
	Irqs,
	rx,
	tx,
	&mut TBUF,
	&mut RBUF,
	Default::default(),
	)
	}
	}
	}

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).

[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.