Document hardware, pinout and I2C devices in a header comment of every device

Merge the old pinout comment blocks into the header and mark what each pin is used for.

mcu-apollo-dev.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: Apollo Automation ESK-1 ESPHome Starter Kit
+# Pinout:
+#   GPIO0                              -> i2c_1 (i2c scl)
+#   GPIO1                              -> i2c_1 (i2c sda)
+#   GPIO4                              -> Accessory Power (switch gpio)
+#   GPIO5                              -> Onboard RGB LED (light esp32_rmt_led_strip)
+#   GPIO14                             -> RGB LEDs (light esp32_rmt_led_strip)
+#   GPIO18                             -> buzzer_output (output ledc)
+# I2C:
+#   0x38  aht20 (sensor aht10)
 substitutions:
   device: apollo-dev #test
   name: Apollo DEV #test

mcu-atoms3.yaml

@@ -1,4 +1,23 @@
 ---
+# Hardware: M5Stack AtomS3
+# Pinout:
+#   GPIO1   Grove SCL                  -> motor_in1 (output gpio)
+#   GPIO2   Grove SDA                  -> motor_in2 (output gpio)
+#   GPIO5                              -> canbus/esp32_can (canbus esp32_can tx_pin)
+#   GPIO6                              -> canbus/esp32_can (canbus esp32_can rx_pin)
+#   GPIO15                             -> display_tft (display mipi_spi cs_pin)
+#   GPIO16                             -> gpio_tft_backlight (output ledc)
+#   GPIO17                             -> spi (spi clk_pin)
+#   GPIO21                             -> spi (spi mosi_pin)
+#   GPIO33                             -> display_tft (display mipi_spi dc_pin)
+#   GPIO34                             -> display_tft (display mipi_spi reset_pin)
+#   GPIO38                             -> i2c_main (i2c sda)
+#   GPIO39                             -> i2c_main (i2c scl)
+#   GPIO41                             -> Button (binary_sensor gpio) (inverted)
+# I2C:
+#   0x21  pcf8574_hub (pcf8574)
+#   0x26  m5stack_relay_1 (m5stack_4relay)
+#   0x3C  lcd (display ssd1306_i2c)
 substitutions:
   device: atoms3
   name: AtomS3

mcu-basement-2.yaml

@@ -1,4 +1,12 @@
 ---
+# Hardware: Sonoff Dual R2
+# Pinout:
+#   GPIO0   Pin "button 0" on expansion header
+#   GPIO5   Relay #2 and green color on LED -> relay_2 (output gpio)
+#   GPIO9   Pin "button 1" on expansion header
+#   GPIO10  Push Button
+#   GPIO12  Relay #1 and red color on LED -> relay_1 (output gpio)
+#   GPIO13  Blue Status LED            -> status_led (status_led) (inverted)
 substitutions:
   device: basement-2
   name_short: Basement
@@ -18,14 +26,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-# Sonoff Dual R2
-# GPIO10	Push Button
-# GPIO00	Pin "button 0" on expansion header
-# GPIO09	Pin "button 1" on expansion header
-# GPIO12	Relay #1 and red color on LED
-# GPIO05	Relay #2 and green color on LED
-# GPIO13	Blue Status LED
-
 status_led:
   pin:
     number: 13

mcu-basement.yaml

@@ -1,4 +1,12 @@
 ---
+# Hardware: Sonoff Dual R2
+# Pinout:
+#   GPIO0   Pin "button 0" on expansion header -> Light Switch (binary_sensor gpio) (inverted)
+#   GPIO5   Relay #2 and green color on LED -> Socket 1 (switch gpio)
+#   GPIO9   Pin "button 1" on expansion header -> Door (binary_sensor gpio) (inverted)
+#   GPIO10  Push Button                -> Socket 1 Switch (binary_sensor gpio) (inverted)
+#   GPIO12  Relay #1 and red color on LED -> Sewage Treatment Aerator Pump [relay_1] (switch gpio)
+#   GPIO13  Blue Status LED            -> status_led (status_led) (inverted)
 substitutions:
   device: basement
   name: Basement
@@ -17,15 +25,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-# Sonoff Dual R2
-# Pin 	  Function
-# GPIO10	Push Button
-# GPIO00	Pin "button 0" on expansion header
-# GPIO09	Pin "button 1" on expansion header
-# GPIO12	Relay #1 and red color on LED
-# GPIO05	Relay #2 and green color on LED
-# GPIO13	Blue Status LED
-
 globals:
   - id: aerator_auto
     type: bool

mcu-bedroom-lamp-left.yaml

@@ -1,4 +1,23 @@
 ---
+# Hardware: Xiaomi Mi Bedside Lamp 2 (ESP-WROOM-32D, single core; RGBW LEDs)
+# Pinout (github.com/mmakaay/esphome-xiaomi_bslamp2, doc/technical_details.md):
+#   GPIO1   Debug pad TX
+#   GPIO2   Debug pad, free I/O
+#   GPIO3   Debug pad RX
+#   GPIO4   LEDs master switch 2
+#   GPIO5   LEDs blue PWM
+#   GPIO12  LEDs white PWM
+#   GPIO13  LEDs red PWM
+#   GPIO14  LEDs green PWM
+#   GPIO16  Front panel interrupt
+#   GPIO17  EEPROM I2C SDA
+#   GPIO18  EEPROM I2C SCL
+#   GPIO19  Front panel I2C SCL        -> front_panel_i2c (i2c scl)
+#   GPIO21  Front panel I2C SDA        -> front_panel_i2c (i2c sda)
+#   GPIO33  LEDs master switch 1
+# I2C:
+#   0x10  EEPROM-like IC on its own bus (GPIO17/18), not configured
+#   0x2C  Front panel
 substitutions:
   device: bedroom-lamp-left
   name: Bedroom Lamp Left
@@ -33,14 +52,6 @@ external_components:
 packages:
   common: !include common/common.yaml
 
-# Mi Desk Lamp
-# Pin 	  Function (Name)
-# GPIO02: Button (GPIO_KEY1)
-# GPIO04: Cold White (GPIO_PWM1)
-# GPIO05: Warm White (GPIO_PWM2)
-# GPIO12: Rotary switch A pin (GPIO_ROT_A)
-# GPIO13: Rotary switch B pin (GPIO_ROT_B)
-
 # ------------------------------------------------------------------------
 # Behavior: default
 #

mcu-bedroom-lamp-right.yaml

@@ -1,4 +1,23 @@
 ---
+# Hardware: Xiaomi Mi Bedside Lamp 2 (ESP-WROOM-32D, single core; RGBW LEDs)
+# Pinout (github.com/mmakaay/esphome-xiaomi_bslamp2, doc/technical_details.md):
+#   GPIO1   Debug pad TX
+#   GPIO2   Debug pad, free I/O
+#   GPIO3   Debug pad RX
+#   GPIO4   LEDs master switch 2
+#   GPIO5   LEDs blue PWM
+#   GPIO12  LEDs white PWM
+#   GPIO13  LEDs red PWM
+#   GPIO14  LEDs green PWM
+#   GPIO16  Front panel interrupt
+#   GPIO17  EEPROM I2C SDA
+#   GPIO18  EEPROM I2C SCL
+#   GPIO19  Front panel I2C SCL        -> front_panel_i2c (i2c scl)
+#   GPIO21  Front panel I2C SDA        -> front_panel_i2c (i2c sda)
+#   GPIO33  LEDs master switch 1
+# I2C:
+#   0x10  EEPROM-like IC on its own bus (GPIO17/18), not configured
+#   0x2C  Front panel
 substitutions:
   device: bedroom-lamp-right
   name: Bedroom Lamp Right
@@ -33,14 +52,6 @@ external_components:
 packages:
   common: !include common/common.yaml
 
