Merge pull request #70 from system76/readme

readme: Add more information for flashing

README.md

@@ -28,7 +28,57 @@ source ~/.cargo/env
 ./scripts/qemu.sh
 ```
 
-### Flashing firmware manually is not recommended for the normal user. For the advanced user, there is a script flash.sh which takes the same arguments as build.sh
+## Flashing
+
+**Flashing firmware manually is *not* recommended for the normal user!**
+
+### Internal programmer
+
+Use this method for flashing a system already running System76 Open Firmware.
+
+```
+./scripts/flash.sh <model>
+```
+
+### External programmer
+
+Use this method for first-time flashing or flashing a bricked system.
+
+#### Creating a SPI Pi
+
+SPI Pi is a Raspberry Pi used to flash the SPI ROM. To create a SPI Pi:
+
+- Get a Raspberry Pi 2 or 3 with Ubuntu 16.04
+- Hook up a SPI clip to the SPI Pi
+  - The SPI Pi's SPI pinout can be found here: https://pinout.xyz/pinout/spi#
+  - The pinout of a SPI rom can be found here: https://www.totalphase.com/media/wysiwyg/soic8-pinout.png
+  - If you need more instructions, you should not be hooking up the SPI clip
+- Connect the SPI Pi's SPI clip to the SPI ROM, ensuring pin 1 of the clip aligns with pin 1 on the ROM
+- On the SPI Pi, run the following commands:
+
+```
+sudo apt install flashrom
+git clone https://github.com/system76/firmware-open.git firmware
+```
+
+#### Flashing with a SPI Pi
+
+1. Turn off the computer
+2. Remove the bottom panel
+3. Attach the clip to the SPI ROM chip
+4. Connect to the Raspberry Pi and wait it for boot
+```
+sudo tio -b 115200 /dev/ttyUSB0
+```
+5. From the RPi session, test that the chip is detected.
+```
+cd firmware
+./scripts/spipi.sh -r backup.rom
+```
+6. From the host, flash the firmware
+```
+SPIPI=<user@spipi> ./scripts/spipi-flash.sh <model>
+```
 
 ## Contents
 

README.md.in

@@ -28,4 +28,54 @@ source ~/.cargo/env
 ./scripts/qemu.sh
 ```
 
-### Flashing firmware manually is not recommended for the normal user. For the advanced user, there is a script flash.sh which takes the same arguments as build.sh
+## Flashing
+
+**Flashing firmware manually is *not* recommended for the normal user!**
+
+### Internal programmer
+
+Use this method for flashing a system already running System76 Open Firmware.
+
+```
+./scripts/flash.sh <model>
+```
+
+### External programmer
+
+Use this method for first-time flashing or flashing a bricked system.
+
+#### Creating a SPI Pi
+
+SPI Pi is a Raspberry Pi used to flash the SPI ROM. To create a SPI Pi:
+
+- Get a Raspberry Pi 2 or 3 with Ubuntu 16.04
+- Hook up a SPI clip to the SPI Pi
+  - The SPI Pi's SPI pinout can be found here: https://pinout.xyz/pinout/spi#
+  - The pinout of a SPI rom can be found here: https://www.totalphase.com/media/wysiwyg/soic8-pinout.png
+  - If you need more instructions, you should not be hooking up the SPI clip
+- Connect the SPI Pi's SPI clip to the SPI ROM, ensuring pin 1 of the clip aligns with pin 1 on the ROM
+- On the SPI Pi, run the following commands:
+
+```
+sudo apt install flashrom
+git clone https://github.com/system76/firmware-open.git firmware
+```
+
+#### Flashing with a SPI Pi
+
+1. Turn off the computer
+2. Remove the bottom panel
+3. Attach the clip to the SPI ROM chip
+4. Connect to the Raspberry Pi and wait it for boot
+```
+sudo tio -b 115200 /dev/ttyUSB0
+```
+5. From the RPi session, test that the chip is detected.
+```
+cd firmware
+./scripts/spipi.sh -r backup.rom
+```
+6. From the host, flash the firmware
+```
+SPIPI=<user@spipi> ./scripts/spipi-flash.sh <model>
+```

scripts/_spipi.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-SPIPI="ubuntu@10.17.89.179"
+SPIPI=${SPIPI:-"ubuntu@10.17.89.179"}
 
 if [ ! -d "models/${MODEL}" ]
 then

scripts/spipi-dump.sh

@@ -13,7 +13,7 @@ source scripts/_spipi.sh
 
 ssh -T "${SPIPI}" <<EOF
 cd firmware
-./spipi.sh -c "${CHIP}" -r dump.rom
+./scripts/spipi.sh -c "${CHIP}" -r dump.rom
 EOF
 
 sftp "${SPIPI}" <<EOF

scripts/spipi-erase.sh

@@ -13,5 +13,5 @@ source scripts/_spipi.sh
 
 ssh -T "${SPIPI}" <<EOF
 cd firmware
-./spipi.sh -c "${CHIP}" -E
+./scripts/spipi.sh -c "${CHIP}" -E
 EOF

scripts/spipi-flash.sh

@@ -18,5 +18,5 @@ EOF
 
 ssh -T "${SPIPI}" <<EOF
 cd firmware
-./spipi.sh -c "${CHIP}" -w "${MODEL}.rom"
+./scripts/spipi.sh -c "${CHIP}" -w "${MODEL}.rom"
 EOF

scripts/spipi.sh

@@ -0,0 +1 @@
+sudo flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=24000 "$@"