04 ‐ MQTT and Home Assistant

MQTT

The FM receiver controller subscribes to MQTT topics to receive commands and publishes to MQTT to report states. This page shows the valid MQTT topics and payloads. The values MQTT_TOPIC_SUB and MQTT_TOPIC_PUB shown will be substituted with the topics you define in the Settings.h file.

By default, the MQTT_TOPIC_SUB is cmnd/fmrecvr and the MQTT_TOPIC_PUB is stat/fmrecvr

See the Settings and Credentials page for more information on changing the default MQTT topics.

While Home Assistant will be used as the source for sending commands and receiving states in this document, any system that can publish and receive MQTT topics can be used.

Command Topics - issued TO the the controller from Home Assistant to change the FM receiver options. As a general rule, these should be published with the retain flag set to false, but you may have reason to use a retained flag.

TOPIC	PAYLOAD	NOTES
MQTT_TOPIC_SUB/volume	0 - 15	Sets the output volume from the FM receiver
MQTT_TOPIC_SUB/preset_up	-	Increases the current preset station to the next station. Payload is optional and can be any character if required. Note that if the last preset is exceeded, it will wrap to the first preset.
MQTT_TOPIC_SUB/preset_down	-	Decreases the current preset station to the previous station. Payload is optional and can be any character if required. Note that if the first preset is exceeded, it will wrap to the last preset.
MQTT_TOPIC_SUB/preset_num	1 to num presets	Jump to a particular preset. "1" based, so first preset is preset 1 and the last preset is the total number defined.
MQTT_TOPIC_SUB/frequency	(n)nnnn	The frequency to tune. This is an integer value determined by mulitiplying the MHz frequency by 100. For example: 94.7 = 9470 and 104.5 = 10450
MQTT_TOPIC_SUB/status	-	Forces an update of all current MQTT states as listed below. Payload is optional but can be any character if required
MQTT_TOPIC_SUB/mute	on / off	Enable or disable mute. Payload can also be 1/0, or true/false
MQTT_TOPIC_SUB/softmute	on / off	Enable or disable soft mute (mutes low strength stations). Payload can also be 1/0, or true/false
MQTT_TOPIC_SUB/stereo	on / off	Enable or disable stereo (mono). Payload can also be 1/0, or true/false
MQTT_TOPIC_SUB/power	on / off	The FM receiver does not actually have a power state. This is only a 'simulated' state that will take certain actions regarding volume, preset, etc. See below for more informaiton on using the power command.

State Topics - issued FROM the controller to the MQTT broker. These states can then be used by Home Assistant for automations or shown on a dashboard. All topics are published as retained, unless otherwise noted.

TOPIC	PAYLOAD	NOTES
MQTT_TOPIC_PUB/mqtt	connected	This is published once, at boot time, to validate the MQTT connection. It is primarily used for troubleshooting
MQTT_TOPIC_PUB/ipaddress	nnn.nnn.nnn.nnn	This is published once, at boot time and is the current IP address of the ESP board (e.g. 192.168.1.205)
MQTT_TOPIC_PUB/volume	0 - 15	The current volume of the receiver.
MQTT_TOPIC_PUB/preset	0/1 to max presets	The currently selected preset station number. If a preset is not active, this value will be either 0 or empty (blank). Presets are "1" based in MQTT, so first preset is preset 1.
MQTT_TOPIC_PUB/freqency	(n)nn.n MHz)	Formatted current active frequency. This includes the 'MHz' (e.g 104.5 MHz)
MQTT_TOPIC_PUB/rawfreq	(n)nnnn	Integer value of raw frequency. This is the MHz value x 100 (e.g. 104.5 MHz = 10450).
MQTT_TOPIC_PUB/mute	on / off	Current state of the mute function. Either 'on' or 'off'.
MQTT_TOPIC_PUB/softmute	on / off	Current state of the soft mute function. Either 'on' or 'off'.
MQTT_TOPIC_PUB/stereo	on / off	Current state of the stereo function. Either 'on' or 'off'.
MQTT_TOPIC_PUB/power	on / off	Current state of the simulated power state. See notes below on power setting. Either 'on' or 'off'.
MQTT_TOPIC_PUB/rdsname	string	The RDS (radio data service) service name being broadcast. See notes below.
MQTT_TOPIC_PUB/rdstext	string	The RDS text being broadcast. See notes below.

NOTE on Power Setting (on/off): The FM receiver used (SI4703) does not have a true power on/off state. Instead this is simulated by using MQTT commands. When the power "off" command is sent, the following actions occur:

• The volume is muted (but not set to on via the MQTT state)
• The MQTT volume is reported as 0 (but not really changed)
• Current MQTT frequency is blanked out
• MQTT preset value is set to 0
• MQTT soft mute and stereo values are set to 'off'
• The MQTT power state is changed to 'off'
• MQTT RDS name and text are cleared.

Other than muting the volume, no actual change to the FM receiver occurs. It is just a change in the reported MQTT states. Since all FM receiver values are still the same, when the power is toggled back 'on', then all the prior settings are simply restored and MQTT values updated. All this really does is provide a way to create a simulated power button on a dashboard or other control option.

Notes on RDS Data:

RDS or Radio Data System data is embedded in some FM broadcasts as small pieces of data that can be decoded and displayed. Often this is information such as the station's call letters and maybe the artist/title of the currently playing song. Not all stations broadcast this information and even if broadcasting, the data may not be received if the FM signal is too weak. There are two separate fields that can be used: The RDS Service Name (normally the station ID) and RDS Text, which can be used for various implementations by the station, including sending ads! There is also a time field, but that is is not implemented in this version.

Even when sending data, how the station opts to use these fields and send their data can vary widely. You may see exactly what might be expected from one station (e.g. 'WZPL' as the service name and 'Current Artist/Song as the text). But another station may send data in a completely different way, including sending a small amount of text with each update. This will often create a scrolling test display on somm receivers and you may have seen this on something like your car stereo. Unfortunately, Home Assistant doesn't have a way to display scrolling text. The code here does not manipulate the received data... it simply publishes the Service Name and Text data as received from the station.

Home Asssistant

As currently written, MQTT and Home Assistant (or other automation system capable of publishing and receiving MQTT topics) is recommended, as that is the primary purpose of this repo. If you do not need or do not plan on using MQTT, then you should just use the RADIO library without the additional wrapper functionality.

Home Assistant does provide a nice interface for sending MQTT commands to control and change some of the options of the FM Receiver. See the /homeassistant folder for examples of integrating the FM Receiver, afew example scrips and automations, and a sample dashboard, along with the YAML necessary to create them.