2021–06–20:
Pinephone keyboard's firmware I2C interface
I've implemented a USB
stack for the pinephone keyboard's firmware, to be able to perform
printf
debugging and tracing of what the MCU does. It's now
possible to see MCU's operation using a simple USB debugging
tool that shows the output from debugging code on the MCU in real-time.
I've used the new debugger it to get to understand precise behavior of I2C
slave peripheral. How interrupts are fired, and what's the contents of
various status registers during various I2C transfers from the pinephone SoC
over POGO pins.
This understanding can be used to write a more proper I2C control interface
for the keyboard, that will be modelled as is typical with various other I2C
devices a set of I2C „registers“ that can be read from and written to. The
proposed specification for the register set is here. It
will be possible to configure the keyboard's scanning behavior in various ways
over the I2C, and perform self-tests for QA purposes.
I've also finalized the USB flashing
tool. It now has a very nice interface and is quite useable and better
documented.
Samuel shared his keyboard kernel
driver recently. So you'll have a choice between kernel and userspace
drivers for the keyboard. Both have their strengths. Userspace one will be
easier to
customize and play with, and the kernel one will be more available and
better integrated into kernel's suspend/resume functionality, I assume.
User firmware
From factory the keyboard will come with the stock keyboard firmware. This
firmware will occupy code memory from addresses 0x2000
to
0x3fff
. The stock firmware will also have a I2C flashing interface,
whose proposed workings are described
here.
The superpower users will be able to write their own firmware, and flash it
to the keyboard over I2C directly from the phone, without having to disassemble
the keyboard and solder on a USB cable. ;) This firmware will not overwrite the
stock firmware, but it will be placed at addresses 0x4000
to
0x7fff
, after the stock firmware. If the user firmware is flashed,
it will run instead of a stock firmware.
There will be a short time window where the stock firmware will wait for a
I2C transactions prior to defering execution to user firmware after MCU reset.
This window can be used to prevent the jump to user firmware, and stay in the
stock one. This will be the mechanism for recovery in case the user flashes
incorrect or borken user firmware.
This mechanism can be used to:
- fix issues in the stock firmware in the field, or
- to allow a completely differnt way of implementing the keyboard
functionality, for example by implementing a standard I2C HID interface instead
of the propsed non-standard one, or
- to add more functionality to the keyboard by using free GPIO on the
keyboard's micorcontroller to perform HW modifications (there's some free
space inside the keyboard), and hook up some extra peripherals to the MCU and
expose them over I2C to the phone.
Power user based hardware or firmware modding the keyboard is quite a likely
possibility when everyhting is developed in the open using FOSS licensing, with
focus on making this relaitvely easy.
I'll propose exposing the free GPIOs as solder pads for the final revision of
the keyboard's PCB.
There's just enough free space in the keyboard's body for a little drilling
and eg. adding proximity sensor (to detect whether the lid is closed or not), to
add notification LEDs visible when the KB is closed, etc.
You can also make much more space inside the keyboard by removing the
battery, and replacing it with your own hardware. You may also expose GPIOs
externally by adding a new connector to the keyboard body, and have some simple
pluggable peripherals.
Next steps
Next, it's necessary to implement the proposed I2C interface. Most
complicated part of which is the flashing interface, which will require further
reverse engineering of the original USB bootloader, because code ROM flashing
registers are not documented.
Once that is done, it will be necessary to again look at making the MCU
operation as low power as possible, by using the power down and green modes of
the MCU.
Charger interface
Charger's I2C interface will still need quite a bit of thought. There's an
issue that the charger chip multiplexes I2C interface with the LED notification
pins, and detects what kind of interface is used by checking the voltage on the
I2C pins whenever it wakes up, which is not predictable.
I2C interface is shared with the keyboard's MCU, so if charger wakes up when
the MCU is communicating with the SoC, it may see low voltage on I2C pins, and
misdetect the interface as LED one, and start driving it as such and break
communication between MCU and SoC.
Samuel also identified another way the charger can break I2C interface, and
that's when the phone is off, and thus it does pull I2C SDA/SCL lines low via
10 kOhm pull-ups to DCDC1 on the SoC side, the voltage on I2C lines will be
just ~1.5V, which is not enough to make the charger think I2C interface is used,
and it again switches to LED driving mode.
We need to figure out some way to prevent this from happening.
The last proposal is to add mosfets between charger I2C pins and the POGO I2C
pins, with gate connected to INT pin. When the INT pin is low (because
it's driven low by MCU, or because DCDC1 is off, because the phone is off),
these mosfets would disconnect the charger I2C pins from the POGO ones, and this
would make the charger always detect the I2C interface mode correctly. It would
also be possible for the SoC to disconnect the charger from I2C interface at any
time by driving the INT pin low during I2C communication with the MCU.
Lastly when the phone is off, this would save some power by cutting off the
path between „grounded“ DCDC1 and pull-ups to VREG (always on 3.1V linear
regulator inside the keyboard charger chip).