Table of contents
  1. Downloading Heads ROMs
    1. What board configuration should I choose?
    2. Downloading ROM files for initial flashing
    3. Internal upgrading from ZIP files
    4. Caution for Rolling Releases

Downloading Heads ROMs

What board configuration should I choose?

Please refer to the devices compatibility matrix.

Downloading ROM files for initial flashing

If you are performing an initial external flash, follow these steps to download the required ROM files and verify their integrity:

  1. Access CircleCI Builds:
    • Go to the Heads GitHub repository and click on the latest commit’s green checkmark. Github-green-circle-ci-checkmark
    • This will display a list of CircleCI jobs. Locate the job corresponding to your board’s name and click the “Details” link. CircleCI-list-of-boards-in-pipeline
  2. Navigate to Artifacts:
    • On the CircleCI job page, click the “Artifacts” tab to view the output files of the build. CircleCI-page-showing-artifact-tabs
  3. Download Required Files:
    • Download the following files by right-clicking their links and selecting “Save Link as…”: CircleCI-artifacts-tabs-showing-files-including-hashes-txt
      • *.rom files (e.g., top.rom and bottom.rom for two SPI chip boards).
      • hashes.txt file containing the SHA256 hashes of the ROM files.
  4. Verify ROM File Integrity:
    • Use sha256sum or an equivalent tool to compute the hash of the downloaded ROM files.
    • Compare the computed hash with the corresponding entry in the hashes.txt file to ensure the files are valid.
  5. Prepare for Flashing:
    • Save the verified ROM files and hashes.txt to the computer or USB drive that will be used for external flashing.

For more details on external flashing, refer to the Upgrading documentation.

Internal upgrading from ZIP files

If you are upgrading an existing Heads installation, you can use the ZIP file provided in the CircleCI artifacts:

  1. Download the ZIP File:
    • From the CircleCI “Artifacts” tab, download the ZIP file corresponding to your board.
  2. Transfer to Target System:
    • Save the ZIP file to a USB drive and transfer it to the target system.
  3. Perform the Upgrade:
    • Use the Heads GUI to upgrade the firmware by selecting the ZIP file. This method automatically verifies the ROM integrity and flashes the firmware.

Note: Internal upgrading via ZIP files is supported for firmware versions built after this November 2023 commit.

For more details on internal upgrading, refer to the Upgrading documentation.

Caution for Rolling Releases

Heads is a rolling release. If you do not have an external programmer, refer to the Upgrading documentation for important precautions before upgrading. This includes:

  • Waiting for community testing and reviewing reported issues to avoid potential regressions.
  • Understanding the implications of UNTESTED and UNMAINTAINED labels in board names. For more details, refer to the UNTESTED and UNMAINTAINED boards documentation.

For more details on upgrading, refer to the Upgrading documentation.