Skip to content

Commit

Permalink
overhaul macros, remove re-exports
Browse files Browse the repository at this point in the history
  • Loading branch information
@Univa
Univa committed Apr 3, 2024
1 parent 297ae98 commit f6566f2
Show file tree
Hide file tree
Showing 27 changed files with 1,419 additions and 1,283 deletions.
105 changes: 67 additions & 38 deletions docs/src/content/docs/features/feature-backlight.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,25 +29,40 @@ Some drivers may not be able to support all backlight types.

## Required code

To set up backlighting, you must add a new type to implement traits on.
Then, you can add `<backlight_type>(id = <type>, driver = "<driver>")` to your `#[keyboard]` macro
invocation, and your new type must implement the appropriate trait depending on the type of lighting you're using.
To set up backlighting, you must create a new type to implement traits on.
Then, you can add `<backlight_type>(id = <type>, driver_setup_fn = <setup_fn>)` to your `#[keyboard]` macro
invocation. Your new type must implement the appropriate traits depending on the type of lighting you're using:

```rust ins={5-8,13-18}
- `simple_backlight`: [`SimpleBacklightDevice`](/rumcake/api/nrf52840/rumcake/lighting/simple_backlight/trait.SimpleBacklightDevice.html)
- `simple_backlight_matrix`: [`SimpleBacklightMatrixDevice`](/rumcake/api/nrf52840/rumcake/lighting/simple_backlight_matrix/trait.SimpleBacklightMatrixDevice.html)
- `rgb_backlight_matrix`: [`RGBBacklightMatrixDevice`](/rumcake/api/nrf52840/rumcake/lighting/rgb_backlight_matrix/trait.RGBBacklightMatrixDevice.html)

The `driver_setup_fn` must be an async function that has no parameters, and returns a type that implements the appropriate
driver trait:

- `simple_backlight`: [`SimpleBacklightDriver<T>`](/rumcake/api/nrf52840/rumcake/lighting/simple_backlight/trait.SimpleBacklightDriver.html)
- `simple_backlight_matrix`: [`SimpleBacklightMatrixDriver<T>`](/rumcake/api/nrf52840/rumcake/lighting/simple_backlight_matrix/trait.SimpleBacklightMatrixDriver.html)
- `rgb_backlight_matrix`: [`RGBBacklightMatrixDriver<T>`](/rumcake/api/nrf52840/rumcake/lighting/rgb_backlight_matrix/trait.RGBBacklightMatrixDriver.html)

```rust ins={5-8,13-22}
use rumcake::keyboard;

#[keyboard(
// somewhere in your keyboard macro invocation ...
simple_backlight_matrix( // TODO: Change this to `rgb_backlight_matrix` or `simple_backlight` if that's what you want.
id = MyKeyboardLighting,
driver = "is31fl3731", // TODO: change this to your desired backlight driver, and implement the appropriate trait (info below)
driver_setup_fn = my_backlight_setup,
)
)]
struct MyKeyboard;

// Backlight configuration
use rumcake::lighting::simple_backlight_matrix::SimpleBacklightMatrixDevice;
use rumcake::lighting::simple_backlight_matrix::{SimpleBacklightMatrixDevice, SimpleBacklightMatrixDriver};
struct MyKeyboardLighting; // New type to implement lighting traits on
async fn my_backlight_setup() -> impl SimpleBacklightMatrixDriver<MyKeyboardLighting> {
// TODO: We will fill this out soon!
todo!()
}
impl SimpleBacklightMatrixDevice for MyKeyboardLighting {
// optionally, set FPS
const FPS: usize = 20;
Expand All @@ -67,7 +82,7 @@ use rumcake::keyboard;
// somewhere in your keyboard macro invocation ...
simple_backlight_matrix( // TODO: Change this to `rgb_backlight_matrix` or `simple_backlight` if that's what you want.
id = MyKeyboardLighting,
driver = "is31fl3731", // TODO: change this to your desired backlight driver, and implement the appropriate trait (info below)
driver_setup_fn = my_backlight_setup,
use_storage // Optional, if you want to save backlight configuration
),
storage(driver = "internal") // You need to specify a storage driver if you enabled `use_storage`. See feature-storage.md for more information.
Expand All @@ -81,37 +96,41 @@ For more information, see the docs for the [storage feature](../feature-storage/

If you're implementing a backlight matrix (either the `simple-backlight-matrix` or `rgb-backlight-matrix`), your keyboard must also implement the `BacklightMatrixDevice` trait:

```rust ins={20-38}
```rust ins={14,25-42}
use rumcake::keyboard;

#[keyboard(
// somewhere in your keyboard macro invocation ...
simple_backlight_matrix( // TODO: Change this to `rgb_backlight_matrix` or `simple_backlight` if that's what you want.
id = MyKeyboardLighting,
driver = "is31fl3731", // TODO: change this to your desired backlight driver, and implement the appropriate trait (info below)
driver_setup_fn = my_backlight_setup,
)
)]
struct MyKeyboard;

