Installation

1. Sign up for Heroku

Navigate to https://www.heroku.com and sign up for a free account. No need to enter your credit card information: We will be using a free dyno.

Download and install the Heroku Toolbelt on your local machine. The toolbelt includes the Heroku CLI (Command Line Interface), which we will be using to configure the web app on the Heroku dyno. Note, that you can complete the configuration without the CLI, by using the Heroku web interface. However, the process becomes a lot more streamlined with the toolbelt.

2. Clone the Repository

Clone the hadashboard repository to the current local directory on your machine.

$ git clone https://github.com/FlorianZ/hadashboard.git

Change your working directory to the repository root. Moving forward, we will be working from this directory.

$ cd hadashboard

3. Install the SmartApp

Navigate to https://graph.api.smartthings.com and log in to your SmartThings IDE account. Select the 'My SmartApps' tab, and click the '+ New SmartApp' button to create a new SmartApp.

Fill in the required information. The 'Name' and 'Description' are both required fields, but their values are not important.

Make sure to click the 'Enable OAuth in Smart App' button to grant REST API access to the new SmartApp. Note the 'OAuth Client ID' and 'OAuth Client Secret'. Both will later be required by the Dashing backend to authenticate with the new SmartApp and talk to SmartThings.

Hit the 'Create' button to get to the code editor. Replace the content of the code editor with the content of the file at: smartapps/DashingAccess.groovy

Click the 'Save' button and then 'Publish -> For Me'.

4. Configure the Web App

Using the Heroku CLI, log in to your Heroku account with the email address and password used to create your Heroku account in step 1. You may be required to generate a new public key in the process. The Heroku CLI will take care of this and upload the key in the process.

$ heroku login
Enter your Heroku credentials.
Email: your@email.com
Password: 
Could not find an existing public key.
Would you like to generate one? [Yn] 
Generating new SSH public key.
Uploading ssh public key /Users/user/.ssh/id_rsa.pub

Now, we will create a new Heroku app. Make sure you are still in the repository root directory (hadashboard) from step 2.

$ heroku create
Creating your-app-name... done, stack is cedar
http://your-app-name.herokuapp.com/ | git@heroku.com:your-app-name.git
Git remote heroku added

This will create a new web app with a random name. The name will be output to the terminal. Take note of it. If you don't like the name, don't worry: You can rename your app at any time using the Heroku CLI or web interface.

Your new app will later be reachable at http://your-app-name.herokuapp.com. We have not deployed your app yet, and before we do we will need to make sure that only you have access to your dashboard, and set up a few Config Variables:

To make sure that your dashboard is not publicly viewable, and that only you have access to it, the hadashboard code is set up to use your Heroku credentials (from step 1) for authentication.

Next, create a client for hadashboard. Make sure to replace your-app-name with the name of your app, as returned by heroku create earlier.

$ heroku clients:create -s "hadashboard" https://your-app-name.herokuapp.com/auth/heroku/callback
HEROKU_OAUTH_ID=some-random-uuid
HEROKU_OAUTH_SECRET=some-random-uuid

The command will return two random uuids. The app id and secret. Note the two uuids, as we will set them in the app environment as Config Variables along with some other variables required by the hadashboard app. Before running this command, make sure to first replace with real values as described below.

$ heroku config:set \
  DASHING_AUTH_TOKEN=some-random-uuid \
  DASHING_URI=http://your-app-name.herokuapp.com \
  HEROKU_OAUTH_EMAIL=your@email.com \
  HEROKU_OAUTH_ID=uuid-from-above \
  HEROKU_OAUTH_SECRET=uuid-from-above\
  SESSION_SECRET=some-random-uuid \
  ST_CLIENT_ID=from-step-3 \
  ST_CLIENT_SECRET=from-step-3

