Unbricking your VOXL 2

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

Table of contents

1. Summary
   1. How does it work?
2. Usage
   1. Prerequisites
      1. Ubuntu Host (Up to Ubuntu version 20.04)
      2. OSX Host
   2. Build
   3. Image Download
3. Flash
   1. Hardware preparation
   2. Flash Flat Build (Runtime: ~3-5 mins)
   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/px4/param/ 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.

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 as 05c6:901d Qualcomm, Inc. via. USB 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

Ubuntu Host (Up to Ubuntu version 20.04)

Some Linux distributions come with ModemManager, a tool for configuring Mobile Broadband. This program, if installed, will interfere with the QDL flashing. One option is to remove the program with the following:

$ sudo apt remove --purge modemmanager

Alternatively, if you need ModemManager, you can temporarily stop it from running with

$ sudo systemctl stop ModemManager

and restart it with:

$ sudo systemctl start ModemManager

GCC is also needed. This can be installed with

$ sudo apt install gcc

OSX Host

Install libusb:

brew install libusb
brew link libusb

Build

Clone the modal-qdl repository using the following:

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

Move into the project directory:

$ cd modal-qdl

Build and install program dependencies using:

$ ./install_dependencies.sh

Copy the qdl binary into your local binary path:

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

This will install the qdl program into /usr/local/bin

Test the install by running the following and verifying the output:

$ 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 and move it into the following repository path:

$ ./qdl/qfil_app/modalai

To view the web UI, run:

$ ./run.sh

Open browser, go to http://127.0.0.1:8000/

Flash

Hardware preparation

In order to force your VOXL 2 into EDL mode, slide the SW2 switch into the ON position, see below:

Now plug in power and USB-C cable from VOXL 2 to host PC.

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

Select the flat build that matches your hardware from the dropdown and click Select Build to choose which flat build to use After selecting a build, click Flash Flat Build to begin flashing the flat build

After the flat build has successful flashed, remove power and USB from the device and flip the SW2 switch to OFF to depart from QDL mode

You can now plug in power and, after a short time, USB (first boot after QDL takes slightly longer than following boots) ADB will be available.

Verify that the flash was successful by checking the installed image version:

# adb onto VOXL 2
$ adb shell

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

This version should match the image you just flashed.

DEBUGGING NOTE: If you are unable to ADB onto the device but the device is being detected correctly by the host PC as seen below:

$ lsusb

Bus 001 Device 022: ID 05c6:901d Qualcomm, Inc. KONA-QRD _SN:21217FEB

restarting the ADB server may fix the issue:

$ adb kill-server

$ adb start-server

You should now be able to ADB onto your device successfully.

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. 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 or keeps boot looping, 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 it’s 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.