https://github.com/bang-olufsen/beoremote-halo
Beoremote Halo Open API
https://github.com/bang-olufsen/beoremote-halo
Last synced: about 2 months ago
JSON representation
Beoremote Halo Open API
- Host: GitHub
- URL: https://github.com/bang-olufsen/beoremote-halo
- Owner: bang-olufsen
- License: mit
- Created: 2021-09-30T06:45:57.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-01-17T07:19:04.000Z (over 3 years ago)
- Last Synced: 2024-04-14T07:41:09.025Z (about 1 year ago)
- Language: HTML
- Homepage:
- Size: 8.19 MB
- Stars: 15
- Watchers: 10
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[
](https://www.bang-olufsen.com/en/us/accessories/beoremote-halo)
# Beoremote Halo Open API
[](https://github.com/bang-olufsen/beoremote-halo/actions/workflows/ci.yaml)
[](./LICENSE)
[](https://pypi.org/project/beoremote-halo)
[](https://pypi.org/project/beoremote-halo)
The [Beoremote Halo](https://www.bang-olufsen.com/en/us/accessories/beoremote-halo) Open API is an open source async API that allows you to interact with a Beoremote Halo from a home automation system.
Using a WebSocket to communicate with the Beoremote Halo, it is possible to create a configuration of buttons to interact with your home automation to control your home applications.
Beoremote Halo supports buttons with icons or text for most general home automation applications.
You can find a list of the [supported icons](https://github.com/bang-olufsen/beoremote-halo/wiki/Icons) on our wiki pages.
For further details on the Open API list of commands please refer to the [API description](https://bang-olufsen.github.io/beoremote-halo/).
## Installation
The Python package `beoremote-halo` requires [Python 3.9](https://www.python.org/downloads/) or higher and contains a library for communicating with Beoremote Halo and a CLI tool for discovering Beoremote Halo on the network.
Install using pip:
```
pip3 install beoremote-halo
```
## Basic Usage
In the following example a client instance connects to Beoremote Halo and listens for events. When a `SystemEvent` is received the `on_system_event` callback is executed and prints the Beoremote Halo's system state. Please refer to the [API](https://bang-olufsen.github.io/beoremote-halo) for details on each type of event.
```python
from beoremote import Halo
from beoremote.events import SystemEvent
def on_system_event(client: Halo, event: SystemEvent):
print(event)
remote = Halo("192.168.1.57")
remote.set_on_system_event_callback(on_system_event)
remote.connect()
```
## Example
Use the `beoremote-halo` CLI tool to discover and then run a demo by connecting to your Beoremote Halo.
In the above demo the CLI is used to locate Beoremote Halo on the network.
```
beoremote-halo scan
```
Afterwards the CLI demo is run by passing the serial number of the discovered Beoremote Halo.
```
beoremote-halo demo --serial xxxxxxxx
```
The demo configures the Beoremote Halo and reacts to events received from Halo. The callbacks each handle a specific type of [event](https://bang-olufsen.github.io/beoremote-halo/#message-event).
`on_system_event` is provided but unused in this example.
`on_wheel_event` changes the indicator ring on the centered/controlled button.
`on_button_event` changes the active/inactive state of a button, will start/pause/resume the timer if the "Oven Timer" button is pressed.