[APP][Pro] Dashboards

Apps
, ,
1

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

This app consists of two parts:

Install the Homey app, and navigate to the web app to access and create dashboards. In order to be able to save dashboards and templates, use the native Homey app to create a Dashboard device.

Security :lock:

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.

Features

Widgets

Dashboards are made up by widgets. These are building blocks that can be used together to create simple or advanced dashboards. Based on their functionality, they are grouped into the following categories:

Layouts - Widgets that structures child widgets in a special way:

  • Grid
  • List
  • Sections

Logic - Advanced widgets that allow for complex views:

  • Foreach
  • Switch

Components - The basic building blocks:

  • Card
  • Dashboard link
  • Device
  • Dialog
  • Flow
  • Iframe
  • Image
  • Insight
  • Section
  • Sensor
  • Slider
  • Template
  • Text
  • Toggle
  • Variable

Templates

The key feature of this app, is the ability to create reusable templates. Some templates will always come built-in, but you can opt-out and create your own based on your needs.

A template consists of two things:

  • One or more widgets
  • And arguments

Widgets are used the same way templates as in a dashboard, but utilizes arguments to make them customizable based on user input.

Example: The Zone Lights built-in template can only be configured with a single argument; the zone to render. The template itself takes this zone argument and uses it to generate a list of all light devices in the zone, and render a Capability built-in template for each of them. This is basically a template that only consists of 2 widgets, but is powerful enough to render controls for all lights in a zone :flexed_biceps:

image
image625×202 7.51 KB

Example: The Capability built-in template on the other hand is much more complex, consisting of multiple layers of switch widgets in order to find out what type of control should be displayed, based on data type and if the capability is gettable/settable.

image
image625×285 13.8 KB

Local network API-key

NOTE: This feature is only available for HP23 because HP16/HP19 does not have the API-key feature.

For HP23 users, the web app is also bundled as a part of the Homey App installation. This means that you can use a wall mounted tablet to view the dashboards, without being dependent on internet access. The url to the bundled web app can be found by navigating to my.homey.app → Settings → Apps → Dashboards → Configure.

Feedback

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!

29 Likes
2

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 :slight_smile:

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.

2 Likes
3

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 :thinking:

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 :wink:

4

Thanks. Now it’s clear how the dashboard it’s connecting to Homey. :slight_smile:
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/

    grafik
    grafik819×409 35.8 KB

  • 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.

2 Likes
5

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 :thinking:

6

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.

1 Like
7

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.

image
image951×592 67.4 KB

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 :thinking:

8 Likes
8

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 :thinking:

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

5 Likes
9

@skogsaas Is there already a test link?

10

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 :heart:)
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.

11

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

1 Like
12

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!

13

Working on it :wink:
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 :closed_lock_with_key:

3 Likes
14

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.

1 Like
15

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 :wink:

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 :confused:
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.

16

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.

17

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.
image

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 :sweat_smile:

18

The last one, I guess :slight_smile:
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.

19

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.

20

image
image1200×675 98.1 KB

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.