Home Assistant API Setup
To get started, you may need to make a few quick changes to your Home Assistant server. You've more than likely edited the configuration files already, so this should be a breeze. If you have already setup an API password, you can skip over this part.
- Set an API password in your configuration.yaml file, in the http section
- Optionally, you can allow CORS access to use the hosted version of the control panel from this server
api_password: Set a password here
# CORS access is optional
- Save the file and reload/restart your Home Assistant server
Running Control Panel
There are currently two methods of using the control panel.
Additionally, for iPhone and iPad users, you can use the 'Add to home screen' function of Safari, to add the Contol Panel as an app. This allows for a full screen experience, which is somewhat improved over Safari.
- Open the Control Panel on your iPhone or iPad, using Safari
- Tap the sharing button in the bottom bar
- Tap the 'Add to home screen' option from the list to add it as an app
Control Panel Setup
The first thing you'll see is the Control Panel setup wizard. Follow the instructions on screen to get connected. However, if you're having trouble, or would like to set it up manually, here is a quick tour of the settings page.
Set the following options to connect to your Home Assistant server
- Server URL - use the address you normally use to access the Home Assistant interface, eg, http://hassio.local:8123
- API Password - add in the password you set in the configuration.yaml file
- Click Save and reload the page to connect
- Settings - Various options to set Edit Mode, Debug Mode, button sizes and notifications
- Background - Choose the look and feel of your Control Panel, using one of the inbuilt background colors, background images - or add your own using the URL field.
- Weather - add in any weather components to show the weather. The Met Office component has been used in the example picture
- Export - Export and import your HACP config file. Copy the config data from the 'Export' field to save your config, or paste in a config using the 'Import' field
- Reset - if something goes wrong, you can reset individual parts of HACP, or choose 'Reset All' to perform a hard reset and setup your Control Panel from scratch
Adding Groups and Entities
If you recently got Home Assistant up and running, there's a chance you won't have setup any groups. If this is the case, you might need to add some to get get everything going. To this, you need to go into Edit Mode:
- To enter Edit Mode, long press on the Settings icon (bottom right)
- To add a new entity to an existing group, press the + button in the group which will open the Entity selection page. Click on an entity to add it to the group
- To add a new group, you should have a + button by the settings icon. Press this to add a new group.
- To delete a group, press 'Delete' under the group heading
- Long press the Settings icon once more to exit Edit Mode
- To reset your custom groups, go into Settings, and press the 'Reset Groups' button from the reset menu
Long Press for Light Switch Controls
Any light or light group buttons on the Control Panel have a dual function. Long press any switch to show brightness, color and automation controls.
Simple timers and Automations
The automation system has been designed to use the pushed events coming from your Home Assistant API, along with the time of day (daytime, sunset etc) and the clock. Automations can be set on groups or entities, however it's currently limited to lights for the moment.
Please be aware that the Control Panel must be powered on all the time for these automations to run, and it must be able to receive pushed events from your Home Assistant's API whilst the screen is off, or if the device is in standby. Most Android tablets do this, however iOS will stop Control Panel from running in the background whilst the screen is off. To help test this you can enable debug mode, please see the troubleshooting section below for more details.
To create an automation:
- Long press on a light, or light group to open the entity controls
- Set the light brightness and color that you want to use for the automation, using the sliders on the settings page
- Select the Automation page to turn on your device at a certain time, time of day or with another entity - and click 'Add' to add the automation to the list
- You may also want to add an automation to turn off the light, either at a set time, time of day or after a period of time (minutes). Again, click 'Add' to add in your automation
Some example automations could be:
- Simple Timer - have an entity or light group come on and go off at set time each day
- Dynamic Timer - have an entity or light group come on at sunset, or go off at sunrise
- Auto Turn Off - if an entity turns on, turn it off after a set time
- Turn on with entity - this allows you to link a light or light group with another entity. This could be a motion detector for eg, to turn a security light on and then go off after a certain time.
- To turn on 1 light with another, link a light with another light. This can be useful for creating dynamic groups of lights, separate to Home Assistant
- You can also link a light to a person's device, which will turn on the light when they come home
- Additionally, you can link lights to a media player hooked up to your TV or projector, which will dim the lights when media is playing
- These type of automations don't currently run during the day. The automations will only trigger at sunset, nighttime and sunrise, to make sure your security lights aren't coming on needlessly. However you can test them during the day by enabling debug mode (see the troubleshooting section below)
Adding a Custom Scene
Once you have your groups setup, you can add custom scenes. Scenes are multifunctional buttons, turning lights and devices on or off, and even setting brightness and color. Very useful for changing multiple entities with 1 button.
- To enter Edit Mode, long press on the Settings icon (bottom right)
- To add a custom scene to an existing group, press the + button in the group which will open the Entity edit page.
- Click on 'Create Scene' from the options on the left.
- Enter a name for the scene.
- Click on 'Create Scene'.
Edit a Custom Scene
The 'Create Scene' function uses the current state of your group, however you may want to edit the scene once you've created it
- Long press on the scene button you want to edit.
- Select 'Edit Scene' from the menu on the left.
- Set the state, brightness and color temperature of the devices in your group.
- All settings are saved once you change them - just click 'Close' to exit back to the Control Panel.
Setting up Dark Sky or other Weather Sensors
The Dark Sky Sensor component provides data which HACP can use to display weather information. To setup HACP with Dark Sky, I recommend including the following monitored conditions in your configuration.yaml:
Once you have these configured in HA, you can set them in the weather settings on HACP:
- Refresh HACP by hitting reload in the browser
- Touch the settings icon to enter settings
- Select 'Weather' from the menu on the left
- Tap on each weather setting to select from a list of senors
- Set Temperature entity to sensor.dark_sky_temperature, or sensor.dark_sky_apparent_temperature
- Set Condition entity to sensor.dark_sky_summary
- Set Precipitation entity to sensor.dark_sky_precip_probability
- Tap 'Save' on the left once you're done
- Refresh HACP again by hitting reload in the browser
If you can't connect to your Home Assistant server, or the control panel is a mess of buttons and things that don't make sense, follow the steps below
- Ensure your device can access the normal Home Assistant interface. Open the browser on your device and enter your Home Assistant URL, eg, http://hassio.local:8123. If it opens ok, move to step 3
- Some Android devices may have issues with local hostnames. Try using the LAN IP address of your server. You can normally get this information from your router
- Double check your API password in your configuration.yaml file, and in the control panel. To test it, you can connect to the API via a web browser. For eg, enter http://hassio.local:8123/api/states?api_password=YOUR_PASSWORD_HERE. If you get an error message, recheck your password. If you get a wall of text, move onto the next step
- Enable CORS access - if you are using the hosted version of this control panel, or hosting it locally on another device, you may need to enable CORS access. You can check this by opening the browser error console and looking for errors related to 'No Access-Control-Allow-Origin header is present' or 'Preflight check failed'. If you are seeing these errors you need to edit your configuration.yaml file, and add the following to the http section. Otherwise skip to step 5.
# add in the domain name or IP mentioned in the CORS error
- Restart your Home Assistant server
- Reset the Control Panel using the RESET button in Settings
- Test the control panel in another web browser, or possibly on another device if you have one available
- The control panel uses your premade Home Assistant groups and entities. If you have too many entities showing, you may need to setup a few groups and views on your Home Assistant server. To find out more, click here
- The device names are being truncated and you can't see what they are. You may need to customise your entities and give them friendly names. Click here for more info
- If no entities are showing, check your API directly, to make sure it's outputting the right data. For eg, open your web browser and visit http://hassio.local:8123/api/states?api_password=YOUR_PASSWORD_HERE, and check there are entites listed. To help view this data, you might want to install a JSON view browser extension. If you're not getting the right data coming back, check your API password and CORS settings in configuration.yaml
- Lastly, if you can open the browser error console and see any errors - I'd love to hear about them. I can be contacted via reddit: u/L33-the-3rd
Enable Debug Mode
The debug tool can be handy to help diagnose certain problems once you're connected to your Home Assistant server. On the settings page, enabling debug mode will do the following:
- Show API requests made by the control. So when you press a button, you'll see the request being submitted. If there's a reply back, the request will be marked as completed
- Pushed events coming from the Home Assistant API. Everytime an entity changes on your network, you should get a notification about it displayed in the top right
- To help with pushed event spam, you can ignore sun events
- Automations triggered by other entities will work during the day, so you can test them
- A notification sound is played when a pushed event is received (you'll need to download the additional .mp3 audio files if you are running it locally). You can use this feature to check if your control panel is updating when the screen is turned off, of if your device goes into standby