Merge remote-tracking branch 'origin/master' into develop

1 files changed, 16 insertions, 4 deletions

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: