openHAB Cloud Setup Guide for Azure and IFTTT

Tags: #<Tag:0x00007f745f788e28> #<Tag:0x00007f745f788d60> #<Tag:0x00007f745f788c98>

Objective

Integrate IFTTT Platform services with openHAB by hosting a private instance of openHAB Cloud Connector on Azure.

Prerequisites

  • Familiarity with Linux command line interface
  • Azure subscription
  • IFTTT account (and optional Maker service setup for webhook example)
  • Existing openHAB instance and UUID and secrets

High-Level Steps

  1. Create and Configure VM
  2. Install openHAB Cloud Connector
  3. Install openHAB Cloud Connector Add-on
  4. Install LetsEncrypt SSL certificates
  5. Install and configure NGINX
  6. IFTTT Platform service integration
  7. Create IFTTT Applet
  8. Final VM configurations

Create and Configure VM

  1. Login to your Azure Portal and create a new Ubuntu 18.04 VM according to your needs
  2. Configure NSG to allow inbound TCP/80 and TCP/443 to your VM private IP address
  3. Create a FQDN DNS Name and note this for later
  4. SSH into your VM
  5. Update the OS and install additional packages
$ sudo apt update;sudo apt upgrade -y
$ sudo apt install build-essential redis-server mongodb nginx python git certbot python-certbot-nginx -y
  1. With this version of Ubuntu we need to install a specific version of Node:
$ wget https://nodejs.org/download/release/v7.10.1/node-v7.10.1-linux-x64.tar.gz -O /var/tmp/node-v7.10.1-linux-x64.tar.gz
$ sudo mkdir /usr/local/lib/nodejs
$ sudo tar -xvf /var/tmp/node-v7.10.1-linux-x64.tar.gz -C /usr/local/lib/nodejs
$ sudo ln -s /usr/local/lib/nodejs/node-v7.10.1-linux-x64/bin/node /usr/bin/node
$ sudo ln -s /usr/local/lib/nodejs/node-v7.10.1-linux-x64/bin/npm /usr/bin/npm
  1. Verify that version 7.10.1 is running
$ node --version
  1. Create user openhabcloud and group openhabcloud
$ sudo useradd -M -r -s /bin/false -c "openHAB Cloud Connector" openhabcloud

Install openHAB Cloud Connector

  1. Download the latest version of cloud connector:
$ sudo git clone https://github.com/openhab/openhab-cloud.git /opt/openhabcloud
$ cd /opt/openhabcloud
$ sudo npm install
  1. Change ownership of the directory
$ sudo chown -R openhabcloud:openhabcloud /opt/openhabcloud
  1. Create the initial configuration file
$ cd /opt/openhabcloud/
$ sudo cp config-development.json config.json
  1. Edit /opt/openhabcloud/config.json, and replace the placeholder with your FQDN created above
  2. MongoDB username and password fields should be deleted, if there is no authentication configured
  3. Check if redis is running with ping command / expect PONG reply if everything is fine
$ redis-cli ping
  1. Start the service to test if it’s working
$ sudo node app.js
  1. Note: the application is now running in the foreground. Press CTRL-C to end.
  2. Check the log output file at /opt/openhabcloud/logs/openhab-cloud-CCYY-MM-DD-process-nnnn.log for errors
  3. Optional: From your host computer (not the VM) configure SSH tunnel to test login of the web UI. Remember this service is running on TCP/3000 and that is not exposed to the public Internet. Otherwise, run netstat -an | grep LISTEN | grep “:3000” to see if the service is listening for incoming connections. Another alternative might be to use ngrok.

Install openHAB Cloud Connector Add-on

  1. From your openHAB Paper UI navigate to Add-ons > Misc
  2. Find misc-openhabcloud - 2.4.0 in the list of available add-ons and install
  3. Edit file services/openhabcloud.cfg adding your FQDN and expose at least one item to openHAB Cloud Connector. This item will be available once IFTTT integration is completed.
baseURL=https://[FQDN]
mode=remote
expose=demoSwitch

