Unbricking your VOXL 2

Recover a VOXL 2 that no longer boots or appears over ADB.

Table of contents

1. Summary
   1. Check the USB mode first
   2. How does it work?
2. Usage
   1. Prerequisites
   2. Build
   3. Image Download
3. Flash
   1. Flash Flat Build (Runtime: ~3-5 mins)
   2. If the flash fails to open UFS
   3. If the device still shows 900e or boot loops after a successful flash
4. Next Steps

Summary

If you have corrupted your VOXL’s filesystem (if ADB is unable to detect your VOXL, this is a common sign), follow this guide.

This process will perform a factory reset. All data on the VOXL will be wiped.

Back up /data/modalai before you flash. The flat build erases it, and it holds the camera and IMU calibration files, including the tracking camera intrinsics that ModalAI calibrates at the factory. Once overwritten, those files cannot be recovered from the board. If the board is still reachable over ADB, pull the directory to the host first:

adb pull /data/modalai ./modalai-backup

After the SDK has been reinstalled, copy back only the calibration files (voxl-imu-server.cal and the opencv_*_intrinsics.yml / opencv_*_extrinsics.yml files) with adb push, rather than the whole directory, so the freshly installed configuration files are not overwritten. PX4 sensor calibration lives separately under /data/modalai/px4/ (/data/px4/param/ on SDK 1.6 and older) and is also erased; back it up the same way if you want to keep it. If the board is already unreachable, ModalAI keeps production calibration backups; see Verifying Camera Calibration for how to request them.

Check the USB mode first

Before flashing, run lsusb on the host with only power and USB connected to the VOXL 2. The USB ID shows which state the board is in:

How does it work?

We use Qualcomm’s tool for unbricking Snapdragon devices called QDL.

Snapdragon based devices contain a special mode of operation, called Emergency Download Mode (EDL). In this mode, the device identifies itself over USB as 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode) and can communicate with a PC host.

EDL mode itself implements the Qualcomm Sahara protocol, which accepts an OEM-digitally-signed programmer over USB. The programmer implements the Firehose protocol which allows the host PC to send commands to write into the onboard storage (UFS).

An open source tool (for Linux) that implements the Qualcomm Sahara and Firehose protocols has been developed by Linaro, and can be used to program (or unbrick) Snapdragon based devices.

Usage

Prerequisites

sudo apt install gcc

sudo apt remove --purge modemmanager

sudo systemctl stop ModemManager
sudo systemctl start ModemManager

brew install libusb
brew link libusb

Build

1. Clone the modal-qdl repository and install its dependencies:

   git clone git@gitlab.com:voxl-public/system-image-build/modal-qdl.git
   cd modal-qdl
   ./install_dependencies.sh
   

2. Copy the qdl binary into /usr/local/bin:

   cp ./qdl/qfil_app/modules/qdl /usr/local/bin
   

3. Run qdl and check that it prints its usage line:

   $ qdl
   
   qdl [--debug] [--storage <emmc|nand|ufs>] [--finalize-provisioning] [--include <PATH>] <prog.mbn> [<program> <patch> ...]
   

Image Download

Flat build images are hosted in the Flat Builds folder on the ModalAI downloads site (downloads.modalai.com). A free account is required to download them. Do not use images from any other source.

If the account verification email does not arrive, check your spam folder. If it still has not arrived, post on the ModalAI Forum or contact support with your board part number and we will get you access.

Download the zip that matches your hardware:

To tell M0054-1 and M0054-2 hardware apart, see VOXL 2 HW Versions.

Unzip the downloaded release into ./qdl/qfil_app/modalai in the repository, then start the web UI and open http://127.0.0.1:8000/:

./run.sh

Flash

Flash Flat Build (Runtime: ~3-5 mins)

1. Slide the SW2 switch to ON to force the VOXL 2 into EDL mode.

   

2. Plug in power, then the USB-C cable from the VOXL 2 to the host.
3. In the web UI, pick the flat build that matches your hardware, click Select Build, then Flash Flat Build.
4. Wait for the log to end with Flash flat build passed. The green “Flash flat build succeeded” message in the web UI is shown even when the flash failed, so check the last line of the log instead. If the log ends with Flash flat build failed, see If the flash fails to open UFS.
5. Remove power and USB, then slide SW2 back to OFF.
6. Plug in power, then USB. The first boot after QDL takes a little longer than later boots.

7. Check the image version matches the build you flashed:

   $ adb shell
   root@qrb5165-rb5:/# cat /etc/version
   1.1.2-M0054-14.1a-FLAT-V3
   

If lsusb shows the board as 05c6:901d but adb shell cannot find it, restart the ADB server with adb kill-server and adb start-server.

If the flash fails to open UFS

If the log shows the programmer loading (Sahara transfer complete, Chip serial num, the list of supported functions) and then stops with lines like these, the flash never wrote anything:

LOG: ERROR: Failed to initialize (open whole lun) UFS Device slot 0 partition 0
LOG: ERROR: Failed to open device, type:UFS, slot:0, lun:0 error:3
qdl: firehose operation timed out
[PROGRAM] failed to setup programming
Flash flat build failed

The processor, memory and USB link are working, because they load and run the programmer. The UFS storage chip does not respond when the programmer opens it, before any data is written. The flat build only writes partitions; it cannot repair or reconfigure the storage chip, so reflashing gives the same result. The Can't decode attribute slot with value line above the errors is a debug message and is not the cause.

Try once more with the board out of the vehicle, nothing connected except power and USB, and a known-good ModalAI power supply. If the error repeats, contact support for an RMA and include the board serial number and the full QDL log.

If the device still shows 900e or boot loops after a successful flash

A board that enumerates as 05c6:900e Qualcomm QUSB_BULK after QDL reported a successful flash has not booted the new image. A board that boots normally enumerates as 05c6:901d and ADB becomes available. The same applies to a board that flashes successfully and then boot loops with ADB never appearing, and to a board that shows no USB device at all in lsusb after the flash. Before anything else, re-check:

• SW2 is back in the OFF position.
• Power and the USB cable were both removed after the flash, before SW2 was moved and the board was powered again.
• The image matches the board revision (M0054-1 versus M0054-2; see the table above and VOXL 2 HW Versions).
• Nothing is connected to the board except power and the USB cable. Remove the VOXL 2 from the vehicle and boot it bare, with every camera and add-on board disconnected. A mis-seated camera flex cable has produced this same 900e state on an otherwise healthy board.

Repeat the flash once with those points confirmed. If the board still returns to 900e, keeps boot looping, or does not enumerate at all, the flat build is not the cause: it restores every partition, so a healthy board boots it regardless of which SDK was installed before. Do not keep running the SDK installer, flash-system-image.sh, or fastboot boot against the board; they cannot fix this and only change its state. In that case, ModalAI support’s guidance is to send the unit in for an RMA. Contact support with the board serial number and the QDL log rather than continuing to reflash.

Next Steps

Now that your VOXL 2 has been reset to the factory image, you will need to reinstall the SDK (including the System Image and VOXL Suite) to get your VOXL back to its original, out-of-the-box state. Without the SDK installed, your VOXL is unable to run the tools, utilities, and services that ModalAI has developed.

To do this, follow this guide.