pinephone-keyboard/README.flashing
Ondrej Jirman 6a5fe581b9 Implement flashing over I2C and user/stock firmware support
I2C register layout changed a bit to make various operations easier
to implement in FW and for the user.

Flashing/debugging tools now share more code. Firmware is now more
configurable (it's now possible to compile-out various features).

Self-testing for column-shorts is implemented.

Firmware is optimized for low power consumption.
2021-06-28 15:09:47 +02:00

118 lines
4.0 KiB
Plaintext

Flashing over USB
=================
This method allows updating the stock firmware on the keyboard.
Flashing tool ppkb-usb-flasher can be used to flash the firmware over USB.
You'll have to solder USB cable to the keyboard controller board to be able
to user this method.
For example to build and flash your own firmware you could run these
commands:
# save the original firmware in case you want to restore it
./ppkb-usb-flasher info > saved-info.txt
./ppkb-usb-flasher --rom-out saved-rom.bin read
# build the new firmware (you may need sdcc 4.1, older versions may
# miscompile the firmware)
(cd firmware && ./build.sh)
# flash the new firmware
./ppkb-usb-flasher --rom-in firmware/build/fw-stock.bin write reset
Full help output
----------------
Usage: ppkb-usb-flasher [--rom-in <path>] [--rom-out <path>] [--verbose]
[--help] [<read|write|info|reset>...]
Options:
-i, --rom-in <path> Specify path to binary file you want to flash.
-o, --rom-out <path> Specify path where you want to store the contents
of code ROM read from the device.
-s, --size <size> Specify how many bytes of code rom to flash
starting from offset 0x2000 in the rom file.
-v, --verbose Show details of what's going on.
-h, --help This help.
Commands:
info Display information about the firmware.
read Read ROM from the device to --rom-out file.
write Flash ROM file to the device from --rom-in.
reset Perform software reset of the MCU.
Format of the ROM files is a flat binary. Only the part of it starting
from 0x2000 will be flashed. Use -s to specify how many bytes to write.
Flashing over I2C
=================
This method users stock stock firmware's flashing interface to allow writing
user's own firmware to the keyboard, while keeping the stock firmware intact.
Stock firmware will remain present and available for future updates of the
users fiwmare.
You can use this method without having to disassemble the keyboard, or
solder anything.
You'll need to build the user firmware in a special way, so that it's placed
at address 0x4000 in code ROM. Interrupt vectors are forwarded with 0x4000
offset.
For example to build and flash your own firmware you could run these
commands:
# build the new firmware (you may need sdcc 4.1, older versions may
# miscompile the firmware)
(cd firmware && ./build.sh)
# flash the new firmware
./ppkb-i2c-flasher --rom-in firmware/build/fw-user.bin write reset
Depending on the user firmware, you may need to change stock firmware entry
method using -e option.
Full help output
----------------
Usage: ppkb-i2c-flasher [--rom-in <path>] [--rom-out <path>] [--verbose]
[--help] [<read|write|erase|info|reset>...]
Options:
-i, --rom-in <path> Specify path to binary file you want to flash.
-o, --rom-out <path> Specify path where you want to store the contents
of code ROM read from the device.
-s, --size <size> Specify how many bytes of code rom to flash
starting from offset 0x4000 in the rom file.
-e, --entry <manual|i2c|none>
Specify how to enter the stock firmware:
- manual: Ask the user to power-cycle the keyboard
- i2c: Send I2C command to make supporting user
- none: Assume stock firmware is already running
-v, --verbose Show details of what's going on.
-h, --help This help.
Commands:
info Display information about the current firmware.
read Read ROM from the device to --rom-out file.
write Flash ROM file to the device from --rom-in.
erase Erase the user firmware.
reset Perform software reset of the MCU.
Format of the ROM files is a flat binary. Only the part of it starting
from 0x4000 will be flashed. Use -s to specify how many bytes to write.
The stock firmware between 0x2000 and 0x4000 will be preserved.