08 Home Assistant Integration and Use
This section assumes you have a properly configured MQTT broker and that MQTT has been properly integrated into Home Assistant. If you are using the Home Assistant MQTT Mosquitto add-on, the integration is handled for you. Otherwise, please see the Home Assistant documentation on integrating MQTT into your instance. This integration is outside of the scope of this project and will not be covered.
For all the examples given (here and in the /homeassistant folder), it is assumed that the root command and state topics are cmnd/deskamp and stat/deskamp, respectively. If you want to use different topics, then you must change the values in the Settings.h file and update all the code examples accordingly (see Credentials and Settings). For example, if you want to use the name garageamp instead of deskamp, then you need to update the Settings.h file to use the topics cmnd/garageamp and stat/garageame and substitute your topics in all the examples given. It is highly recommended that you maintain different topics for commands and states. Otherwise, the retain flag may be set improperly leading to ghosting or other unexpected actions occurring with the amp.
There are no auto-discovery topics defined in the code. Any desired sensors, switches, etc. will need to be manually created in Home Assistant.
The MQTT topics can be used directly in automations and scripts. YAML is shown below, but the same thing can be done via the UI Automation editor. MQTT topics and payloads can be used as triggers, conditions or actions. The state topics (/stat) are generally used for triggers and conditions, while the command topics (/cmnd) are normally used for actions.
Example triggers
trigger:
platform: mqtt
topic: "stat/deskamp/source"
payload: "BT"
trigger:
platform: mqtt
topic: "stat/deskamp/volume"
The payload may or may not be used in the trigger depending upon when you want the automation trigger to fire. In the first example, the automation will only run when a payload of "BT" is received on the state /source topic. In the second example, the automation will fire anytime a new volume value is received on the state /volume topic.
Note that payloads can also be used in conditions and actions. They are normally referenced using {{trigger.payload}}. See the Home Assistant documention for more information on using automation triggers and conditions.
Example actions
action:
service: mqtt.publish
data:
topic: "cmnd/deskamp/source"
payload: "BT"
action:
service: mqtt.publish
data:
topic: "cmnd/deskamp/volume"
payload: "40"
You can publish a command to the amp in an automation (or script) action by simply specifying the topic and payload as part of an mqtt.publish service call. In the first example, a command is issued on the /source topic with a payload of "BT", which will cause the amp to switch to bluetooth as its source. In the second example, the volume of the amp will be set to a value of 40. These are just a few simple examples. The payload can also be used in choose, if-then, while and other actions. See the Home Assistant documentation for more details on these actions.
Currently, MQTT based sensors and switches can only be created via YAML. In the future, there may be a UI option for these. In addition, the exact syntax and indentation will vary depending on whether you are using a single configruation.yaml file, have a split configuration or are using packages. So, the following are examples only that you may have to adapt to how your particular configuration is setup in Home Assistant.
Sensors
Sensor will generally just contain the last payload value published on a particular state topic and are easy to define.
mqtt:
sensor:
- name: "Amp Volume"
topic: "stat/deskamp/volume"
This is an example of a sensor in its simpliest state. Whenever a value (payload) is received on the state topic /volume, the value of the sensor is set to the payload. If the amp publishes a payload of 35 for /volume, then the Home Assistant entity sensor.amp_volume will have a value of "35".
You can add any other valid sensor attribute if desired, like icon, unit of measure, etc. You can even translate values if desired by using template values:
mqtt:
sensor:
- name: "Amp Volume"
state_topic: "stat/deskamp/volume"
value_template: |-
{% if (value < 35) %}
Low
{% else if (value < 70) %}
Medium
{% else %}
High
{% endif %}
In this example, the value of the entity sensor.amp_volume will be either Low, Medium or High based on the payload value received on the /volume topic. You can create binary sensors in the same manner if the payload expected to be only one of two possible values such as '0' or '1'.
Switches
Switches are unique in the fact that they subscribe to one topic to determine their state, but also publish on a different topic to change the state of an amp. They are normally used to control buttons, slider or other selectors on the dashboard. The example I'm showing below is some of the code used to both show and control the current source of the amp:
Each button is a switch entity, defined as follows:
mqtt:
switch:
# Bluetooth
- name: "Desk Amp Source Bluetooth"
state_topic: "stat/deskamp/source"
value_template: "{{ value == 'BT' }}"
command_topic: "cmnd/deskamp/source"
payload_on: "BT"
payload_off: ""
state_on: true
state_off: false
retain: false
# USB
- name: "Desk Amp Source USB"
state_topic: "stat/deskamp/source"
value_template: "{{ value == 'USB' }}"
command_topic: "cmnd/deskamp/source"
payload_on: "USB"
payload_off: ""
state_on: true
state_off: false
retain: false
# .... other switches defined in same manner
As you can see, a switch has both a state topic and a command topic. The state topic determines whether the switch is "on" or "off", based on the state topic. In the first switch example, when the amp publishes it source stat on the topic /source, if the payload value is "BT", then the switch is turned "on". Other buttons or switches will be turned "off" as the payload does not match their value template. This method always keeps the dashboard (and switch state) in sync with the app, even if the source is changed outside of Home Assistant, for example via a button on the amp itself or via a remote control device.
If the actual button on the dashboard is clicked, then the switch issue a command on the command topic with an appropriate payload. Using the second example, if the USB button is clicked on the dashboard, the switch will publish a command topic on the /source topic with a payload of "USB". The amp will receive this and switch to the USB source:
Note that not only did the USB button turn on, but the Bluetooth button turned off. This is because these state topic /source returned by the amp is now "USB", so the bluetooth switch has a value of "off" while the USB switch's value is "on".
This is just a basic example. See the Home Assistant documentation for more information on switches.
MQTT topics and payloads can also be used to update other entities and helpers, such as sliders (input_number), drop down lists (input_select) and text fields (input_text):
To see my full YAML package that contains my automations, scripts, sensors, switches and helpers, it is avaliable in the /homeassistant folder. But please note that this if for my specific amp build, MQTT topics and Home Assistant configuration layout. It is very unlikely that you can simply copy and paste this code directly into your Home Assistant without modification. But it may assist you in creating your own MQTT entities for your amp.