qcom-boot-validate
/qcom-boot-validate
Validate that a Qualcomm Linux board boots to a working login shell by watching its serial console: wait for the login prompt, log in with the image's default credentials, and check uname, /etc/os-release (incl. BUILD_ID) and systemd state, reporting BOOT-VALIDATION: PASS/FAIL. Use after flashing, when asked to "validate the board boots", "check the board over serial", "did the new image come up", or "watch the boot console". Needs the serial console attached to this host (or reachable over ssh). Do NOT use for flashing (see qcom-flash-qdl) or for diagnosing a healthy-but-degraded system.
- Author
- qualcomm-linux ↗
- Repository
- qcom-linux-skills ↗
- Licence
- BSD-3-Clause
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
BSD-3-Clause, otwarta.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/boot-validate.py
What it does and when to use it
Validate that a Qualcomm Linux board boots to a working login shell by watching its serial console: wait for the login prompt, log in with the image's default credentials, and check uname, /etc/os-release (incl. BUILD_ID) and systemd state, reporting BOOT-VALIDATION: PASS/FAIL. Use after flashing, when asked to "validate the board boots", "check the board over serial", "did the new image come up", or "watch the boot console". Needs the serial console attached to this host (or reachable over ssh). Do NOT use for flashing (see qcom-flash-qdl) or for diagnosing a healthy-but-degraded system.
Triggers from the description
Original author description
Validate that a Qualcomm Linux board boots to a working login shell by watching its serial console: wait for the login prompt, log in with the image's default credentials, and check uname, /etc/os-release (incl. BUILD_ID) and systemd state, reporting BOOT-VALIDATION: PASS/FAIL. Use after flashing, when asked to "validate the board boots", "check the board over serial", "did the new image come up", or "watch the boot console". Needs the serial console attached to this host (or reachable over ssh). Do NOT use for flashing (see qcom-flash-qdl) or for diagnosing a healthy-but-degraded system.
How it works
- Prerequisites
- Credentials matrix
- Usage
- How validation works
- Notes / gotchas
SKILL.md preview
---
name: qcom-boot-validate
description: >-
Validate that a Qualcomm Linux board boots to a working login shell by
watching its serial console: wait for the login prompt, log in with the
image's default credentials, and check uname, /etc/os-release (incl.
BUILD_ID) and systemd state, reporting BOOT-VALIDATION: PASS/FAIL. Use
after flashing, when asked to "validate the board boots", "check the
board over serial", "did the new image come up", or "watch the boot
console". Needs the serial console attached to this host (or reachable
over ssh). Do NOT use for flashing (see qcom-flash-qdl) or for
diagnosing a healthy-but-degraded system.
metadata:
version: "0.2"
---
# Validate a board boots over the serial console
Drives the board's serial console to prove a boot actually reached a usable
shell — the natural follow-up to `qcom-flash-qdl`. Everything is done by
`scripts/boot-validate.py` (paths relative to this skill's directory).
## Prerequisites
- The board's debug UART attached to a host you can run Python on, at
115200 baud (check `dmesg | grep tty` for the device, e.g. `/dev/ttyUSB0`).
- `python3` with `pyserial` on that host; the user in the `dialout` group
(or equivalent) so the port opens without root.
- Nothing else holding the serial port (close `screen`/`picocom`/`minicom`
sessions first — the validator warns if it reads no output).
- The image's login credentials (see matrix below).
## Credentials matrix
| Image | username | password |
|---|---|---|
| nodistro `core-image-base` (debug image) | `root` | empty |
| qcom-distro images (`qcom-console-image`, ...) | `root` | `oelinux123` |
## Usage
Local serial port:
```bash
python3 scripts/boot-validate.py --port /dev/ttyUSB0 --password oelinux123 \
[--timeout 300] [--power-cycle-cmd '<host command>'] [--logfile PATH]
```
Serial port on a remote host (nothing is copied to it — the script is piped
over ssh):
```bash
ssh <host> "python3 - --port /dev/ttyUSB0 --password oelinux123" \
< scripts/boot-validate.py
```
- With no `--power-cycle-cmd`, the script watches the console and tells you
to power-cycle/reset the board — start it right before (or immediately
after) resetting, e.g. right after a flash completes.
- `--power-cycle-cmd` runs a host command once at startup for setups that
can drive board power programmatically (lab automation, smart PDU). Keep
site-specific automation in that command, not in this skill. The command
is split shell-style and run without a shell; wrap it in `sh -c '...'`
if it needs pipes, redirection, variable or `~` expansion, or is a script
without a `#!` line. If it cannot be started, the script warns and keeps
watching the console, so the board must then be reset by hand.
- Exit code `0` on `BOOT-VALIDATION: PASS`, non-zero on failure. The full
console capture is mirrored to the log file (default
`/tmp/qcom-boot-validate-<timestamp>.log`) for evidence.
## How validation works
1. Optionally power-cycle, then discard any stale console output so an old
login prompt cannot satisfy the check.
2. Wait (default 300 s) for a fresh `login:` prompt.
3. Log in; handle both password and no-password images, and wait for the
shell to actually be ready before typing (early commands get swallowed
during session setup).
4. Run fenced sanity checks: `uname -a`, `PRETTY_NAME`/`VERSION`/`BUILD_ID`
from `/etc/os-release`, `systemctl is-system-running`.
5. Verdict: `PASS` for `running`/`starting`; `PASS(warn)` for `degraded`
(booted, but some unit failed) or non-systemd images; `FAIL` otherwise,
with the last 40 console lines printed for triage.
Compare the reported `BUILD_ID` with the build you just flashed — a PASS on
a stale image is not a validation of the new one.
## Notes / gotchas
- "no output at all" almost always means the wrong tty device, a console
muxed away by DIP switches, or another process holding the port.
- OE images enable bash's semantic prompt escapes; the validator strips
ANSI/OSC sequences before parsing, so don't be surprised that the raw log
file looks noisier than the parsed report.
- `degraded` is reported as PASS(warn) on purpose: the board booted. Chase
the failing units separately (`systemctl --failed`) rather than treating
the boot as broken.
- The script is read-only on the target apart from logging in and running
the three sanity commands; it logs out (`exit`) when done.
Files in this package (2)
- SKILL.md 4 KB
- scripts/boot-validate.py 12 KB
Versions
The database has no other skills named qcom-boot-validate.
Database snapshot: 13.11.2026 · package version d813f7e18313 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 98qcom-flash-qdl
Flash a Qualcomm Linux qcomflash image bundle onto a board in Emergency Download (EDL) mode using the QDL tool, including multi-board selection via --serial. Use when asked to "flash the board", "flash the RB3 Gen2 / rb1 / EVK", "flash the qcomflash image", "reflash over EDL",… - 100qcom-kernel-qcom-next-build
Cross-build the qualcomm-linux kernel (qcom-next branch) standalone on an x86 host: arm64 defconfig with the prune.config + qcom.config fragment merge used by meta-qcom's linux-qcom-next recipe, producing Image, DTBs and modules. Use when asked to "build the qcom-next kernel",… - 100serial-console
This skill should be used when a board is attached to the host and the user asks what it printed, whether it booted, why it stopped at U-Boot or a kernel panic, to "check the serial console", "watch the board boot", "send a command to the board", "/serial-console", or when a… - 100stm32-keil
Use when Codex needs to generate, review, validate, flash, debug, or diagnose STM32 Keil/CubeMX projects, especially .ioc files, HAL peripheral configuration, ST-Link/OpenOCD/CubeProgrammer flashing, and serial console workflows. - 100esp32s3-bringup
Use when an ESP32-S3 board (DevKitC-1, N16R8 modules, any S3 dev board) is plugged in over USB and the user wants to find it, check whether it works, read its boot log, watch its serial output or Wi-Fi state, or flash a merged .bin (Arduino or ESP-IDF). Also read when esptool… - 100logscope
Observe and drive a device's serial logs without pasting them into chat. Use whenever the task involves watching firmware/device output, waiting for something to happen on hardware, sending CLI commands to a board, or running a flash/OTA/test flow and checking whether it worked.…