Setting Up MQTT Publishing
====
-This is a rough guide on the setup of MQTT publishing in ShairPort-Sync.
+This is a rough guide on the setup of MQTT publishing in ShairPort-Sync. The MQTT service listens for and publishes metadata generated by the airplay source and shairport-sync.
+Below is a simple example of configuring shairport-sync to send parsed metadata to a MQTT server under the topic "shairport"
-The MQTT listens for and publishes metadata generated by shairport-sync
+Example Configuration
+----
+
+Shairport-sync is configured below to published parsed metadata information and album-art to a MQTT server.
+
+```xml
+
+metadata =
+{
+ enabled = "yes"; // set this to yes to get Shairport Sync to solicit metadata from the source and to pass it on via a pipe
+ include_cover_art = "yes"; // set to "yes" to get Shairport Sync to solicit cover art from the source and pass it via the pipe. You must also set "enabled" to "yes".
+ cover_art_cache_directory = "/tmp/shairport-sync/.cache/coverart"; // artwork will be stored in this directory if the dbus or MPRIS interfaces are enabled or if the MQTT client is in use. Set it to "" to prevent caching, which may be useful on some systems
+ pipe_name = "/tmp/shairport-sync-metadata";
+ pipe_timeout = 5000; // wait for this number of milliseconds for a blocked pipe to unblock before giving up
+};
+
+
+mqtt =
+{
+ enabled = "yes"; // set this to yes to enable the mqtt-metadata-service
+ hostname = "192.168.1.111"; // Hostname of the MQTT Broker
+ port = 1883; // Port on the MQTT Broker to connect to
+ username = "username"; //set this to a string to your username in order to enable username authentication
+ password = "password"; //set this to a string you your password in order to enable username & password authentication
+ topic = "shairport"; //MQTT topic where this instance of shairport-sync should publish. If not set, the general.name value is used.
+// publish_raw = "no"; //whether to publish all available metadata under the codes given in the 'metadata' docs.
+ publish_parsed = "yes"; //whether to publish a small (but useful) subset of metadata under human-understandable topics
+ publish_cover = "yes"; //whether to publish the cover over mqtt in binary form. This may lead to a bit of load on the broker
+// enable_remote = "no"; //whether to remote control via MQTT. RC is available under `topic`/remote.
+};
+```
+
+Import Notes
+----
+
+Publish Options
+
+One needs to set either `publish_raw`, `publish_parsed` or `publish_cover` in the MQTT setup or no messages will be published.
+
+
+Overall Active State of Stream
+
+`active_start` and `active_end` represent a stable on/off flag for the current airplay session.
+
+`active_start` is plublished when any new airplay session begins
+
+`active_end` will fire after a configured timeout period unless the airplay stream is resumed.
+
+```xml
+sessioncontrol =
+{
+// "active" state starts when play begins and ends when the active_state_timeout has elapsed after play ends, unless another play session starts before the timeout has fully elapsed.
+ active_state_timeout = 30.0;
+};
+```
MetaData Parsing
----
* `snua` -- a "user agent" e.g. "iTunes/12..." has started a play session. Specifically, it's the "User-Agent" string.
* `stal` -- this is an error message meaning that reception of a large piece of metadata, usually a large picture, has stalled; bad things may happen.
-The next two two tokens are to facilitiate remote control of the source. There is some information at http://nto.github.io/AirPlay.html about remote control of the source.
- * `daid` -- this is the source's DACP-ID (if it has one -- it's not guaranteed), useful if you want to remotely control the source. Use this string to identify the source's remote control on the network.
- * `acre` -- this is the source's Active-Remote token, necessary if you want to send commands to the source's remote control (if it has one).
- * `dapo` -- the payload is the port number (as text) of the source's remote control, to which commands should be sent. It is 3689 for iTunes but varies for iOS devices.
-
-
Parsed Messages
----
* `active_start` -- fired when a new active airplay session begins
* `active_end` -- fired after a configured timeout period after the stream ends (unless a new stream begins)
-Import Notes
-----
-One needs to set either `publish_raw`, `publish_parsed` or `publish_cover` in the MQTT setup or no messages will be published.
-`active_start` and `active_end` represent a stable on/off flag for the current airplay session.
+## Consuming MQTT Data
-`active_start` is plublished when any new airplay session begins
+Users will find examples on how to consume the MQTT data in various home automation projects. If a user has an interesting use please raise a new issue to suggest adding it to the guide, or simply fork the development branch and create a pull-request.
-`active_end` will fire after a configured timeout period unless the airplay stream is resumed.
+### Home Assistant Variable Templates
-```xml
-sessioncontrol =
-{
-// "active" state starts when play begins and ends when the active_state_timeout has elapsed after play ends, unless another play session starts before the timeout has fully elapsed.
- active_state_timeout = 30.0;
-};
-```
+Examples of consuming "parsed" MQTT data in [Home Assistant](https://www.home-assistant.io/)
+The `active_start` and `active_end` have good potential use as triggers to turn on and off various connect receivers/zones. The messages published are empty and therefor no "payload_on" is set, "payload_off" however is set to prevent accidental triggering.
+```yml
+binary_sensor:
+ - platform: mqtt
+ name: "shairport active start"
+ state_topic: "shairport/active_start"
+ payload_on: ""
+ payload_off: "OFF"
+ off_delay: 300
-Example Configuration
-----
-
-Shairport-sync is configured below to published parsed metadata information and album-art to a MQTT server.
-
-```xml
-
-metadata =
-{
- enabled = "yes"; // set this to yes to get Shairport Sync to solicit metadata from the source and to pass it on via a pipe
- include_cover_art = "yes"; // set to "yes" to get Shairport Sync to solicit cover art from the source and pass it via the pipe. You must also set "enabled" to "yes".
- cover_art_cache_directory = "/tmp/shairport-sync/.cache/coverart"; // artwork will be stored in this directory if the dbus or MPRIS interfaces are enabled or if the MQTT client is in use. Set it to "" to prevent caching, which may be useful on some systems
- pipe_name = "/tmp/shairport-sync-metadata";
- pipe_timeout = 5000; // wait for this number of milliseconds for a blocked pipe to unblock before giving up
-};
-
+ - platform: mqtt
+ name: "shairport active end"
+ state_topic: "shairport/active_end"
+ payload_on: ""
+ payload_off: "OFF"
+ off_delay: 300
+```
-mqtt =
-{
- enabled = "yes"; // set this to yes to enable the mqtt-metadata-service
- hostname = "192.168.1.111"; // Hostname of the MQTT Broker
- port = 1883; // Port on the MQTT Broker to connect to
- username = "username"; //set this to a string to your username in order to enable username authentication
- password = "password"; //set this to a string you your password in order to enable username & password authentication
- topic = "shairport"; //MQTT topic where this instance of shairport-sync should publish. If not set, the general.name value is used.
-// publish_raw = "no"; //whether to publish all available metadata under the codes given in the 'metadata' docs.
- publish_parsed = "yes"; //whether to publish a small (but useful) subset of metadata under human-understandable topics
- publish_cover = "yes"; //whether to publish the cover over mqtt in binary form. This may lead to a bit of load on the broker
-// enable_remote = "no"; //whether to remote control via MQTT. RC is available under `topic`/remote.
-};
+Below parsed data is saved into the Home Assistant database as sensor data. Please not the conversion of the volume from dB to percentage.
+
+```yml
+sensor:
+ - platform: mqtt
+ name: "shairport album"
+ state_topic: "shairport/album"
+ expire_after: 600
+
+ - platform: mqtt
+ name: "shairport artist"
+ state_topic: "shairport/artist"
+ expire_after: 600
+
+ - platform: mqtt
+ name: "shairport title"
+ state_topic: "shairport/title"
+ expire_after: 600
+
+ - platform: mqtt
+ name: "shairport genre"
+ state_topic: "shairport/genre"
+ expire_after: 600
+
+ - platform: mqtt
+ name: "shairport volume (dB)"
+ state_topic: "shairport/volume"
+
+ - platform: mqtt
+ name: "shairport volume (PCT)"
+ state_topic: "shairport/volume"
+ value_template: "{{ value | regex_findall_index(find='^(.+?),', index=0, ignorecase=False) | float / 30 + 1 }}"
+ unit_of_measurement: 'percent'
```
projects / thirdparty / shairport-sync.git / commitdiff
