Q-Marauder: Hardware & Installation

Build guide / Arduino UNO Q / Foundation alpha

Build a wireless field console with a portrait touchscreen, a Debian desktop app, and shared Wi-Fi, Bluetooth, and capture-analysis tools.

This guide covers the hardware, Windows USB installation, first checks, and everyday startup. Source code, documentation, and downloads are hosted on Gitea.

Download source + installer ZIPBrowse all source code ↗Open the user wiki ↗

Alpha 10 release & checksums · All releases · More Valleytech projects

Q-Marauder portrait home menu rendered from the current TFT firmware
Portrait home menu, rendered from the current TFT firmware. Explore more touchscreen and desktop views below.
Before you buy: the TFT uploader currently supports the tested Arduino Zephyr 0.11.0-rc5 core and the shield described below. Other core versions stop before display upload. Q-Marauder installs onto Arduino's existing Debian system; it is not a replacement OS image or a browser-only flasher.

What you need

The basic touchscreen build uses these parts and setup tools. An SD card or external Wi-Fi adapter is not required for basic installation and onboard discovery.

Qty Item Specification
1 Arduino UNO Q Arduino Debian initialized with the standard arduino account. UNO R3/R4 boards are not substitutes. Official board information.
1 3.5-inch UNO TFT touch shield 320 × 480, 8-bit parallel, dual UNO header rows, ILI9486-compatible initialization and resistive touch. The unbranded development sample is tested; SPI breakouts and other clone pinouts are not verified.
1 USB data cable PC USB to UNO Q USB-C, supporting data and adequate power. A charge-only cable cannot install the app.
1 Windows PC Internet access, a USB port, Arduino App Lab for initial setup, and Google's Platform-Tools. Windows does not need Python or the Arduino IDE for this installer.
1 Wi-Fi connection The board needs Internet access for Debian packages and pinned display libraries during first installation.

Full bill of materials and compatibility notes ↗ · Display wiring and validation ↗

Optional expansions

Desk setup

A powered USB-C hub with DP Alt Mode video output, HDMI monitor, keyboard, and mouse. The desktop software is implemented; this project's exact HDMI/hub combination has not been physically validated.

Desktop setup notes ↗

Radio & portable power

The PC-forwarded ALFA/MediaTek 0e8d:7961 radio has experimental monitor reception. Injection remains unverified. A GNSS receiver, enclosure, battery, or UPS can be added after checking support.

External-radio evidence · Battery and UPS notes

Install over USB from Windows

  1. Fit the shield with power disconnected.
    Align every shield pin with its labeled UNO header position. Use the parallel shield above; do not offset the rows or force the connector.
  2. Complete Arduino's initial setup.
    Use Arduino App Lab to set up Debian and Wi-Fi. Keep the standard arduino account, and have the board password available. Close other apps using the MCU serial bridge.
  3. Download and extract Q-Marauder.
    Download the source ZIP above, right-click it, and choose Extract All. Open the extracted folder containing Install-QMarauder.cmd. Do not launch it from inside the ZIP viewer. The release includes the app, sketch, scripts, documentation, and images.
  4. Add Google's Platform-Tools.
    Download Platform-Tools for Windows from Google. In the extracted Q-Marauder folder, create .tools, then place the extracted platform-tools folder inside it. Confirm this path exists: 
    Q-Marauder folder/
  Install-QMarauder.cmd
  .tools/
    platform-tools/
      adb.exe
  5. Connect the UNO Q and run the installer.
    Connect one initialized UNO Q directly to the PC with the data cable. Double-click Install-QMarauder.cmd. Enter the board's Debian password in the installer window if packages require it. Keep power connected: the first MCU recovery backup can take several minutes.
  6. Wait for the console and portrait menu.
    The installer checks board/core compatibility, installs the Linux app and tool packages, compiles and backs up the display firmware, and uploads the portrait sketch. The browser opens at http://127.0.0.1:8788. With USB at the bottom, the TFT shows the BWM loader, then the menu without automatic calibration prompts.
  7. Enable Bluetooth tools once.
    Double-click scripts/Enable-BLELab.cmd to install the Bluetooth D-Bus bindings. For BLE packet capture and supported packet detectors, run scripts/Enable-LabRadio.cmd and choose 1. These additional setup steps may request the Debian password locally.

