From 2e29c24145f4c0a576d3043ef6227713b073c5c1 Mon Sep 17 00:00:00 2001 From: Ondrej Jirman Date: Wed, 16 Jun 2021 14:32:28 +0200 Subject: [PATCH] Add HACKING file --- HACKING | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 HACKING diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..0e64757 --- /dev/null +++ b/HACKING @@ -0,0 +1,63 @@ +Pinephone keyboard firmware +--------------------------- + +Current firmware implementation relies on polling the key matrix +once every 20ms. + +The controller has ability to detect change on +the row input port, so it is possible to ground all column GPIOs +enable pull-ups on row GPIOs, and wait on change on the row GPIOs. + +This only works when no key is pressed, otherwise one pressed +key would mask changes in the state of other keys on the same row. +This is good to achieve large power savings by not polling when +we detect that no keys are pressed, which is the normal state +of all keys. + +Firmware thus switches between two modes of operation: + +- idle - when no keys are pressed, columns are grouded, rows are pulled up + and the controller only reacts on the change in the row GPIOs + - when the change is detected, it switches to active mode +- active - when a key is pressed, the firmware performs periodic + full scans of the keyboard matrix, to determine what keys + are actually pressed + - when no keys are pressed anymore it switches to idle mode + +It is possible to power down the CPU and all peripherals in idle mode +via PCON.PD bit and only wait to be woken up by GPIO change interrupt. +(or I2C interrupt) + +My prototype keyboard has Z key always pressed due to some HW bug, +so this method of switching to idle mode and powering down the +controller will not work on my keyboard. The firmware implements +in this case a always active polling mode. + + +Observations +------------ + +- Power consumption in polled mode is about 20mW. +- I2C interrupts don't always wake from power down. (maybe the wakeup + only works on the I2C address match condition, as stated in the manual + so we need to ensure that the controller is not put back to powerdown + mode, until the I2C transaction finishes) + + +How to flash the firmware +------------------------- + +- If you have original firmware, it's enough to just run the flashing tool. +- If you have this firmware, you can enter flashing mode by pressing + FN + PINE + F +- If you have broken firmware, you need to short P90 (7th test pad from the left) + to GND and power cycle the keyboard controller. + - Power cycling requires powering down the connected pinehone and maybe + ensuring VOUT is disabled on the kb charger (can be done via I2C, + or by pressing the charger key) + - You need to keep P90 shorted until the flashing is complete. +- You can insert the flasing USB cable safely even with 5V/VBUS wire + connected regardless of whether the charger's VOUT is enabled or not. +- Flashing tool is configured by modifying the source code for now. + If your firmware grows, don't forget to increase the flashing area + size. Currently it's set to 0x2000 - 0x2600.