Authentication

When you first launch HousePanel, an authentication page will be displayed for you to provide your credentials and other setup information. The page will look as follows:

Timezone
The timezone is in standard TZ format. A list of supported names is here.

Skin Directory
Skin Directory is the name of an existing folder with your preferred skin. The default is “skin-housepanel” that is provided. By convention skin folders should start with the word “skin-” but that is not required.

Listen On Port
This value is the port number that is used to by the hub app to communicate to the Node.js application. It can be any unused port. The communication process for this port is a simple http post command.

WebSocket Port
This value is the port used by the Node.js application to communicate directly with the housepanel.js Javascript code using the WebSocket protocol. The default of 1337 is a good choice but any unused value should work fine.

Username and Password
Next, you must supply a username and a password. Blank usernames are no longer supported so you must provide at least one valid username and password pair. A blank password is allowed but strongly discouraged. Blank passwords mean anyone with physical access to the server where you installed HousePanel can control your home if they guess your username.

Multiple users can be defined, each with their own unique Username. If this is your first time running HP, enter your main username and proceed with authenticating your hubs. You can return to this page later to add additional usernames. When you add a new username later, you can skip the hub auth step by clicking the “Done Authorizing” button. For now, proceed with identifying your default main user and giving a password. Then proceed with selecting your first hub and hub info below.

Authentication Block

This authentication block in yellow is where you provide hub-specific authentication information. Multiple hubs are supported. The drop-down box in blue is used to select which hub to authenticate. If a new hub is being added, the last item in the list should be selected. This will be the only choice for first-time users.

API Url
You ALWAYS have to provide a valid API Url address. Typical values for the API Url are:

SmartThings: https://graph.api.smarthings.com
Hubitat Local: e.g., http://191.168.1.50
Hubitat Cloud: https://oauth.cloud.hubitat.com

If you want local processing for Hubitat use the local version. If you want to be able to use your panel anywhere use the cloud version. For local Hubitat processing there is no auth challenge. For the cloud versions you will have to provide your login information, and then you select all of the devices that you want HousePanel to control. Your login information is the same information used to access your hub account online.

Client ID and Client Secret
These two parameters are unique to your hub and must be provided. They are created when you installed HousePanel.groovy and activated OAUTH2 on your hub. During the installation step you were instructed to save these values for later use. This is where they are used. Please refer to the Installation Section for details.

Fixed Access Token and Fixed Endpoint
The Fixed Access Token and Fixed Endpoint values are optional. If provided you do not have to provide the Client ID and Client Secret values. You also will not be redirected to an auth challenge page. This option is provided for those who know their tokens and don’t want to bother being challenged every time to enter their credentials when doing a reauth. These values are printed in the log file of your hub whenever a hub is authorized.

Hub Name
The Hub Name field is optional and will be filled in automatically if left blank. If you provide a name here that name will be used instead of the name provided by your hub.

Refresh Timer
The final parameter, Refresh Timer, is the number of milliseconds to wait before all data is refreshed by reading the hub. A good value to use here is 60000 which is every 60 seconds or once a minute. Smaller values will refresh the page more frequently. Values smaller than 30000 are not recommended because hub refreshes are slow and will make your dashboard unresponsive. Refreshes can be disabled completely by setting this value to 0. This is a reasonable approach if you have the Node.js companion application installed and working well because all tiles stay in sync.

Authorize Hub
When all required fields are provided, click this button to start the authorize process. For SmartThings hubs, you will be shown a list of your hubs. Select which hub you want to associate with HP. Most people only have 1 hub so there isn’t any decision to make here, but you will still need to explicitly click on the one hub that you have. After you click on the hub, or in the case of Hubitat, after you authenticate, all supported things will be shown in a list. Select which things you want HousePanel to have the option of displaying and controlling. I am saying the “option of” because HP does not have to display everything you select here. It is just that ONLY the things selected here will be possible to display. The way you select what is displayed where and how they are displayed will be described in other sections.

I recommend selecting everything that is supported in the most intuitive category. For example, dimmer switches will show up on both the switch list and the switchlevel list. I would select it only on the switchlevel list, but you can do both. You might decide to exlude some devices. For instance, I excluded a light that I have in my food pantry that is activated by a door open sensor, since I don’t ever anticipate needing to turn the lights on in a closed food pantry. Anyway, just select the things you want and you will be good to go. To finish this step click on the Save button at the bottom of the screen. Things can also be selected when you install the app. The things you selected when the app was installed will be selected by default when you authenticate the hub.

After you finish selecting your devices you will be redirected back to this same Authentication page where the number of devices read will be shown for the hub you selected. At this point you can authorize another hub following the same procedure. Just select the hub you want from the “Authorize which hub” drop down list and proceed accordingly. If you want to add a hub then select the last item which is always a new blank hub.

Remove Hub
If you click this button, the hub selected in the blue drop down list area will be removed from HousePanel. This cannot be undone other than adding the hub all over again.

Done Authorizing
When you are done authorizing hubs, select the “Done Authorizing” button at the bottom of the screen. You can also click this button if you just changed some of the parameters on the top, thus skipping the authorizing step altogether. Your selections will be processed and the main HousePanel page will display.

When the HousePanel main dashboard loads the first time, it reads all things that you selected and their states. It then assigns unique ID numbers to each thing, it automatically organizes each thing selected into one of several pre-defined rooms. That information is then saved in a file called hmoptions.cfg onto your server. In our example case, it will be stored in: “/var/www/html/housepanel/hmoptions.cfg”. As an aside, this is why you had to do the step of making your server directory Read/Write. Without that setting HousePanel will not be able to save this file. If all goes well HousePanel will then render the page and display it to you.

Sometimes when a new hub has been authorized or other authentication changes are made, a page Refresh is needed for all available things to show up. Just reload your browser or click the Refresh button.

Security Considerations

It is this authentication step that prevents anyone from accessing your HousePanel installation. This is why it is important to protect this login information; otherwise, anyone who has it will also be able to access your HousePanel and control your smart home. On the other hand, if you installed HousePanel on a Raspberry Pi on your home local network, then only people with access to your home network will have access to HousePanel. This gives you one extra layer of protection and is why I prefer the Raspberry Pi installation option (see Option 1 in Section 1). This same extra layer of protection exists for Option 2 installations on a PC or Mac with a web server, but such a server must stay on and can be more easily accessed via a keyboard than a rPi that has been tucked inside a cabinet.