Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/raman325/broadlink-rm-rest

Python based REST server to interact with Broadlink RM IR/RF blasters
https://github.com/raman325/broadlink-rm-rest

broadlink homeautomation iot python rest

Last synced: 2 months ago
JSON representation

Python based REST server to interact with Broadlink RM IR/RF blasters

Awesome Lists containing this project

README 

        
# Broadlink RM REST Server



## Purpose

This Python based web server provides REST interactivity with any local [Broadlink RM*](http://www.ibroadlink.com/rm/) type IR/RF blasters.



NOTE: To connect your RM devices to your network without downloading the Broadlink mobile app, refer to the [python-broadlink Example Use](https://github.com/mjg59/python-broadlink#example-use) instructions.



Please read the [Notes](#notes) section before using. Refer to the [API](#api) section to learn how this server can be used.



## Intro

There are three objects that this application manages:

- *Blasters* are the Broadlink devices on your network which can transmit IR/RF signals

- *Targets* are aliases for the devices you want to control using *blasters*

- *Commands* are aliases for raw IR/RF commands



The basic process to use this app is:

1. Discover all *blasters* on your network by making a `GET` request on the `/discoverblasters` endpoint (this is done on app initialization so it's only required if the initial discovery failed or a new device gets added to the network). This will add them to the application's database. You can assign a friendly name to each one or use MAC/IP addresses to reference them after they have been discovered.

2. Create a *target* for every device you want to control using your *blasters* by making a `PUT` request on the `/targets/` endpoint

3. For each *target*, you can either use a specific *blaster* to learn a *command* by making a `PUT` request on the `/targets//commands/?blaster_attr=&blaster_value=` endpoint and pressing the corresponding key on your remote while pointing at the *blaster* specified, or you can create a *command* from a base64 value if you already know the raw *command* by making a `PUT` request on the `/targets//commands/?value=` endpoint

4. Repeat 2 + 3 until all *targets* and *commands* have been added to the database.

5. From now on, you can reference *blasters*, *targets*, and *commands* by the aliases you created.



## Setup



### Docker Instructions



To create and start container:

```docker run -d --name broadlink_rm_rest --restart unless-stopped -p 8000:8000 -v :/app/data raman325/broadlink-rm-rest```



> I have tested this on my Synology Diskstation NAS and have run into problems with my network configuration that prevented python-broadlink from being able to discover blasters. To resolve this problem, I switched from bridged network mode to host network mode by changing `-p 8000:8000` in the above command to `--network host`.



### Local Setup

1. Clone this repo.

2. `cd broadlink-rm-rest/`

2. Install dependencies via pip: `pip3 install -r requirements.txt`

3. `cd app/`

5. `gunicorn -b 0.0.0.0:8000 app:app`



Your databases will be available in the app/data folder.



#### Environment Variables

To override the default values, add `-e =` for each corresponding parameter name and value.



Parameter Name | Default Value | Description

-------------- | ------- | -----------

`HOST` | `0.0.0.0` | Specifies the HOST that will be used to access the REST server. Default exposes the server to the entire network. To provide local access only, use `127.0.0.1` or `localhost` instead.

`PORT` | `8000` | Specifies the port that the container will listen on. Note that if this is changed, the `create` command should be updated accordingly (e.g. `-p :`).

`DISCOVERY_TIMEOUT` | `5` | Specifies the number of seconds (supports floats) that the application will wait for blasters to respond to discovery requests.

`HEALTH_TIMEOUT` | `1` | Specifies the number of seconds (supports floats) that the application will wait for the specified Broadlink blaster to confirm availability before timing out.



#### Persist DB files

In the `docker run` command listed above, the DB files (commands.db and blasters.db) will be persisted in /local/path/to/data on your host server.



## API

- An `HTTP 200 OK` will be returned if the call was successful.

- An `HTTP 400 BAD REQUEST` will be returned if a request was malformed or if a given resource was not found.

- An `HTTP 409 CONFLICT ` will be returned if a request attempted to create/update a resource that conflicts with an existing resource.

- All responses are in JSON format.



Endpoint | HTTP Method | Description

-------- | ----------- | -----------

`/discoverblasters` | `GET` | Discovers all new Broadlink RM blasters and adds them to the database (Note: blasters must be in the database before they can be used by the application, and they must be on and connected to the local network to be discoverable. You can add the Broadlink devices to your network using the instructions [here](https://github.com/mjg59/python-broadlink#example-use)). Blasters will be added to the database unnamed, so it's recommended to use `PUT /blasters//?new_name=` to set a friendly name for each blaster.

NOTE: Discovery will also update blaster IP addresses when applicable.

`/blasters` | `GET` | Gets all blasters (only returns blasters that have already been discovered once). | 

`/blasters?target_name=&command_name=` | `POST` | Sends command `` for target `` to all blasters.

`/blasters//` | `GET` | Gets specified blaster. `` should be either `ip`, `mac`, or `name`, and `` should be the corresponding value.

`/blasters//` | `DELETE` | Deletes specified blaster. `` should be either `ip`, `mac`, or `name`, and `` should be the corresponding value.

`/blasters//?new_name=` | `PUT` | Sets blasters name to ``, replacing an existing name if it already exists. `` should be either `ip`, `mac`, or `name`, and `` should be the corresponding value.

NOTE: If blaster lookup via IP isn't working, try to rediscover blasters using /discoverblasters which will update IP addresses to their latest.

`/blasters//?target_name=&command_name=` | `POST` | Sends command `` for target `` via specified blaster. `` should be either `ip`, `mac`, or `name`, and `` should be the corresponding value.

NOTE: If blaster lookup via IP isn't working, try to rediscover blasters using /discoverblasters which will update IP addresses to their latest.

`/blasters///status` | `GET` | Verifies availability of specified blaster. `` should be either `ip`, `mac`, or `name`, and `` should be the corresponding value. Returns an `HTTP 200 OK` if the blaster responds to status check within the `BROADLINK_STATUS_TIMEOUT` timeout window, else returns an `HTTP 408 GATEWAY TIMEOUT`.

`/commands` | `GET` | Gets all commands.

`/targets` | `GET` | Gets all targets.

`/targets/` | `PUT` | Creates target ``.

`/targets/` | `DELETE` | Deletes target `` and all of its associated commands.

`/targets/?new_name=` | `PATCH` | Updates the name of `` to ``.

`/targets//commands` | `GET` | Gets all commands for target ``.

`/targets//commands/` | `GET` | Gets command `` for target ``.

`/targets//commands/` | `DELETE` | Deletes command `` for target ``.

`/targets//commands/?new_name=` | `PATCH` | Updates command name of  `` for target `` to ``.

`/targets//commands/?blaster_attr=&blaster_value=` | `PUT` | Learns command `` for target `` using specified blaster. `` should be either `ip`, `mac`, or `name` and `` should be the corresponding value. If `` already exists, it will be replaced with the new value. Waits for ~10 seconds to detect an input signal from the blaster specified before timing out and consequently returning an `HTTP 408 GATEWAY TIMEOUT`.

NOTE: If blaster lookup via IP isn't working, try to rediscover blasters using /discoverblasters which will update IP addresses to their latest.

`/targets//commands/?value=` | `PUT` | Sets the value command `` for target `` to ``. If `` already exists, it will be replaced with the new value. If you plan to use this method, you should look at the code to see how values are encoded, or use existing command values in the database.



## Notes

1. The blasters and target/commands databases, blasters.db and commands.db, are independent files because  they are completely unrelated. As long as you are using Broadlink RM* blasters, you can use the same commands.db for every instance of the application.

2. The database files are in SQLite3 format and can be hand edited if needed. I use [SQLiteStudio](https://sqlitestudio.pl/index.rvt).

3. To reset all settings/data, simply stop the container/app, delete the two .db files, and restart.

4. This was tested on an RM3 Mini but should theoretically support any RM device that [python-broadlink](https://github.com/mjg59/python-broadlink) does.



## Shout outs

1. @mjg59 for [python-broadlink](https://github.com/mjg59/python-broadlink)

2. @falconry for [falcon](https://github.com/falconry/falcon). This is my first REST app and [falcon](https://github.com/falconry/falcon) made it a breeze.

3. @coleifer for [peewee](https://github.com/coleifer/peewee) which made persisting the data simple.

4. My wife for putting up with my late night/weekend experimentation.



## TODO

1. Test cases

2. Authentication

3. Mechanism to export/import commands

4. Mechanism to share commands