-# Mi Desk Lamp
-# Pin 	  Function (Name)
-# GPIO02: Button (GPIO_KEY1)
-# GPIO04: Cold White (GPIO_PWM1)
-# GPIO05: Warm White (GPIO_PWM2)
-# GPIO12: Rotary switch A pin (GPIO_ROT_A)
-# GPIO13: Rotary switch B pin (GPIO_ROT_B)
-
 # ------------------------------------------------------------------------
 # Behavior: default
 #

mcu-c6-test-1.yaml

@@ -1,4 +1,7 @@
 ---
+# Hardware: Espressif ESP32-C6-DevKitC-1
+# Pinout:
+#   GPIO8                              -> LED (light esp32_rmt_led_strip)
 substitutions:
   device: c6-test-1
   name: C6 TEST 1

mcu-c6-test-2.yaml

@@ -1,4 +1,7 @@
 ---
+# Hardware: Espressif ESP32-C6-DevKitC-1
+# Pinout:
+#   GPIO8                              -> LED (light esp32_rmt_led_strip)
 substitutions:
   device: c6-test-2
   name: C6 TEST 2

mcu-cam-1.yaml

@@ -1,4 +1,21 @@
 ---
+# Hardware: ESP32-CAM (AI-Thinker style, runs hot)
+# Pinout:
+#   GPIO0                              -> Camera (esp32_camera)
+#   GPIO5                              -> Camera (esp32_camera data_pins)
+#   GPIO18                             -> Camera (esp32_camera data_pins)
+#   GPIO19                             -> Camera (esp32_camera data_pins)
+#   GPIO21                             -> Camera (esp32_camera data_pins)
+#   GPIO22                             -> Camera (esp32_camera pixel_clock_pin)
+#   GPIO23                             -> Camera (esp32_camera href_pin)
+#   GPIO25                             -> Camera (esp32_camera vsync_pin)
+#   GPIO26                             -> i2c_bus (i2c sda)
+#   GPIO27                             -> i2c_bus (i2c scl)
+#   GPIO32                             -> Enable (switch gpio)
+#   GPIO34                             -> Camera (esp32_camera data_pins)
+#   GPIO35                             -> Camera (esp32_camera data_pins)
+#   GPIO36                             -> Camera (esp32_camera data_pins)
+#   GPIO39                             -> Camera (esp32_camera data_pins)
 substitutions:
   device: cam-1
   name: Cam 1

mcu-can-node-1.yaml

@@ -1,4 +1,10 @@
 ---
+# Hardware: ESP32 DevKit
+# Pinout:
+#   GPIO0                              -> Boot (binary_sensor gpio) (inverted)
+#   GPIO2                              -> LED (switch gpio)
+#   GPIO22                             -> can_bus (canbus esp32_can rx_pin)
+#   GPIO23                             -> can_bus (canbus esp32_can tx_pin)
 substitutions:
   device: can-node-1
   name: CAN Node 1

mcu-can-node-2.yaml

@@ -1,4 +1,13 @@
 ---
+# Hardware: ESP32 DevKit
+# Pinout:
+#   GPIO17                             -> i2c (i2c sda)
+#   GPIO18                             -> i2c (i2c scl)
+#   GPIO19                             -> as3935_i2c (as3935_i2c irq_pin)
+#   GPIO22                             -> can_bus (canbus esp32_can rx_pin)
+#   GPIO23                             -> can_bus (canbus esp32_can tx_pin)
+# I2C:
+#   0x03  as3935_i2c (as3935_i2c)
 substitutions:
   device: can-node-2
   name: CAN Node 2

mcu-cec-bedroom.yaml

@@ -1,4 +1,13 @@
 ---
+# Hardware: M5Stack M5Stamp Pico
+# Pinout:
+#   GPIO22                             -> uart_distance (uart rx_pin)
+#   GPIO25                             -> uart_distance (uart tx_pin)
+#   GPIO26                             -> hdmi_cec (hdmi_cec)
+#   GPIO27                             -> LED (light esp32_rmt_led_strip)
+#   GPIO32  Grove SDA                  -> i2c (i2c sda)
+#   GPIO33  Grove SCL                  -> i2c (i2c scl)
+#   GPIO39                             -> Bedroom TV Button (binary_sensor gpio) (inverted)
 substitutions:
   device: cec-bedroom
   name: Bedroom TV

mcu-clock-1.yaml

@@ -1,4 +1,18 @@
 ---
+# Hardware: M5Stack M5Stamp C3
+# Pinout:
+#   GPIO0   I2C SCL
+#   GPIO1   I2C SDA, BUTTON
+#   GPIO2   RGB
+#   GPIO4   DISPLAY CLOCK              -> tm1637_display (display tm1637 clk_pin)
+#   GPIO5   DISPLAY DIO                -> tm1637_display (display tm1637 dio_pin)
+#   GPIO6   GPIO
+#   GPIO7   GPIO
+#   GPIO8   GPIO
+#   GPIO9   GPIO (BUZZER?)             -> rtttl_out (output ledc)
+#   GPIO10  GPIO
+#   GPIO20  UART RX
+#   GPIO21  UART TX
 substitutions:
   device: clock-1
   name: Clock 1
@@ -25,21 +39,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# GPIO21  UART TX
-# GPIO20  UART RX
-# GPIO0   I2C SCL
-# GPIO1   I2C SDA
-# GPIO2   RGB
-# GPIO1   BUTTON
-# GPIO4   DISPLAY CLOCK
-# GPIO5   DISPLAY DIO
-# GPIO6   GPIO
-# GPIO7   GPIO
-# GPIO8   GPIO
-# GPIO10   GPIO
-#
-# GPIO9   GPIO (BUZZER?)
-
 # https://github.com/granadaxronos/120-SONG_NOKIA_RTTTL_RINGTONE_PLAYER_FOR_ARDUINO_UNO/blob/master/RTTTL_PLAYER/songs.h
 api:
   actions:

mcu-clock-living-room.yaml

@@ -1,4 +1,13 @@
 ---
+# Hardware: M5Stack M5Stamp Pico
+# Pinout:
+#   GPIO25                             -> rtttl_out (output ledc)
+#   GPIO27                             -> LED (light esp32_rmt_led_strip)
+#   GPIO32  Grove SDA                  -> i2c_main (i2c sda)
+#   GPIO33  Grove SCL                  -> i2c_main (i2c scl)
+#   GPIO39                             -> Button (binary_sensor gpio) (inverted)
+# I2C:
+#   0x24  tm1650_display (display tm1650)
 substitutions:
   device: clock-living-room
   name: Living room Clock

mcu-desk-lamp.yaml

@@ -1,4 +1,11 @@
 ---
+# Hardware: Xiaomi Mi Desk Lamp, brain transplant: M5Stack M5Stamp Pico (originally ESP8266)
+# Pinout:
+#   GPIO18  Warm White (GPIO_PWM2)     -> warm_white (output ledc)
+#   GPIO19  Cold White (GPIO_PWM1)     -> cold_white (output ledc)
+#   GPIO21  Rotary switch A pin (GPIO_ROT_A) -> rotary (sensor rotary_encoder pin_a)
+#   GPIO26  Rotary switch B pin (GPIO_ROT_B) -> rotary (sensor rotary_encoder pin_b)
+#   GPIO36  Button (GPIO_KEY1)         -> rotary_button (binary_sensor gpio) (inverted)
 substitutions:
   device: desk-lamp
   name: Desk Lamp
@@ -21,14 +28,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# Mi Desk Lamp
-# Pin 	  Function (Name)
-# GPIO18: Warm White (GPIO_PWM2)
-# GPIO19: Cold White (GPIO_PWM1)
-# GPIO21: Rotary switch A pin (GPIO_ROT_A)
-# GPIO26: Rotary switch B pin (GPIO_ROT_B)
-# GPIO36: Button (GPIO_KEY1)
-
 
 binary_sensor:
   - platform: gpio

mcu-dimmer.yaml

@@ -1,4 +1,11 @@
 ---
