ti-radar-cli

Reliability-first command-line tools and an agent skill for TI mmWave radar capture.

Inspect hardware state · record packet verdicts · operate safely with agents

Why · Quick Start · Agent Setup · Device Verification · FAQ · Roadmap · 简体中文

Why

TI mmWave radar capture usually fails at the state boundary: device identity, firmware route, COM ports, RSTD, mmWave Studio launch context, DCA1000 Ethernet, LVDS layout, packet logs, and raw bin verification.

ti-radar-cli turns those fragile boundaries into a small command surface that can be inspected by a person or operated by a coding agent.

Manual radar bring-up	With ti-radar-cli
Recreate GUI steps from memory.	Run named readiness and capture commands.
Trust a raw bin exists.	Read a manifest with packet counters and verdict.
Let agents guess Lua or hardware sequence.	Give agents a skill with approval gates and safe defaults.
Share vague hardware support claims.	Label routes as verified, scaffold, or community evidence.

Quick Start

git clone https://github.com/Zhenyu98/ti-radar-cli.git
cd ti-radar-cli
python -m pip install -e .
ti-radar version
ti-radar doctor
ti-radar capture smoke --backend mock
ti-radar session inspect latest

Expected success signal:

ti-radar version prints package and Python information
ti-radar doctor completes without starting capture
capture smoke writes a mock session
session inspect latest reads manifest.yaml

Optional hardware extras:

python -m pip install -e ".[studio,serial,plot]"

pythonnet is required for direct RSTD control. pyserial improves COM-port checks. matplotlib is used for quicklook plots.

Hardware connection reference: TI DCA1000 + mmWave Studio hardware guide.

Agent Setup

Copy this to Codex, Claude Code, Cursor, or another coding agent:

Read https://github.com/Zhenyu98/ti-radar-cli/blob/main/agent-setup.md and follow it to install and configure ti-radar-cli for me.
Goal: inspect the environment first, run the non-hardware smoke path, and ask before hardware state changes.

The agent guide points to README.md and skills/ti-radar/SKILL.md, then starts with ti-radar version, ti-radar doctor, ti-radar capture smoke --backend mock, and ti-radar session inspect latest.

Hardware Readiness

Inspection commands:

ti-radar doctor --profile default_6843
ti-radar studio status
ti-radar studio ping
ti-radar studio identify

Short capture pilot, after you intentionally approve hardware state changes:

ti-radar studio run --profile default_6843 --frames 10
ti-radar session inspect latest

CLI Shape

Top-level help stays small:

version
doctor
studio    Expert backend commands
capture
session
device

Expert mmWave Studio/RSTD commands stay under:

ti-radar studio --help

Typical user-facing commands:

ti-radar doctor
ti-radar capture smoke --backend mock
ti-radar capture raw --backend studio --profile default_6843 --frames 10
ti-radar session list
ti-radar session inspect latest
ti-radar device route --part-id 6843

Device Verification

Hardware coverage is labeled by evidence level.

Device/profile	Path	Verification level	Evidence expectation
default_6843 / xWR6843-style route	mmWave Studio + RSTD + DCA1000	verified for the author's lab route	clean short capture with manifest and DCA packet verdict
Other xWR/AWR/IWR routes	device decode scaffolds	scaffold	derived from TI route semantics, needs contributor packet-log evidence before promotion

The default DCA1000 network values are common board defaults:

PC DCA adapter: 192.168.33.30/24
DCA1000 FPGA:   192.168.33.180
Command port:   4096
Data port:      4098

Always run ti-radar doctor before capture on a new machine.

Capture Verdict

Capture sessions write manifest.yaml with a strict verdict:

verdict: pass
failure_reasons: []

Failure reasons include missing raw bin, tiny raw bin, missing DCA packet log, zero received packets, out-of-order packets, and zero-filled packets/bytes.

FAQ

Can this run without hardware?

Yes. Use ti-radar capture smoke --backend mock and ti-radar session inspect latest for the non-hardware path.

Does ti-radar studio identify start RF or capture frames?

It reads device identity through RSTD and should avoid firmware download, RF enable, and StartFrame.

What makes a capture usable?

A usable capture has a passing manifest verdict, a raw bin larger than the minimum threshold, received packets above zero, and zero out-of-sequence or zero-filled packet counters.

Roadmap

ti-radar-cli is moving toward a broader, agent-operable TI radar workflow:

• cfg explain and profile linting for zero-hardware setup checks.
• A headless SDK + DCA1000 path for Linux-friendly raw capture.
• A device configuration table so more TI radar boards can be added with clear verification levels.
• Raw ADC quicklook tools for range-Doppler sanity checks after capture.

Stay tuned. Contributions from more developers and hardware users are welcome.

Acknowledgements

This project is shaped by TI's public mmWave Studio, DCA1000, and radar toolbox concepts. TI binaries and private lab captures remain outside this repository.

Contributing

Issues and pull requests are welcome. Please include the device/profile, backend, command line, manifest verdict, and packet-log counters when reporting hardware behavior. Keep secrets and local machine details out of logs and screenshots.

License

This project is released under the MIT License. See LICENSE.

Star History