document how to build a solenoid driver and install a solenoid

* In contrast to the relay breakout board I was using before,
  the solenoid driver is HIGH-active, so some code had to be changed
  as well.

4 files changed, 40 insertions, 20 deletions

diff --git a/README.md b/README.md
index c25db83..5879d3e 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ while supporting most of its original features and many new features:
   Try pressing LSHIFT+ET1+ET2+F1 and LSHIFT+ET1+ET2+F2.
 * Several keyclick modes are supported.
   Press LSHIFT+ET1+ET2+Space to toggle them.
-  * Trigger a solenoid via a relay (or trigger only the relay).
+  * Trigger a solenoid via a solenoid driver (or a relay breakout board).
     The original hardware did not feature any solenoid.
   * Emit a short beep on every keypress.
 
@@ -45,8 +45,6 @@ You can watch a [demo video here](https://drive.google.com/file/d/16d42nZZ2FOZdN
 
 ## Building the Replacement Controller
 
-**This section is under construction.**
-
 You will need to acquire the following items:
 
 * [Teensy 2.0++](https://www.pjrc.com/store/teensypp.html).
@@ -54,10 +52,6 @@ You will need to acquire the following items:
   particular shape.
 * Pin Headers
 * Lots of jumper cables
-* If you want to attach the solenoid:
-  * Some Arduino-compatible relay breakout board
-  * A "flyback" diode
-  * _The solenoid is currently under evaluation._
 * (De)soldering equipment.
 
 First, you should desolder the UB 880 D processor and the 8212 IO chips.
@@ -131,12 +125,6 @@ It will connect to pin D0 of the Teensy.
 
 Desolder the IFFS cable.
 
-Connect the VCC, GND and the control pin of the relay using jumper cables with
-the Teensy.
-The control pin should be connected to B3 of the Teensy.
-
-__FIXME__: How to connect the solenoid.
-
 You should now be ready to test your installation.
 If everything goes well and you can determine that possibly dead keys are only
 related to missing solder, you can fixate/solder your Teensy to the PCB.
@@ -145,6 +133,41 @@ The endresult should look similar to this:
 
 ![K7637 front](pics/disassembled-front.jpg) ![K7637 backside](pics/disassembled-back.jpg)
 
+## Installing the Solenoid (Optional)
+
+If you want to install a solenoid, you will need the following components:
+
+* A 5V-rated solenoid like [this one](https://www.ebay.de/itm/113932404840).
+  Ideally it should be a push-trough solenoid (that can hit against something).
+* A tranistor like IRFZ44N. TTL-level transistors should also work well.
+* A diode.
+* 10kOhm resistor (may be optional).
+
+The place near the LEDs in the top left corner turned out to be well suited for installing
+small solenoids.
+It can be placed between the PCB and metal frame and fixed with double-sides duct tape.
+If you buy the same one as I did, you may also have to glue on some plastic or steel sheet
+to the solenoid in order to increase its surface.
+
+The solenoid cannot be directly wired to the Teensy 2.0++, we will need to
+build a simple solenoid driver.
+In the most simple case, it can be assembled on a small breadboard that fits into
+the keyboard's case.
+It should be built according to the following circuit diagram:
+
+![Solenoid driver](pics/solenoid-driver.png)
+
+**NOTE:** Using one of the Arduino-compatible relay breakout boards
+(together with a flyback diode of course) as a solenoid driver turned
+out to be impractical.
+It apparently draws too much power which will result in MCU crashes.
+Perhaps this might work when using an externally powered USB hub.
+You can however attach a bare relay breakout board (without solenoid)
+to get some clicky feedback - but it's nowhere as load as even a small
+dedicated solenoid.
+Some of these breakout boards are LOW-active, so you might have to
+tweak the code and invert the use of PB3 (solenoid trigger).
+
 ## Building and Flashing the Firmware
 
 First install some packages:
diff --git a/keyclick.h b/keyclick.h
index c7c7fd2..c88e313 100644
--- a/keyclick.h
+++ b/keyclick.h
@@ -38,13 +38,10 @@ extern enum keyclick_mode keyclick_mode;
 static inline void
 keyclick_solenoid_set(bool state)
 {
-	/*
-	 * NOTE: The solenoid/relay is LOW-active.
-	 */
 	if (state)
-	        PORTB &= ~(1 << PB3);
-	else
 		PORTB |= (1 << PB3);
+	else
+	        PORTB &= ~(1 << PB3);
 }
 
 #endif
diff --git a/matrix.c b/matrix.c
index 47623f7..4c1cea9 100644
--- a/matrix.c
+++ b/matrix.c
@@ -293,10 +293,10 @@ static void init_pins(void)
     PORTF &= ~0b00001000;
 
     /*
-     * Solenoid (ie. relay). It's LOW-active.
+     * Solenoid
      */
     DDRB  |= (1 << PB3);
-    PORTB |= (1 << PB3);
+    PORTB &= ~(1 << PB3);
 }
 
 static void select_col(uint8_t col)
diff --git a/pics/solenoid-driver.png b/pics/solenoid-driver.png
new file mode 100644
index 0000000..1e6e412
--- /dev/null
+++ b/pics/solenoid-driver.png