{"id":24005324,"url":"https://github.com/betrusted-io/betrusted-scripts","last_synced_at":"2025-04-15T02:08:40.096Z","repository":{"id":36836426,"uuid":"202381046","full_name":"betrusted-io/betrusted-scripts","owner":"betrusted-io","description":"Shell scripts for debugging and flashing betrusted","archived":false,"fork":false,"pushed_at":"2024-09-21T15:19:31.000Z","size":146,"stargazers_count":4,"open_issues_count":2,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-15T02:08:34.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/betrusted-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-14T15:47:54.000Z","updated_at":"2024-09-21T15:19:35.000Z","dependencies_parsed_at":"2025-01-08T02:55:23.373Z","dependency_job_id":"7009c73c-ccaf-4904-a1b0-f845abfe9897","html_url":"https://github.com/betrusted-io/betrusted-scripts","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fbetrusted-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fbetrusted-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fbetrusted-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fbetrusted-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/betrusted-io","download_url":"https://codeload.github.com/betrusted-io/betrusted-scripts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991544,"owners_count":21194894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-08T02:54:48.553Z","updated_at":"2025-04-15T02:08:40.081Z","avatar_url":"https://github.com/betrusted-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# betrusted-scripts\n\nScripts to provision Precursor using a Raspberry Pi plus the Raspberry Pi debug hat.\n\nIf you're just looking to update your device, perhaps this would be a\nbetter starting point:\n\nhttps://github.com/betrusted-io/betrusted-wiki/wiki/Updating-Your-Device\n\n## Setup\n\nThe core scripts most users will want to use are `update_xous.sh`, `config_up5k.sh`,\nand `wfx_image.sh`. These are all in the root level of this repository.\n\nThese scripts assume the following file structure:\n\n```\n/home/pi/\n   |\n  code---\n        |\n        ------ betrusted-scripts    \u003c-- this repo\n        |\n        ------ precursors           \u003c-- where firmware artifacts (built on another computer) are staged\n\t|\n\t------ fomu-flash           \u003c-- https://github.com/betrusted-io/fomu-flash\n```\n\nThis repo uses submodules, so be sure to either clone using `--recursive` or call a\n`git submodule init \u0026\u0026 git submodule update` after cloning.\n\nNote that the `jtag-tools` has dependencies, please consult its README file on how to\nsetup and install.\n\nFurthermore note that you will need [fomu-flash](https://github.com/betrusted-io/fomu-flash) installed\nand built for the Pi. Please refer to its repo for compilation and installation instructions.\n\nIf you want GDB debugging capability, you may also want to install [wishbone-tool](https://wishbone-utils.readthedocs.io/en/latest/wishbone-tool/) and plug Precursor's USB port into the Raspberry Pi's USB port.\n\n## Xous Updates\n\nThis flow assumes you have initialized your root keys, and that you are just looking to apply a built-from-source update.\n\n1. Check out [xous-core](https://github.com/betrusted-io/xous-core)\n1. Run the build \u0026 stage script for [linux](https://github.com/betrusted-io/xous-core/blob/main/buildpush.sh) or [windows](https://github.com/betrusted-io/xous-core/blob/main/buildpush.bat). This will stage `soc_csr.bin`, `xous_img.bin`, and `loader.bin` into the `precursors` directory.\n1. Alternatively, download the [bleeding-edge binaries](https://ci.betrusted.io/latest-ci/) and copy them to the `precursors` directory.\n1. Run `update_xous.sh`. Specify any one of `-f`, `-l`, or `-k` to _skip_ burning any of the FPGA, loader or kernel images.\n1. Choose `Install gateware update` from the main menu.\n\n## Unbricking \u0026 Factory Reset\n\n\"Firmware artifacts\" are binary files that correspond to various\nsections of the device firmware. If you are simply trying to flash\nyour device from a pre-build, you would receive an archive of the\nbinaries and extract them into the `precursors` directory.\n\nCopies of the bleeding-edge binaries can be found [on the CI\nserver](https://ci.betrusted.io/latest-ci/). They aren't stable, but\nif you also don't want to set up a build environment, it's the fastest\nway to get started. As of writing, there is not yet a \"stable\" release\nprocess for Precursor.\n\nIf you are trying to build everything from scratch, there are corresponding\nscripts in the firmware generation directories for:\n\n- Xous ([xous-core](https://github.com/betrusted-io/xous-core/blob/main/buildpush.sh))\n- the EC image (betrusted-ec - run `cargo xtask push [ip address] [ssh ID file]` in the root of the repo)\n\nNote that you should build *either* Xous *or* the validation firmware image. At the time of writing, it's strongly\nencouraged that you build for Xous, as Xous is actively maintained and the validation firmware (which was used mainly\nfor hardware board bringup) is soon to be depracated.\n\nThese scripts will build firmware images and copy them to the `code/precursors` directory on the target\nRaspberry Pi automatically, once you specify the IP address of the Pi and a ssh private key file (if used).\n\nHere is a description of the relevant commands, in the order that you would execute them to bring up a board \"from factory blank state\" (that is, with brand new, blank FLASH memories everywhere):\n\n- `wfx_image.sh` will write the firmware blob for the SiLabs WF200 to the EC's SPI memory space. Note that the WF200 is an untrusted entity, and the system trusts the WF200 precisely as much as it would trust any cable modem or core router. The firmware image comen from within the `wfx-firmware` submodule within this repo.\n- `config_up5k.sh` will set the QE bit of the EC SPI memory and provision an image located in `precursors/bt-ec.bin` onto the EC SPI. This effectively provisions the EC.\n- `provision_xous.sh` will do a factory reset of your Precursor. This is also the script to use if you have **not** initialized root keys on the device (that is, it's already in a factory-new state). It burns an FPGA image `precursors/encrypted.bin`, a firmware file `precursors/xous.img`, and a loader `precursors/loader.bin` to the correct locations in SoC FLASH space.\n\nNote that an \"encrypted\" image is used for the FPGA by default; however,\nfor FPGAs that have not been sealed by the end user, the encrypted image\nis encrypted by default to the \"dummy key\", e.g. an AES key of all 0's.\n\n## Fused-locked Devices\n\nDevices where the eFuse has been blown \u0026 secured will only accept SoC images that are\nencrypted to the device's key. As JTAG burning of the FLASH requires loading an intermediate\nbitstream, this intermediate bitstream must be encrypted to your device.\n\nIf you have the backup key of a fuse-locked device, you can use the scripts here\nto unbrick a device. You can specify the backup key with the `--key` argument to\neither `update_xous.sh` or `provision_xous.sh` scripts.\n\nThe script will always accept a key that is formatted as a hex string. If you have\na recent enough version of Python that you can run `bip_utils` (`pip3 install bip_utils`),\nyou can directly pass your BIP-39 key to the script by providing it as an escaped quoted\nstring, e.g. `--key \"\\\"canoe lift art ...\\\"\"`.\n\nHowever, Rasbpians version \"Stretch\" or older ship with a Python that is too old for\n`bip_utils`. In this case, you need to translate the BIP-39 phrase into the \"entropy\"\nas a hex string using another utility.\n\n## Other scripts\n\nSome other scripts included here:\n\n- `vbus.sh` -- takes an argument `0` or `1` to turn off or on the power to Precursor. Do not turn on power to Precursor if you have it already plugged into a charger. This script is mostly useful for low-level debug of stand-alone boards.\n- `uart_fpga.sh` -- mux the SoC UART to the Rpi `/dev/ttyS0`\n- `uart_up5k.sh` -- mux the EC UART to the Rpi `/dev/ttyS0`\n- `reset_soc.sh` -- pulls the PROG_N line on the SoC, forcing it to reload. Also resets the SPI ROM out of OPI mode.\n- `reset_ec.sh` -- pulls the CRESET_B line on the EC, forcing it to reload.\n- `start_gdb*.sh` -- will start `wishbone-tools` wish some defaults that enable variations of GDB connectivity, either via USB, TTY, or otherwise. Assumes `crossover` UART unless `-noterm` is used. Requires a .csv file that describes the FPGA in question, which should be provisioned automatically if you use the `buildpush.sh` script in the correpsonding FPGA's repo.\n\n## Limitations\nThere is a hard cap on the size of a bitstream that can be handled by the script, due\nto an FFI array that is pre-allocated. It is 20Mbits, or about 2.9Mbytes. The script will\nalso segfault if you try to readback-verify very large files (\u003e3.5MiB or so); this may be due\nto stack size limitations imposed by the shell environment. This is because readback verification\nis done in a \"single shot\" into a large buffer (for performance reasons). Programming a binary\ndoes not have a parallel limitation because files are broken into erase-sector sized blocks and\niteratively programmed. In pracitce, I have never seen a verify failure, so for large files\nI just drop the verification step.\n\n# BBRAM key provisioning\n\nThe BBRAM key is an ephemeral (battery-backed) key for the FPGA. You should use this if you have high value,\nephemeral secrets you wish to protect. Don't use it for archival (because when the battery dies you lose\nyour data). It's also useful for development.\n\nThe 7-Series FPGA is unable to provision its own BBRAM key, unfortunately. It needs help of an external tool\nto receive the secret material and turn it into JTAG commands. `bbram_helper.py` is a script that does this.\nWhile it creates no files or intentionally permanent record of the key, if you are worried about safety:\n\n- Run this on a use-once Raspberry Pi that has been airgapped from the network\n- Turn off the device immediately after provisioning\n- Wait at least few minutes (so the DRAM cells fully discharge) before powering on again\n- Ideally, destroy the microSD card used to boot the image, just in case portions of RAM were committed to disk (e.g. as swap).\n\n## Prerequisites\n\nYou will need to install the following packages  (installed via `pip3 install` or `pip install` based on your distro):\n\n- `pexpect`\n- `pycrypto`\n- `cffi`\n- `progressbar2`\n\n## Running\n\n1. Connect the Precursor device to a Raspberry Pi via the debug HAT (see https://github.com/betrusted-io/betrusted-wiki/wiki/Updating-Your-Device#failsafe-method)\n1. Boot the Precursor device\n1. Run `./bbram_helper.py` and follow the on-screen instructions\n\n# Contribution Guidelines\n\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details on\nhow to make a contribution.\n\nPlease note that this project is released with a\n[Contributor Code of Conduct](CODE_OF_CONDUCT.md).\nBy participating in this project you agree to abide its terms.\n\n## License\n\nCopyright © 2021\n\nLicensed under the [GPL-3.0](https://opensource.org/licenses/GPL-3.0) [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetrusted-io%2Fbetrusted-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetrusted-io%2Fbetrusted-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetrusted-io%2Fbetrusted-scripts/lists"}