Metadata-Version: 2.2
Name: ecuconnect-tool
Version: 0.9.4
Summary: Python ECUconnect CLI and CANyonero protocol bindings
Author: ECUconnect
License: MIT
Requires-Python: >=3.9
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: python-can>=4.2.2
Requires-Dist: pyobjc-framework-CoreBluetooth>=10.0; platform_system == "Darwin"
Requires-Dist: dbus-python>=1.3.2; platform_system == "Linux"
Requires-Dist: PyGObject>=3.42.0; platform_system == "Linux"
Description-Content-Type: text/markdown

# ecuconnect-tool (Python)

Python CLI for ECUconnect using libCANyonero bindings. The default transport is WiFi/TCP at `192.168.42.42:129` (override with `--endpoint` for mocks or other adapters).

## Build + install

```bash
python -m pip install -e ./python/ecuconnect_tool
```

## Quick start

```bash
ecuconnect-tool info
ecuconnect-tool login
ecuconnect-tool ping 512 --count 10
ecuconnect-tool benchmark --count 32
ecuconnect-tool term 500000 --proto raw
ecuconnect-tool --url ecuconnect-l2cap://FFF1:129 term 500000 --proto raw
ecuconnect-tool monitor --bitrate 500000
ecuconnect-tool send "02 3E 80" --tx-id 0x123 --rx-id 0x321
ecuconnect-tool test --can-interface can0 --busload 1 --duration 5
```

## BLE/L2CAP

Use the ECUconnect L2CAP endpoint format (works on both macOS and Linux):

```bash
ecuconnect-tool --url ecuconnect-l2cap://FFF1:129 info
```

### macOS

Install CoreBluetooth bindings:

```bash
python3 -m pip install pyobjc-framework-CoreBluetooth
```

Optionally target a specific peripheral UUID:

```bash
ecuconnect-tool --url ecuconnect-l2cap://FFF1:129/12345678-1234-1234-1234-123456789abc info
```

### Linux

Requires BlueZ and the system D-Bus/GLib Python packages (usually pre-installed):

```bash
sudo apt install python3-dbus python3-gi
```

Discovery uses the BlueZ D-Bus API; the L2CAP connection uses the kernel socket API directly (no extra pip dependencies).

Optionally filter by BD_ADDR:

```bash
ecuconnect-tool --url ecuconnect-l2cap://FFF1:129/DC:DA:0C:3A:E3:06 info
```

## Dev flow (no install)

This builds the native extension in-place and runs the CLI from the repo:

```bash
python3 -m pip install --user pybind11 typer rich python-can
python3 ./python/ecuconnect_tool/scripts/run_dev.py test --can-interface can0 --busload 20 --duration 5
```

Auto ramp mode (start at 1 pps, step 1 pps until max busload):

```bash
ecuconnect-tool test --can-interface can0 --busload auto --auto-max-busload 1
```

Preflight info + ping happens before the load test by default. Disable with `--preflight false`.
Use `--preflight-only` to stop after the connectivity checks (no CAN open).
Use `--traffic none` to open the CAN channel + set arbitration, then exit without data transfer.
Use `--traffic rx` for CAN->ECU only, `--traffic tx` for ECU->CAN only.

## Notes

- `ecuconnect-l2cap://` is supported on macOS (CoreBluetooth) and Linux (BlueZ + kernel L2CAP).
- Windows currently supports TCP endpoints only.
- Socket buffers default to `4M`; override with `--rx-buffer/--tx-buffer` using bytes or `K/M/G` suffixes.
- Set `ECUCONNECT_DEBUG_IO=1` to print raw TX/RX frame traces while debugging transport issues.
