[APP][Pro] Dashboards

[skogsaas]

This is the first post I’ve made to the Homey Community, and I’m glad to use it to present this project.

Getting started

You can install the Homey companion app from the App Store here: Dashboards App for Homey | Homey

HP23 users can access the locally installed dashboard by navigating to the app configuration page.
HP16/HP19 users must use the online version hosted at GitHub: homeyboard.github.io, as only the HP23 has the API-key feature.

Security

This app has no backend! Only the front end web application you use to create and view dashboards. That means that no data is ever sent to third parties. Your dashboard, devices, flows, insight and images is only transmitted between you and your Homey. Security and privacy is priority one. I cannot even see how many has logged in or uses this project.

Dashboards

In time of writing, there are no customizable dashboards available in Homey. The next best thing I’ve come across is using MQTT and NodeRED Dashboards. This project, and I emphazise project, will allow you to create custom dashboards with widgets to display and control your Homey.

Example of a dashboard displaying some basic Homey device capabilities:

Homey app certification status

Draft → Test → Published

You can get the app from the Homey App Store here: Dashboards App for Homey | Homey

Technical

This app is actually composed of two apps:

• Homey app for making the dashboard hosted from your Homey itself
• Svelte web app built as a SPA that uses the Homey Web API to access data.

Widgets

Capability

Display readonly or controllable device capabilities from your Homey.

Currently supports

• Boolean values (yes/no)
• Numeric (will display a slider if min, max and step is defined)
• Text (will display value and unit if available)

Flow

Display a simple play button to trigger flows.

Image

Display an image registered to a device. Typically this can be a snapshot from a surveillance camera, or artwork from a chromecast device. When the image is clicked, it will open a larger view to let you see the details. As images from streams do not typically trigger an update, it is possible to select a refresh interval.

Insights

Display graphs based on Homey Insights data. It is possible to select the same resolutions as in the Homey native insights view.

Breakpoints

Four different screen sizes allow the user to customize the layout on different screen sizes. In other words; rotating the screen allows a custom layout:

Horizontal:

Vertical:

The four breakpoints are:

• 640px (6 columns)
• 768px (12 columns)
• 1024px (18 columns)
• 1280px (24 columns)

Feedback

For now, I would love to have some feedback on the project. What you would like to see implemented?
If you have any ideas for widgets, please describe the functionality and design. Any illustrations or examples would be great!

[RonnyW]

Please clarify what API key you are using.

• Is it a local API key created in HomeyPro23? Then the dashboard is only usable for HP23 users using the Homey-specific cloud URL. But it’s the official way to allow access to local Homey.

• Is it an internal Athom API key? Then you shoud not publish your app/web app using a foreign key.

• Is it the example key from https://api.developer.homey.app/ for development use only? It’s prohibited to use it in public non-development purpose.

• Or is it a official Athom WebAPI key you requested and got from Athom as private key+secret to pusblish your app using the WebAPI access? Then all is fine

I’m just curious how you are using the WebAPI (and not a Homey specific cloud API ) with a “generated” ApiKey. I ask because I went the official way and got an official ApiKey fromAthom for my project.

[skogsaas]

Oh, yeah, I should clarify that part.
I only have a HP23 available, so I’m using the local API key functionality with the local http://homey-[ID of my homey].local address, so no cloud involved.

Looking at the documentation for the AthomCloudAPI, the difference is how you authenticate. So this app should also work on older Homeys as a cloud service

I’ll add a task to the “roadmap” to test using the example-key, and possibly request a set of OAuth2 credentials when I confirm that it works

[RonnyW]

Thanks. Now it’s clear how the dashboard it’s connecting to Homey.
So currently it can only be used with HP23 and a local API key.

For your roadmap some hints - I stumbled already over it…

