Document where to find/download latest CircleCI builds

[tlaurion]

---

End-users:

• CircleCI builds for each accepted change. In Github/Git terms, that means, for each commit pushed in the project. So all accepted commits are here: https://github.com/osresearch/heads/commits/master

• CircleCI also builds Pull Requests (PR). The same logic below applies to PR, but you will see the red/green mark in the PR itself. Clicking green marks will bring you to downloadable artifacts for a board, including ROMs.

---

Code contributors:

• If you are the owner of a PR, it is highly suggested to login on CircleCI and have CircleCI follow your own Heads reprository. That way, each time you push a commit, CircleCI will build all the boards on your own time. You will also be the owner of your own CircleCI instance, meaning that if for whatever reason, you need to kick a stalled build, you will be able to from CircleCI.

For commits pushed together, you will see a red X (for builds that failed) and a green mark for builds that were successful.

To access a build ROM for a specific board, taking x230-htop-maximized as an example:

• Click latest green mark at https://github.com/osresearch/heads/commits/master and note the Commit ID (7 characters hexadecimal value, which will be in the name of the ROM you will download later)
• This opens the list of boards for which ROMs have been built. Click on a board name "details" ( here x230-hotp-maximized ). This brings you to CircleCI for a specific "Job" (which is the board build you selected).
• Click on the "Make board" Open in a Tab link. This opens the build log for that board builld, where the last lines there show the sha256sum hashes of the ROM(s) that have been built fro that board.
• Click the Artifacts tab (Artifacts are kept results for 30 days, including logs, ROMs, hashes etc)
• Right-click a ROM, save as.. and decide where you want to keep it. We take for granted here that it is in the Downloads directory of the current qubes (Depending of browsers's internals, some will open the ROMs as text. We do not want that which is why "Save as..." is suggested.

To verify hashes:

• Open a Terminal in the same qube the rom was downloaded from.
  • Type sha256sum ~/Downloads/heads-x230-hotp-maximized*
  • Compare the hash value you get at the console from what was obtained from the "Make board" tab you opened earlier. They should match.

To copy that rom to a USB thumb drive:

• On that same terminal, qvm-copy ~/Downloads/heads-x230-hotp-maximized* and select sys-usb.
• Open Files application on sys-usb qubes.
  • Plug your formatted ext3/ext4 thumb drive. Mount it. Go to your Home directory, click QubesIncoming, select the qubes directory name from which you copied the rom from. Move the rom image on your USB thumb drive. Eject the device.

Flashing instructions depends of what you current running firmware is. If you already run a Maximized rom, you can upgrade the firmware from the Graphical Interface. Otherwise, please refer to https://osresearch.net/Prerequisites#legacy-vs-maximized-boards. Basic instructions are below, but only proceed if you are sure what you are doing, otherwise a brick could occur.

---

What to download:
For maximized boards already flashed externally:

• Download the non top/bottom rom.

For maximized board non already flashed externally:

• Download top + bottom rom files and flash externally.

For the PrivacyBeast (and other KNOWN TO BE UNLOCKED IFD AND UNLUCKED ME regions on initial external flashing of bottom SPI ( or those having followed https://osresearch.net/Clean-the-ME-firmware/):

• Download non top/bottom rom (12mb rom image)
• DO NOT USE HEADS FLASH MENU TO FLASH INTERNALLY INITIAL MAXIMIZED ROM. Instead:
  • From recovery shell:
    • mount-usb
    • sha256sum /media/ADDITIONAL_PATH_TO/heads-xx30-hotp-maximized-12mb.rom (Double verify that the hash corresponds to the hash of the file you downloaded. If different, do not proceed)
    • flashrom --force --noverify-all -p internal -w /media/ADDITIONAL_PATH_TO/heads-xx30-hotp-maximized-12mb.rom

For non maximized board (legacy) non already flashed externally

• Consider using maximized boards (and external initial flashing of SPI chip(s)!)
• If initial flashing is not possible:
  • Download corresponding board flash board's ROM (x230-flash, t430-flash) and flash externally (1vyrain too...)
  • Download corresponding board ROM (x230/t430, x230/t430-hotp-verification) (applies to skulls->heads upgrade)

Comments/Help welcome to turn this into a PR.

[tlaurion]

Take into consideration linuxboot/heads#920 (comment)

[tlaurion]

Fixed as part of #93