152 lines
4.0 KiB
Plaintext
152 lines
4.0 KiB
Plaintext
---
|
|
title: Installation
|
|
description: Install openocd-python and its dependencies
|
|
---
|
|
|
|
import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
|
|
|
|
openocd-python requires **Python 3.11 or later** and a working OpenOCD installation. The library itself has a single dependency: `cmsis-svd` for SVD register decoding.
|
|
|
|
## Install the package
|
|
|
|
<Tabs>
|
|
<TabItem label="uv">
|
|
```bash
|
|
uv add openocd-python
|
|
```
|
|
</TabItem>
|
|
<TabItem label="pip">
|
|
```bash
|
|
pip install openocd-python
|
|
```
|
|
</TabItem>
|
|
<TabItem label="pipx (CLI only)">
|
|
```bash
|
|
pipx install openocd-python
|
|
```
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
The package installs both the Python library (`import openocd`) and a CLI tool (`openocd-python`).
|
|
|
|
## Dependencies
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `cmsis-svd` | >= 0.4 | SVD file parsing for peripheral register decoding |
|
|
|
|
No other Python dependencies are required. The library uses only the standard library for networking (`asyncio`), subprocess management, and data types.
|
|
|
|
## Install OpenOCD
|
|
|
|
openocd-python communicates with OpenOCD over its TCL RPC interface. You need OpenOCD installed and either already running or available on your `PATH` so the library can spawn it.
|
|
|
|
<Tabs>
|
|
<TabItem label="Arch Linux">
|
|
```bash
|
|
sudo pacman -S openocd
|
|
```
|
|
</TabItem>
|
|
<TabItem label="Debian / Ubuntu">
|
|
```bash
|
|
sudo apt install openocd
|
|
```
|
|
</TabItem>
|
|
<TabItem label="macOS">
|
|
```bash
|
|
brew install openocd
|
|
```
|
|
</TabItem>
|
|
<TabItem label="Windows">
|
|
Download the latest release from [openocd.org](https://openocd.org/pages/getting-openocd.html) and add the `bin` directory to your system `PATH`.
|
|
</TabItem>
|
|
<TabItem label="From source">
|
|
```bash
|
|
git clone https://github.com/openocd-org/openocd.git
|
|
cd openocd
|
|
./bootstrap
|
|
./configure
|
|
make
|
|
sudo make install
|
|
```
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Verify OpenOCD is installed and accessible:
|
|
|
|
```bash
|
|
openocd --version
|
|
```
|
|
|
|
<Aside type="note">
|
|
openocd-python supports OpenOCD 0.11 and later. Some commands (like `adapter name`) require OpenOCD 0.12+. The library handles version differences automatically, falling back to older command variants when needed.
|
|
</Aside>
|
|
|
|
## Verify the installation
|
|
|
|
After installing both openocd-python and OpenOCD, run a quick check to confirm everything is working.
|
|
|
|
First, start OpenOCD with your target configuration. For example, with a CMSIS-DAP probe and an STM32F1 target:
|
|
|
|
```bash
|
|
openocd -f interface/cmsis-dap.cfg -f target/stm32f1x.cfg
|
|
```
|
|
|
|
Then, in another terminal, verify the Python package can connect:
|
|
|
|
```python
|
|
from openocd import Session
|
|
|
|
with Session.connect_sync() as ocd:
|
|
state = ocd.target.state()
|
|
print(f"Target: {state.name}, State: {state.state}")
|
|
```
|
|
|
|
You can also verify using the CLI:
|
|
|
|
```bash
|
|
openocd-python info
|
|
```
|
|
|
|
This prints the target name, state, transport, adapter, and clock speed.
|
|
|
|
<Aside type="tip">
|
|
If you get a `ConnectionError`, check that OpenOCD is running and that the TCL RPC port (default 6666) is not blocked by a firewall. The TCL RPC port is distinct from the GDB server port (3333) and the telnet port (4444).
|
|
</Aside>
|
|
|
|
## Development installation
|
|
|
|
To work on openocd-python itself, clone the repository and install the development dependencies:
|
|
|
|
```bash
|
|
git clone https://git.supported.systems/ryan/openocd-python.git
|
|
cd openocd-python
|
|
uv sync --extra dev
|
|
```
|
|
|
|
The `dev` extras include:
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `pytest` >= 8.0 | Test runner |
|
|
| `pytest-asyncio` >= 0.24 | Async test support |
|
|
| `ruff` >= 0.8 | Linter and formatter |
|
|
|
|
Run the test suite (no hardware needed -- all tests use a mock OpenOCD server):
|
|
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
Run the linter:
|
|
|
|
```bash
|
|
uv run ruff check src/ tests/
|
|
```
|
|
|
|
## Next steps
|
|
|
|
- [First Connection](/getting-started/first-connection/) -- connect to OpenOCD and run your first command
|
|
- [Quick Start](/getting-started/quick-start/) -- complete working examples for common tasks
|
|
- [CLI Reference](/getting-started/cli/) -- use the `openocd-python` command-line tool
|