08 MQTT and Home Assistant
MQTT is entirely optional and not required for use of the parking assistant. However, if you do have an MQTT broker and a home automation system that can also communicate with the broker (like Home Assistant), you can use the parking system as a vehicle presense sensor and can also utilize the current measured distance in your automations.
MQTT is somewhat limited at this point, but additional features may be added based on feedback and example use cases.
Setup of MQTT is covered in the Using the Web Interface section of the wiki, but if you've used MQTT in other applications, it should be pretty self-explanatory.
Entering a topic: All messages will be published with a topic prefix of stat/ and the topic value you enter. The topic you enter must be 16 alphanumeric characters or less. Do not include spaces or symbols. Each parking assistant device that you have connected to MQTT must have a unique topic defined or they will overwrite each other's data.
Just remember that any changes to these settings require that you save the settings as new boot defaults and reboot the server, as described on the settings page.
Currently, the application published messages on the following topics:
| Topic | Payload | Values/Notes |
|---|---|---|
stat/your_topic/mqtt |
connected | Only published at boot time and shows a successful connection to broker. |
stat/your_topic/cardetected |
0 or 1 | 0 if no car (or object) detected in any parking zone, 1 otherwise |
stat/your_topic/parkdistance |
nnnn.n | Current measurement from the TFMini sensor. In millimeters if you selected millimeters as the unit of measure for distances on the web settings page, inches otherwise (see following note). |
stat/your_topic/ipaddress |
IP Address | (v0.45 and later) The current IP address of the parking assistant. This topic is updated at boot time, so any IP address changes will require a reboot of the controller before the topic is updated. |
stat/your_topic/macaddress |
MAC Address | (v0.45 and later) The current MAC address of the ESP board used in the parking assistant. |
All messages are published with the retain flag set to true.
Note on reported distance: Starting with version 0.42, an MQTT distance of 200" (or 5080 mm) will be published if an out-of-range measurement is returned from the TFMini. This is done to distinguish between an error (generally returned with a distance of 60,000+) and a simply out-of-range condition, such as when a car or no object is in range. If you see an MQTT reported distance value of greater than 50000 published (whether using inches or millimeters), then it means that the TFMini is reporting an error condition instead of an actual measurement.
As of the current version, there are no MQTT commands to topics that can be issued to control the parking assistant. I haven't come up with a good use case for this (yet). All settings must be entered via the web interface to be saved to the configuration file upon a reboot, so MQTT commands to update any settings would be practically meaningless. I suppose there may be a desire to use MQTT to turn the LEDs on/off and I may consider implementing that in some future release. But the current code is close to maxing out what the ESP8266 can handle, so any significant increase in features will likely also involve a port to ESP32.
This is also why the telemetry period (how often the controller updates the MQTT values) has a minimum value of 60 seconds.
Beginning with release 0.45, Home Assistant MQTT Discovery is now available. It is currently considered a beta feature as it has not undergone extensive testing by others, but it should allow the parking assistant to automatically create a device and the associated entities under the MQTT integration without any manual YAML or other Home Assistant configuration required.
Requirements
Please note the following are required for Home Assistant Discovery to work:
- You must have an MQTT broker installed and properly configured (the Home Assistant MQTT add-on is fine)
- The broker must be on the same network/subnet as the Parking Assistant and must be reachable by the Parking Assistant (e.g. no firewall blocks)
- You must have the MQTT integration installed in Home Assistant and properly configured for your broker.
- Discovery must be enabled in the MQTT integration (it is enabled by default so this should by OK unless you have changed it.)
- The default discovery topic (/homeassistant) must not have been changed in the MQTT integration
- You must have completed the MQTT broker information within the Parking Assistant application saved the settings as the new boot defaults and rebooted the controller
Enabling Discovery
With version 0.45 and later, there is a new option to 'Configure Home Assistant MQTT Discovery' just under the MQTT configuration information in the Parking Assistant web application. Clicking this link will open a new page:
Before clicking the button to enable Discovery, please note the following important points:
- Discovery executes immediately upon clicking the Enable Discovery button. There are no prompts or notifications in Home Assistant as the device and entities will be created automatically.
- The device created will have the same name as the name you gave your device when it was initially configured and installed. The device name is shown on this page (parkasst2 in the screen shot) and also at the top of the main controller settings page. If you wish to change this name before creating the Home Assistant entities, you must do a 'RESET ALL' of the device via the main settings page and complete the intial First Time Setup steps again.
- If you have already manually created MQTT entities in Home Assistant, this process will create a second version of those entities. You can either remove your manually created entities or keep both versions.
If the Parking Assistant is able to successfully send the discovery commands to your MQTT broker, a success page will be displayed. You should see a new device with your device's name listed under your MQTT integrations in Home Assistant (Settings -> Devices and Services then MQTT in Home Assistant). It should have two sensors and two diagnostics listed. If one or more of the entities are missing, try a simple refresh of the page. There seems to occasionally be an issue where all the entities are not immediately shown until the page is refreshed/reloaded.
You should also see the following entities under the Developer Tools -> States in Home Assistant (hint: filter by your device name, e.g. parkasst):
If car presence and/or park distance may show unknown if you just recently enabled MQTT in the Parking Assistant. As soon as the specified telemetry period in the Parking Assistant is reached, values will be published and should show up in Home Assistant. This make take a few moments as the minimum telemetry period is 60 seconds (1 minute), but may be longer if you changed this value.
You can rename any of the entity IDs or friendly names if desired by editing those entities from the above page in Home Assistant. See the Home Assistant documentation if you are unsure how to do this.
At this point, you can add these entities to your dashboard or use them in automations or scripts. You should not need to enable Discovery again from the Parking Assistant. If you do, any changes that you have made to these entities will be lost and the original ID/names will be restored.
Disabling Discovery (removing the device and entities)
If something doesn't work quite right or if you wish to simply remove the automaticatlly created device and entities from Home Assistant, you can use the 'Disable Discovery' button.
This step is immediate as soon as you click the disable button. The device and entities will be removed from Home Assistant with no further prompts or interaction.
If the process is successful, the device will no longer be seen under the MQTT integration in Home Assistant and the entities will no longer be listed under the developer tools.
If you had previously added these entities to your dashboard, or used them in any automations or scripts, you will need to remove or correct those items for the now missing entities.
If you want to recreate the original device and entities after they are removed by disabling discovery, you can simply reenable discover again.
Troubleshooting
The most common issue with discovery usually involves a failure of the Parking Assistant to communicate with the MQTT broker. A free MQTT viewer. like MQTT Explorer can be invaluable in helping you to resolve issue or confirm whether communication is occurring. If you have set up MQTT on the Parking Assistant settings page (and saved as default and rebooted), then a simple way to verify communication is to use this utility and look under the /stat topic for your device name:
Depending on which version of the parking assistant you are using, you should see your device's name and three or five topics underneath. If you do not see your device's name and do not see the 'mqtt = connected' topic, then your device is not communicating with the broker and Home Assistant Discovery is never going to work. Double check all your MQTT settings and assure your User Name and password are correct. When you see the above information in your MQTT broker, you can try discovery again.
No Device appears in Home Assistant or Entities are missing
If you receive a message in the Parking Assistant app that MQTT Discovery topics were successfully sent to Home Assistant, but you do not see your device appear under the MQTT integration, then use the MQTT utility again to look at your broker.
This time you should look under the /homeassistant topic. You should see one binary sensor and three sensors listed that start with 'prkast', six alphanumeric characters (last 6 of your device's MAC address) and a single letter indicating the type of sensor (P - car presence, D - Distance, I - IP Address and M - MAC address). If none of these are present, then it is again likely that your Parking Assistant lost the connection or was unable to re-establish a connection to the broker. Reboot your controller and try again.
If the topics are present, but one or more entities are missing in Home Assistant, it could be a number of things. First thing, try a simply refresh of the browser page in Home Assistant. There is intermittent issue with the device page in Home Assistant that newly discovered devices don't immediately show all the entities. Also check the entity state page under the developer tools to see if the entities are there, as described above.
If one or more entities are truly missing in Home Assistant, it is likely an issue with the generated payload. Use MQTT Explorer (or other utility) to copy the payload of the /config topic under the missing entity (P, D, I or M). Then paste this into a new message under the Discussion area of this repo. You will find a Home Assistant MQTT Discovery Toubleshooting topic. Please do not open a new issue. If it is determine that this is truly an issue with the firmware, I will happily move the discussion over to a new issue. By placing all the troubleshooting issues in one location, it may help others to resolve any problems they may be having.
Disabling Discovery Does Not Remove the Home Assistant Device/Entities OR The removed device and enties keep reappearing in Home Assistant after a restart
When you disable MQTT Discovery, the device and entities should immediately be removed from Home Assistant. This is done by sending an empty payload to the original MQTT discovery topics, which removes the topic and in turn causes Home Assistant to remove the entities. If there is a problem communicating with the broker or another unforeseen problem occurs when you click the 'Disable' button, these topics may not be removed from the broker.
The first thing to try is to simply disabling discovery again via the Parking Assistant app. If this still doesn't work (or the device/entities initially disappear but keep returning in Home Assistant), then you may need to manually delete the "stuck" (e.g. retained) topics from your broker via MQTT Explorer or other utility.
To manually delete the discover topics, browse to the /homeassistant topic as shown below. Check under binary_sensor and sensor, locate any remaining topics that begin with 'prkast' and delete the topic.
Do not inadvertanly delete any other topics. This should immediately remove the entities from Home Assistant (if they still exist) and prevent them from reappearing.
Other Problems or Issues
Please remember that the Home Assistant MQTT Discovery is still considered a beta feature at this point. If none of the above resolve a problem you may be having, please post the problem in the Home Assistant MQTT Discovery Toubleshooting topic and please do not create a new Issue.
If the problem still cannot be resolved, you can still integrate the Parking Assistant into Home Assistant using the prior manual method.
If you are running a version prior to v0.45 of the Parking Assistant or simply cannot get Discovery to work, you can still manually add the MQTT entities to Home Assistant and integrate your Parking Assistant. The /examples folder of this repository has a few examples of manually setting up MQTT sensors in Home Assistant that you can use on dashboards or in your automations.