// Backlight configuration
use rumcake::lighting::simple_backlight_matrix::{SimpleBacklightMatrixDevice, SimpleBacklightMatrixDriver};
use rumcake::lighting::{BacklightMatrixDevice, setup_backlight_matrix};
struct MyKeyboardLighting;
use rumcake::lighting::simple_backlight_matrix::SimpleBacklightMatrixDevice;
async fn my_backlight_setup() -> impl SimpleBacklightMatrixDriver<MyKeyboardLighting> {
// TODO: We will fill this out soon!
todo!()
}
impl SimpleBacklightMatrixDevice for MyKeyboardLighting {
// optionally, set FPS
const FPS: usize = 20;
}

use rumcake::lighting::{BacklightMatrixDevice, setup_backlight_matrix};
impl BacklightMatrixDevice for MyKeyboardLighting {
setup_backlight_matrix! {
{ // LED layout
led_layout: {
[ (0,0) (17,0) (34,0) (51,0) (68,0) (85,0) (102,0) (119,0) (136,0) (153,0) (170,0) (187,0) (204,0) (221,0) (238,0) (255,0) ]
[ (4,17) (26,17) (43,17) (60,17) (77,17) (94,17) (111,17) (128,17) (145,17) (162,17) (178,17) (196,17) (213,17) (234,17) (255,17) ]
[ (6,34) (30,34) (47,34) (64,34) (81,34) (98,34) (115,34) (132,34) (149,34) (166,34) (183,34) (200,34) (227,34) (227,34) (255,34) ]
[ (11,51) (0,0) (38,51) (55,51) (72,51) (89,51) (106,51) (123,51) (140,51) (157,51) (174,51) (191,51) (208,51) (231,51) (255,51) ]
[ (28,68) (49,68) (79,68) (121,68) (155,68) (176,68) (196,68) (213,68) (230,68) ]
}
{ // LED flags (must have same number of rows and columns as the layout above)
},
led_flags: { // must have same number of rows and columns as the layout above
[ NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE ]
[ NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE ]
[ NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE ]
Expand All @@ -129,30 +148,38 @@ Note that for reactive effects, matrix positions will map directly to LED positi
a key at switch matrix position row 0, column 0, will correspond to the LED at row 0, column 0 on your LED matrix.
:::

Lastly, you must also implement the appropriate trait that corresponds to your chosen driver in the `#[keyboard]` macro.
Check the [list of available backlight drivers](#available-drivers) for this information.
Lastly, you must set up the driver. To do this, you need to complete your `driver_setup_fn` by constructing the driver.
You can [check the API reference for your chosen driver](/rumcake/api/nrf52840/rumcake/drivers/index.html) for a set up
function or macro to make this process easier.

For example, with `is31fl3731`, you must implement `IS31FL3731DriverSettings` and `IS31FL3731BacklightDriver`:
Depending on the driver, you may also need to implement the appropriate trait that corresponds to your chosen driver.
Check the [list of available backlight drivers](#available-drivers) for this information.

```rust ins={3-30}
// later in your file...
For example, with `is31fl3731`, you must implement `IS31FL3731BacklightDriver`, and you can use the `setup_is31fl3731!` macro to set up the driver:

```rust del={9-10} ins={3-5,11-23,25-34}
use rumcake::lighting::simple_backlight_matrix::{SimpleBacklightMatrixDevice, SimpleBacklightMatrixDriver};
use rumcake::lighting::{BacklightMatrixDevice, setup_backlight_matrix};
use rumcake::hw::platform::setup_i2c;
use rumcake::drivers::is31fl3731::{
get_led_from_matrix_coordinates, IS31FL3731BacklightDriver
get_led_from_matrix_coordinates, setup_is31fl3731, IS31FL3731BacklightDriver
};
// Note: The IS31FL3731DriverSettings trait does NOT come from the `rumcake` library. It is generated by the `keyboard` macro.
impl IS31FL3731DriverSettings for MyKeyboardLighting {
const LED_DRIVER_ADDR: u8 = 0b1110100; // see https://github.com/qmk/qmk_firmware/blob/d9fa80c0b0044bb951694aead215d72e4a51807c/docs/feature_rgb_matrix.md#is31fl3731-idis31fl3731

setup_i2c! { // Note: The arguments of setup_i2c may change depending on platform. This assumes STM32.
I2C1_EV, // Event interrupt
I2C1_ER, // Error interrupt
I2C1, // I2C peripheral
PB6, // SCL
PB7, // SDA
DMA1_CH7, // RX DMA Channel
DMA1_CH6 // TX DMA Channel
struct MyKeyboardLighting;
async fn my_backlight_setup() -> impl SimpleBacklightMatrixDriver<MyKeyboardLighting> {
// TODO: We will fill this out soon!
todo!()
setup_is31fl3731! {
device: MyKeyboardLighting, // Must be a type that implements IS31FL3731BacklightDriver
address: 0b1110100, // see https://github.com/qmk/qmk_firmware/blob/d9fa80c0b0044bb951694aead215d72e4a51807c/docs/feature_rgb_matrix.md#is31fl3731-idis31fl3731
i2c: setup_i2c! { // Note: The arguments of setup_i2c may change depending on platform. This assumes STM32.
event_interrupt: I2C1_EV,
error_interrupt: I2C1_ER,
i2c: I2C1,
scl: PB6,
sda: PB7,
rx_dma: DMA1_CH7,
tx_dma: DMA1_CH6,
}
}
}
impl IS31FL3731BacklightDriver for MyKeyboardLighting {
Expand All @@ -165,6 +192,10 @@ impl IS31FL3731BacklightDriver for MyKeyboardLighting {
[ C5_2 C5_3 C5_6 C5_7 C5_10 C5_11 C5_12 C5_13 C5_14 ]
}
}

impl SimpleBacklightMatrixDevice for MyKeyboardLighting { /* ... */ }
impl BacklightMatrixDevice for MyKeyboardLighting { /* ... */ }

```

:::note
Expand Down Expand Up @@ -238,9 +269,7 @@ impl KeyboardLayout for MyKeyboard {

# Available Drivers

| Name | Feature Flag | `keyboard` Macro Driver String | Required Traits |
| -------------- | ---------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IS31FL3731 | `is31fl3731` | `"is31fl3731"` | `IS31FL3731DriverSettings`[^1], [`IS31FL3731BacklightDriver`](/rumcake/api/nrf52840/rumcake/drivers/is31fl3731/backlight/trait.IS31FL3731BacklightDriver.html) |
| WS2812 Bitbang | `ws2812_bitbang` | `"ws2812_bitbang"` | `WS2812BitbangDriverSettings`[^1], [`WS2812BitbangBacklightDriver`](/rumcake/api/nrf52840/rumcake/drivers/ws2812_bitbang/backlight/trait.WS2812BitbangBacklightDriver.html) |

[^1]: This trait is generated by the `keyboard` macro, and not included in the `rumcake` API.
| Name | Feature Flag | Required Traits |
| -------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| IS31FL3731 | `is31fl3731` | [`IS31FL3731BacklightDriver`](/rumcake/api/nrf52840/rumcake/drivers/is31fl3731/backlight/trait.IS31FL3731BacklightDriver.html) |
| WS2812 Bitbang | `ws2812_bitbang` | [`WS2812BitbangBacklightDriver`](/rumcake/api/nrf52840/rumcake/drivers/ws2812_bitbang/backlight/trait.WS2812BitbangBacklightDriver.html) |
70 changes: 41 additions & 29 deletions docs/src/content/docs/features/feature-display.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,58 +18,71 @@ You must enable the following `rumcake` features:

## Required code

To set up your display, you must add `display(driver = "<driver>")` to your `#[keyboard]` macro invocation,
To set up your display, you must add `display(driver_setup_fn = <setup_fn>)` to your `#[keyboard]` macro invocation,
and your keyboard must implement the `DisplayDevice` trait.

```rust ins={5-7,11-17}
The `driver_setup_fn` must be an async function that has no parameters, and returns a type that implements the
[`DisplayDriver<T>`](/rumcake/api/nrf52840/rumcake/display/drivers/index.html) trait.

```rust ins={5-7,11-22}
use rumcake::keyboard;

#[keyboard(
// somewhere in your keyboard macro invocation ...
display(
driver = "ssd1306" // TODO: change this to your desired display driver, and implement the appropriate trait (info below)
driver_setup_fn = my_display_setup
)
)]
struct MyKeyboard;

// Display configuration
use rumcake::display::DisplayDevice;
use rumcake::display::driver::DisplayDriver;
async fn my_display_setup() -> impl DisplayDriver<MyKeyboard> {
// TODO: We will fill this out soon!
todo!()
}
impl DisplayDevice for MyKeyboard {
// Optional: set timeout and FPS
const FPS: usize = 0 // Only update the display when information changes. Change this if you are displaying animations.
const TIMEOUT: usize = 20
}
```

Lastly, you must also implement the appropriate trait that corresponds to your chosen driver in the `#[keyboard]` macro.
Check the [list of available display drivers](#available-drivers) for this information.
Lastly, you must set up the driver. To do this, you need to complete your `driver_setup_fn` by constructing the driver.
You can [check the API reference for your chosen driver](/rumcake/api/nrf52840/rumcake/drivers/index.html) for a set up
function or macro to make this process easier.

For example, with `ssd1306`, you must implement `Ssd1306I2cDriverSettings` and `Ssd1306I2cDisplayDriver`:
Depending on the driver, you may also need to implement the appropriate trait that corresponds to your chosen driver.
Check the [list of available display drivers](#available-drivers) for this information.

```rust ins={3-23}
// later in your file...
For example, with `ssd1306`, you must implement `Ssd1306I2cDisplayDriver`, and you can use the `setup_ssd1306!` macro to set up the driver:

use rumcake::hw::platform::setup_i2c_blocking;
use rumcake::drivers::ssd1306::driver::size::DisplaySize128x32;
```rust del={6-7} ins={3-4,8-21,23}
use rumcake::display::DisplayDevice;
use rumcake::display::driver::DisplayDriver;
use rumcake::drivers::ssd1306::setup_ssd1306;
use rumcake::drivers::ssd1306::display::Ssd1306I2cDisplayDriver;
// Note: The Ssd1306I2cDriverSettings trait does NOT come from the `rumcake` library. It is generated by the `keyboard` macro.
impl Ssd1306I2cDriverSettings for MyKeyboard {
// Set size of the display
type SIZE_TYPE = DisplaySize128x32;
const SIZE: Self::SIZE_TYPE = DisplaySize128x32;

// Optional: set rotation
const ROTATION: DisplayRotation = DisplayRotation::Rotate90;

// Set up the I2C peripheral to communicate with the SSD1306 screen
setup_i2c_blocking! {
SPIM0_SPIS0_TWIM0_TWIS0_SPI0_TWI0,
TWISPI0,
P0_17,
P0_20
async fn my_display_setup() -> impl DisplayDriver<MyKeyboard> {
// TODO: We will fill this out soon!
todo!()
setup_ssd1306! {
i2c: setup_i2c! { // Note: The arguments of setup_i2c may change depending on platform. This assumes STM32.
event_interrupt: I2C1_EV,
error_interrupt: I2C1_ER,
i2c: I2C1,
scl: PB6,
sda: PB7,
rx_dma: DMA1_CH7,
tx_dma: DMA1_CH6,
},
// See the API reference for the ssd1306 crate for `size` and `rotation` values: https://docs.rs/ssd1306/latest/ssd1306/
size: DisplaySize96x16,
rotation: Rotate90,
}
}
impl Ssd1306I2cDisplayDriver for MyKeyboard {}
impl DisplayDevice for MyKeyboard { /* ... */ }
```

# Custom graphics
Expand Down Expand Up @@ -128,9 +141,8 @@ impl Ssd1306I2cDisplayDriver for MyKeyboard {

# Available Drivers

| Name | Feature Flag | `keyboard` Macro Driver String | Required Traits |
| ----------- | ------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| SSD1306[^1] | `ssd1306` | `"ssd1306"` | `Ssd1306I2cDriverSettings`[^2], [`Ssd1306I2cDisplayDriver`](/rumcake/api/nrf52840/rumcake/drivers/ssd1306/display/trait.Ssd1306I2cDisplayDriver.html) |
| Name | Feature Flag | Required Traits |
| ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| SSD1306[^1] | `ssd1306` | [`Ssd1306I2cDisplayDriver`](/rumcake/api/nrf52840/rumcake/drivers/ssd1306/display/trait.Ssd1306I2cDisplayDriver.html) |

[^1]: I2C only
[^2]: This trait is generated by the `keyboard` macro, and not included in the `rumcake` API.
Loading

0 comments on commit f6566f2

Please sign in to comment.