+# Hardware: M5Stack M5Stamp Pico
+# Pinout:
+#   GPIO22                             -> dimmer1 (output ac_dimmer gate_pin)
+#   GPIO25                             -> dimmer1 (output ac_dimmer zero_cross_pin) (inverted)
+#   GPIO27                             -> LED (light esp32_rmt_led_strip)
+#   GPIO32  Grove SDA
+#   GPIO33  Grove SCL
 substitutions:
   device: dimmer
   name: Dimmer

mcu-echo-1.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: M5Stack ATOM Echo
+# Pinout:
+#   GPIO19                             -> speaker_bus (i2s_audio i2s_bclk_pin)
+#   GPIO22                             -> speaker_id (speaker i2s_audio i2s_dout_pin)
+#   GPIO23                             -> echo_microphone (microphone i2s_audio i2s_din_pin)
+#   GPIO26  Grove SDA
+#   GPIO27                             -> LED (light esp32_rmt_led_strip)
+#   GPIO32  Grove SCL
+#   GPIO33                             -> speaker_bus (i2s_audio i2s_lrclk_pin)
+#   GPIO39                             -> Button (binary_sensor gpio) (inverted)
 substitutions:
   device: echo-1
   name: Echo 1

mcu-echo.yaml

@@ -1,4 +1,15 @@
 ---
+# Hardware: M5Stack ATOM Echo
+# Pinout:
+#   GPIO12                             -> Button (binary_sensor gpio) (inverted)
+#   GPIO19                             -> speaker_bus (i2s_audio i2s_bclk_pin)
+#   GPIO21                             -> led_red (output ledc)
+#   GPIO22                             -> speaker_id (speaker i2s_audio i2s_dout_pin)
+#   GPIO23                             -> led_status (light status_led); led_blue (output ledc)
+#   GPIO25                             -> led_green (output ledc)
+#   GPIO26  Grove SDA                  -> i2c (i2c sda)
+#   GPIO32  Grove SCL                  -> i2c (i2c scl)
+#   GPIO33                             -> speaker_bus (i2s_audio i2s_lrclk_pin)
 substitutions:
   device: echo
   name: Echo

mcu-eworkbench.yaml

@@ -1,4 +1,22 @@
 ---
+# Hardware: M5Stack M5Stamp C3
+# Pinout:
+#   GPIO0   I2C SCL                    -> i2c_grove (i2c scl)
+#   GPIO1   I2C SDA, BUTTON            -> i2c_grove (i2c sda)
+#   GPIO2   RGB
+#   GPIO4   GPIO
+#   GPIO5   GPIO
+#   GPIO6   GPIO
+#   GPIO7   GPIO
+#   GPIO8   GPIO
+#   GPIO9   GPIO
+#   GPIO10  GPIO
+#   GPIO18  UART RX                    -> uart_hdmi_switch (uart rx_pin)
+#   GPIO19  UART TX                    -> uart_hdmi_switch (uart tx_pin)
+#   GPIO20  UART RX, LOGGER            -> uart_log (uart rx_pin)
+#   GPIO21  UART TX, LOGGER            -> uart_log (uart tx_pin)
+# I2C:
+#   0x20  pcf8574_hub (pcf8574)
 substitutions:
   device: eworkbench
   name: Electronics Workbench
@@ -22,23 +40,6 @@ esp32:
 packages:
   common: !include common/common.yaml
 
-# GPIO20  UART RX, LOGGER
-# GPIO21  UART TX, LOGGER
-# GPIO9   GPIO
-#
-# GPIO0   I2C SCL
-# GPIO1   I2C SDA
-# GPIO2   RGB
-# GPIO1   BUTTON
-# GPIO4   GPIO
-# GPIO5   GPIO
-# GPIO6   GPIO
-# GPIO7   GPIO
-# GPIO8   GPIO
-# GPIO10   GPIO
-# GPIO18   UART RX
-# GPIO19   UART TX
-
 i2c:
   - id: i2c_grove
     sda: 1

mcu-fireplace.yaml

@@ -1,4 +1,22 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO1   UART0 TX
+#   GPIO3   UART0 RX
+#   GPIO12  IR
+#   GPIO19  Relay2
+#   GPIO21  I2C1 SCL                   -> i2c (i2c scl)
+#   GPIO22  Relay1
+#   GPIO23  RS485 Tx
+#   GPIO25  I2C1 SDA - red             -> i2c (i2c sda)
+#   GPIO26  I2C0 SDA - white
+#   GPIO27  NEO 1x
+#   GPIO32  I2C0 SCL
+#   GPIO33  RS485 Rx
+#   GPIO39  BUTTON                     -> Status Button (binary_sensor gpio)
+# I2C:
+#   0x18  one_wire_bus (one_wire ds2482)
+#   0x27  pca9554_module (pca9554)
 substitutions:
   device: fireplace
   name: Heating Fireplace
@@ -30,21 +48,6 @@ packages:
   ipv6_only: !include common/ipv6_only.yaml
 
 
-# PINOUTS: M5ATOM+Atom Hub Switch
-# IR        G12
-# NEO       G27 1x
-# BUTTON    G39
-# I2C0 SDA  G26 - white
-# I2C0 SCL  G32
-# I2C1 SDA  G25 - red
-# I2C1 SCL  G21
-# UART0 RX  G3
-# UART0 TX  G1
-# RS485 Rx  G33
-# RS485 Tx  G23
-# Relay1    G22
-# Relay2    G19
-
 i2c:
   # - id: i2c0
   #   sda: 26

mcu-gate.yaml

@@ -1,4 +1,19 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO1   UART0 TX
+#   GPIO3   UART0 RX
+#   GPIO12  IR
+#   GPIO19  RELAY-2                    -> relay_2 (output gpio)
+#   GPIO21  I2C1 SCL
+#   GPIO22  RELAY-1                    -> relay_1 (output gpio)
+#   GPIO23  RS485 TX
+#   GPIO25  I2C1 SDA red
+#   GPIO26  I2C0 SDA white
+#   GPIO27  NEO
+#   GPIO32  I2C0 SCL                   -> gate_ogi_state (binary_sensor gpio) (inverted); gate_ogi_blink (binary_sensor gpio) (inverted)
+#   GPIO33  RS485 RX
+#   GPIO39  BUTTON
 substitutions:
   device: gate
   name: Gate
@@ -21,21 +36,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# PINOUTS: M5ATOM
-# IR        G12
-# NEO       G27
-# BUTTON    G39
-# I2C0 SDA  G26 white
-# I2C0 SCL  G32
-# I2C1 SDA  G25 red
-# I2C1 SCL  G21
-# UART0 RX  G3
-# UART0 TX  G1
-# RS485 RX  G33
-# RS485 TX  G23
-# RELAY-1   G22
-# RELAY-2   G19
-
 button:
   - platform: output
     name: Open

mcu-gateway.yaml

@@ -1,4 +1,31 @@
 ---
+# Hardware: Olimex ESP32-POE-ISO
+# Pinout:
+#   # UEXT
+#       3V3    1 2   GND
+#     GPIO4    3 4   GPIO36  U1TXD/U1RXD
+#    GPIO16    5 6   GPIO13  I2C-SCL/I2C-SDA
+#    GPIO15    7 8   GPIO2   HS2_CMD/HS2_DATA0
+#    GPIO14    9 10  GPIO5   HS2_CLK/SPI_CS
+#
+#    SD/MMC; shared with UEXT, no CS!!!
+#    GPIO15  HS2_CMD
+#    GPIO14  HS2_CLK
+#    GPIO2   HS2_DATA0
+#
+#    GPIO34  BUT1
+#    GPIO35  Battery Measurment ADC
+#    GPIO39  Ext Power Sense ADC
+# Used:
+#   GPIO4   uart_modbus (uart tx_pin)
+#   GPIO12  ethernet (ethernet power_pin)
+#   GPIO13  i2c (i2c sda)
+#   GPIO16  i2c (i2c scl)
+#   GPIO17  ethernet (ethernet)
+#   GPIO18  ethernet (ethernet mdio_pin)
+#   GPIO23  ethernet (ethernet mdc_pin)
+#   GPIO34  user_button (binary_sensor gpio) (inverted)
+#   GPIO36  uart_modbus (uart rx_pin)
 substitutions:
   device: gateway
   name: Gateway