DASHING_AUTH_TOKEN: Set this to a new, random uuid. You may be able to generate a new uuid using the uuidgen command line tool, if it is installed on your local machine. You can also use one of the many online tools to generate uuids. This is used as a machine-to-machine password of sorts, so you could even make up your own. Just make sure it's long, and random, and comlicated in order to ensure it is as secure as possible. This uuid/password is used for the SmartApp to communicate with the Heroku app.
DASHING_URI: This is the URI to your heroku app. The heroku create command will return this value. It is usually http://your-app-name.herokuapp.com, but make sure to replace your-app-name with the actual app name. Also make sure there is no trailing / character in this value.
HEROKU_OAUTH_EMAIL: The email address you used to sign up to Heroku (step 1).
HEROKU_OAUTH_ID: Set this to the HEROKU_OAUTH_ID uuid returned by the previous command (heroku clients:create).
HEROKU_OAUTH_SECRET: Set this to the HEROKU_OAUTH_SECRET uuid returned by the previous command (heroku clients:create).
SESSION_SECRET: Generate a new, random uuid for this, just like you did for DASHING_AUTH_TOKEN. This uuid/password is used to encrypt the session cookie in your browser.
ST_CLIENT_ID: Set this to the SmartApp 'OAuth Client ID' from step 3.
ST_CLIENT_SECRET: Set this to the SmartApp 'OAuth Client Secret' from step 3.

Lastly, we will add a PostgreSQL database. Heroku makes this trivial by simple configuring an add-on:

$ heroku addons:add heroku-postgresql:hobby-dev
Adding heroku-postgresql:hobby-dev to your-app-name... done, v69 (free)
Attached as HEROKU_POSTGRESQL_GOLD
Database has been created and is available

Heroku may require up to 5 minutes to set up the database for you. You can run the following command to make sure the database is ready before you move on to the next step.

$ heroku pg:wait
Waiting for database HEROKU_POSTGRESQL_GOLD... done

5. Deploy to Heroku

To deploy the hadashboard app, all we need to do is push the git repository to Heroku. This will automatically install all the dependencies on the server, and restart the app.

$ git push heroku
Initializing repository, done.
Counting objects: 301, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (171/171), done.
Writing objects: 100% (301/301), 447.67 KiB | 537.00 KiB/s, done.
Total 301 (delta 120), reused 301 (delta 120)

-----> Ruby app detected
-----> Compiling Ruby/Rack
-----> Using Ruby version: ruby-2.0.0
-----> Installing dependencies using 1.6.3
       ...
       
-----> Discovering process types
       Procfile declares types -> (none)
       Default types for Ruby  -> console, rake, web

-----> Compressing... done, 18.5MB
-----> Launching... done, v6
       http://your-app-name.herokuapp.com/ deployed to Heroku

To git@heroku.com:your-app-name.git
 * [new branch]      master -> master

To access the hadashboard app, navigate to http://your-app-name.herokuapps.com. You will be asked to grant the hadashboard app access to your Heroku account. Make sure to Allow Access. The hadashboard app needs access to your Heroku account in order to verify your identity. You may be asked to log in to your Heroku account, as well. Use the email address and password from step 1.

You will see the default dashboard, but it will not yet have access to your SmartThings.

6. Authorize with SmartThings

To grant the hadashboard access to SmartThings, you must first authorize with the SmartApp created in step 3. To do so, navigate to http://your-app-name.herokuapps.com/smartthings/authorize. Log in with your SmartThings credentials and allows access to all the devices you would like to be able to control from the hadashboard.

After clicking Authorize you should be redirected back to the default dashboard, and you should now have access to your things.

Note, that currently authorization only persists for the lifetime of the execution context of the hadashboard app. So, whenever you restart the Heroku dyno (such as after deploying changes - step 5) you will have to repeat this step. You may also have to authorize after making changes to the SmartApp, for the changes to take effect.

Changing Widgets

The hadashboard is a Dashing app, so make sure to read all the instructions on http://dashing.io to learn how to add widgets to your dashboard, as well as how to create new widgets.

Essentially, you will have to modify the dashboards/main.erb file. After modifying this file, you must commit the changes to the git repository:

$ git add .
$ git commit -m "Made some changes to the main.erb layout file."
$ git push heroku

This will re-deploy your application, so make sure to repeat installation step 6.

The basic anatomy of a widget is this:

<li data-row="1" data-col="1" data-sizex="1" data-sizey="1">
  <div data-id="sofalamp" data-view="Stswitch"
    data-icon="lightbulb" data-title="Sofa" data-device="Sofa Lamp"
    data-event-touchend="onClick"
    data-event-click="onClick">
  </div>
</li>

data-row, data-col: The position of the widget in the grid.
data-sizex, data-sizey: The size of the widget in terms of grid tile.
data-id: The unique id of the widget.
data-view: The type of widget to be used (Stswitch, Sttemp, etc.)
data-icon: For Stswitch, the icon displayed on the tile. See http://fontawesome.io for an icon cheatsheet.
data-title: The title to be

Hadashboard

Install / Use

README