{"id":13801794,"url":"https://github.com/agners/micropython-ha-mqtt-device","last_synced_at":"2025-05-07T20:10:41.166Z","repository":{"id":138111222,"uuid":"262187158","full_name":"agners/micropython-ha-mqtt-device","owner":"agners","description":"MicroPython module which allows to create Entites for HomeAssistant using MQTT Discovery","archived":false,"fork":false,"pushed_at":"2020-05-08T00:20:59.000Z","size":4,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-02T00:34:43.296Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agners.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-05-08T00:20:37.000Z","updated_at":"2024-04-22T10:41:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c7d7e92-570b-41bb-8ab3-b78e40588205","html_url":"https://github.com/agners/micropython-ha-mqtt-device","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agners%2Fmicropython-ha-mqtt-device","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agners%2Fmicropython-ha-mqtt-device/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agners%2Fmicropython-ha-mqtt-device/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agners%2Fmicropython-ha-mqtt-device/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agners","download_url":"https://codeload.github.com/agners/micropython-ha-mqtt-device/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252949279,"owners_count":21830152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T00:01:27.525Z","updated_at":"2025-05-07T20:10:41.098Z","avatar_url":"https://github.com/agners.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["Communications"],"readme":"# MicroPython library to create sensors for HomeAssistant using MQTT Discovery\n\nThis is a simple MicroPython library which allows to create sensors and group of\nsensors for HomeAssistant. The library makes use of the HomeAssistant [MQTT\nDiscovery](https://www.home-assistant.io/docs/mqtt/discovery/) method by\nannouncing the devices through a configuration topic.\n\n## Getting Started\n\n### Prerequisites\n\n* MicroPython board capable of sending MQTT messages\n* HomeAssistant with MQTT Broker running\n* Some kind of sensor (not mandatory, but useful ;-))\n\n### Usage\n\n#### MQTT Client\n\nFirst a MQTT Client needs to be created. The module\n[umqtt.simple](https://github.com/micropython/micropython-lib/tree/master/umqtt.simple)\nprovides a simple MQTT client. The module can be installed using upip. Make\nsure you are connected to the internet, e.g. using WiFi:\n\n```\nimport network\nwl = network.WLAN(network.STA_IF)\nwl.active(True)\nwl.connect(\u003cSSID\u003e, \u003cPSK\u003e)\nwl.config(dhcp_hostname=\"Testboard\")\n```\n\nInstall the `umqtt.simple` module and create a MQTTClient object:\n```\nupip.install(\"micropython-umqtt.simple\")\nfrom umqtt.simple import MQTTClient\nmqttc = MQTTClient(b\"umqtt-testboard\", \u003cMQTT Server IP\u003e, keepalive=10)\nmqttc.connect()\n```\n\n#### Basic sensor\n\nThis example creates a single sensor and announces values. The second argument\nto the `Sensor` constructor is the name argument and will be the entity name in\nHomeAssistant. The argument `extra_config` allows to pass additional\nconfiguration values as specified by the [MQTT Sensor\nComponent](https://www.home-assistant.io/integrations/sensor.mqtt/). In this\ncase the device class and unit of measurement of the sensor is specified.\n\nWith the creation of the Sensor object a persistent MQTT message is sent to the\ndiscovery topic. The configuration will be picked up by HomeAssistant and a\nsensor is created. The topic for the entites states update is handled by the\nclass.\n\nThe `publish_state()` function will send the MQTT message to the state topic\nwhich will update the state of the particular entity in HomeAssistant.\n\n```\n# Temperature sensor...\nimport time\ntemp_config = { \"unit_of_measurement\": \"°C\", \"device_class\": \"temperature\" }\ntemp = Sensor(mqttc, b\"temperature_sensor\", b\"sensorid\", extra_conf=temp_config)\nfor i in range(10, 30):\n    temp.publish_state(str(i))\n    time.sleep(1)\n\n# This deletes the sensor from HomeAssistant as well!\ntemp.remove_entity()\n```\n\n#### Multiple sensors\n\nMultiple entities can share the same MQTT state topic. This allows to send a\nsingle (JSON formatted) MQTT message to update multiple entites in\nHomeAssistant. For this each entity needs to have a `value_template` specified\nso each entity know which value it needs to parse.\n\n```\ngroup = EntityGroup(mqttc, b\"testboard\")\nsensor1_config = { \"unit_of_measurement\": \"°C\", \"device_class\": \"temperature\",\n    \"value_template\": \"{{ value_json.temperature }}\" }\nsensor1 = group.create_sensor(b\"test1\", b\"test1id\", extra_conf=sensor1_config)\n\nsensor2_config = { \"unit_of_measurement\": \"%\", \"device_class\": \"humidity\",\n    \"value_template\": \"{{ value_json.humidity }}\" }\nsensor2 = group.create_sensor(b\"test2\", b\"test2id\", extra_conf=sensor2_config)\n```\n\nTo update the group the `publish_state()` function on the group object needs to\nbe used:\n```\nfor i in range(10, 30):\n    group.publish_state({ \"temperature\": str(i), \"humidity\": str(10 + i) })\n    time.sleep(1)\n```\n\nTo delete all entities of this group:\n```\ngroup.remove_group()\n```\n\n#### Multiple sensors with Device registry\n\nHomeAssistant allows to group entites into devices via the [Device\nRegistry](https://developers.home-assistant.io/docs/device_registry_index/)\nconcept. MQTT entities allow to use the [device\nregistry](https://www.home-assistant.io/integrations/sensor.mqtt/#device) to\ngroup individual entities to a device as well.\n\nFor this to work a `device` dictionary needs to be added to the configuration\nvariable. A `unique_id` property with a unique ID for each entity is required\ntoo.\n\n```\ndevice_conf = { \"identifiers\": [ \"common_identifier\" ], \"name\": \"Testboard\",\n    \"manufacturer\": \"MicroPython\", \"model\": \"TinyPico\", \"sw_version\": \"0.1\" }\ncommon_conf = { \"device\": device_conf }\ngroup = EntityGroup(mqttc, b\"testboarder\", extra_conf=common_conf)\n\nsensor1_config = { \"unit_of_measurement\": \"°C\", \"device_class\":\n    \"temperature\", \"value_template\": \"{{ value_json.temperature }}\"),\n    \"unique_id\": mqtt_status + \"sensor1\"}\nsensor1 = group.create_sensor(b\"test1\", b\"test1id\", extra_conf=sensor1_config)\n\nsensor2_config = { \"unit_of_measurement\": \"%\", \"device_class\":\n    \"humidity\", \"value_template\": \"{{ value_json.humidity }}\",\n    \"unique_id\": mqtt_status + \"sensor2\"}\nsensor2 = group.create_sensor(b\"test2\", b\"test2id\", extra_conf=sensor2_config)\n```\n\nPublishing state and removing the group stays the same as regular entity\ngroups.\n\n#### Using availability topic\n\nMQTT allows to specify a last will message which is sent to the specified topic\nwhen a device does not connect for a certain period. The last will message is\ntransmitted when connecting, hence this needs to be configured before\nconnecting. Also choose a keep alive timeout which is higher than your expected\nsensor update time. E.g. if you plan to update the sensor value every minute,\na value higher than 60 seconds make sense. The same topic then needs to be\nspecified when creating the sensor:\n\n```\nmqtt_availability_topic = b\"testboard/status\"\nmqttc = MQTTClient(b\"umqtt-testboard\", \u003cMQTT Server IP\u003e, keepalive=70)\nmqttc.set_last_will(mqtt_status, b\"offline\", True)\nmqttc.connect()\nmqttc.publish(mqtt_status, b\"online\", retain=True)\n\ntemp_config = { \"availability_topic\": mqtt_availability_topic }\ntemp = Sensor(mqttc, b\"temperature_sensor\", b\"sensorid\", extra_conf=temp_config)\n```\n\n## License\n\nThis project is licensed under the MIT License - see the\n[LICENSE](LICENSE) file for details\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagners%2Fmicropython-ha-mqtt-device","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagners%2Fmicropython-ha-mqtt-device","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagners%2Fmicropython-ha-mqtt-device/lists"}