Installation

This guide covers how to install the alpha-hwr library and its dependencies.

Prerequisites

Python 3.13 or higher.
A supported Bluetooth Low Energy (BLE) adapter (internal or USB dongle).
Operating System:
- Linux: Recommended for full feature support (especially Schedule downloading).
- macOS: Supported for Control and Telemetry (Schedule download is currently restricted by the OS).
- Windows: Supported for Control and Telemetry.

Installing via pip

Note: The package is not yet on PyPI. Installation is currently from source.

# Future command
pip install alpha-hwr

Installing from Source

To use the latest development version or contribute to the project:

Clone the repository:

git clone https://github.com/eman/alpha-hwr.git
cd alpha-hwr

Create a virtual environment (recommended):

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
If requirements.txt is not present, install the core dependencies:
```
pip install bleak pydantic rich typer
```
Install the package in editable mode:
```
pip install -e .
```

Platform-Specific Notes

Linux (Raspberry Pi / Debian / Ubuntu)

Bleak (the underlying BLE library) uses BlueZ on Linux. You might need to install development headers:

sudo apt-get install libglib2.0-dev libbluetooth-dev python3-dev

Permissions: By default, accessing the Bluetooth adapter requires root privileges. To run scripts without sudo, you can grant the Python interpreter the necessary capabilities:

sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f $(which python3))

(Note: This applies to the specific python binary found in your path. If using a venv, apply it to the venv's python binary).

macOS

On macOS, you must grant Bluetooth Permission to your terminal application (e.g., iTerm2, Terminal.app, VS Code) in System Settings -> Privacy & Security -> Bluetooth.

The first time you run a script, macOS usually prompts you to allow access.