@@ -33,22 +60,6 @@ packages:
   # common: !include common/common.yaml
   common_eth: !include common/common_eth.yaml
 
-## UEXT
-#    3V3    1 2   GND
-#  GPIO4    3 4   GPIO36  U1TXD/U1RXD
-# GPIO16    5 6   GPIO13  I2C-SCL/I2C-SDA
-# GPIO15    7 8   GPIO2   HS2_CMD/HS2_DATA0
-# GPIO14    9 10  GPIO5   HS2_CLK/SPI_CS
-#
-# SD/MMC; shared with UEXT, no CS!!!
-# GPIO15  HS2_CMD
-# GPIO14  HS2_CLK
-# GPIO2   HS2_DATA0
-
-# GPIO34  BUT1
-# GPIO35  Battery Measurment ADC
-# GPIO39  Ext Power Sense ADC
-
 i2c:
   sda: 13
   scl: 16

mcu-heater.yaml

@@ -1,4 +1,22 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO1   UART0 TX
+#   GPIO3   UART0 RX
+#   GPIO12  IR
+#   GPIO19  NC                         -> Demand [heating_demand] (switch gpio)
+#   GPIO21  I2C1 SCL                   -> i2c (i2c scl)
+#   GPIO22  1-WIRE                     -> Demand [hot_water_demand] (switch gpio)
+#   GPIO23  UART1 RX                   -> uart_modbus (uart rx_pin)
+#   GPIO25  I2C1 SDA                   -> i2c (i2c sda)
+#   GPIO26  I2C0 SDA
+#   GPIO27  NEO
+#   GPIO32  I2C0 SCL
+#   GPIO33  UART1 TX                   -> uart_modbus (uart tx_pin)
+#   GPIO39  BUTTON
+# I2C:
+#   0x18  one_wire_bus (one_wire ds2482)
+#   0x27  pca9554_module (pca9554)
 substitutions:
   device: heater
   name: Heater
@@ -39,21 +57,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# PINOUTS: M5ATOM
-# IR        G12
-# NEO       G27
-# BUTTON    G39
-# I2C0 SDA  G26
-# I2C0 SCL  G32
-# I2C1 SDA  G25
-# I2C1 SCL  G21
-# UART0 RX  G3
-# UART0 TX  G1
-# UART1 RX  G23
-# UART1 TX  G33
-# 1-WIRE    G22
-# NC        G19
-
 #logger:
 #  level: VERBOSE
 #  logs:

mcu-kitchen.yaml

@@ -1,4 +1,21 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO1   UART0 TX
+#   GPIO3   UART0 RX
+#   GPIO12  IR
+#   GPIO19  Relay2
+#   GPIO21  I2C1 SCL                   -> i2c (i2c scl)
+#   GPIO22  Relay1                     -> power_supply1 (power_supply)
+#   GPIO23  RS485 Tx
+#   GPIO25  I2C1 SDA - red             -> i2c (i2c sda)
+#   GPIO26  I2C0 SDA - white
+#   GPIO27  NEO 1x
+#   GPIO32  I2C0 SCL
+#   GPIO33  RS485 Rx
+#   GPIO39  BUTTON                     -> Status Button (binary_sensor gpio)
+# I2C:
+#   0x40  pca9685_hub1 (pca9685)
 substitutions:
   device: kitchen
   name: Kitchen
@@ -41,21 +58,6 @@ packages:
 api:
   reboot_timeout: 300s
 
-# PINOUTS: M5ATOM+Atom Hub Switch
-# IR        G12
-# NEO       G27 1x
-# BUTTON    G39
-# I2C0 SDA  G26 - white
-# I2C0 SCL  G32
-# I2C1 SDA  G25 - red
-# I2C1 SCL  G21
-# UART0 RX  G3
-# UART0 TX  G1
-# RS485 Rx  G33
-# RS485 Tx  G23
-# Relay1    G22
-# Relay2    G19
-
 i2c:
   # - id: i2c0
   #   sda: 26

mcu-lightening.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: M5Stack M5Stamp Pico
+# Pinout:
+#   GPIO22                             -> i2c (i2c scl)
+#   GPIO25                             -> i2c (i2c sda)
+#   GPIO26                             -> as3935_i2c (as3935_i2c irq_pin)
+#   GPIO27                             -> neo (light esp32_rmt_led_strip)
+#   GPIO32  Grove SDA
+#   GPIO33  Grove SCL
+# I2C:
+#   0x03  as3935_i2c (as3935_i2c)
 substitutions:
   device: lightening
   name: Lightening detector

mcu-lvgl-4848s040.yaml

@@ -1,4 +1,51 @@
 ---
+# Hardware: Guition ESP32-S3-4848S040
+# Pinout:
+#   # Display (RGB, pins in the mipi_rgb model)
+#    CS        39
+#    SCK       48  ST7701S init (3-wire SPI)
+#    SDA       47
+#    DE        18
+#    HSYNC     16
+#    VSYNC     17
+#    PCLK      21
+#    BL        38
+#   # Capacitive Touch (GT911)
+#    TP_SDA    19
+#    TP_SCL    45
+#   # Relays (86 box variant)
+#    RELAY1    40
+#    RELAY2     2
+#    RELAY3     1
+# Used:
+#   GPIO0   main_display (display mipi_rgb data_pins.red)
+#   GPIO3   main_display (display mipi_rgb data_pins.green)
+#   GPIO4   main_display (display mipi_rgb data_pins.blue)
+#   GPIO5   main_display (display mipi_rgb data_pins.blue)
+#   GPIO6   main_display (display mipi_rgb data_pins.blue)
+#   GPIO7   main_display (display mipi_rgb data_pins.blue)
+#   GPIO8   main_display (display mipi_rgb data_pins.green)
+#   GPIO9   main_display (display mipi_rgb data_pins.green)
+#   GPIO10  main_display (display mipi_rgb data_pins.green)
+#   GPIO11  main_display (display mipi_rgb data_pins.red)
+#   GPIO12  main_display (display mipi_rgb data_pins.red)
+#   GPIO13  main_display (display mipi_rgb data_pins.red)
+#   GPIO14  main_display (display mipi_rgb data_pins.red)
+#   GPIO15  main_display (display mipi_rgb data_pins.blue)
+#   GPIO16  main_display (display mipi_rgb hsync_pin)
+#   GPIO17  main_display (display mipi_rgb vsync_pin)
+#   GPIO18  main_display (display mipi_rgb de_pin)
+#   GPIO19  i2c_main (i2c sda)
+#   GPIO20  main_display (display mipi_rgb data_pins.green)
+#   GPIO21  main_display (display mipi_rgb pclk_pin)
+#   GPIO38  gpio_backlight_pwm (output ledc)
+#   GPIO39  main_display (display mipi_rgb cs_pin)
+#   GPIO45  i2c_main (i2c scl)
+#   GPIO46  main_display (display mipi_rgb data_pins.green)
+#   GPIO47  lcd_spi (spi mosi_pin)
+#   GPIO48  lcd_spi (spi clk_pin)
+# I2C:
+#   0x5D  main_touch (touchscreen gt911)
 substitutions:
   device: lvgl-4848s040
   name: LVGL 4848S040
@@ -35,24 +82,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# PINOUTS: Guition ESP32-S3-4848S040, 4", 480x480, ST7701S, capacitive
-## Display (RGB, pins in the mipi_rgb model)
-# CS        39
-# SCK       48  ST7701S init (3-wire SPI)
-# SDA       47
-# DE        18
-# HSYNC     16
-# VSYNC     17
-# PCLK      21
-# BL        38
-## Capacitive Touch (GT911)
-# TP_SDA    19
-# TP_SCL    45
-## Relays (86 box variant)
-# RELAY1    40
-# RELAY2     2
-# RELAY3     1
-
 api:
   # status page until Home Assistant connects (log viewers don't subscribe to states)
   on_client_connected:

