{"id":15145394,"url":"https://github.com/danobot/mqtt_payload_processor","last_synced_at":"2025-10-24T00:31:28.938Z","repository":{"id":45288601,"uuid":"159139240","full_name":"danobot/mqtt_payload_processor","owner":"danobot","description":"Custom Home Assistant component that converts MQTT message payloads to events and callback functions for consumption in automations. Can be used to assign schedule-based actions to remote controls or button wall panels.","archived":false,"fork":false,"pushed_at":"2024-05-04T12:14:37.000Z","size":416,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-27T11:23:58.378Z","etag":null,"topics":["custom-component","home-assistant","home-automation","iot","mqtt","mqtt-payload","mqtt-topic","mqtt-topics","openmqttgateway","python","rf","rf-codes","wall-button-panel"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danobot.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-26T08:56:59.000Z","updated_at":"2024-05-04T12:14:40.000Z","dependencies_parsed_at":"2022-09-21T07:30:54.645Z","dependency_job_id":null,"html_url":"https://github.com/danobot/mqtt_payload_processor","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danobot%2Fmqtt_payload_processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danobot%2Fmqtt_payload_processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danobot%2Fmqtt_payload_processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danobot%2Fmqtt_payload_processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danobot","download_url":"https://codeload.github.com/danobot/mqtt_payload_processor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219867315,"owners_count":16555821,"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":["custom-component","home-assistant","home-automation","iot","mqtt","mqtt-payload","mqtt-topic","mqtt-topics","openmqttgateway","python","rf","rf-codes","wall-button-panel"],"created_at":"2024-09-26T11:24:29.845Z","updated_at":"2025-10-24T00:31:23.616Z","avatar_url":"https://github.com/danobot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\nCustom Home Assistant component that converts MQTT message payloads to events and callback functions for consumption in automations. Provides a neat way to decouple implementation specific payloads (such as RF codes) from your Home Assistant configuration. Define schedule specific actions to execute when a device button is triggered.\n\n## Use cases:\n\n* **Gateway:** Acts as a gateway to convert RF codes (or other implementation specific identifier) to native Home Assistant events\n* **Schedules:** reuse the same RF device (wall panel or remote control) to perform mulitple actions depending on some pre-defined schedule\n* **Clean \u0026 Maintainable:** Store all RF specific integer codes in one location and use events as triggers in automations.\n* **Post processing:** for payloads delivered by Open MQTT Gateway\n\n## How does it work?\n\n![Diagram](images/diagram.png)\n\nYou need have some kind of device that emits __specific payloads__ on an MQTT topic that you want to convert to Home Assistant events. My use case is integration with OpenMQTTGateway where RF payloads are sent on a specific MQTT topic.\n\nFor example, an RF motion sensor, door sensor and wall button panel may send the following messages on `/rf/all`:\n\n```\n/rf/all 121330\n/rf/all 163562\n/rf/all 136566\n```\n\nEach payload is unique to a device. Some devices have multiple payloads.\n\nThis component allows you to name and define these devices (including their respective RF codes) in one central location. The rest of your Home Assistant configuration then refers to events and callback scripts instead. (This way your RF codes are not duplicated and used throughout the configuration.)\n\nMy examples are specific to RF devices, but you can use this component in any situation where implementation specific data is sent on an MQTT topic and you want to add a layer of abstraction on top of it.\n\n# Getting Started\nInstallation with HACS is not possible due to HACS limitations. This component comes with a new domain and platform. The latter is not loaded with HACS.\nCopy the folders in `custom_components` directory to the same directory in your Home Assistant configuration directory.\n\nThen add the following to your configuration:\n```yaml\n\nprocessor:\n  - platform: mqtt_code\n    topic: /rf/all\n    callback_script: script.buzz_short      # Global Callback (Executed disabled downstream)\n    event: True                             # Global event flag, overwrites local (send HA events)\n    entities: \n      - name: wallpanel-button-1\n        type: button\n        payload: 5842324\n        callback_script: script.buzz_long\n      - name: wallpanel-button-2\n        type: button\n        payloads_on: \n          - 5842324\n          - 5842325\n        payloads_off: \n          - 5842333\n          - 5842334\n        callback: False                     # Do not call global callback, True is default\n\n```\n\nThis configuration listens for RF codes on the specified MQTT topic and generates events named after the `name` attribute when the corresponding payload is received. The `type` attribute only adds a custom icon in the event log for now. Supported options so far are `button` and `motion`.\n\nYou will likely have a large number of defined devices as they add up quickly. A three-button RF wall panel sends out 6 different codes depending on what combination of buttons is pressed. You can split your rf_code definition into a separate file like this:\n\n```yaml \nprocessor:\n  - platform: mqtt_code\n    topic: /rf/all\n    entities: !include rf_codes.yaml\n\n```\n\nWhere the file has the following contents:\n\n```yaml\n- name: wp-lr-btn-1\n  type: button\n  payload: 5842324\n- name: wp-lr-btn-2\n  type: button\n  payload: 5842322\n```\n# Configuration\n**Device:** A high level device containing many entities. E.g. Wall panel with multiple buttons.\n**Mapping** A button on a wall panel triggered by an MQTT payload. Contains many actions that define scripts for one or more schedules (including the `default` schedule).\n**Schedule:** Defines when a certain set of actions is executed.\n\n\n## Callback Scripts\nYou can define a script to be called as a sort of callback function. I use this to emit a short sound when specific buttons are pressed. (Sometimes the automation triggered by the button does not have immediate feedback). By default, the top level script is called if (and only if) the device declares `callback: true`.\n\nYou can define device-level callback scripts as well. Use the `callback` attribute to control whether or not the global callback script is executed when a local script is defined.\n```yaml\n\nprocessor:\n  - platform: mqtt_code\n    topic: /rf/all\n    callback_script: script.buzz_short\n    entities: \n      - name: wp-lr-btn-1\n        type: button\n        payload: 5842324\n        callback: true        # uses global callback script\n      - name: wp-lr-btn-2\n        type: button\n        payload: 5842322\n        callback_script: script.custom_script\n```\n\nIn addition to scripts, you can build automations that are triggered by the event emitted by the component when certain payloads are received. For example:\n\n```yaml\n- alias: WP BR Button 1\n  hide_entity: yes\n  trigger:\n    platform: event\n    event_type: wp-lr-btn-1\n  action:\n    - service: light.toggle\n      entity_id:\n        - light.living_room_floor_lamp\n```\n\n## Defining Actions\nThe following configuration shows how to assign a script action directly to the mapping.\n\n```yaml\n    - name: Black Button \n      type: panel\n      mappings:\n        button:\n          payload: 1870753\n          actions:\n            default:\n              - service: fan.toggle\n                entity_id: fan.living_room_fan\n```\n## Scheduling\nThe component provides an advanced scheduling mechanism using schedules that change the functionality of a device button (`mapping`) depending on the schedule implementation. The design supports multiple schedule types, though only the `TimeSchedule` has been implemented so far. This leaves the possibility to define other schedule types in the future. For example, one that is active when a Home Assistant template condition evaluates to `true`.)\n\nYou can define any number of schedules, with or without overlapping times. If your schedules overlap, then both schedule scripts are triggered.\n\nThe default schedule will be executed if no other schedule is active or no other schedules are defined for the mapping. \n\n```yaml\nprocessor:\n  - platform: mqtt_code\n    topic: /rf/all\n    callback_script: script.buzz_short\n    entities: !include rf_codes.yaml\n    event: True\n    entities:\n      - name: Wall Button \n        type: panel\n        schedules:\n          morning:\n            type: time\n            start_time: '08:00:00'\n            end_time: '08:00:00'\n          evening:\n            type: time\n            start_time: '18:00:00'\n            end_time: '23:00:00'\n        mappings:\n          button_1:\n            payload: 1870753\n            actions:\n              morning:\n                - service: light.toggle\n                  entity_id: light.lounge_lamp\n              evening:\n                - service: media_player.pause\n                  entity_id: media_player.tv\n              default:\n                - service: fan.toggle\n                  entity_id: fan.bedroom_fan\n\n```\n## State Tracking\nThe component creates entities for each device defined in the configuration. An example state is shown below:\n```json\n{\n    'last_triggered': '2018-11-27T10:47:10.640502', \n    'payload': '1268280', \n    'type': 'button', \n    'callback_script': 'script.buzz_short', \n    'global_callback': 'script.buzz_short'\n}\n```\n\n\n# Future Enhancements\n[x] Group multiple devices into larger entities representing the physical device.\n\n# Automatic updates\nUse the `custom_updater` component to track updates.\n```yaml\ncustom_updater:\n  track:\n    - components\n  component_urls:\n    - https://raw.githubusercontent.com/danobot/mqtt_payload_processor/master/tracker.json\n```\n\n# Changelog\nRefer to the `Changelog` file for detailed information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanobot%2Fmqtt_payload_processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanobot%2Fmqtt_payload_processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanobot%2Fmqtt_payload_processor/lists"}