Install LetsEncrypt SSL Certificates

  1. Optional: It’s free and easy so why not? This requires port TCP/80 open inbound which is why the Azure NSG contains this entry. Can be removed from NSG once certs are installed with this process.

  2. Setup front-end NGINX web server by copying site configuration file that came with openhab cloud connector

  3. Note: LetsEncrypt certificates expire after 2 months.

$ sudo cp /opt/openhabcloud/etc/nginx_openhabcloud.conf /etc/nginx/sites-available/default
$ sudo sed -i '/listen \*:80/d' /etc/nginx/sites-enabled/default
$ sudo service nginx restart
$ sudo certbot --nginx -d [FQDN]

Install and Configure NGINX

  1. Edit /etc/nginx/sites-enabled/default to reflect the location of the SSL certificates and update the server_name directive as shown below.
server {
listen *:443;
ssl on;
ssl_certificate /etc/letsencrypt/live/[FQDN]/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/[FQDN]/privkey.pem;
server_name [FQDN];
if ( $scheme = "http" ) {
rewrite ^/(.*)$ https://$host/$1 permanent;
}

charset utf-8;
access_log /var/log/nginx/openhab-cloud.org-access.log;
error_log /var/log/nginx/openhab-cloud.org-error.log;
client_max_body_size 300m;
location /css {
alias /opt/openhabcloud/public/css;
}

location /js {
alias /opt/openhabcloud/public/js;
}

location /img {
alias /opt/openhabcloud/public/img;
}

location /bootstrap {
alias /opt/openhabcloud/public/bootstrap;`
}

location /font-icons {
alias /opt/openhabcloud/public/font-icons;
}

location /fonts {
alias /opt/openhabcloud/public/fonts;
}

location /js-plugin {
alias /opt/openhabcloud/public/js-plugin;
}

location /downloads {
alias /opt/openhabcloud/public/downloads;
}

location / {
proxy_pass http://localhost:3000;
proxy_redirect off;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Real-IP $remote_addr ;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for ;
proxy_set_header X-Forwarded-Proto https;
}

#error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
}
  1. Start the NGINX web service
$ sudo service nginx restart
$ sudo node app.js
  1. Visit your openHAB Cloud Connector at [https://FQDN]
  2. Register your openHAB instance by creating an account and supplying the UUID and Secret

IFTTT Service Integration

This section is based on the excellent guide: How To: Integrate Custom openHAB Cloud with IFTTT

  1. Generate Client ID and the second Client Secrets by running the following command twice. Save the output for step 7.
$ python3 -c "import secrets; print(secrets.token_hex(32))"
  1. Create a demo account your instance of openHAB Cloud Connector. UUID and secret values won’t be used so anything will work. IFTTT Platform requires a demo account in step 10.
  2. Visit https://platform.ifttt.com/ and create a new Organization and Service.
  3. Fill out any required items under Service > General
  4. Navigate to “API” and fill in the IFTTT API URL with your FQDN
  5. Note the Service Key which will be used later
  6. Navigate to “Authentication” and select “My API has users with non-expiring OAuth2 access tokens” and enter Client ID and Client Secret here
  7. Set the “Authorization URL” to “https://[FQDN]/oauth2/authorize”
  8. Set the “Token URL” to “https://[FQDN]]/oauth2/token”
  9. Enter the demo account credentials that you created in Step 1 and Save all settings
  10. SSH into your openHAB Cloud Connector VM and configure the following oauth settings in mongodb
$ mongo
>>> use openhab
>>> db.oauth2clients.insert({ clientId: "[Client ID]", clientSecret: "[Client Secret]"})
>>> db.oauth2scopes.insert( { name : "ifttt", description: "Access to openHAB Cloud specific API for IFTTT", } )
>>> exit
  1. Add your IFTTT Service Key to config.json
    "ifttt" : {
    "iftttChannelKey" : "[IFTTT Service Key]",
    "iftttTestToken" : ""
    },
  1. Restart openHAB cloud connector service
  2. Login to your openHAB cloud instance with your demo account
  3. From the API tab navigate to “Authentication Test” and click “Begin Test”
  4. After a short wait, you will be redirected to your openHAB Cloud Connector’s OAuth2 authorization prompt. Click Allow.

  1. The results should look like this:

  1. Expand “Request access token” section and find the BODY entry under Response. Copy the access_token value and enter it into the iftttTestToken value in your config.json file.

  1. Optional: Execute the Endpoint tests. Expect these to fail but responses should contain HTTP status code “200” to indicate successful response from your endpoint.

  1. To send a command to openHAB from IFTTT applets you will need to configure an Action. Example form:

  1. Click Save and create two Action fields
  2. Field 1: This is a dynamically retrieved list of exposed items from your openHAB instance.
  1. Field 2: This is the command or value to set the OH item to. In an applet this might be state of ON or OFF.
  • Label: Command to send
  • Key name: command
  • Required: This action field is required…
  • Action field type: Text input
  • Messages: Short text
  1. Once completed the Action “Send a command” should have these two action fields:

  1. Important: Disable registration feature so that your instance of openHAB Cloud remains private. Edit the config.json file and append/edit the registration_enabled value to false
  2. Restart the service for the change to take affect
    ...
    "legal": {
    "terms" : "",
    "policy": ""
    },
    "registration_enabled": false
    }

Create Sample IFTTT Applet

  1. Ensure that your item(s) appear on your openHAB Cloud instance. If none appear use Karaf remote console to set a value to an exposed item. This will force the item to appear in the openHAB Cloud item list.
openhab> smarthome:send demoSwitch ON

  1. Visit https://ifttt.com/create
  2. Choose trigger: Webhooks (Note: Maker service setup required before using Webhooks)
  3. In the “Event Name” field enter demoSwitchON this will be passed as part of the URL in the Webhook call
  4. Next click +That and in the search box type in the name of your IFTTT Platform service
  5. If this is the first time using your service you will be redirected to your OAUTH2 sign in page. Important: Login with your openHAB Cloud Connector account (not the demo account) and click Allow. This has authorized IFTTT to read your OH exposed items and send them commands.
  6. Choose action: Send a command
  7. Which item?: [Select your exposed item]
  8. Command to send: ON
  9. Create Action, Review and finish!
  10. Repeat steps 2-10 again to create an OFF action.
  11. Issue a request to the webhook URL via browser or command line
$ curl -X POST https://maker.ifttt.com/trigger/demoSwitchON/with/key/[redacted]

Congratulations! You’ve fired the demoSwitchON event

$ curl -X POST https://maker.ifttt.com/trigger/demoSwitchOFF/with/key/[redacted]

Congratulations! You’ve fired the demoSwitchOFF event

  1. Visit your openHAB Cloud Connector > Event log page and verify that the events were received

Final VM configurations

  1. Configure the service to start on boot by copying example systemd service file to /etc/systemd/service
$ sudo cp /opt/openhabcloud/etc/openhabcloud.service /etc/systemd/system
$ sudo vim /etc/systemd/system/openhabcloud.service
  1. Edit the file so it looks like the one below.
[Unit]
Description=node.js openhab cloud server
After=nginx.service redis-server.service mongodb.service

[Service]
User=openhabcloud
Group=openhabcloud
Environment=NODE_ENV=production
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=openhabcloud
WorkingDirectory=/opt/openhabcloud
ExecStart=/usr/local/lib/nodejs/node-v7.10.1-linux-x64/bin/node /opt/openhabcloud/app.js

[Install]
WantedBy=multi-user.target
  1. Enable the service to start on boot
$ sudo systemctl enable openhabcloud.service
$ sudo systemctl start openhabcloud.service
$ systemctl status openhabcloud.service
4 Likes

just want to say @garagehacker thanks for such a well documented tutorial. I don’t use IFTTT but two years since last visit and such a great contribution to the community! This shows that there is a huge ‘silent majority’ of OpenHAB users that don’t necessarily participate on a daily or weekly basis but are committed to this project.
Bravo :+1:

1 Like