Different display core? Do not force the upload or blindly downgrade the board. The console-only option in PowerShell is .\scripts\Install-Windows.ps1 -AppOnly. It installs the Linux side without changing the TFT sketch. See the firmware compatibility guide.

Illustrated installation guide ↗ · Linux/SSH installation, recovery, and boot service ↗

Make sure it is working

  • Touchscreen: tap WiFi → Scan APs, wait for completion, and tap a network row to see details. Change the look under Settings → Themes.
  • Bluetooth: run discovery after BLE Lab setup. Select a device you own for pairing or GATT inspection. BLE walkthrough.
  • Network tools: open Linux tools → Network tools on the TFT. Try Nmap TCP ports with 127.0.0.1 to check the local board first. The desktop exposes the same tools in the Lab workspace.
  • Saved packet captures: on the TFT, open Linux tools → Packet analysis → Saved captures, select a PCAP and tap USE. On the desktop, select PCAP source and Show tools → Packets / TShark. A saved capture is required before analysis has results.
Portrait packet-analysis menu rendered from the actual display firmware
Software render from the TFT drawing code. Capture selection and packet details were confirmed on the physical development screen.
Actual running Q-Marauder desktop workspace with TShark tools and a completed protocol report
Actual browser capture of the shared Debian workspace. This is not an HDMI hardware photograph.

Packet-analysis how-to ↗ · Nmap and network how-to ↗ · Full UI gallery ↗

This is a foundation alpha. Scan, capture, and attack capabilities depend on the backend and radio; a visible menu entry is not a promise of full upstream parity. Check the active-test status before relying on a feature.

Everyday startup: handheld or desktop

USB-tethered touchscreen

After rebooting the UNO Q, double-click Start-QMarauder.cmd. This starts the Linux console and reopens USB forwarding. Keep the extracted folder and Platform-Tools together.

The sketch stays installed, but live actions need the Linux app running. For automatic handheld startup, follow the separate boot-service instructions.

Debian desktop app

With a compatible powered display hub and Debian desktop session, open Applications → Q-Marauder Lab, or run ~/.local/bin/q-marauder desktop. It shares the same service, settings, and reports as the TFT.

Moving the USB-C connection from the PC to a hub disconnects PC forwarding, including any forwarded ALFA radio. Follow the desktop guide.

To update, extract a newer release and rerun its installer so the app and TFT remain on the same revision. Saved observations and touch settings remain on the board. Keep backups of important captures.

Troubleshooting

The board is not detected

Complete Arduino's initial setup, use a data-capable cable, and connect one UNO Q. Check adb devices from Platform-Tools. Close competing serial/bridge apps and follow Arduino's setup flow if the device is unauthorized.

The installer says the display core is unsupported

The tested core is Zephyr 0.11.0-rc5. Use the console-only -AppOnly option and consult the firmware guide. Do not bypass the version check.

The previously working display is blank

Run Repair-Display.cmd and allow about 15 seconds. It restarts the display MCU and restores settings without flashing or clearing calibration. On a first install, a white backlight can mean the sketch did not upload or the shield wiring differs.

The screen is mirrored or taps miss

Use Settings → Screen orientation or Settings → Calibrate touch. For calibration, press and release all three targets. Adjustments are saved by the Linux console.

A scan or analysis view has no results

Confirm the Linux console is running, wait for the job to finish, and check its diagnostics in the browser. BLE needs the BLE Lab setup step. Packet analysis needs a saved PCAP. Wi-Fi monitor capture needs a separately validated radio; onboard discovery does not prove monitor reception.

Can I flash it directly from this webpage?

A browser-only UNO Q installer is not included. The supported path here is the Windows USB launcher on Arduino's Debian image. Read the web-installer assessment for the current scope.

Keep the full guide handy: Installation wiki · Bill of materials · Troubleshooting wiki · Project issues.

Guide checked October 19, 2026. The source ZIP includes the current documentation; alpha 10 remains available as a tagged release. MIT application code; see the repository's credits and third-party notices.