mcu-lvgl-eworkbench.yaml

@@ -1,4 +1,17 @@
 ---
+# Hardware: Guition JC3248W535
+# Pinout:
+#   GPIO1                              -> main_backlight (power_supply)
+#   GPIO4                              -> touchscreen_bus (i2c sda)
+#   GPIO8                              -> touchscreen_bus (i2c scl)
+#   GPIO21                             -> display_qspi (spi data_pins)
+#   GPIO39                             -> display_qspi (spi data_pins)
+#   GPIO40                             -> display_qspi (spi data_pins)
+#   GPIO45                             -> main_display (display mipi_spi cs_pin)
+#   GPIO47                             -> display_qspi (spi clk_pin)
+#   GPIO48                             -> display_qspi (spi data_pins)
+# I2C:
+#   0x3B  main_touch (touchscreen axs15231)
 substitutions:
   device: lvgl-eworkbench
   name: Electronics Workbench Display

mcu-lvgl-trainer.yaml

@@ -1,4 +1,19 @@
 ---
+# Hardware: Guition JC3248W535
+# Pinout:
+#   GPIO1                              -> gpio_backlight_pwm (output ledc)
+#   GPIO4                              -> touchscreen_bus (i2c sda)
+#   GPIO8                              -> touchscreen_bus (i2c scl)
+#   GPIO21                             -> display_qspi (spi data_pins)
+#   GPIO39                             -> display_qspi (spi data_pins)
+#   GPIO40                             -> display_qspi (spi data_pins)
+#   GPIO43                             -> ext_uart (uart tx_pin)
+#   GPIO44                             -> ext_uart (uart rx_pin)
+#   GPIO45                             -> main_display (display mipi_spi cs_pin)
+#   GPIO47                             -> display_qspi (spi clk_pin)
+#   GPIO48                             -> display_qspi (spi data_pins)
+# I2C:
+#   0x3B  main_touch (touchscreen axs15231)
 substitutions:
   device: lvgl-trainer
   name: Trainer Display

mcu-lvgl.yaml

@@ -1,42 +1,6 @@
 ---
-substitutions:
+# Hardware: Sunton ESP32-8048S043 (CYD 4.3", 800x480, capacitive touch)
-  device: lvgl
+# Pinout:
-  name: LVGL
-  area: DEV
-  comment: LVGL
-
-esphome:
-  name: mcu-${device}
-  friendly_name: ${name}
-  area: ${area}
-  comment: ${comment}
-  on_boot:
-    - priority: -100
-      then:
-        - lvgl.page.show: status_page
-
-esp32:
-  variant: esp32s3
-  flash_size: 16MB
-  toolchain: esp-idf
-  framework:
-    type: esp-idf
-    # PSRAM bandwidth for the RGB panel (not set by ESPHome); without it the
-    # image shifts during flash/WiFi activity
-    sdkconfig_options:
-      CONFIG_ESP32S3_DATA_CACHE_64KB: y
-      CONFIG_SPIRAM_FETCH_INSTRUCTIONS: y
-      CONFIG_SPIRAM_RODATA: y
-
-psram:
-  mode: octal
-  speed: 80MHz
-
-packages:
-  common: !include common/common.yaml
-  ipv6_only: !include common/ipv6_only.yaml
-
-# PINOUTS: ESP32 Cheap Yellow Display, 4.3", IPS, Capacitive
 #   # Display
 #    R0        GND
 #    R1        GND
@@ -92,6 +56,69 @@ packages:
 #    2         18
 #    3         19  TP_SDA
 #    4         20  TP_SCL
+# Used:
+#   GPIO1   main_display (display mipi_rgb data_pins.blue)
+#   GPIO2   gpio_backlight_pwm (output ledc)
+#   GPIO3   main_display (display mipi_rgb data_pins.blue)
+#   GPIO4   main_display (display mipi_rgb data_pins.green)
+#   GPIO5   main_display (display mipi_rgb data_pins.green)
+#   GPIO6   main_display (display mipi_rgb data_pins.green)
+#   GPIO7   main_display (display mipi_rgb data_pins.green)
+#   GPIO8   main_display (display mipi_rgb data_pins.blue)
+#   GPIO9   main_display (display mipi_rgb data_pins.blue)
+#   GPIO14  main_display (display mipi_rgb data_pins.red)
+#   GPIO15  main_display (display mipi_rgb data_pins.green)
+#   GPIO16  main_display (display mipi_rgb data_pins.green)
+#   GPIO19  i2c_main (i2c sda)
+#   GPIO20  i2c_main (i2c scl)
+#   GPIO21  main_display (display mipi_rgb data_pins.red)
+#   GPIO38  main_touch (touchscreen gt911 reset_pin)
+#   GPIO39  main_display (display mipi_rgb hsync_pin)
+#   GPIO40  main_display (display mipi_rgb de_pin)
+#   GPIO41  main_display (display mipi_rgb vsync_pin)
+#   GPIO42  main_display (display mipi_rgb pclk_pin)
+#   GPIO45  main_display (display mipi_rgb data_pins.red)
+#   GPIO46  main_display (display mipi_rgb data_pins.blue)
+#   GPIO47  main_display (display mipi_rgb data_pins.red)
+#   GPIO48  main_display (display mipi_rgb data_pins.red)
+# I2C:
+#   0x5D  main_touch (touchscreen gt911)
+substitutions:
+  device: lvgl
+  name: LVGL
+  area: DEV
+  comment: LVGL
+
+esphome:
+  name: mcu-${device}
+  friendly_name: ${name}
+  area: ${area}
+  comment: ${comment}
+  on_boot:
+    - priority: -100
+      then:
+        - lvgl.page.show: status_page
+
+esp32:
+  variant: esp32s3
+  flash_size: 16MB
+  toolchain: esp-idf
+  framework:
+    type: esp-idf
+    # PSRAM bandwidth for the RGB panel (not set by ESPHome); without it the
+    # image shifts during flash/WiFi activity
+    sdkconfig_options:
+      CONFIG_ESP32S3_DATA_CACHE_64KB: y
+      CONFIG_SPIRAM_FETCH_INSTRUCTIONS: y
+      CONFIG_SPIRAM_RODATA: y
+
+psram:
+  mode: octal
+  speed: 80MHz
+
+packages:
+  common: !include common/common.yaml
+  ipv6_only: !include common/ipv6_only.yaml
 
 api:
   # status page until Home Assistant connects (log viewers don't subscribe to states)

mcu-m5paper.yaml

@@ -1,4 +1,25 @@
 ---
+# Hardware: M5Stack M5Paper
+# Pinout:
+#   GPIO2                              -> main_power (switch gpio)
+#   GPIO5                              -> ext_power (switch gpio)
+#   GPIO12                             -> spi (spi mosi_pin)
+#   GPIO13                             -> spi (spi miso_pin)
+#   GPIO14                             -> spi (spi clk_pin)
+#   GPIO15                             -> m5paper_display (display it8951 cs_pin)
+#   GPIO21                             -> i2c_main (i2c sda)
+#   GPIO22                             -> i2c_main (i2c scl)
+#   GPIO23                             -> m5paper_display (display it8951 reset_pin)
+#   GPIO27                             -> m5paper_display (display it8951 busy_pin)
+#   GPIO35                             -> Battery Voltage (sensor adc)
+#   GPIO36                             -> gt911_touchscreen (touchscreen gt911 interrupt_pin)
+#   GPIO37                             -> M5Paper Button UP (binary_sensor gpio) (inverted)
+#   GPIO38                             -> M5Paper Button Press (binary_sensor gpio) (inverted)
+#   GPIO39                             -> M5Paper Button Down (binary_sensor gpio) (inverted)
+# I2C:
+#   0x44  sensor sht3xd (sensor sht3xd)
+#   0x51  rtc_time (time bm8563)
+#   0x5D  gt911_touchscreen (touchscreen gt911)
 substitutions:
   device: m5paper
   name: M5Paper

mcu-mains-power.yaml

@@ -1,4 +1,19 @@
 ---
