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/2, Microchip SAMA5, NXP i.MX6/7/8/93, TI AM335x, Allwinner SUNXI, TI AM62x, TI AM64x, TI AM62Lx and Xilinx ZynqMP. Please check supported_socs.yaml or run snagrecover --list-socs for a more precise list of supported SoCs.

Installation on Linux

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

Installing the gui variant: python3 -m pip install --user snagboot[gui], provides the additional "snagfactory" command.

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
OR
$ ./install.sh --with-gui

There is also an AUR package available.

Installation on Windows 10 or 11

Note: Am335x devices are not supported on Windows!

Snagboot requires the "libusb-win32" driver to be bound to any device it processes apart from i.MX and SAMA5 devices, which already have their own s. This can be done using the Zadig tool which you can obtain here.

After opening Zadig, select the device entry corresponding to your board's VID:PID pair.

Then, make sure the "libusb-win32" driver is selected and click on "Install driver". You should only have to do this once for a given VID:PID pair.

Powershell is required by Snagboot, but it should already be installed.

Option 1: Using the snagboot installer

An executable installer based on PyInstaller and InnoSetup can be downloaded from the latest Snagboot release.

Option 2: Using pip

Please install the following software:

After installing Python, Swig and libusb, you should add them to your PATH environment variable:

  • Open the start menu and type « environment variable » into the search bar
  • click on « Edit environment variables for your account »
  • In « User variables », click on « Path » then « Edit »
  • In the edit window, add four new paths:
C:\Users\path\to\swigwin-4.2.1\swigwin-4.2.1
C:\users\yourusername\appdata\roaming\python\python312\site-packages\libusb\_platform\_windows\x64
C:\users\yourusername\appdata\roaming\python\python312\site-packages\libusb\_platform\_windows\x32
C:\Users\yourusername\AppData\Roaming\Python\Python312\Scripts

setuptools: Run pip install setuptools then pip install snagboot in powershell

Usage guide

Note: On Linux, 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

For recovering and flashing large batches of boards efficiently, you may use the Snagfactory application which is included in Snagboot. Usage instructions for Snagfactory are available at snagfactory.md. The configuration file syntax for Snagfactory is documented at snagfactory_config.md.

Note that Snagfactory support is only included in the "gui" package variant: pip install snagboot[gui]

Some benchmark results are provided in the Snagfactory docs.

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-2.3.tar.gz (171.7 kB view details)

Uploaded Source

Built Distribution

snagboot-2.3-py3-none-any.whl (216.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: snagboot-2.3.tar.gz
  • Upload date:
  • Size: 171.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.1

File hashes

Hashes for snagboot-2.3.tar.gz
Algorithm Hash digest
SHA256 c6a97ea0c83a2d7eea639741b2f667c75e95d50278eeb6a8adbce5d1a7cf65fa
MD5 885a929681452e82c0bce18cab60c68f
BLAKE2b-256 32d01b227ecbf52e12833d035e6a68a2b827e6accdb703a2581f5e878cdce6d6

See more details on using hashes here.

File details

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

File metadata

  • Download URL: snagboot-2.3-py3-none-any.whl
  • Upload date:
  • Size: 216.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.1

File hashes

Hashes for snagboot-2.3-py3-none-any.whl
Algorithm Hash digest
SHA256 11feedd9935aa52d9f228b5eb4e633904531331802c5193abb70bc0ebc3e56a5
MD5 03be42105489db62a6c118502b8e615b
BLAKE2b-256 4d943e75473152eddb9fac4b13fcfb8e1c64f1e48e120045207891139df67608

See more details on using hashes here.

Supported by

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