{"id":13581364,"url":"https://github.com/bessarabov/mac2mqtt","last_synced_at":"2025-04-15T11:53:45.274Z","repository":{"id":43085506,"uuid":"355321367","full_name":"bessarabov/mac2mqtt","owner":"bessarabov","description":"View and control some aspects of macOS computer via MQTT","archived":false,"fork":false,"pushed_at":"2024-04-13T07:00:01.000Z","size":20,"stargazers_count":78,"open_issues_count":14,"forks_count":24,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-28T19:45:09.581Z","etag":null,"topics":["home-assistant","macos","mqtt"],"latest_commit_sha":null,"homepage":"","language":"Go","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/bessarabov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-06T20:28:37.000Z","updated_at":"2025-03-25T04:12:56.000Z","dependencies_parsed_at":"2024-06-19T00:34:10.968Z","dependency_job_id":null,"html_url":"https://github.com/bessarabov/mac2mqtt","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bessarabov%2Fmac2mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bessarabov%2Fmac2mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bessarabov%2Fmac2mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bessarabov%2Fmac2mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bessarabov","download_url":"https://codeload.github.com/bessarabov/mac2mqtt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067759,"owners_count":21207395,"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":["home-assistant","macos","mqtt"],"created_at":"2024-08-01T15:02:00.820Z","updated_at":"2025-04-15T11:53:45.258Z","avatar_url":"https://github.com/bessarabov.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# mac2mqtt\n\n`mac2mqtt` is a program that allows viewing and controlling some aspects of computers running macOS via MQTT.\n\nIt publishes to MQTT:\n\n * current volume\n * volume mute state\n * battery charge percent\n * if macOS is connected to MQTT\n\nYou can send commands to MQTT to:\n\n * change volume\n * mute/unmute\n * put computer to sleep\n * shutdown computer\n * turn off display\n\n## Overview\n\nTo control macOS via MQTT using this project you need several elements:\n\n * File `mac2mqtt` with compiled program (also known as 'binary' or 'executable')\n * File with configuration `mac2mqtt.yaml`. You need to write this file yourself, but you can use file `mac2mqtt.yaml` stored in this repository as a starting point\n * A system that automatically launches mac2mqtt after macOS restarts. You can run `mac2mqtt` manually without such system, but in such case you need to start `mac2mqtt` every time after restarting macOS. Manually running mac2mqtt is a good starting point when setting up the project.\n * MQTT server (it is often called MQTT Broker)\n * Some system what will read data from MQTT and send command to MQTT. Originally this project was created to make it possible to control macOS computer via [Home Assistant](https://www.home-assistant.io/), but any software that work with MQTT can be used with `mac2mqtt`.\n\nIt is recommended to put executable file and configuration file in your home directory in the subdirectory `mac2mqtt`:\n\n```\n/Users/USERNAME/mac2mqtt/\n├── mac2mqtt\n└── mac2mqtt.yaml\n```\n\n## Installation\n\nThere are several ways you can get `mac2mqtt` binary.\n\n### Use pre-compiled binaries\n\nDownload the file from GitHub Releases section.\n\nMake sure to download the correct file for your architecture:\n\n * `mac2mqtt_VERSION_arm64` — use this file for Apple Silicon Macs\n * `mac2mqtt_VERSION_x86_64` — use this file for Intel-based Macs\n\nYou need to make downloaded file executable `chmod +x FILE_NAME`.\n\n### Compile the source code yourself\n\nYou need golang to be installed on your system — https://go.dev/doc/install\n\n 1. Clone this repo\n 2. `cd mac2mqtt/`\n 3. `go build .`\n\nThis will create file `mac2mqtt` that you can run.\n\n## Running\n\nTo run this program you need 2 files in a directory:\n\n```\n/Users/USERNAME/mac2mqtt/\n├── mac2mqtt\n└── mac2mqtt.yaml\n```\n\nTake `mac2mqtt.yaml` that is stored in this repository, but edit it, and put your data into it.\n\nThen run `./mac2mqtt` in the terminal. You should see see somthing like this:\n\n    $ ./mac2mqtt\n    2021/04/12 10:37:28 Started\n    2021/04/12 10:37:29 Connected to MQTT\n    2021/04/12 10:37:29 Sending 'true' to topic: mac2mqtt/bessarabov-osx/status/alive\n\n## Running in the background\n\nYou need `mac2mqtt.yaml` and `mac2mqtt` to be placed in the directory `/Users/USERNAME/mac2mqtt/`,\nthen you need to create file `/Library/LaunchDaemons/com.bessarabov.mac2mqtt.plist`:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n    \u003cdict\u003e\n        \u003ckey\u003eLabel\u003c/key\u003e\n        \u003cstring\u003ecom.bessarabov.mac2mqtt\u003c/string\u003e\n        \u003ckey\u003eProgram\u003c/key\u003e\n        \u003cstring\u003e/Users/USERNAME/mac2mqtt/mac2mqtt\u003c/string\u003e\n        \u003ckey\u003eWorkingDirectory\u003c/key\u003e\n        \u003cstring\u003e/Users/USERNAME/mac2mqtt/\u003c/string\u003e\n        \u003ckey\u003eRunAtLoad\u003c/key\u003e\n        \u003ctrue/\u003e\n        \u003ckey\u003eKeepAlive\u003c/key\u003e\n        \u003ctrue/\u003e\n    \u003c/dict\u003e\n\u003c/plist\u003e\n```\n\nAnd run:\n\n    launchctl load /Library/LaunchDaemons/com.bessarabov.mac2mqtt.plist\n\n(To stop you need to run `launchctl unload /Library/LaunchDaemons/com.bessarabov.mac2mqtt.plist`)\n\n## Home Assistant sample config\n\n![](https://user-images.githubusercontent.com/47263/114361105-753c4200-9b7e-11eb-833c-c26a2b7d0e00.png)\n\n`configuration.yaml`:\n\n```yaml\nscript:\n  air2_sleep:\n    icon: mdi:laptop\n    sequence:\n      - service: mqtt.publish\n        data:\n          topic: \"mac2mqtt/bessarabov-osx/command/sleep\"\n          payload: \"sleep\"\n\n  air2_shutdown:\n    icon: mdi:laptop\n    sequence:\n      - service: mqtt.publish\n        data:\n          topic: \"mac2mqtt/bessarabov-osx/command/shutdown\"\n          payload: \"shutdown\"\n\n  air2_displaysleep:\n    icon: mdi:laptop\n    sequence:\n      - service: mqtt.publish\n        data:\n          topic: \"mac2mqtt/bessarabov-osx/command/displaysleep\"\n          payload: \"displaysleep\"\n\nsensor:\n  - platform: mqtt\n    name: air2_alive\n    icon: mdi:laptop\n    state_topic: \"mac2mqtt/bessarabov-osx/status/alive\"\n\n  - platform: mqtt\n    name: \"air2_battery\"\n    icon: mdi:battery-high\n    unit_of_measurement: \"%\"\n    state_topic: \"mac2mqtt/bessarabov-osx/status/battery\"\n\nswitch:\n  - platform: mqtt\n    name: air2_mute\n    icon: mdi:volume-mute\n    state_topic: \"mac2mqtt/bessarabov-osx/status/mute\"\n    command_topic: \"mac2mqtt/bessarabov-osx/command/mute\"\n    payload_on: \"true\"\n    payload_off: \"false\"\n\nnumber:\n  - platform: mqtt\n    name: air2_volume\n    icon: mdi:volume-medium\n    state_topic: \"mac2mqtt/bessarabov-osx/status/volume\"\n    command_topic: \"mac2mqtt/bessarabov-osx/command/volume\"\n```\n\n`ui-lovelace.yaml`:\n\n```yaml\ntitle: Home\nviews:\n  - path: default_view\n    title: Home\n    cards:\n      - type: entities\n        entities:\n          - sensor.air2_alive\n          - sensor.air2_battery\n          - type: 'custom:slider-entity-row'\n            entity: number.air2_volume\n            min: 0\n            max: 100\n          - switch.air2_mute\n          - type: button\n            name: air2\n            entity: script.air2_sleep\n            action_name: sleep\n            tap_action:\n              action: call-service\n              service: script.air2_sleep\n          - type: button\n            name: air2\n            entity: script.air2_shutdown\n            action_name: shutdown\n            tap_action:\n              action: call-service\n              service: script.air2_shutdown\n          - type: button\n            name: air2\n            entity: script.air2_displaysleep\n            action_name: displaysleep\n            tap_action:\n              action: call-service\n              service: script.air2_displaysleep\n\n      - type: history-graph\n        hours_to_show: 48\n        refresh_interval: 0\n        entities:\n          - sensor.air2_battery\n```\n\n## MQTT topics structure\n\nProgram is working with several MQTT topics. All topix are prefixed with `mac2mqtt` + `/` + `COMPUTER_NAME`.\nFor example, topic with current volume on my machine is `mac2mqtt/bessarabov-osx/status/volume`, in this\ncase the PREFIX if `mac2mqtt/bessarabov-osx`.\n\n`mac2mqtt` send info to the topics `mac2mqtt/COMPUTER_NAME/status/#` and listen for commands in topics\n`mac2mqtt/COMPUTER_NAME/command/#`.\n\n### Status MQTT topics\n\n`mac2mqtt` is sending data to those topics.\n\n#### PREFIX + `/status/alive`\n\nThere can be `true` of `false` in this topic. If `mac2mqtt` is connected to MQTT server there is `true`.\nIf `mac2mqtt` is disconnected from MQTT there is `false`. This is the standard MQTT thing called Last Will and Testament.\n\n#### PREFIX + `/status/volume`\n\nThe value is the numbers from 0 (inclusive) to 100 (inclusive). The current volume of computer.\n\nThe value of this topic is updated every 2 seconds.\n\n#### PREFIX + `/status/mute`\n\nThere can be `true` of `false` in this topic. `true` means that the computer volume is muted (no sound),\n`false` means that it is not multed.\n\n#### PREFIX + `/status/battery`\n\nThe value is the nuber up to 100. The charge percent of the battery.\n\nThe value of this topic is updated every 60 seconds.\n\n### Control MQTT topics\n\n`mac2mqtt` is listening for those topics and executes the actions.\n\n#### PREFIX + `/command/volume`\n\nYou can send integer numberf from 0 (inclusive) to 100 (inclusive) to this topic. It will set the volume on the computer.\n\n#### PREFIX + `/command/mute`\n\nYou can send `true` of `false` to this topic. When you send `true` the computer is muted. When you send `false` the computer\nis unmuted.\n\n#### PREFIX + `/command/sleep`\n\nYou can send string `sleep` to this topic. It will put computer to sleep mode. Sending some other value will do nothing.\n\n#### PREFIX + `/command/shutdown`\n\nYou can send string `shutdown` to this topic. It will try to shutdown the computer. The way it is done depends on\nthe user who run the program. If the program is run by `root` the computer will shutdown, but if it is run by ordinary user\nthe computer will not shut down if there is other user who logged in.\n\nSending some other value but `shutdown` will do nothing.\n\n#### PREFIX + `/command/displaysleep`\n\nYou can send string `displaysleep` to this topic. It will turn off display. Sending some other value will do nothing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbessarabov%2Fmac2mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbessarabov%2Fmac2mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbessarabov%2Fmac2mqtt/lists"}