+# Hardware: M5Stack ATOM Lite
+# Pinout:
+#   GPIO1   UART0 TX
+#   GPIO3   UART0 RX
+#   GPIO12  IR
+#   GPIO19  NC
+#   GPIO21  I2C1 SCL
+#   GPIO22  1-WIRE
+#   GPIO23  UART1 RX
+#   GPIO25  I2C1 SDA
+#   GPIO26  I2C0 SDA                   -> uart_modbus (uart rx_pin)
+#   GPIO27  NEO
+#   GPIO32  I2C0 SCL                   -> uart_modbus (uart tx_pin)
+#   GPIO33  UART1 TX
+#   GPIO39  BUTTON
 substitutions:
   device: mains-power
   name: Mains Power
@@ -28,21 +43,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# PINOUTS: M5ATOM
-# IR        G12
-# NEO       G27
-# BUTTON    G39
-# I2C0 SDA  G26
-# I2C0 SCL  G32
-# I2C1 SDA  G25
-# I2C1 SCL  G21
-# UART0 RX  G3
-# UART0 TX  G1
-# UART1 RX  G23
-# UART1 TX  G33
-# 1-WIRE    G22
-# NC        G19
-
 modbus:
   uart_id: uart_modbus
 

mcu-nrf-dk.yaml

@@ -1,4 +1,5 @@
 ---
+# Hardware: Nordic nRF52840 DK
 esphome:
   name: mcu-nrf-dk
   friendly_name: mcu-nrf-dk

mcu-office-r.yaml

@@ -1,4 +1,15 @@
 ---
+# Hardware: M5Stack M5Stamp C3
+# Pinout:
+#   GPIO0   I2C SDA
+#   GPIO1   I2C SCL
+#   GPIO2   NEO
+#   GPIO3   BUTTON
+#   GPIO4                              -> led_red (output ledc)
+#   GPIO5                              -> led_green (output ledc)
+#   GPIO6                              -> led_blue (output ledc)
+#   GPIO20  UART RX
+#   GPIO21  UART TX
 substitutions:
   device: office-r
   name: Office R
@@ -24,13 +35,6 @@ packages:
   common: !include common/common.yaml
   ipv6_only: !include common/ipv6_only.yaml
 
-# GPIO21   UART TX
-# GPIO20   UART RX
-# GPIO0   I2C SDA
-# GPIO1   I2C SCL
-# GPIO2  NEO
-# GPIO3  BUTTON
-
 light:
   - platform: rgb
     name: "MS Teams Presence Light"

mcu-patio.yaml

@@ -1,4 +1,21 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO1   UART0 TX
+#   GPIO3   UART0 RX
+#   GPIO12  IR
+#   GPIO19  Relay2                     -> Relay (switch gpio)
+#   GPIO21  I2C1 SCL                   -> i2c (i2c scl)
+#   GPIO22  Relay1                     -> power_supply1 (power_supply)
+#   GPIO23  RS485 Tx
+#   GPIO25  I2C1 SDA - red             -> i2c (i2c sda)
+#   GPIO26  I2C0 SDA - white
+#   GPIO27  NEO 1x
+#   GPIO32  I2C0 SCL
+#   GPIO33  RS485 Rx
+#   GPIO39  BUTTON                     -> Status Button (binary_sensor gpio)
+# I2C:
+#   0x40  pca9685_hub1 (pca9685)
 substitutions:
   device: patio
   name: Patio
@@ -40,21 +57,6 @@ packages:
   ipv6_only: !include common/ipv6_only.yaml
 
 
-# PINOUTS: M5ATOM+Atom Hub Switch
-# IR        G12
-# NEO       G27 1x
-# BUTTON    G39
-# I2C0 SDA  G26 - white
-# I2C0 SCL  G32
-# I2C1 SDA  G25 - red
-# I2C1 SCL  G21
-# UART0 RX  G3
-# UART0 TX  G1
-# RS485 Rx  G33
-# RS485 Tx  G23
-# Relay1    G22
-# Relay2    G19
-
 i2c:
   # - id: i2c0
   #   sda: 26

mcu-pow-dishwasher.yaml

@@ -1,4 +1,16 @@
 ---
+# Hardware: Sonoff POW Elite
+# Pinout:
+#   GPIO0                              -> reset (binary_sensor gpio)
+#   GPIO2                              -> relay_on (switch gpio)
+#   GPIO4                              -> relay_off (switch gpio)
+#   GPIO5                              -> wifi_status_led (light status_led) (inverted)
+#   GPIO14                             -> tm1621_display (display tm1621 data_pin)
+#   GPIO16                             -> cse7766_uart (uart rx_pin)
+#   GPIO18                             -> led (output ledc) (inverted)
+#   GPIO25                             -> tm1621_display (display tm1621 cs_pin)
+#   GPIO26                             -> tm1621_display (display tm1621 read_pin)
+#   GPIO27                             -> tm1621_display (display tm1621 write_pin)
 substitutions:
   device: pow-dishwasher
   name: Dishwasher POW

mcu-pow-washer.yaml

@@ -1,4 +1,16 @@
 ---
+# Hardware: Sonoff POW Elite
+# Pinout:
+#   GPIO0                              -> reset (binary_sensor gpio)
+#   GPIO2                              -> relay_on (switch gpio)
+#   GPIO4                              -> relay_off (switch gpio)
+#   GPIO5                              -> wifi_status_led (light status_led) (inverted)
+#   GPIO14                             -> tm1621_display (display tm1621 data_pin)
+#   GPIO16                             -> cse7766_uart (uart rx_pin)
+#   GPIO18                             -> led (output ledc) (inverted)
+#   GPIO25                             -> tm1621_display (display tm1621 cs_pin)
+#   GPIO26                             -> tm1621_display (display tm1621 read_pin)
+#   GPIO27                             -> tm1621_display (display tm1621 write_pin)
 substitutions:
   device: pow-washer
   name: Washer POW

mcu-rf.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: M5Stack ATOM Lite
+# Pinout:
+#   GPIO19                             -> spi (spi mosi_pin)
+#   GPIO21                             -> rf_tx (remote_transmitter)
+#   GPIO22                             -> spi (spi miso_pin)
+#   GPIO23                             -> spi (spi clk_pin)
+#   GPIO25                             -> rf_rx (remote_receiver)
+#   GPIO26  Grove SDA
+#   GPIO32  Grove SCL
+#   GPIO33                             -> cc1101 (cc1101 cs_pin)
 substitutions:
   device: rf
   name: RF Bridge

mcu-rf433.yaml

@@ -1,4 +1,9 @@
 ---
+# Hardware: Sonoff RF Bridge (obsolete)
+# Pinout:
+#   GPIO4                              -> remote_receiver (remote_receiver)
+#   GPIO5                              -> remote_transmitter (remote_transmitter)
+#   GPIO13                             -> status_led (status_led) (inverted)
 substitutions:
   device: rf433
   name: RF433 Bridge

mcu-rfid-reader.yaml

@@ -1,4 +1,16 @@
 ---
+# Hardware: M5Stack M5Stamp S3
+# Pinout:
+#   GPIO0   Button
+#   GPIO1   I2C SDA                    -> i2c_rfid (i2c sda)
+#   GPIO2   I2C SDA, Notify LED        -> i2c_rfid (i2c scl)
+#   GPIO3                              -> notify_led (light esp32_rmt_led_strip)
+#   GPIO4   Buzzer                     -> buzzer (output ledc)
+#   GPIO19  U-
+#   GPIO20  U+
+#   GPIO21  RGB                        -> status_led (light esp32_rmt_led_strip)
+# I2C:
+#   0x24  pn532_module (pn532_i2c)
 substitutions:
   device: rfid-reader
   name: RFID Reader
@@ -45,15 +57,6 @@ packages:
 # logger:
 #   hardware_uart: UART0
 
