1"""
  2# Overview
  3
  4`benlink` is a cross-platform Python library for communicating with and
  5controlling Benshi radios (e.g. Vero VR-N76, RadioOddity GA-5WB, BTech UV-Pro)
  6over BLE and Bluetooth Classic (RFCOMM).
  7
  8In addition to providing a high-level async Python interface for controlling
  9Benshi radios, the larger goal of this project is to document their BLE / RFCOMM
 10protocol. An understanding of the protocol used by these radios will empower
 11Benshi radio owners and the wider open source community to:
 12
 131. Control their radios without relying on proprietary apps or software.
 14
 152. Extend the functionality of their radios through custom software and
 16   integrations.
 17
 183. Preserve the usability of their radios, even when the official "HT" app is no
 19   longer supported or updated.
 20
 21It is a work in progress and is nowhere close to feature complete.
 22[Pull requests](https://github.com/khusmann/benlink) are welcome!
 23
 24## Software / Hardware Support
 25
 26benlink uses [bleak](https://github.com/hbldh/bleak) for BLE communication,
 27making it compatible with Windows, macOS, and Linux. RFCOMM support is via
 28python's built-in `socket` module, and also works on Windows, macOS, and Linux.
 29(Although automatic service discovery for RFCOMM
 30[isn't supported yet](https://github.com/khusmann/benlink/issues/9)).
 31
 32The following radios should work with this library:
 33
 34- BTech UV-Pro
 35- RadioOddity GA-5WB
 36- Vero VR-N76 (untested)
 37- Vero VR-N7500 (untested)
 38- BTech GMRS-Pro (untested)
 39
 40If you know of other radios that use the same Benshi BLE / RFCOMM protocol,
 41please [open an issue](https://github.com/khusmann/benlink/issues) to let me
 42know!
 43
 44# Installation
 45
 46To install the latest stable version of benlink from PyPI:
 47
 48```bash
 49pip install benlink
 50```
 51
 52If you're wanting to contribute to the project, clone the repository and install
 53it in "editable" mode with
 54
 55```bash
 56pip install -e .
 57```
 58
 59# Quick Start
 60
 61First, make sure your radio is paired with your computer, and get its device
 62UUID (e.g. `XX:XX:XX:XX:XX:XX`).
 63
 64The following will connect to the radio and print its device info:
 65
 66```python
 67import asyncio
 68from benlink.controller import RadioController
 69
 70async def main():
 71    async with RadioController.new_ble("XX:XX:XX:XX:XX:XX") as radio:
 72        print(radio.device_info)
 73
 74asyncio.run(main())
 75```
 76
 77# Next Steps
 78
 79To see what else you can do with this library, check out the examples in the
 80[benlink.controller](https://benlink.kylehusmann.com/benlink/controller.html)
 81module documentation.
 82
 83# Other Projects
 84
 85Benlink has already begun to inspire other projects! Here are some that I know
 86of so far:
 87
 88- [HTCommander](https://github.com/Ylianst/HTCommander)
 89
 90If you've found benlink's documentation of the Benshi protocol helpful, or use
 91benlink in your own project, please let me know so I can add it to this list.
 92
 93# Known issues
 94
 95Audio sending / receiving is a awkward because it relies on pyav for decoding /
 96encoding. In the long run, I hope to make
 97[Python bindings for libsbc](https://github.com/khusmann/benlink/issues/11).
 98
 99# Roadmap
100
101Things to do:
102
103- [ ] Improve audio sending / receiving with bindings to libsbc
104      ([issue](https://github.com/khusmann/benlink/issues/11))
105- [ ] Make a higher-level interface for sending / receiving TNC data (auto
106      retry, queue message fragments)
107      ([issue](https://github.com/khusmann/benlink/issues/1))
108- [ ] Figure out firmware flashing process / protocol (this is key for long-term
109      independence from the HT app)
110      ([issue](https://github.com/khusmann/benlink/issues/10))
111- [ ] Implement more commands and settings
112- [ ] Find more radios that use this protocol and test them with this library
113
114# Acknowledgements
115
116[@spohtl](https://github.com/spohtl) for help figuring out audio transmit /
117receive
118
119[@na7q](https://github.com/na7q) for early testing and feedback
120
121# Disclaimer
122
123This project is an independent grassroots effort, and is **not** affiliated with
124or endorsed by Benshi, Vero, RadioOddity, BTech, or any other company.
125
126Use this library at your own risk. I am **not** responsible for any damage
127caused to your radio or any other equipment while using this library.
128"""
129
130from . import controller
131from . import command
132from . import audio
133
134__all__ = ['controller', 'command', 'audio']