Smart Home Controls
SEPIA can use different smart home systems (often called HUBs in this document) to access and control smart home devices. Here you will find all the necessary info to connect SEPIA to one of these HUBs.
- Access to a Smart Home HUB
- User rights
- Client/App settings
- Tutorial: openHAB
- Tutorial: FHEM
- Tutorial: SEPIA Internal HUB
- Testing
The quick setup roughly looks like this:
- Install your favorite smart home HUB software (e.g. openHAB or FHEM)
- Open the SEPIA Control-HUB and add the HUB server URL and name to your SEPIA-Assist server config (e.g.:
smarthome_hub_host=http://localhost:8080/test,smarthome_hub_name=test) - Give your (or any) SEPIA user the
smarthomeguestrole to control devices and optionally thesmarthomeadminrole to get access to the smart home configuration via SEPIA Control-HUB - Use the SEPIA Control-HUB to check your smart home HUB connection and tweak device settings as necessary
- Use your SEPIA client to control your smart home via voice 😎
To communicate with a smart home system (HUB) the SEPIA-Framework usually uses the REST interface of the HUB, so the first thing you need to do is to tell the SEPIA Assist-Server where to find the HUB interface and what type of interface it is. This can be done via the SEPIA Control-HUB (admin tools).
SEPIA v2.5.0+: Start the SEPIA Control-HUB and log in with your admin account then open the page 'Smart Home'. In the 'Smart Home HUB' section on top of the page select one of the supported systems. Systems like FHEM and openHAB can be accessed directly and for systems like ioBroker or a general MQTT interface you can use 'Internal (SEPIA)'. The SEPIA internal interface will also allow you to combine multiple different instances of FHEM or openHAB. Enter the URL of your Smart Home HUB (see individual sections below for more details) in the 'Server' field and press 'Write HUB info'. This will store the data in the settings file of your SEPIA server and will trigger a server restart as well. If you need to enter authentication info for non-internal HUBs please follow the description below about smarthome_hub_auth_type and smarthome_hub_auth_data.
Example using FHEM as HUB
Older versions: Go to the 'Core Settings' page in the SEPIA Control-HUB and load the persistent Assist-Server settings by pressing the "get" button at the top (the same settings can be found in your installation folder, usually: ~/SEPIA/sepia-assist-server/Xtensions/assist.custom.properties). Look for the entrys: smarthome_hub_host and smarthome_hub_name and fill in the sever URL (including the port) and smart home HUB brand ('openhab', 'fhem', 'test', ...), e.g.:
smarthome_hub_host=http://192.168.0.10:8080
smarthome_hub_name=openhab
If your smart home HUB is secured by a user-name and password via HTTP basic authentication or an access token delivered via the HTTP request header you can add this information via the fields smarthome_hub_auth_type (e.g. 'Basic' or 'Bearer') and smarthome_hub_auth_data (e.g. base64 encoded username:password or access token), e.g.:
smarthome_hub_auth_type=Basic
smarthome_hub_auth_data=bXl1c2VyOjEyMzQ1
I this example the auth. data represents the base64 encoded username:password combination for 'myuser:12345'. There are online tools that can encode your data if you don't know how to generate the string.
Remember to restart the server afterwards to activate your changes!
To keep access to your smart home system secure the SEPIA administrator has to allow a user access by giving him specific user-roles. This step is required no matter what smart home HUB you will use later. The required roles are:
- smarthomeguest - to control smart home devices via the client (e.g. "Switch on the light in the bathroom")
- smarthomeadmin - to be able to load devices via the SEPIA Control-HUB and change device properties like 'type' (light, heater, ...) or 'room' (living-room, office, bath, ...).
This can be done via the 'User Management' page in the SEPIA Control-HUB. Please see the 'Create and Edit Users' Wiki entry for more info.
The SEPIA admin and users with the smarthomeadmin role can configure smart devices for the use with SEPIA on the SEPIA Control-HUB Smart Home page. If the previous steps were successful you will be able to load devices from your smart home HUB and they will be shown as "cards" on the page. Simply press the 'load HUB info' button if the data is not already shown and then use the 'get devices' selector to load data. The device-cards can be used to change things like the device-type (light, roller shutter, tv, etc.), room (living-room, bath, etc.), room number (1, 212, 300, ...) and more complex settings like the state-type or even custom set commands. The latter is especially useful if SEPIA cannot identify the correct device and state type automatically or set commands are unknown to the HUB interface. You can read a bit more about this in the openHAB example. Feel free to post your questions in the issues section.
From v0.20.0 on the SEPIA client (app) has a setting for the 'local device site'. This setting can be used to assign a client device to a certain room in your smart home enabling SEPIA to understand commands like "Light" without saying "Light in the living-room". To use this feature check settings page 1 in your app and look for 'device site' below 'device ID'. If you choose 'home' as location and 'room' as type you can use the name field to select a specific room and the index if you have multiple rooms with the same name.
Another feature that can be configured from the account page of the client settings is the default temperature unit (C for Celsius, F for Fahrenheit). If the device unit and user request do not fit SEPIA will try to automatically convert the units (e.g. "set temperature to 80 degrees Fahrenheit" will be converted to Celsius if required). Compared to the 'device site' this setting is part of the user account and will be applied to the client during log-in.
If you have questions/comments about SEPIA + openHAB you can check out the official openHAB forum topic as well.
Please see the openHAB installation guide and documentation to learn how to set up your openHAB server if you've never used one before (it is open-source and works very well on a Raspberry Pi ^_^).
SEPIA can use openHAB to control numerous smart home devices out-of-the-box after you've set up the connection between SEPIA and your openHAB server as described previously. Typically the address for the openHAB REST interface is the IP-address followed by port 8080, e.g.: http://192.168.178.13:8080. The smarthome_hub_name is openhab.
SEPIA will recognize some items automatically depending on their "category" field in openHAB but sometimes you'll want to adjust the item configuration manually. Depending on the way you manage your items in openHAB select one of the following ways to proceed:
Simply follow the steps mentioned in the previous section to load device-cards and change the configuration. Changes are stored automatically on the openHAB server. To check if an item is configured correctly and responses to the SEPIA interface you can use the 'toggle' button on the top right of each device-card.
NOTE: If you've used "simple" mode to add your items to openHAB they might be write-protected and you will see an error when trying to edit device-cards. In this case you need to switch off simple mode, remove the item and add it again.
Option B: If you create Items via .items File (credits to MtotheKay)
SEPIA uses the "tags" field of each openHAB item to store for example the assigned type (e.g. sepia-type=light) and room (e.g. sepia-room=livingroom), but it seems that items directly assigned to a channel do not accept these "tags" modification. So either create a second item for each device and write a rule to set the value or create a group to control them. Since you usually don't want to control each type of device (e.g. each lamp) individually it is good practice to create groups per room.
If you don't know, go with the groups. For example: Create a lamp group for each room, assign it to the light items and add the tags for SEPIA in your .items file like this:
Group gLR_Light "Dimmable Light Living Room [%s]" <light> ["sepia-type=light", "sepia-room=livingroom"]
Tags and possible values (SEPIA-Home v2.5.0):
sepia-type
- light
- heater
- tv
- music_player
- fridge
- oven
- coffee_maker
- roller_shutter
- power_outlet
- sensor
- device
- other
- hidden
sepia-room
- livingroom
- diningroom
- kitchen
- bedroom
- bath
- study
- office
- childsroom
- garage
- basement
- terrace
- balcony
- garden
- shack
- hallway
- sunroom
- other
- unassigned
sepia-room-index
- 1, 20, 303, ...
sepia-state-type
- number_plain
- number_percent
- number_temperature_c
- number_temperature_f
- text_binary (e.g. ON/OFF or OPEN/CLOSED)
- text_raw
sepia-set-cmds (expert setting)
- JSON as string, e.g.:
{"enable":"on", "disable":"off", "number":"pct <val>"}
The SEPIA Control-HUB should show the correct values now if you press 'Get Devices'.
To manually test your openHAB items configuration you can enter the URL http://<openHAB Server Address>:8080/rest/items/<item name> into your browser address field and check if the tags field lists sepia-type or sepia-room etc..
If you have questions/comments about SEPIA + FHEM you can check out the official FHEM forum topic as well.
Please visit the FHEM homepage to learn how to set up and use your open-source FHEM server if you've never used one before.
SEPIA can use FHEM to control numerous smart home devices out-of-the-box after you've set up the connection between SEPIA and your FHEM server as described previously. Typically the address for the FHEM REST interface is the IP-address followed by port 8083 and path '/fhem', e.g.: http://192.168.178.13:8083/fhem. The smarthome_hub_name is fhem.
SEPIA will recognize some items automatically depending on the attributes set in FHEM but you can easily configure each one via the SEPIA Control-HUB. Simply follow the steps mentioned in the previous section to load device-cards. Before you can change the item configuration make sure to press the register SEPIA button (this will create SEPIA attributes on the FHEM server). Item configuration changes are sent to the FHEM server directly BUT will only be stored permanently in your FHEM HUB after you've pressed the 'save config' button of FHEM (this might be different for non-default FHEM setups).
To check if an item is configured correctly and responses to the SEPIA interface you can use the 'toggle' button on the top right of each device-card.
In the previous scenarios the external systems (FHEM, openHAB) will manage your devices and all SEPIA related configurations will be stored inside those HUBs. This is great but unfortunately its not possible for all supported systems and there might be scenarios where you want to access multiple different HUBs at the same time. For these situations you can use the SEPIA internal management system that will store custom devices in SEPIA's own database.
It is important to understand the pros and cons of this setup so here is a little summary:
- Pro: Connect to devices/HUBs/systems that do not offer all the necessary interfaces or have no state management
- Pro: Granular control over the devices and settings
- Pro: Efficient access and less overhead since only those devices that are really in use will be loaded
- Pro: Mix devices of different systems or multiple instances of the same system
- Pro: New interfaces can be very simple (think of basic HTTP calls) and can be added quickly
- Con: Setup is a bit more complicated and time consuming, especially if you want to control many devices
- Con: If you change the settings of the external HUB you probably need to adjust SEPIA settings as well
To setup the internal HUB choose "Internal (SEPIA)" as system in the drop-down field and enter an arbitrary value for "Server", e.g. "internal" (this is required because the server expects a non-null value). It should look like this:
Setup for SEPIA's internal HUB
Press "Write HUB Info" to store the new configuration and wait a few seconds until the server reloads (soft restart).
Since the internal HUB does not know any interfaces or devices yet we need to add them one by one. First we create a new, blank device card by pressing the button "Create Device":
Blank device card
Now we need to do the following things to connect this "virtual" device to a real one:
- Choose a name for the device by pressing the little pen button next to "New Item". The name should be something that distinguishes it from other devices of the same type and room. For example "Ambient" or positions like "Left" and "Top" can be good names for a light. Numbers work well too and can be combined with other tags, e.g. "Top (1)".
- Choose the device 'Type'. This will define the way how you interact with the device later. For example a 'light' will be triggered by the sentence "switch on the light in the living-room". If your device does not fit to any given type you can always choose 'device' and use sentences like "Switch on device [name]".
- Choose the 'Room' the device will be in and optionally add an index number. For example 'Bath' and '2'. You can use the value 'Other' in combination with the index for sentences like "Lights in room 202".
- Press the floppy button on the top right to store the current device configuration in the SEPIA database before you continue.
- The next step is to create the 'Interface' that will connect SEPIA to your devices and then select the 'Int. Device Id' (Int. = Internal) of a specific device accessible via the same interface. Continue with one of the examples below to use for example FHEM, openHAB, MQTT or ioBroker.
In your newly created device card (previous step) go to the field 'Interface', choose '-NEW-' and press the little pen button at the right to create a new interface. You will see the blank interface editor. For FHEM and openHAB the setup is basically identical to what was described in the FHEM and openHAB section above just this time we will store each interface as separate object in the SEPIA database and use them at the same time. Here are two examples, feel free to add as many interfaces as you want if you use more than one server:
Example interfaces for openHAB (left) and FHEM (right)
Choose what you like as name, just make sure that each interface gets a unique one or it will be overwritten! If the server access is protected by a password (e.g. via reverse proxy) you can use the fields 'Auth. Type' and 'Auth. Data' to enter data for Basic Authentication (type: Basic, data: Base64 encoding of 'username:password').
Each time you add a new interface the server will store the data and the UI will try to update your 'Interface' selector field. If (for any reason) this did not happen just quickly reload the devices via the 'Get Devices' selector.
The final step is to find the 'Internal Device Id' of the devices we want to connect. This is usually the unique ID given to a device by the external HUB and used to read or write data/state changes. For FHEM you can find it if you open your FHEM browser interface and navigate to the device you want to control. The ID should be given in the URL like this:
How to find the 'internal device ID' in FHEM
For openHAB it is the "name" of the device. You can see it for example in the items section of the Paper UI:
How to find the 'internal device ID' in openHAB
Copy this ID and paste it into your 'Int. Device Id' field of the corresponding device card and you are done 😃 . Your newly created "virtual" SEPIA smart home device should now be connected to the real device.
To test the connection first reload all devices and check if the red floppy icon of your new device card has disappeared. If you can still see it that means SEPIA was not able to read data from the device. In this case you might want to check all your settings and eventually the log of your SEPIA Assist-Server for errors (~/SEPIA/sepia-assist-server/log.out). If there is no red floppy icon anymore you can use the toggle button next to the delete button (trash bin icon) to switch the device on and off.
Coming soon.
Coming soon.
If everything worked out fine open your SEPIA client, log-in with your new smarthomeguest user and tell SEPIA something like Turn on the lights ... hopefully you will see some action :-)