-# GPIO20  U+
-# GPIO19  U-
-# GPIO0   Button
-# GPIO1   I2C SDA
-# GPIO2   I2C SDA
-# GPIO2   Notify LED
-# GPIO4   Buzzer
-# GPIO21  RGB
-
 api:
   actions:
   - action: rfidreader_tag_ok

mcu-shed.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO19                             -> Light (switch gpio)
+#   GPIO21                             -> i2c (i2c scl)
+#   GPIO22                             -> Garden Light (switch gpio)
+#   GPIO25                             -> i2c (i2c sda)
+#   GPIO26  Grove SDA
+#   GPIO32  Grove SCL
+# I2C:
+#   0x27  pca9554_module (pca9554)
 substitutions:
   device: shed
   name: Shed

mcu-socket-01.yaml

@@ -1,4 +1,15 @@
 ---
+# Hardware: BlitzWolf BW-SHP2/SHP6
+# Pinout:
+#   GPIO0   GPIO_LED1_INV Red LED (inverted), Power Status -> led_red (output gpio)
+#   GPIO1   GPIO_USER RXD, Optional sensor
+#   GPIO2   GPIO_LEDLNK_INV Blue LED (inverted), Link Status -> led_blue (output gpio)
+#   GPIO3   GPIO_USER TXD, Optional sensor
+#   GPIO5   GPIO_HJL_CF BL0937 or HJL-01 CF power -> sensor/hlw8012 (sensor hlw8012 cf_pin)
+#   GPIO12  GPIO_NRG_SEL_INV BL0937 or HJL-01 Sel output (0 = Voltage) -> sensor/hlw8012 (sensor hlw8012 sel_pin) (inverted)
+#   GPIO13  GPIO_KEY1 Button           -> Button (binary_sensor gpio) (inverted)
+#   GPIO14  GPIO_NRG_CF1 BL0937 or HJL-01 CF1 current / voltage -> sensor/hlw8012 (sensor hlw8012 cf1_pin)
+#   GPIO15  GPIO_REL1 Relay            -> Relay (switch gpio)
 substitutions:
   device: socket-01
   name: Socket 01
@@ -19,18 +30,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-# BlitzWolf BW-SHP2 and BW-SHP6 (ESP8285 - BL0937 or HJL-01 Energy Monitoring)
-# Pin 	  Name              Function
-# GPIO15 	GPIO_REL1         Relay
-# GPIO13 	GPIO_KEY1         Button
-# GPIO00 	GPIO_LED1_INV     Red LED (inverted), Power Status
-# GPIO02 	GPIO_LEDLNK_INV   Blue LED (inverted), Link Status
-# GPIO05  GPIO_HJL_CF       BL0937 or HJL-01 CF power
-# GPIO12  GPIO_NRG_SEL_INV  BL0937 or HJL-01 Sel output (0 = Voltage)
-# GPIO14  GPIO_NRG_CF1      BL0937 or HJL-01 CF1 current / voltage
-# GPIO01 	GPIO_USER         RXD, Optional sensor
-# GPIO03 	GPIO_USER         TXD, Optional sensor
-
 binary_sensor:
   - platform: gpio
     pin:

mcu-socket-02.yaml

@@ -1,4 +1,15 @@
 ---
+# Hardware: BlitzWolf BW-SHP2/SHP6
+# Pinout:
+#   GPIO0   GPIO_LED1_INV Red LED (inverted), Power Status -> led_red (output gpio)
+#   GPIO1   GPIO_USER RXD, Optional sensor
+#   GPIO2   GPIO_LEDLNK_INV Blue LED (inverted), Link Status -> led_blue (output gpio)
+#   GPIO3   GPIO_USER TXD, Optional sensor
+#   GPIO5   GPIO_HJL_CF BL0937 or HJL-01 CF power -> sensor/hlw8012 (sensor hlw8012 cf_pin)
+#   GPIO12  GPIO_NRG_SEL_INV BL0937 or HJL-01 Sel output (0 = Voltage) -> sensor/hlw8012 (sensor hlw8012 sel_pin) (inverted)
+#   GPIO13  GPIO_KEY1 Button           -> Button (binary_sensor gpio) (inverted)
+#   GPIO14  GPIO_NRG_CF1 BL0937 or HJL-01 CF1 current / voltage -> sensor/hlw8012 (sensor hlw8012 cf1_pin)
+#   GPIO15  GPIO_REL1 Relay            -> Relay (switch gpio)
 substitutions:
   device: socket-02
   name: Socket 02
@@ -19,18 +30,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-# BlitzWolf BW-SHP2 and BW-SHP6 (ESP8285 - BL0937 or HJL-01 Energy Monitoring)
-# Pin 	  Name              Function
-# GPIO15 	GPIO_REL1         Relay
-# GPIO13 	GPIO_KEY1         Button
-# GPIO00 	GPIO_LED1_INV     Red LED (inverted), Power Status
-# GPIO02 	GPIO_LEDLNK_INV   Blue LED (inverted), Link Status
-# GPIO05  GPIO_HJL_CF       BL0937 or HJL-01 CF power
-# GPIO12  GPIO_NRG_SEL_INV  BL0937 or HJL-01 Sel output (0 = Voltage)
-# GPIO14  GPIO_NRG_CF1      BL0937 or HJL-01 CF1 current / voltage
-# GPIO01 	GPIO_USER         RXD, Optional sensor
-# GPIO03 	GPIO_USER         TXD, Optional sensor
-
 binary_sensor:
   - platform: gpio
     pin:

mcu-socket-03.yaml

@@ -1,4 +1,15 @@
 ---
+# Hardware: BlitzWolf BW-SHP2/SHP6
+# Pinout:
+#   GPIO0   GPIO_LED1_INV Red LED (inverted), Power Status -> led_red (output gpio)
+#   GPIO1   GPIO_USER RXD, Optional sensor
+#   GPIO2   GPIO_LEDLNK_INV Blue LED (inverted), Link Status -> led_blue (output gpio)
+#   GPIO3   GPIO_USER TXD, Optional sensor
+#   GPIO5   GPIO_HJL_CF BL0937 or HJL-01 CF power -> sensor/hlw8012 (sensor hlw8012 cf_pin)
+#   GPIO12  GPIO_NRG_SEL_INV BL0937 or HJL-01 Sel output (0 = Voltage) -> sensor/hlw8012 (sensor hlw8012 sel_pin) (inverted)
+#   GPIO13  GPIO_KEY1 Button           -> Button (binary_sensor gpio) (inverted)
+#   GPIO14  GPIO_NRG_CF1 BL0937 or HJL-01 CF1 current / voltage -> sensor/hlw8012 (sensor hlw8012 cf1_pin)
+#   GPIO15  GPIO_REL1 Relay            -> Relay (switch gpio)
 substitutions:
   device: socket-03
   name: Socket 03
@@ -25,18 +36,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-# BlitzWolf BW-SHP2 and BW-SHP6 (ESP8285 - BL0937 or HJL-01 Energy Monitoring)
-# Pin 	  Name              Function
-# GPIO15 	GPIO_REL1         Relay
-# GPIO13 	GPIO_KEY1         Button
-# GPIO00 	GPIO_LED1_INV     Red LED (inverted), Power Status
-# GPIO02 	GPIO_LEDLNK_INV   Blue LED (inverted), Link Status
-# GPIO05  GPIO_HJL_CF       BL0937 or HJL-01 CF power
-# GPIO12  GPIO_NRG_SEL_INV  BL0937 or HJL-01 Sel output (0 = Voltage)
-# GPIO14  GPIO_NRG_CF1      BL0937 or HJL-01 CF1 current / voltage
-# GPIO01 	GPIO_USER         RXD, Optional sensor
-# GPIO03 	GPIO_USER         TXD, Optional sensor
-
 binary_sensor:
   - platform: gpio
     pin:

mcu-stackchan.yaml

