Skip to main content

pyGdbToolkit

pyGdbToolkit logo

GDB commands for inspecting and diagnosing embedded targets, especially Arm Cortex-M microcontrollers. The toolkit provides processor identification, debug access-port inspection, memory discovery, fault analysis, SVD peripheral access, profiling, security auditing and Camelot RTOS inspection.

Use it directly in GDB, or run pyGdbServer and pyGdbClient for a supervised debug session with a terminal dashboard and a JSON-RPC automation interface.

Installation

Requires Python 3.12+, GDB with compatible embedded Python, and a debug probe with a supported OCD, or QEMU for an emulated target. From a checkout:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

Follow the first-session guide for GDB setup or the server/client workflow. Adapt an example configuration to your board and probe. Keep the server API on loopback unless protected by appropriate network, TLS and authentication controls.

For a connected, stopped target without an SVD or firmware ELF, use memmap discover --verify to collect identity and declared memory regions and sample their endpoints. Confirmed fingerprints enrich the shared SESSION; manufacturer baselines remain separate hypotheses. See the memory-mapping guide for confidence levels and safe probing limits.

Agent-assisted audit

The dashboard can attach an LLM agent (GitHub Copilot first) that uses the OCD, GDB and toolkit commands to answer the auditor's natural-language requests. Risky plans require explicit approval, and production data should only be analysed with a local model on trusted equipment. See the agent-assisted audit guide.

Run the tests with tox

tox -e py312     # GDB-side toolkit and server tests, using a fake gdb module
tox -e client    # dashboard and LLM client tests, without GDB or a target
tox -e qemu      # opt-in functional tests with real QEMU/GDB, no physical probe

The two suites run in separate processes: the client suite rejects any import of gdb, pyGdbToolkit, or pyGdbServer. The separate QEMU mode supports hardware-free CI with emulated STM32 targets; install QEMU and GDB with embedded Python 3.12+ before running its dedicated functional suite.

Build the documentation with tox

The user guide is generated from the Markdown sources in doc/. Tox creates an isolated environment and installs the Python documentation dependencies from the dev extra. From the repository root:

python -m pip install tox
npm install --global @mermaid-js/mermaid-cli@11
tox -e docs

Node.js and the Mermaid CLI (mmdc on PATH, with its Puppeteer browser) are required to render diagrams. The HTML includes local resources and works offline; no web server is needed. Open doc/_build/html/index.html after the build. The continuous, single-page guide is in doc/_build/singlehtml/index.html; keep its accompanying resource directories.

To generate the PDF as well, install GNU Make, latexmk, pdfLaTeX and the TeX packages required by Sphinx. On Debian/Ubuntu:

sudo apt install make latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
tox -e docs,docs-pdf

The PDF is written to doc/_build/latex/pyGdbToolkit-user-guide.pdf. Both tox environments fail on documentation warnings and unresolved internal references. These tools are build-only dependencies, not application runtime requirements.

See documentation build details for browser configuration, distribution archives and source-maintenance instructions. The guide contains the command reference, configuration examples, troubleshooting and technical appendices.

Metadata

Release files for pyGdbToolkit 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for pyGdbToolkit 1.2.0
File Interpreter ABI Platform Actions
pygdbtoolkit-1.2.0-py3-none-any.whl Python 3 none any Details for pygdbtoolkit-1.2.0-py3-none-any.whl

Release files / pygdbtoolkit-1.2.0-py3-none-any.whl

Download URL pygdbtoolkit-1.2.0-py3-none-any.whl
Size 256.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d488e0001b7474520fcf46b0e7188cffb22faff7552559c0bd4bf509f25c00ef
BLAKE2b-256 checksum
How to use checksums
994992c22a514de3052796fae570033440f062c5accd25271039d3da3c19af43
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Security for pyGdbToolkit 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page