{"id":13991817,"url":"https://github.com/maddox/harmony-api","last_synced_at":"2025-04-05T18:10:23.935Z","repository":{"id":36124992,"uuid":"40428048","full_name":"maddox/harmony-api","owner":"maddox","description":"🗼 A simple server allowing you to query/control multiple local Harmony Home Hubs over HTTP or MQTT","archived":false,"fork":false,"pushed_at":"2020-04-14T14:52:16.000Z","size":137,"stargazers_count":397,"open_issues_count":41,"forks_count":113,"subscribers_count":48,"default_branch":"master","last_synced_at":"2025-03-29T17:11:19.993Z","etag":null,"topics":["harmony","home-assistant","home-automation","javascript","mqtt"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/maddox.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}},"created_at":"2015-08-09T06:45:36.000Z","updated_at":"2025-03-10T20:08:17.000Z","dependencies_parsed_at":"2022-07-29T21:09:33.513Z","dependency_job_id":null,"html_url":"https://github.com/maddox/harmony-api","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddox%2Fharmony-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddox%2Fharmony-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddox%2Fharmony-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddox%2Fharmony-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maddox","download_url":"https://codeload.github.com/maddox/harmony-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378149,"owners_count":20929297,"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":["harmony","home-assistant","home-automation","javascript","mqtt"],"created_at":"2024-08-09T14:01:36.681Z","updated_at":"2025-04-05T18:10:23.909Z","avatar_url":"https://github.com/maddox.png","language":"JavaScript","readme":"# Harmony API!!\n\nHarmony API is a simple server allowing you to query/control multiple local [Harmony\nHome Hubs](http://myharmony.com/products/detail/home-hub/) and their devices\nover HTTP or MQTT.\n\nWith HTTP, you can simply turn on and off activities, check hub status, and send\ncommands to individual devices with simple HTTP requests from almost any other\nproject.\n\nWith MQTT, you can easily monitor the state of your devices as well as set\nthe current activity of your hub or send specific commands per device. This\nmakes it super easy to integrate into your existing home automation setup.\n\n\n## Features\n\n* Control multiple Harmony hubs.\n* List activities.\n* Get current status, including if everything is off, or what the current\nactivity is.\n* Turn everything off.\n* Start a specific activity.\n* List devices.\n* List device commands.\n* Execute discrete commands for each device.\n\n## Setup\n\n    script/bootstrap\n\n## Settings\n\nHarmony API discovers your hubs automatically. You can optionally add your MQTT\nbroker's host to connect to it.\n\n```json\n{\n  \"mqtt_host\": \"mqtt://192.168.1.106\",\n  \"mqtt_options\": {\n      \"port\": 1883,\n      \"username\": \"someuser\",\n      \"password\": \"somepassword\",\n      \"rejectUnauthorized\": false\n  },\n  \"topic_namespace\": \"home/harmony\"\n}\n```\n\n`mqtt_options` is optional, see the [mqtt](https://github.com/mqttjs/MQTT.js#connect) project for\nallowed host and options values.\n\n## Running It\nGet up and running immediately with `script/server`.\n\n#### Note: \nOn some distros, you might get an error when running it:\n`/usr/bin/node: No such file or directory`\n\nThat can probably be fixed by creating a symlink:\n``sudo ln -s `which nodejs` /usr/bin/node``\n\nHarmony API will run on port `8282` by default. Use the `PORT` environment\nvariable to use your own port.\n\n### Forever\nharmony-api has support for [Forever](https://github.com/foreverjs/forever). It uses\n`launchd` on OS X to kick it off so that it starts on boot.\n\n### Development\nYou can simply run it by calling `script/server`. This will run it in development\nmode with logging to standard out.\n\n### Install as Service on OS X\n\n    script/install\n\n### Install as systemd unit on Linux\n\n    sudo script/install-linux\n\n### Docker\nInstallation with Docker is straightforward. Adjust the following command so that\n`/path/to/your/config` points to the folder where your want to store your config and run it:\n\n    $ docker run --name=\"harmony-api\" -v /path/to/your/config:/config \\\n        -p 8282:8282 -d jonmaddox/harmony-api\n\nThis will launch Harmony API and serve the web interface from port 8282 on your Docker host. Hub\ndiscovery requires host networking (`--net=host`). However, you can specify your Harmony Hub IP\naddress in `config.json` as `hub_ip`.\n\n## Logging\n\nHarmony API logs all of its requests. In `production`, it logs to a file at `log/logs.log`.\nIn `development` mode, it just logs to stdout.\n\n## How to Upgrade to 2.0\n\nSimply run `script/upgrade` from the root of the project and Harmony API will\nupgrade to the newest version.\n\nYou are then going to have to change anything you integrate with Harmony API to\nreflect the change in HTTP endpoints and MQTT topics. Read the docs in this\nREADME to see how they have changed.\n\n## Development\n\nLaunch the app via `script/server` to run it in the development environment.\n\n## MQTT Docs\n\nharmony-api can report its state changes to your MQTT broker. Just edit your\nconfig file in `config/config.json` to add your MQTT host and options.\n\nBy default harmony-api publishes topics with the namespace of: `harmony-api`. This can be overriden\nby setting `topic_namespace` in your config file.\n\n### State Topics\n\nWhen the state changes on your harmony hub, state topics will be immediately\nbroadcasted over your broker. There's quite a few topics that are broadcasted.\n\nState topics are namespaced by your Harmony hub's name, as a slug. You can rename your hub\nin the Harmony app.\n\nHere's a list:\n\n#### Current State\n\nThis topic describes the current power state. Message is `on` or `off`.\n\n`harmony-api/hubs/family-room/state` `on`\n\n#### Current Activity\n\nThis topic describes what the current activity of the hub is. The message is\nthe slug of an activity name.\n\n`harmony-api/hubs/family-room/current_activity` `watch-tv`\n\n#### Activity States\n\nThese topics describe the state of each activity that the hub has. The message\nis `on` or `off`. There will a topic for every activity on your hub.\n\n`harmony-api/hubs/family-room/activities/watch-tv/state` `off`  \n`harmony-api/hubs/family-room/activities/watch-apple-tv/state` `on`  \n`harmony-api/hubs/family-room/activities/play-xbox-one/state` `off`  \n\n\n### Command Topics\n\nYou can also command harmony-api to change activities, and issue device and acivity commands by publishing topics.\nharmony-api listens to these topics and will change to the activity, or issue the command when it sees\nit.\n\n#### Switching activities\nJust provide the slug of the hub and activity you want to switch to and `on` as\nthe message. Any use of this topic with the message `off` will turn everything\noff.\n\n`harmony-api/hubs/family-room/activities/watch-tv/command` `on`  \n\n#### Device commands\nJust provide the slug of the hub and the device to control with the command you want to execute. \n`harmony-api/hubs/family-room/devices/tv/command` `volume-down`\n\nTo optionally repeat the command any number of times, provide an optional repeat integer.\n`harmony-api/hubs/family-room/devices/tv/command` `volume-down:5`\n\n#### Current activity commands\nJust provide the slug of the hub and the command you want to execute. \n`harmony-api/hubs/family-room/command` `volume-down`\n\nTo optionally repeat the command any number of times, provide an optional repeat integer.\n`harmony-api/hubs/family-room/command` `volume-down:5`\n\n## HTTP API Docs\n\nThis is a quick overview of the HTTP service. Read [app.js](app.js) if you need more\ninfo.\n\n### Resources\n\nHere's a list of resources that may be returned in a response.\n\n#### Activity Resource\n\nThe Activity resource returns all the information you really need for an\nActivity set up in your Harmony Hub.\n\n```json\n{\n  \"id\": \"15233552\",\n  \"slug\": \"watch-tv\",\n  \"label\": \"Watch TV\",\n  \"isAVActivity\": true\n}\n```\n\n#### Device Resource\n\nThe Device resource returns all the information you need to know about the\ndevices set up for the hub.\n\n```json\n{\n  \"id\": \"38343689\",\n  \"slug\": \"tivo-premiere\",\n  \"label\": \"TiVo Premiere\"\n}\n```\n\n#### Command Resource\n\nThe Command resource returns all the information you really need for a\nCommand to let you execute it.\n\n```json\n{\n  \"name\": \"ChannelDown\",\n  \"slug\": \"channel-down\",\n  \"label\":\"Channel Down\"\n}\n```\n\n#### Status Resource\n\nThe Status resource returns the current state of your Harmony Hub.\n\n```json\n{\n  \"off\": false,\n  \"current_activity\": {\n    \"id\": \"15233552\",\n    \"slug\": \"watch-tv\",\n    \"label\": \"Watch TV\",\n    \"isAVActivity\": true\n  }\n}\n```\n\n### Methods\n\nThese are the endpoints you can hit to do things.\n\n#### Info\n  Use these endpoints to query the current state of your Harmony Hub.\n\n    GET /hubs =\u003e {\"hubs\": [\"family-room\", \"bedroom\"] }\n    GET /hubs/:hub_slug/status =\u003e StatusResource\n    GET /hubs/:hub_slug/commands =\u003e {\"commands\": [CommandResource, CommandResource, ...]}\n    GET /hubs/:hub_slug/activities =\u003e {\"activities\": [ActivityResource, ActivityResource, ...]}\n    GET /hubs/:hub_slug/activities/:activity_slug/commands =\u003e {\"commands\": [CommandResource, CommandResource, ...]}\n    GET /hubs/:hub_slug/devices =\u003e {\"devices\": [DeviceResource, DeviceResource, ...]}\n    GET /hubs/:hub_slug/devices/:device_slug/commands =\u003e {\"commands\": [CommandResource, CommandResource, ...]}\n\n#### Control\n  Use these endpoints to control your devices through your Harmony Hub.\n\n    PUT /hubs/:hub_slug/off =\u003e {message: \"ok\"}\n    POST /hubs/:hub_slug/commands/:command_slug =\u003e {message: \"ok\"}\n    POST /hubs/:hub_slug/commands/:command_slug?repeat=3 =\u003e {message: \"ok\"}\n    POST /hubs/:hub_slug/activities/:activity_slug =\u003e {message: \"ok\"}\n    POST /hubs/:hub_slug/devices/:device_slug/commands/:command_slug =\u003e {message: \"ok\"}\n    POST /hubs/:hub_slug/devices/:device_slug/commands/:command_slug?repeat=3 =\u003e {message: \"ok\"}\n\n## Contributions\n\n* fork\n* create a feature branch\n* open a Pull Request\n","funding_links":[],"categories":["Interfaces","JavaScript"],"sub_categories":["Home Entertainment"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaddox%2Fharmony-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaddox%2Fharmony-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaddox%2Fharmony-api/lists"}