Skip to content

Updating Your Device

bunnie edited this page Dec 6, 2023 · 82 revisions

You can update your device by running the Precursor Updater (source).

First, run pip3 install precursorupdater --upgrade. It's highly recommended to check for updates, since earlier versions had significant bugs.

Then, run python3 -m precursorupdater to update an attached device; use --help to see the options available.

Platform support:

  • Linux (see udev rules)
  • Windows
  • Mac
  • Requires:
    • Python3.8+ (Ubuntu 18.04 is Python3.6, so 20.04 would be minimum LTS version)
    • requests >=2
    • pyusb >=1 (see PyUSB)
    • progressbar2 >= 3
    • pycryptodome

You can run the updater from source, assuming you've cloned xous-core already:

python3 tools/updater/precursorupdater/ --bleeding-edge

Or if you've only installed the pip package, you can run it just like this:

python3 -m precursorupdater --bleeding-edge

This would update your device to use the latest version of Xous in the CI builds. Without --bleeding-edge, it will load the latest stable release.

Once you have finished the update, you will need to reset the Precursor using a paperclip, as shown in the image below:

Resetting a Precursor after an update

Only perform the reset if the update was successful. If an update fails, you can try re-running it before you punch the reset button.


  • Update performance is slow on machines with buggy USB stacks, such as M1 Macs and AMD-based PCs. If you have one of these, try running the update on a Raspberry Pi.
  • If the device isn't enumerating, switch to shellchat and type usb debug. Apps such as vault lock out USB access by default.


You'll need these packages:

  • pip3 install pyusb progressbar2

Add a udev rule so you can access the device without sudo:

  1. Add a file called 99-precursor-usb.rules to /etc/udev/rules.d/:
cat <<EOF | sudo tee /etc/udev/rules.d/99-precursor-usb.rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="5bf0", GROUP="plugdev", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="3613", GROUP="plugdev", TAG+="uaccess"
  1. Run sudo udevadm control --reload-rules
  2. If the device was plugged in, you'll have to unplug it and plug it back in again for the new rules to take effect.

Windows 10

  • You will need to install python3 from the Windows App store if you don't already have it
  • use zadig to remap Precursor pvt2's Windows driver to libusb-win32
  • Run the command from a Powershell; elevated privs are not necessary after using zadig.

Users have reported trouble navigating the Zadig UI. Here is a guide:

zadig screenshot

  1. Select "Precursor pvt2" from the large pull-down box. Click the "Edit" checkbox if the menu is blank or unselectable.
  2. Select the driver to be "libusb-win32", using the red highlighted arrows, as shown in the right text box. You can ignore the text in the left box.
  3. Click the "Install Driver" (or "Reinstall driver") button (highlighted in green) once these settings are made. This step can take several minutes.

For Developers and Bricked Devices

If you have bricked your device, you will need to use the failsafe method to fix your device.

There's a very comprehensive guide on how to do updates, including manual and failsafe methods, at Updating for Advanced Users. For OG devs, this is also the original landing page for Updating.