Metadata-Version: 2.4
Name: mvave-tankg-ble
Version: 0.1.0
Summary: Control an M-Vave Tank-G multi-effects guitar pedal over Bluetooth LE
Project-URL: Homepage, https://github.com/hudsonbrendon/mvave-tankg-ble
Project-URL: Issues, https://github.com/hudsonbrendon/mvave-tankg-ble/issues
Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ble,bluetooth,cuvave,guitar,home-assistant,m-vave,midi,mvave,tank-g
Requires-Python: >=3.11
Requires-Dist: bleak>=0.21
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/cuvave-logo-white.png">
    <img src="assets/cuvave-logo-black.png" alt="M-Vave / Cuvave" width="360">
  </picture>
</p>

# mvave-tankg-ble

[![CI](https://github.com/hudsonbrendon/mvave-tankg-ble/actions/workflows/ci.yml/badge.svg)](https://github.com/hudsonbrendon/mvave-tankg-ble/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mvave-tankg-ble)](https://pypi.org/project/mvave-tankg-ble/)
[![Python](https://img.shields.io/pypi/pyversions/mvave-tankg-ble)](https://pypi.org/project/mvave-tankg-ble/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Control an **M-Vave Tank-G** multi-effects guitar pedal over Bluetooth LE.

The pedal speaks BLE-MIDI: presets are switched with a MIDI **Program Change** on
channel 0, over the standard BLE-MIDI characteristic. This library is the pure
Bluetooth layer — discovery, the command frames, and an async device class — with
no Home Assistant dependency. It powers the
[Home Assistant integration](https://github.com/hudsonbrendon/ha-mvave-tankg).

## Install

```bash
pip install mvave-tankg-ble
```

## Usage

```python
import asyncio
from mvave_tankg_ble import TankG, discover


async def main():
    devices = await discover(timeout=5.0)
    if not devices:
        print("No Tank-G found.")
        return
    async with TankG(devices[0]) as pedal:
        await pedal.set_preset(12)   # UI preset 1-36


asyncio.run(main())
```

`TankG` accepts a bleak `BLEDevice` (preferred — e.g. from Home Assistant's shared
scanner or a Bluetooth proxy) or a string MAC/UUID address.

### API

| Symbol | Description |
|---|---|
| `TankG(device)` | Async device wrapper. Use as an async context manager. |
| `await pedal.set_preset(n)` | Switch to UI preset `n` (1–36). |
| `await pedal.send_program_change(program, channel=0)` | Raw MIDI Program Change. |
| `await discover(timeout=5.0)` | List nearby Tank-G pedals (`list[BLEDevice]`). |
| `program_change_frame(program, channel=0)` | Build the raw BLE-MIDI frame. |
| `preset_to_program(preset)` | UI preset (1–36) → MIDI program (0–35). |
| `program_to_bank_position(program)` | Program → `(bank, "A"/"B"/"C"/"D")`. |

### CLI

```bash
mvave-tankg scan              # list nearby pedals
mvave-tankg preset 12         # switch to preset 12 (scans first)
mvave-tankg preset 12 --address AA:BB:CC:DD:EE:FF
```

## Scope & limitations

- **Presets only.** The pedal exposes a proprietary Cuvave service (`0xAE40`) the
  official app uses for LED colour and other settings; that protocol is not
  reverse-engineered, so it isn't supported here.
- **No battery.** The Tank-G doesn't report battery over BLE (the official app
  shows none) — only the physical "L"/"LO" display warning and the charge LED.
- **Presets are one-way.** The pedal doesn't report its current preset, so there's
  no read-back.

## License

[MIT](LICENSE) © Hudson Brendon
