Add YAML and README.md

README.md

@@ -0,0 +1,89 @@
+# Hauslane UC-PS18 external component
+
+This ESPHome external component allows control of a Hauslane UC-PS18 range
+hood by manipulating its front panel buttons and by reading the communications
+from the front panel to the main control board.
+
+## Setup
+
+### Hardware
+
+You will need the following hardware to wire up the range hood:
+
+- 1x ESP device such as ESP32-C3 Super Mini
+- 5x optocouplers such as 4N35\*
+- 5x resistors 1 $k\Omega$
+- 1x PNP transistor such as 2N3906
+- 1x 2cmx8cm perforated prototype board
+
+\* I used 4N35 optocouplers in my build because that is what I had on hand, but
+they are overkill for this application since they are only used to "press" the
+front panel buttons, which uses very slow switching speeds of >250 ms. If I were
+patient, I would have waited for the much cheaper PC817 which should be more
+than sufficient for this task. That said, I do not guarantee that it wlll work
+with PC817 optocouplers. I suggest doing a test on one of the buttons using a
+breadboard before making a more permanent installation.
+
+For safety, unplug the range hood from the AC power source before taking it
+apart. Remove the drip tray and the washable baffle filters. Use a screwdriver
+to remove the 8 screws from the fan cover assembly and remove the cover. You
+can then remove the 2 screws from the light assembly to detach the lights ---
+be careful to support the light assembly as you remove the screws as each bulb
+is attached to a cable. Detach the cables to remove the light assembly and put
+it aside. This should expose two more screws on the bottom by the front panel.
+Remove the screws and unclip the 3-wire harness connecting it to the main
+conrol board, and you can gently pull the front panel assembly out. The front
+panel is screwed into a plastic box with two smaller screws. Remove the
+small screws to remove the front panel control board from the assembly.
+
+![Wiring of the front panel control board](wiring.png)
+
+On the front of the panel find where the 3-wire harness connects to the board.
+Flip the board to the back and identify the solder points on the back. From 
+left to right, these are GND, TX, and 5V. To power the ESP32-C3 (or the
+variant of ESP board you are using) from the panel, connect GND on the
+panel to GND on the ESP32-C3 and 5V on the panel to 5V on the ESP32-C3. To read
+the state of the fans and lights, connect the transistor's emitter (on the 
+2N390 this is the leftmost leg with the flat side facing you) to RX on GPIO 6
+of the ESP32-C3. The transistor's base (middle leg) connects to the TX point on
+the front panel board, and the collector (rightmost leg) attaches to GND either
+at the front panel board or on the ESP32-C3.
+
+Each buttton is a capacitive spring with a single connection point to the
+front panel control board at the spring's base. Shorting this point to ground
+discharges the spring and acts as a press --- or more accurately a touch --- of
+the button. In theory, a transistor can do the job here too, but the leakage
+from the transistor will influence the capacitive spring and will not register
+presses reliably. Instead, wire the output side of the optocoupler by
+connecting the spring to the optocoupler collector and ground to the optocoupler
+emitter. On the input side, connect GPIO pin->resistor->optocoupler anode
+in series and the optocoupler cathode to ground. These can be done using GPIO 
+0, 1, and 3-5 on the ESP32-C3. Avoid pin 2 if using the ESP32-C3 as it is a
+strapping pin and will cause issues with detecting button presses. The sample
+configuration YAML assumes the timer button is on GPIO 0, up botton on GPIO 1,
+down button on GPIO 3, light button on GPIO 4, and power button on GPIO 5, but 
+these can be configured in YAML.
+
+Since a lot of new connections will need to be made to ground, I recommend using
+something like a perforated prototype board and make a single connection to
+ground from the prototype board to the front panel control board, then connect
+all other grounds needed for the circuiti to each other using the prototype 
+board. A 2cm$\times$8cm board fits perfectly in the empty space below the front panel in the front panel assemple. I also made all connections to the back of
+the front panel control board with wires with female Dupont connectors, then
+used male headers on the prototype board so that the additional circuitry can
+easily be removed.
+
+![Perforated prototype board](proto.png)
+
+![ESP32-C3 and prototype board inside front panel assembly](assembly.png)
+
+Once you have everything connected, reassemble the range hood.
+
+### Software
+
+Use the [uc-ps18.yaml](uc-ps18.yaml) sample configuration and change any options
+such as Wi-FI and API settings to match your preferences. If you are using
+different pins or a different model of ESP board, make sure to change those
+blocks in the YAML file. Flash the ESP32-C3 using ESPHome. The `command` API
+can be used to control the device, or you can interface the device with
+something like Home Assistant for a graphical user interface..

uc-ps18.yaml

@@ -0,0 +1,60 @@
+substitutions:
+  name: uc-ps18
+  friendly_name: Hauslane UC-PS18 Range Hood
+
+external_components:
+  - source:
+      type: git
+      url: https://git.kkozai.com/kenji/esphome-ucps18
+
+esphome:
+  name: ${name}
+  friendly_name: ${friendly_name}
+
+esp32:
+  board: esp32-c3-devkitm-1
+
+# Enable logging
+logger:
+  level: DEBUG
+
+api:
+  password: !secret api_password
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+  ap:
+    ssid: ${name}
+    password: !secret wifi_password
+
+captive_portal: 
+
+uart:
+  baud_rate: 3600
+  rx_pin: 6
+
+hauslane:
+  id: hauslane_id
+  pin_timer: 0
+  pin_up: 1
+  pin_down: 3
+  pin_light: 4
+  pin_power: 5
+
+light:
+  platform: hauslane
+  hauslane_id: hauslane_id
+  id: hood_light
+  name: Light
+
+fan:
+  platform: hauslane
+  hauslane_id: hauslane_id
+  id: hood_fan
+  name: Fan