broadlink-bridge

A HTTP/MQTT/LIRC bridge to Broadlink IR/RF devices, written in Python and powered by python-broadlink.

Note: that there is a similar project for Node.js with the same name.

Features

supports HTTP protocol
supports MQTT protocol
supports LIRC protocol
supports multiple Broadlink devices
supports Broadlink IR/RF codes
supports Pronto hex codes
supports defining named commands
supports specifying repeats
can act as sending hardware for IrScrutinizer via the LIRC output

Installing/running

To install: pip install [--user] git+https://github.com/lbschenkel/broadlink-bridge.git

To run: broadlink-bridge [config-file]

Docker

(to be written)

Usage in Home Assistant

This bridge is available as an unnoficial add-on.

Codes can be transmitted via RESTful commands:

rest_command:
  my_command:
    url: http://BRIDGE_HOST:PORT/device/DEVICE
    method: post
    payload: CODE

Or by publishing via MQTT, for example in an entity button:

type: entity-button
name: My command
entity: ...
tap_action:
  action: call-service
  service: mqtt.publish
  service_data:
    topic: PREFIX/device/DEVICE/transmit
    payload: CODE

An on/off switch can be implemented directly via a MQTT switch:

switch:
- platform: mqtt
  command_topic: PREFIX/device/DEVICE/transmit
  payload_on: CODE
  payload_off: CODE

Or by combining RESTful commands with a boolean input and an automation:

rest_command:
  my_device_on:
    url: http://BRIDGE_HOST:PORT/device/DEVICE
    method: post
    payload: CODE
  my_device_off:
    url: http://BRIDGE_HOST:PORT/device/DEVICE
    method: post
    payload: CODE
input_boolean:
  my_device:
    name: My Device
automation:
  trigger:
    platform: state
    entity_id: input_boolean.my_device
  action:
    service_template: rest_command.my_device_{{ trigger.to_state.state }}

Note that the RESTful switch is not useful, because it relies on the REST endpoint providing the state (not possible here) and it does not implement an optimistic mode with an assumed state (like the MQTT switch does).

In the above:

BRIDGE_HOST is the hostname/IP address of this bridge
PORT is the HTTP port (default 8780)
PREFIX is the MQTT prefix (default broadlink)
DEVICE identifies the target device
CODE is the code (or command) to transmit, prefixed by any repeats

Configuration

A configuration file can be optionally specified as a command-line argument. An example file is provided.

MQTT client

To enable the MQTT client, it is necessary to specify the URL of the MQTT broker as the broker_url value inside the [mqtt] section.

The prefix for the MQTT topics is configurable via topic_prefix.

Manually declared devices

Devices can be manually declared in the [devices] section. When a device is declared in this way it is given an alias which can act as an additional identifier for the device in the bridge. Auto-discovered devices do not have aliases.

Commands

Commands can be defined in the [commands] section. Commands associate a name with a code. The name can then be used anywhere where a code can appear.

The code for the command can be in any supported format and contain repeats, with the exception that it cannot be another command.

Protocols

Definitions

Device

A device represents a Broadlink device which can be addressed on any of the protocols. It can be identified by any of the following:

by its alias (as specified in the configuration file)
by its host (as specified in the configuration file or found via discovery)
by its MAC address
by one of its IP addresses

When the device is not found via one of the mechanisms above, a final attempt is made by interpreting device as a host: in case a device is discovered at that address, then it is added to the list of known devices (this can be considered a lazy discovery mechanism).

Default device

The default device is the device with an alias of default. If there is no device with such an alias, it is the first declared or discovered device.

Code

The code is the data to transmit. It can have one of the following forms:

IR/RF data in Broadlink format (encoded as base64): JgAcAB0dHB44HhweGx4cHR06HB0cHhwdHB8bHhwADQUAAAAAAAAAAAAAAAA=

IR data in Pronto hex format:

0000 006C 0022 0002 015B 00AD 0016 0016 0016 0016 0016 0041 0016 0016 0016
0016 0016 0016 0016 0016 0016 0016 0016 0041 0016 0041 0016 0016 0016 0041
0016 0041 0016 0041 0016 0041 0016 0041 0016 0016 0016 0016 0016 0041 0016
0016 0016 0016 0016 0016 0016 0041 0016 0041 0016 0041 0016 0041 0016 0016
0016 0041 0016 0041 0016 0041 0016 0016 0016 0016 0016 05F7 015B 0057 0016
0E6C

a command defined via the configuration file: in that case the code for the command is used (which can have any of the above forms)

Note that codes can contain repeats (see next section).

Repeats

Repeats are the number of times a code will be retransmitted. Repeats can be specified in multiple ways:

as part of the code — if the code starts with N* (number plus asterisk) then the code will be sent N times (N-1 repeats), for example:
- 3 * JgAcAB... (Broadlink format, sent 3 times)
- 2 * 0000 006C ... (Pronto hex format, sent 2 times)
- 5 * tv/on (command defined via configuration file, sent 5 times)
inside Broadlink data packet (second data byte is the number of repeats)
via the protocol command (in case of LIRC)

When repeats are specified in more than one way, their effects multiply. For example, LIRC command SEND_ONCE default 3*tv/on 1 (1 being the repeat and tv/on being a command defined in the configuration file as 2*JgAcAB...) will result in the code being sent 2x3x2 = 12 times (11 repeats).

HTTP

verb	path	description
POST	/device/device	transmits the submitted code via device

Status codes:

404 when the device is unknown
400 when the code is invalid or not recognized

MQTT

The topic prefix defaults to broadlink and can be changed via the configuration file.

topic	description
prefix/device/device/transmit	transmits the submitted code via device

LIRC

A subset of the LIRC command interface and the unofficial CCF extension is supported.

command	description
SEND_ONCE device code [repeat]	transmits the given code (no spaces) via device, optionally repeating it repeat times
SEND_CCF_ONCE repeat code	transmits the given code (spaces allowed) via the default device, repeating it repeat times
LIST	replies with all known devices
LIST device	replies with all defined commands (commands are not device-specific)
VERSION	replies with bridge version

lbschenkel / broadlink-bridge