diff options
Diffstat (limited to 'docs/drivers')
-rw-r--r-- | docs/drivers/aw20216s.md | 2 | ||||
-rw-r--r-- | docs/drivers/battery.md | 73 | ||||
-rw-r--r-- | docs/drivers/spi.md | 2 | ||||
-rw-r--r-- | docs/drivers/ws2812.md | 20 |
4 files changed, 90 insertions, 7 deletions
diff --git a/docs/drivers/aw20216s.md b/docs/drivers/aw20216s.md index 36a6d63c33..042c8df129 100644 --- a/docs/drivers/aw20216s.md +++ b/docs/drivers/aw20216s.md @@ -2,7 +2,7 @@ SPI 18x12 LED matrix driver by Awinic. Supports a maximum of four drivers, each controlling up to 216 single-color LEDs, or 72 RGB LEDs. -[AW20216S Datasheet](https://doc.awinic.com/doc/20230609wm/b6a9c70b-e1bd-495b-925f-bcbed3fc2620.pdf) +[AW20216S Datasheet](https://doc.awinic.com/doc/202412/a055779b-49c0-4d09-8f04-73029f44b72b.pdf) ## Usage {#usage} diff --git a/docs/drivers/battery.md b/docs/drivers/battery.md new file mode 100644 index 0000000000..e482ffc8b6 --- /dev/null +++ b/docs/drivers/battery.md @@ -0,0 +1,73 @@ +# Battery Driver + +This driver provides support for sampling battery level. + +## Usage + +To use this driver, add the following to your `rules.mk`: + +```make +BATTERY_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|--------------------------|--------|--------------------------------------------------| +|`BATTERY_SAMPLE_INTERVAL` |`30000` |The time between battery samples in milliseconds. | + +## Driver Configuration {#driver-configuration} + +Driver selection can be configured in `rules.mk` as `BATTERY_DRIVER`. Valid values are `adc` (default), `vendor`, or `custom`. See below for information on individual drivers. + +### ADC Driver {#adc-driver} + +This is the default battery driver. The default configuration assumes the battery is connected to a ADC capable pin through a voltage divider. + +```make +BATTERY_DRIVER = adc +``` + +The following `#define`s apply only to the `adc` driver: + +|Define |Default |Description | +|-----------------------------|--------------|--------------------------------------------------------------| +|`BATTERY_PIN` |*Not defined* |The GPIO pin connected to the voltage divider. | +|`BATTERY_REF_VOLTAGE_MV` |`3300` |The ADC reverence voltage, in millivolts. | +|`BATTERY_VOLTAGE_DIVIDER_R1` |`100` |The voltage divider resistance, in kOhm. Set to 0 to disable. | +|`BATTERY_VOLTAGE_DIVIDER_R2` |`100` |The voltage divider resistance, in kOhm. Set to 0 to disable. | +|`BATTERY_ADC_RESOLUTION` |`10` |The ADC resolution configured for the ADC Driver. | + +## Functions + +### `uint8_t battery_get_percent(void)` {#api-battery-get-percent} + +Sample battery level. + +#### Return Value {#api-battery-get-percent-return} + +The battery percentage, in the range 0-100. + +## Callbacks + +### `void battery_percent_changed_user(uint8_t level)` {#api-battery-percent-changed-user} + +User hook called when battery level changed. + +### Arguments {#api-battery-percent-changed-user-arguments} + + - `uint8_t level` + The battery percentage, in the range 0-100. + +--- + +### `void battery_percent_changed_kb(uint8_t level)` {#api-battery-percent-changed-kb} + +Keyboard hook called when battery level changed. + +### Arguments {#api-battery-percent-changed-kb-arguments} + + - `uint8_t level` + The battery percentage, in the range 0-100. diff --git a/docs/drivers/spi.md b/docs/drivers/spi.md index 140b204945..56b294ad3a 100644 --- a/docs/drivers/spi.md +++ b/docs/drivers/spi.md @@ -39,8 +39,6 @@ To enable SPI, modify your board's `halconf.h` to enable SPI, then modify your b #pragma once #define HAL_USE_SPI TRUE // [!code focus] -#define SPI_USE_WAIT TRUE // [!code focus] -#define SPI_SELECT_MODE SPI_SELECT_MODE_PAD // [!code focus] #include_next <halconf.h> ``` diff --git a/docs/drivers/ws2812.md b/docs/drivers/ws2812.md index 4d1e727928..0c26ec6248 100644 --- a/docs/drivers/ws2812.md +++ b/docs/drivers/ws2812.md @@ -144,18 +144,30 @@ The following defines apply only to ARM devices: |`WS2812_T1L`|`(WS2812_TIMING - WS2812_T1H)`|The length of a "1" bit's low phase in nanoseconds (bitbang and PIO drivers only)| |`WS2812_T0L`|`(WS2812_TIMING - WS2812_T0H)`|The length of a "0" bit's low phase in nanoseconds (bitbang and PIO drivers only)| -### Push-Pull and Open Drain {#push-pull-open-drain} +### Logic Levels {#logic-levels} -By default, the GPIO used for data transmission is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground. +WS2812 LEDs usually operate at 5V, but some microcontrollers, particularly ARM-based ones, run on 3.3V. This can pose an issue when driving the LED chain as the logic level voltage is lower than the power supply voltage, leading to unreliable data transmission. There are two main workarounds: -For situations where the logic level voltage is lower than the power supply voltage, however, this can pose an issue. The solution is to configure the pin for *open drain* mode instead, and use a pullup resistor between the DI pin and VCC. In this mode, the MCU can only pull the GPIO *low*, or leave it floating. The pullup resistor is then responsible for pulling the line high, when the MCU is not driving the GPIO. +#### 1. Open Drain Circuit {#open-drain-circuit} -To configure the DI pin for open drain configuration, add the following to your `config.h`: +By default, `WS2812_DI_PIN` is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground; however, it can be configured in *open drain* mode instead. + +In this mode, the MCU will only pull the GPIO *low*, and leaves it floating otherwise. A pullup resistor (typically around 10kΩ) between DI and 5V is then responsible for pulling the line high when the MCU is not driving the GPIO. + +To use the DI pin in open drain configuration, add the following to your `config.h`: ```c #define WS2812_EXTERNAL_PULLUP ``` +::: warning +Because the GPIO is being pulled to 5V in this situation rather than VCC (3.3V), **it must be a 5V tolerant pin**. Consult your MCU's datasheet first – if there are no eligible pins, you must use a level shifter instead. +::: + +#### 2. Level Shifter {#level-shifter} + +A level shifter IC, such as the SN74LV1T34, can be placed between the GPIO and the first LED's DI pin to convert the 3.3V logic to 5V. This requires no additional configuration in the firmware, nor a 5V tolerant GPIO, but may be more expensive and is generally less handwire-friendly. + ### SPI Driver {#arm-spi-driver} Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like: |