• If you want to use a real WebAPI access you have to implement the oAuth procedure. That’s not so easy when using only http access to the API (without NodeJS module). I did a lot of research how to do it. At the end you have to call the oAuth URL (login to Athom account) with your real API key. Then you have to provide a callback URL to resolve the auth token. Then you have to do the login to Homey (using auth key) to get the Bearerr token.
  The local API key is the same as the Bearer token but without a expiry date.

• You have to request the API key using the request document:
  https://api.developer.homey.app/
  

  

• And most important:
  With local API key or the example key from SDK documentation you get full Homey access. The real API key will get more differentiated scopes. So no full access will be granted (to other users, to apps etc). Only access to flows/devices. And the user can choose the right he want to give your Dashboard in oAuth page (e.g. read only device access). So you have to deal with situations where write access to Hoemy is denied.

I hope it’s a bit clearer now. Just ask if you need more information.

[skogsaas]

Thanks for the heads up regarding the scopes through Athom OAuth. Access only to flows and devices might impose challenges, but not impossible. The app currently uses app settings to store the dashboard settings. A cloud version using AthomCloudAPI has to have somewhere else to store the settings. A possible solution working both for both locally and cloud, could be to introduce a new custom device “dashboard”, and save the dashboard settings as device settings. This also allows each dashboard to have custom trigger, condition and action flow-cards in the future

[RonnyW]

Well, using WebAPI you don’t need the HomeyApp. You are only using the http endpoints at Athom to read devices and capabilities or change capabilities or start flows. You don’t access apps (app APIs) directly, only the devices.
I can’t imagine that you can access app APIs via WebAPI, but I haven’t tried that. I only use the official http URLs like WebApp or mobile app is doing to read/change devices/flows.

But at the end it depends if you only want to provide a ‘local’ dashboard and what you want to do in Homey.

[skogsaas]

Progress update

Added widget for displaying images. This can be as illustrated below; the price of electricity for today, courtesy of the app Power by the Hour. It can also be images from surveillance cameras or other devices in Homey.

Added widget for displaying charts with data from Homey Insight.

Next on the agenda after this is to make the app ready to submit for review by the Athom/Homey developers. It will be interesting to see if they have any comments

[skogsaas]

Progress update

The app has now been submitted for certification by Homey. Hopefully soon it should be available for download and testing.

I solved the api-key problem by giving the app the homey:manager:api permission. This allows the app to retrieve a token that is valid for 2 weeks according to the documentation. By doing this, the app should also work for pre HP23 units that does not allow you to create api-keys from the UI. What do you think @RonnyW, a viable solution?
A future version of the app should implement a way to retrieve an updated token before expiry

Next progress update should hopefully be with a link to the published app

[LRvdLinden]

@skogsaas Is there already a test link?

[skogsaas]

No sorry @LRvdLinden, as far as I understand, the first version of the app has to be certified by Homey before it’s made available, even in ‘test’. As soon as it’s certified, it’s available in production. (Yes, we’re testing in production here )
I already have the next patch ready with some minor improvements, but that will have to wait until the current version is certified, as I don’t want to restart the certification process.

[R0B]

Looks promising and I would definitely give it a try as soon as it is available.
Keep up the good work. Tak.

[Alf_Sjostrom]

This is my biggest let down of the Homey Pro 2023 so far, the Dashboard, so hope they hurry up and approve this, looks very promising!

[skogsaas]

Working on it
Status right now is that the Homey team is reviewing the app. But as the current version submitted to Homey requests the homey:manager:api permission, and makes the Homey “owner token” available as a part of the URL, the Homey team is skeptical. So I’m right now implementing a oauth2-ish JWT with asymetric encryption keys for exchanging the homey-token to the actual dashboard in the browser. With this in place, it will be a lot more secure

[Ole_Landfald]

This looks really promising, and I will definitely test it when it’s out!

Suggestion:
Support for adding multiple pages with custom titles. Lets you swipe from page to page.

[skogsaas]

By pages with custom titles, are you referring to multiple browser tabs with their titles, or do you want to switch between different dashboards as tabs inside the web app?

