Skip to main content

Generic recovery and reflashing tool for embedded platforms

Project description

Snagboot

Snagboot intends to be an open-source and generic replacement to the vendor-specific, sometimes proprietary, tools used to recover and/or reflash embedded platforms. Examples of such tools include STM32CubeProgrammer, SAM-BA ISP, UUU, and sunxi-fel. Snagboot is made of two separate parts:

  • snagrecover uses vendor-specific ROM code mechanisms to initialize external RAM and run U-Boot, without modifying any non-volatile memories.
  • snagflash communicates with U-Boot to flash system images to non-volatile memories, using either DFU, UMS or Fastboot.

animated

The currently supported SoC families are ST STM32MP1, Microchip SAMA5, NXP i.MX6/7/8, TI AM335x, Allwinner SUNXI and TI AM62x. Please check supported_socs.yaml or run snagrecover --list-socs for a more precise list of supported SoCs.

Installation

System requirements:

  • libusb 1.x, libusb 0.1.x or OpenUSB
  • The ensurepip Python package. On Debian, you can install the python[your python version]-venv package
  • Swig is required to build pylibfdt. You can simply install the swig package on most distros.

Snagboot is available on pip: python3 -m pip install --user snagboot.

This package provides two CLI tools:

$ snagrecover -h
$ snagflash -h

You also need to install udev rules so that snagrecover has read and write access to the USB devices exposed by the SoCs.

$ snagrecover --udev > 50-snagboot.rules
$ sudo cp 50-snagboot.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

These rules work by adding the "uaccess" tag to the relevant USB devices. Systemd will then add an ACL to give access to currently logged in users. More info here.

Warning: If your distro does not use systemd, the "uaccess" method could possibly not work. In this case, make sure to customize the provided udev rules for your specific system.

Alternatively, Snagboot can be installed as a local Python wheel. An installation script is provided to automatically build and install the package.

$ cd snagboot
$ ./install.sh

There is also an AUR package available.

Usage guide

Note: Running snagboot as root is not recommended and will typically not work, since it is probably installed for the current user only

To recover and reflash a board using snagboot:

  1. Check that your SoC is supported in snagrecover by running: snagrecover --list-socs
  2. Setup your board for recovery
  3. Build or download the firmware binaries necessary for recovering and reflashing the board.
  4. Run snagrecover and check that the recovery was a success i.e. that U-Boot is running properly.
  5. Run snagflash to reflash the board

If you encounter issues, please take a look at the troubleshooting section.

You can play the snagrecover tutorial in your terminal!

sudo apt install asciinema
asciinema play -s=2 docs/tutorial_snagrecover.cast

Contributing

Contributions are welcome! Since Snagboot includes many different recovery techniques and protocols, we try to keep the code base as structured as possible. Please consult the contribution guidelines.

License

Snagboot is released under the GNU General Public License version 2

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

snagboot-1.3.tar.gz (79.9 kB view details)

Uploaded Source

Built Distribution

snagboot-1.3-py3-none-any.whl (116.5 kB view details)

Uploaded Python 3

File details

Details for the file snagboot-1.3.tar.gz.

File metadata

  • Download URL: snagboot-1.3.tar.gz
  • Upload date:
  • Size: 79.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.9.2

File hashes

Hashes for snagboot-1.3.tar.gz
Algorithm Hash digest
SHA256 b9d781bdc79d92d940e27d89d3025eab6dc459087dad126766e2bf76dc9dddee
MD5 a2efdf6f8d7a731e66cb145acf143200
BLAKE2b-256 d2b115cbb5ba120e8f0076a6b1e578b00c197545d822f2e2a3806ba1097bf6d1

See more details on using hashes here.

File details

Details for the file snagboot-1.3-py3-none-any.whl.

File metadata

  • Download URL: snagboot-1.3-py3-none-any.whl
  • Upload date:
  • Size: 116.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.9.2

File hashes

Hashes for snagboot-1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 79c701c2267ac035eb722fafa4e9d7f91eac9c10977812fc94d21a44d4aa07f0
MD5 26fd75b57499a542224b4160271ed237
BLAKE2b-256 3a3a156a5ac5508fc882da81c780a1c439be885472641f43bbaabe941cb68062

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page