@@ -1,3 +1,43 @@
+# Hardware: M5Stack CoreS3 + Stack-chan kit
+# Pinout:
+#   GPIO0                              -> i2s_bus (i2s_audio i2s_mclk_pin)
+#   GPIO2                              -> Camera (esp32_camera)
+#   GPIO3                              -> display_tft (display mipi_spi cs_pin)
+#   GPIO5                              -> ir_tx (remote_transmitter)
+#   GPIO6                              -> uart_servo (uart tx_pin)
+#   GPIO7                              -> uart_servo (uart rx_pin)
+#   GPIO10                             -> ir_rx (remote_receiver)
+#   GPIO11                             -> i2c_bsp (i2c scl)
+#   GPIO12                             -> i2c_bsp (i2c sda)
+#   GPIO13                             -> speaker_id (speaker i2s_audio i2s_dout_pin)
+#   GPIO14                             -> stackchan_microphone (microphone i2s_audio i2s_din_pin)
+#   GPIO15                             -> Camera (esp32_camera data_pins)
+#   GPIO16                             -> Camera (esp32_camera data_pins)
+#   GPIO33                             -> i2s_bus (i2s_audio i2s_lrclk_pin)
+#   GPIO34                             -> i2s_bus (i2s_audio i2s_bclk_pin)
+#   GPIO35                             -> display_tft (display mipi_spi dc_pin)
+#   GPIO36                             -> spi_bus (spi clk_pin)
+#   GPIO37                             -> spi_bus (spi mosi_pin)
+#   GPIO38                             -> Camera (esp32_camera href_pin)
+#   GPIO39                             -> Camera (esp32_camera data_pins)
+#   GPIO40                             -> Camera (esp32_camera data_pins)
+#   GPIO41                             -> Camera (esp32_camera data_pins)
+#   GPIO42                             -> Camera (esp32_camera data_pins)
+#   GPIO45                             -> Camera (esp32_camera pixel_clock_pin)
+#   GPIO46                             -> Camera (esp32_camera vsync_pin)
+#   GPIO47                             -> Camera (esp32_camera data_pins)
+#   GPIO48                             -> Camera (esp32_camera data_pins)
+# I2C:
+#   0x23  sensor ltr_als_ps (sensor ltr_als_ps)
+#   0x34  axp2101_pmu (axp2101)
+#   0x36  aw88298_dac (audio_dac aw88298)
+#   0x38  touch_lcd (touchscreen ft63x6)
+#   0x40  es7210_adc (audio_adc es7210)
+#   0x41  sensor ina226 (sensor ina226)
+#   0x51  rtc_time (time bm8563)
+#   0x58  aw9523b_hub (aw9523b)
+#   0x68  touch_hub (si12t)
+#   0x6F  m5ioe1_hub (m5ioe1)
 substitutions:
   device: stackchan
   name: StackChan

mcu-staircase-light.yaml

@@ -1,4 +1,8 @@
 ---
+# Hardware: Sonoff Mini
+# Pinout:
+#   GPIO12                             -> relay (output gpio)
+#   GPIO13                             -> led_blue (output gpio)
 substitutions:
   device: staircase-light
   name: Staircase

mcu-tft.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: M5Stack M5Stamp C3
+# Pinout:
+#   GPIO0   Grove SCL                  -> touchscreen/xpt2046 (touchscreen xpt2046 cs_pin)
+#   GPIO1   Grove SDA                  -> touchscreen/xpt2046 (touchscreen xpt2046 interrupt_pin)
+#   GPIO4                              -> spi (spi clk_pin)
+#   GPIO5                              -> spi (spi mosi_pin)
+#   GPIO6                              -> spi (spi miso_pin)
+#   GPIO7                              -> main_display (display mipi_spi cs_pin)
+#   GPIO8                              -> main_display (display mipi_spi dc_pin)
+#   GPIO10                             -> main_display (display mipi_spi reset_pin)
 substitutions:
   device: tft
   name: TFT

mcu-tracker.yaml

@@ -1,4 +1,5 @@
 ---
+# Hardware: LilyGO T-PCIE
 substitutions:
   device: tracker
   name: Tracker

mcu-tv-light.yaml

@@ -1,4 +1,22 @@
 ---
+# Hardware: Huacanxing H801
+# Pinout:
+#   # H801 LED module
+#    Function       Pin       Channel
+#    R            GPIO15    PWM1
+#    G            GPIO13    PWM2
+#    B            GPIO12    PWM3
+#    W1           GPIO14    PWM4
+#    W2           GPIO04    PWM5
+#    LED D1 R       GPIO05
+#    LED D2 G       GPIO01
+# Used:
+#   GPIO4   pwm_warm_white (output esp8266_pwm)
+#   GPIO5   status_led_id (light status_led)
+#   GPIO12  pwm_blue (output esp8266_pwm)
+#   GPIO13  pwm_green (output esp8266_pwm)
+#   GPIO14  pwm_cold_white (output esp8266_pwm)
+#   GPIO15  pwm_red (output esp8266_pwm)
 substitutions:
   device: tv-light
   name: TV Light
@@ -17,16 +35,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-## H801 LED module
-# Function 	Pin 	  Channel
-# R 	      GPIO15 	PWM1
-# G 	      GPIO13 	PWM2
-# B 	      GPIO12 	PWM3
-# W1 	      GPIO14 	PWM4
-# W2 	      GPIO04 	PWM5
-# LED D1 R 	GPIO05
-# LED D2 G 	GPIO01
-
 light:
   - platform: status_led
     id: status_led_id

mcu-vehicle-honda-pcx125.yaml

@@ -1,4 +1,6 @@
 ---
+# Hardware: M5Stack ATOM Lite
+# Pinout: see common/vehicle_base.yaml
 substitutions:
   device: vehicle-honda-pcx125
   name: Vehicle Honda PCX125

mcu-vehicle-suzuki-dl650.yaml

@@ -1,4 +1,6 @@
 ---
+# Hardware: M5Stack ATOM Lite
+# Pinout: see common/vehicle_base.yaml
 substitutions:
   device: vehicle-suzuki-dl650
   name: Vehicle Suzuki DL650

mcu-vehicle-toyota-auris-ts.yaml

@@ -1,4 +1,6 @@
 ---
+# Hardware: M5Stack ATOM Lite
+# Pinout: see common/vehicle_base.yaml
 substitutions:
   device: vehicle-toyota-auris-ts
   name: Vehicle Toyota Auris TS

mcu-vehicle-toyota-yaris-cross.yaml

@@ -1,4 +1,6 @@
 ---
+# Hardware: M5Stack ATOM Lite
+# Pinout: see common/vehicle_base.yaml
 substitutions:
   device: vehicle-toyota-yaris-cross
   name: Vehicle Toyota Yaris Cross

mcu-waterproof-socket.yaml

@@ -1,4 +1,11 @@
 ---
+# Hardware: Sonoff Basic R2
+# Pinout:
+#   GPIO0   BUTTON                     -> Button (binary_sensor gpio) (inverted)
+#   GPIO1   TX PIN
+#   GPIO3   RX PIN
+#   GPIO12  RELAY                      -> Relay (switch gpio)
+#   GPIO13  LED1                       -> led (output gpio)
 substitutions:
   device: waterproof-socket
   name: Waterproof Socket
@@ -17,13 +24,6 @@ esp8266:
 packages:
   common: !include common/common_esp8266.yaml
 
-# Sonoff Basic R2
-# GPIO00 - BUTTON
-# GPIO12 - RELAY
-# GPIO13 - LED1
-# GPIO03 - RX PIN
-# GPIO01 - TX PIN
-
 binary_sensor:
   - platform: gpio
     pin:

mcu-well.yaml

@@ -1,4 +1,14 @@
 ---
+# Hardware: M5Stack ATOM Lite + ATOM Hub Switch
+# Pinout:
+#   GPIO21                             -> i2c (i2c scl)
+#   GPIO23                             -> modbus_uart (uart tx_pin)
+#   GPIO25                             -> i2c (i2c sda)
+#   GPIO26  Grove SDA
+#   GPIO32  Grove SCL
+#   GPIO33                             -> modbus_uart (uart rx_pin)
+# I2C:
+#   0x27  relay_module (pca9554)
 substitutions:
   device: well
   name: Well