I’m already planning to do the last one

Status right now is basically that Athom do not want the owner token, which is retrieved by the using the permission homey:manager:api, in the browser. No matter how securely it is transferred and never stored in the browser storage. The token is basically just the same as the native API-Key feature of the HP23, just that it has a limited lifetime. So it safer to use than the API-Key feature, but for some reason Athom are being difficult
It might just be that they dont want the app released, because they are working on a similar feature themselves. (The HP23 has an undocumented dashboard-API)
I’m going back and forth with Athom 1 email a day, so it takes a while discussing available options.

[RonnyW]

Wouldn’t it be easier to request a real WebAPI key and use the WebAPI (http only) with oAuth instead of having an Homey app between?
The WebAPI key can read devices, use quick actions, read and start flows, read favorites etc.

I can understand Athoms position not want to spread out a personal token - independent how it’s transferred or stored. The user don’t know about and can’t restrict rights.

Using the local API key, the user has to allow actively access and has to set scopes he want to allow. That means the dashboard must handle different scopes in that case.

That’s the difference. WebAPI and lokal API is in direct user control, your way to export the token is not.

If you want to offer a public dashboard, you shouldn’t use hacky auth methods.

[skogsaas]

My reason for not wanting to use OAuth, is because I want to have everything local on the Homey, and not be reliant on internet access to display a dashboard when everything is on my local network. The SPA is hosted and served from the Homey Pro sitting on my desk.

If I switch to using Athom OAuth, I would have to host the SPA somewhere in order to get a static callback endpoint with TLS.

And I wouldn’t say that the user is in direct control with OAuth. They just get a prompt that say the same as an app requesting the homey:manager:api permission: Full access to Homey.

There is no way to withdraw access after it’s first allowed with OAuth. With both API-keys and OwnerToken, you can easily withdraw access by deleting the key or removing the app if you want to. The owner token stops working when the app is deleted. Just take the Homeydash project as an example; it works by extracting the token from the homey.ink app after logging in, and after that have no requirement to use homey.ink. There’s nothing stopping my project from doing the same thing, just adding a description that tells users to log in with homey.ink and use their token in my SPA

[Ole_Landfald]

The last one, I guess
If I implement this dash the front page would fill up quickly. Swiping right and to access next dash/page would be nice. And then be able to give it a headline of my choice.

[RonnyW]

Yes, using oAuth the scopes are predefined by Athom (what they allow for your API key). Thats not a full access how it is possible while reusing the HomeyInk API key.

For a local only access you are right. You don’t need a WebAPI key.
So the local API key (HomeyPro23) would be the best approach for me. You get a key where the user can set scopes.

I thought the dashboard would also be used on a mobile phone and that would need a WebAPI access. If you only create local dashboards (tablet at home) in the same LAN, you have more possibilities.

[skogsaas]

After having some mental discussions with myself regarding the homey:manager:api permission. I’ve decided to drop this permission. The only reason I tried to use it, was to make the dashboard work for owners of older Homey Pro’s.

As a proof of concept, the dashboard is now available online for anyone to try it at the GitHub page: https://skogsaas.github.io. It requires you to log in the same way you would use Homeydash, by first logging in at https://homey.ink and copy the full URL from the developer console.

I’m still planning on releasing this as an installable app, as I have no plan for a backend to store the dashboard configurations. This means that using the cloud version without the Dashboards app installed on your Homey, will result in using your browser’s local storage for retaining configuration between refreshes. I have also implemented login using an API-key manually generated on a Homey Pro 2023. This will give you the option to specify exactly what scopes you want the dashboard to have. Giving you the option to have a read-only dashboard somewhere for everyone to access. Local login currently requires the web app to be installed on your Homey, as I have not made it possible to input the local url anywhere.

As always, the source code is available on GitHub if anyone want to see what happens under the hood: GitHub - skogsaas/homey.dashboards.