hacklock: document

Change-Id: I949937a050857e3790645cc4ad93ead7a141ccf8
Reviewed-on: https://gerrit.hackerspace.pl/c/hscloud/+/1526
Reviewed-by: q3k <q3k@hackerspace.pl>

hswaw/hacklock/README.md

@@ -8,7 +8,7 @@ Aims to replace `doorman` which lives at https://code.hackerspace.pl/doorman .
 Hardware
 ---
 
-`hacklock-2137` is the main hardware implementaton for the door lock controller. It's based on an ESP32-S3. The PCB design files and board documentation are available at [hardware/hacklock-2137](hswaw/hacklock/hardware/hacklock-2137).
+`hacklock-2137` is the main hardware implementaton for the door lock controller. It's based on an ESP32-S3. The PCB design files and board documentation are available at [hardware/hacklock-2137](hardware/hacklock-2137).
 
 Firmware
 ---

hswaw/hacklock/hardware/hacklock-2137/README.md

@@ -0,0 +1,137 @@
+hacklock-2137
+===
+
+![](board.jpg)
+
+Controller board for next gen [hacklock](/hswaw/hacklock) door / lock / access control system.
+
+Specifications
+--
+
+ - Built around an ESP32S3: dual-core 32-bit microcontroller with wifi/bluetooth, maximum of 8MB SPIRAM and 16MB Flash memory. Programmable with Micropython, C, C++ or Rust.
+ - Programming and debugging over USB-C (Serial and JTAG using built-in USB/JTAG bridge).
+ - Wide range of power supply voltage, from 10 to 24V.
+ - Two independent and monitored power inputs.
+ - 2x hardware UART, at 3v3, 5v or RS232 levels.
+ - Two Omron G5V-1 relays, contacts rated at 24V 1A hold current.
+ - Two digital outputs at Vsupply level.
+ - Two digital inputs at Vsupply level.
+ - I2C bus connector for functionality expansion.
+
+Power
+---
+
+10-24V is expected at PWR1/PWR2, with 12V typical.
+
+Whichever input voltage is higher will be used to power the device.
+
+Two ADC pins can be used to monitor the voltage at PWR1/PWR2:
+
+| Function | GPIO |
+|----------|------|
+| PWR1 monitoring | GPIO1/ADC1 |
+| PWR2 monitoring | GPIO2/ADC2 |
+
+The voltage at PWR1/PWR2 is divided by 28 before it reaches the ESP32 ADC, so 24V on PWR1 == 857mV on the ADC.
+
+UART
+---
+
+One of three outputs can be enabled: 3v3, 5v, RS232. This is done by setting two pins per UART: 5V enable and RS232 enable. Truth table:
+
+| 5V enable | RS232 enable | Selected connector |
+|---|---|-----|
+| 0 | 0 | 3v3 |
+| 1 | 0 | 5v |
+| 1 | 1 | RS232 |
+| 0 | 1 | undef |
+
+Pinout for UART1:
+
+| Function | GPIO |
+|----------|------|
+| UART1 TX (from hacklock) | 17 |
+| UART1 RX (to hacklock)   | 18 |
+| UART1 5V enable | 6 |
+| UART1 RS232 enable | 8 |
+
+Pinout for UART2:
+
+| Function | GPIO |
+|----------|------|
+| UART2 TX (from hacklock) | 3 |
+| UART2 RX (to hacklock)   | 4 |
+| UART2 5V enable | 7 |
+| UART2 RS232 enable | 9 |
+
+The RS232 connectors are wired as a DCE, which is a happy accident. No hardware flow control is available.
+
+Digital I/O
+---
+
+Digital I/O is at power supply levels, optimized for a ~12V rail. Digital I/O connectors also carry GND and Vsupply on them so that it's easy to use these I/O connectors to read switch state or drive other 'industrial' equipment. 
+
+Output pins can sink/source up to 500mA (via ULN2003A).
+
+Input pins need to be driven to at least 10V to register a signal as a logical high.
+
+| Function | GPIO |
+|----------|------|
+| O12 (output) | 12 |
+| O13 (output) | 13 |
+| I10 (input) | 10 |
+| I11 (input) | 11 |
+
+Relay outputs
+---
+
+Two relay outputs are available, using OMRON G5V-1 relays. These relays allow for controlling up to a 1A load at 24V.
+
+| Function | GPIO |
+|----------|------|
+| Relay 21 | 21 |
+| Relay 14 | 14 |
+
+I2C connector
+---
+
+Running I2C off-board is not recommended, but is provided as a backup solution in case you wish to expand the capabilities of the board.
+
+| Function | GPIO |
+|----------|------|
+| SCL | 38 |
+| SDA | 47 |
+
+The bus runs at 3v3 and has 1.8k pullups included.
+
+LEDs
+---
+
+Two RGB LEDs (WS2812B) are included and connected to GPIO48. However, they're untested.
+
+Programming
+---
+
+You can power the device from USB-C, but digital I/O will not run well. Everything else should work. You can connect via USB when the device is powered on via PWR1/PWR2.
+
+Hold SW1 while powering on the device, or hold SW1 while resetting the device with SW2. The device will switch into BootROM serial mode and can be programmed using esptool.py.
+
+J15 is an 'FTDI cable' connector a la sparkfun/adafruit. Pin 1 is GND and is facing away from the ESP32. This exposes the UART0 console from the ESP32 in case you want to have a second debugging/logging channel in adition to the USB serial/jtag console.
+
+Manufacturing
+===
+
+Runs
+---
+
+| Revision | Date       | Count | Fab    | Serials   | Notes                                        |
+|----------|------------|-------|--------|-----------|----------------------------------------------|
+| rev. A   | 2022/06/21 | 5pcs  | JLCPCB | Q001-Q005 | HW fixes applied (see revision detail below) |
+
+Revision A
+---
+
+First revision, has the following hardware bugs:
+
+1. Current limiting resistors R1, R2, R3, R11, R12 are way too low value, they should be closer to 10k.
+2. R35 should be removed if an FTDI cable is used, otherwise 5V from the FTDI cable will go into the 3v3 rail of the device, slowly killing the ESP32.