Skip to content

Better Harmony Hub Integration with SmartThings

I put off getting a Harmony Hub for a long time because with my Xfinity X1 remote I had voice control that was simple to use and did what I needed it to do. I also did not like the idea of going from RF to IR control as that is a step backwards. I was missing one thing that I really wanted though, the ability to turn my TV off at night when I ran my Goodnight Routine through Alexa. The Harmony Hub gave me that ability and I could even integrate activities into SmartThings which has led to me using the Harmony Hub for more than just turning the TV off at night. That was nice and all, but I wanted more, I wanted to be able to control individual devices from my Harmony Hub through SmartThings. This want led me to KuKuHarmony, device handler and smartapp for SmartThings.

KuKuHarmony is interesting, it uses the Harmony API to allow you to selectively add devices and commands into SmartThings and have them be executed through the Harmony Hub. This seems perfect, but it does require that the Harmony API is running on another machine connected to the network and that is where my good old friend the Raspberry Pi 3+B comes in. The developer of KuKuHarmony has released a Docker Image for the Raspberry Pi 3+B that really does make setup a snap although the instructions could have been a bit clearer and that is where I will come in. Below I will document the process of getting everything up and running from first unboxing your Raspberry Pi 3+B.

First what will you need?

To begin the installation process you will need a MicroSD Memory Card, and the ability to format and burn an image to that MicroSD Memory Card. I am sure most of you know how to do these steps already but I will give my recommendations, for formatting I


prefer to use SD Memory Card Formatter for Windows and to burn the image Etcher.

Memory Card Preparation:

  1. Insert MicroSD Memory Card into a computer
  2. Open SD Memory Card Formatter for Windows
  3. In SD Memory Card Formatter for Windows Select the Drive that corresponds to your Memory Card
  4. In SD Memory Card Formatter for Windows Click Format and wait for it to finish
  5. Download the Raspbian disk image from
  6. Open Etcher.
  7. In Etcher Select the previously Downloaded Image
  8. In Etcher Select the Drive that corresponds to your Memory Card
  9. In Etcher Click Flash and wait for Etcher to Finish

Raspberry Pi Setup:

  1. From the Raspbian Desktop launch Terminal
  2. From Terminal you need to install Docker using the follow command,
  1. From Terminal reboot your Raspberry Pi using,

    sudo reboot

  2. From the Raspbian Desktop launch Terminal
  3. From Terminal run the following commands to download the Docker Image,
  • sudo docker search turlvo/harmony-api
  • sudo docker pull turlvo/harmony-api
  1. From Terminal run the following command to create and run your Docker Container,
  • sudo docker run -ti –net=host –name harmony-api turlvo/harmony-api:latest /home/harmony-api/harmony-api/script/server

That’s it the Harmony-Api is now running on your Raspberry Pi
but you will also want to set it so that it will run automatically on reboot. This can be done by create is file that the system reads at boot and instructs the Raspberry Pi to run the Docker Container.
To do this follow the instructions below:

  1. From the Raspbian Desktop launch Terminal
  2. From Terminal you need to create the .service file using the follow command,
  • sudo nano /etc/systemd/system/harmony-api.service
  1. Inside of that file paste the following text:


    Description=Harmony API container





    ExecStart=/usr/bin/docker start -a harmony-api

    ExecStop=/usr/bin/docker stop -t 2 harmony-api


  2. Press Ctrl – X
  3. Press Y
  4. Press Enter
  5. Now back in Terminal run the following command,
  • sudo systemctl enable /etc/systemd/system/harmony-api.service

With that done we can next work on SmartThings integration. This is straight forward if you have ever installed a Device Handler and/or SmartApp.

Below is the process for those who may not be as familiar.

SmartThings Device Handler Setup:

  1. Log onto the SmartThings IDE at:
  2. Click on My Device Handlers
  3. Click on Settings in the upper right
  4. Click on Add New Repository
  5. Enter the following:


  1. Click Update From Repo
  2. Select KuKuHarmony (master)
  3. Select all of the Device Handlers in the New Box
  4. Check Publish
  5. Select Execute Update

SmartThings SmartApp Setup:

  1. Click on My SmartApps
  2. Click Update From Repo
  3. Select KuKuHarmony (master)
  4. Select the SmartApp in the New Box
  5. Check Publish
  6. Select Execute Update

Almost done all we have left to do is to get things set up in the SmartThings App.

SmartThings App Configuration:

  1. Launch the SmartThings App on your mobile device
  2. Select Automation
  3. Select SmartApps
  4. Select Add a SmartApp
  5. Scroll down to My Apps and Select
  6. KuKu Harmony
  7. Enter the IP Address of your Harmony API (your Raspberry Pi) followed by Port 8282 (ex.
  8. Select Save

  9. Now simply launch the SmartApp, select any devices you want to add and configure the buttons you want.

If you made it through all of this, you will now see your Harmony Hub connected devices showing up in your SmartThings devices and be able to execute any of the commands you configured for them. I find this helpful as it eliminates an app on my phone and allows me to integrate devices connected to my Harmony Hub into webCoRE and ActionTiles.

Any SmartThings users using a Harmony Hub? Do you think it is useful to have the devices connected to your Harmony Hub also appear as devices in SmartThings? Let me know in the comments below.


Mike View All

I am passionate about the IoT and connected devices. Using connectivity to automate our lives will empower civilization to achieve greatness.

32 thoughts on “Better Harmony Hub Integration with SmartThings Leave a comment

  1. Looks very very interesting what about all this integrated with Action Tilles? I can see a alot of potential if I can Open a tile and control all functions of my Home theater instead of open the Harmony App ( like change volume)


  2. Trying to get this setup on debian VM (HyperV) and when I use this “docker run -ti –net=host –name harmony-api turlvo/harmony-api:latest /home/harmony-api/harmony-api/script/server” command I get an error message “docker: invalid reference format.
    See ‘docker run –help’.”

    Any help you can provide would get greatly appreciated


  3. Using your first step I installed docker. Even when using “sudo” and adding my user to the docker group, I get the same error.


  4. Appears to be running, below is the command with teh response
    …@KuKuHarmony:~$ docker -v
    Docker version 18.05.0-ce, build f150324
    I choose debian because from what I read raspbian is based off debain


    • So first thing I see is that KuKuHarmony is your user? Not sure if that would have anything to do it. What hardware are you running this on? Is it ARM based?


  5. Having the same issue on a Rasberry Pi 3B. when i run docker – v it displays:
    Docker version 18.05.0-ce, build f150324
    This is the error i get:
    pi@raspberrypi:~ $ sudo docker run -ti –net=host –name harmony-api turlvo/harmony-api:latest /home/harmony-api/harmony-api/script/server
    docker: invalid reference format.
    See ‘docker run –help’.
    Any idea what is causing this issue?


  6. sudo docker run -ti ––net=host ––name harmony-api turlvo/harmony-api:latest /home/harmony-api/harmony-api/script/server


  7. Mike, i have basic turn on/off all setup now. Is there a way to setup deeper commands for each harmony device? ie: i have a vizio soundbar that i would like to configure the voice commands through google assistant to turn up the volume up or down.


    • You should be able to select the commands you want when setting up the device. If there. Is not a command listed you should also have Custom commands down the bottom.


  8. Yes, i have that part configured but can i have google assistant activate a specific button click such as input on my tv remote or volume? Basically, i would like to give google a command that i choose (ok google, change input) and i can then program the command to any button key i want that harmony can control?


  9. I got it to work! Basically ended up using webCore to take care of the specific command and tying that to a routine in SmartThings. From there you can create a routine in google assistant to customize the verbal commands and response.


  10. Can anyone please help, Im getting the same error even after adding the two dashes. I’m using a raspberry pi 3. Below is what I’m getting.

    pi@raspberrypi:~ $ sudo docker run -ti ––net=host ––name harmony-api turlvo/harmony-api:latest /home/harmony-api/harmony-api/script/server
    docker: invalid reference format.
    See ‘docker run –help’.


  11. OK. I double checked. I also copied and pasted the latest code you had in the comments to make sure I did it right. I’m still getting the same error.


    • I just checked that code on my system and it is working fine. Make sure your code matches sudo docker run -ti –net=host –name harmony-api turlvo/harmony-api:latest /home/harmony-api/harmony-api/script/server


      • Weird… I ended up copying and pasting from the KuKuHarmony community post, and it worked. But it appears to be the exact same code. Either I missed something, or my browser outputted a weird character. Thank you so much for your help! Now on to the fun!!! 🙂


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: