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
  • Setup via Paper UI
  • Manual entry of SEPIA tags: device, room, etc.
• Tutorial: FHEM
• Tutorial: Home Assistant
• Tutorial: SEPIA Internal HUB
  • Setting up FHEM and openHAB interfaces
    • Adding new interfaces
    • Finding the device ID
  • Setting up MQTT for e.g. Node-RED
    • SEPIA MQTT Setup
    • Node-RED Integration
  • Setting up ioBroker
    • Adding new interfaces
    • Finding the device ID
    • Device card custom config
  • Setting up Home Assistant
    • Adding new interfaces
• 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, choose your smart home HUB (e.g. openHAB, FHEM, Internal) 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 smarthomeguest role to control devices and optionally the smarthomeadmin role 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).

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.

Example using FHEM as HUB

If your smart home HUB is secured by a username and password via HTTP basic authentication or an access token etc. press the 'Set Authorization' button after loading the HUB info and add the data via the pop-up:

Enter HUB authentication data via pop-up

The same data can be added via the 'Core Settings' page in your SEPIA Control-HUB. Check out the fields starting with smarthome_hub_... like smarthome_hub_auth_type (e.g. 'Basic' or 'Bearer') and smarthome_hub_auth_data (e.g. base64 encoded username:password or access token).
Please note that basic auth. data is usually entered as base64 encoded username:password combination, for example 'myuser:12345' becomes '=bXl1c2VyOjEyMzQ1'. The auth. pop-up mentioned above can handle the encoding for you.

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

NOTE 1: Since openHAB 3 authentication seems to be mandatory! In this case please use auth. type Bearer with your API token or use Basic and activate basic authentication in your openHAB settings.

NOTE 2: If you set up your items via *.items file/script and not the GUI your items might be write protected for SEPIA! Please check out the instructions below.

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.

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

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

If you have questions/comments about SEPIA + Home Assistant feel free to create new issues here or mention @sepia-assistant when you use the official HA community page.

Please visit the Home Assistant homepage to learn how to set up and use your open-source HA server if you've never used one before.
Unfortunately SEPIA cannot auto-detect all of the required properties to control your Home Assistant devices out-of-the-box, but you have 2 options to add the missing configuration data. Either use the SEPIA Internal Multi-HUB (see below) and store the information in your SEPIA database or use the Home Assistant configuration.yaml file and create device templates.
If you prefer to use templates make sure to add the Home Assistant URL and long-lived access token as described previously. Typically the address of the Home Assistant REST interface is the IP-address followed by port 8123, e.g.: http://192.168.178.13:8123 and the access token can be generated following this HA tutorial. The smarthome_hub_name is home_assistant.

This section will explain how to use sensor templates as link between SEPIA and Home Assistant. The idea is to create a kind of "proxy" device that stores all required SEPIA properties as persistent attributes. SEPIA will then use this info to read the state of the device and send commands via Home Assistant services or intents.

TODO: ADD MORE INFO

Example template for a HUE light:

template:
  - sensor:
      - unique_id: 'sepia_device_0001'
        name: 'SEPIA Light LV 1'
        state: '{{ True }}'
        availability: '{{ states.light.hue_white_lamp_1 is not none }}'
        icon: 'mdi:transit-connection-variant'
        attributes:
          sepia-interface-device: 'light.hue_white_lamp_1'
          sepia-interface-config: '{"default": {"state": "off", "value": "0"}, "set": {"service": "light/turn_on", "write": "<attributes.brightness_pct>"}, "read": "round(<attributes.brightness>*0.392)", "off": {"service": "light/turn_off"}, "on": {"service": "light/turn_on"}}'
          sepia-state: '{{ ((state_attr("light.hue_white_lamp_1", "brightness")|default(0, true) / 255) * 100)|round }}'
          sepia-state-type: 'number_percent'
          sepia-type: 'light'
          sepia-name: 'Ceiling'
          sepia-room: 'livingroom'
          sepia-room-index: ''
          sepia-mem-state: 70
          sepia-set-cmds: '{"enable": 70, "disable": 0, "number": "<val>", "raw": "<val>"}'

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. = Interface) 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.
• Some HUB interfaces like 'Home Assistant' use multiple different endpoints to read and control devices. In this case you need to add a 'Int. dev. config' (Interface device configuration). Learn more about it in the Home Assistant section below.
• Bonus: Check out the custom config section below for more info about 'Custom Config' and 'State type' field.

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.

MQTT is a "lightweight, publish-subscribe network protocol that transports messages between devices" (Wikipedia) and has become a common and very popular method for IoT connections. There are different ways in SEPIA to make use of MQTT but in this section the focus is on how to send state updates to Node-RED.
Note: To make this example work you'll need access to a MQTT broker (server). If you're not already running one check out Eclipse Mosquitto.

First make sure you've set up the Internal Multi-HUB properly as described at the top of this section.

We will now create a new interface for your MQTT broker (see previous section). As before you can create as many interfaces as you like for different MQTT brokers but please note that SEPIA will establish a permanent connection to each of these brokers at startup as long as the interface exists, even if it is not in use!

Here is an example for a broker using a TCP connection (WebSocket is possible as well) including username/password authentication:

Example interfaces for MQTT (TCP)

After you've created the interface you can edit your device card, select the interface and enter the MQTT Topic for your device into the field 'Int. Device Id'.
Important: The topic name can be anything you like but SEPIA devices will ALWAYS start with sepia/smart-devices/... and it might be useful to include at least device type and room as well. In return SEPIA will listen to ALL messages that belong to the 'sepia/smart-devices' topic even if you haven't created a device for a specific sub-topic yet. Here is an example device card:

Example device card for MQTT connections

First make sure you've set up the Internal Multi-HUB properly as described at the top of this section.

In Node-RED we need to add a connection to the same MQTT broker that we used in SEPIA. This can be done via the mqtt in node. Here is a configuration that fits to the previous example:

Node-RED example MQTT input node

As Topic we use the FULL path as described above and the output will be JSON object of the format: {"state": "..value.."}.

For testing purposes we can look at the output of the MQTT node by connecting a debug node. If we then send requests to SEPIA, for example: "Switch on the ceiling light in the living-room", we should be able to see the following output in Node-RED:

Node-RED debug node example

Now it is up to you to make use of this information and connect your Node-RED logic and events 😉

First make sure you've set up the Internal Multi-HUB properly as described at the top of this section.

To connect SEPIA to ioBroker it is required to install the Simple-API adapter for ioBroker first, since we will use the HTTP REST interface it creates. It is important to note that your ioBroker PORT and your Simple-API PORT will be different. Keep that in mind when you add the SEPIA interface (use the Simple-API port ;-) )

If your Simple-API adapter is up and running adding the interface is pretty straight forward (see previous sections). Here is an example that includes (optional) authentication via username/password (as defined by ioBroker):

Example interfaces for ioBroker Simple-API

Finding the correct 'Int. Device Id' for ioBroker can be a bit tricky sometimes ^^. In general you need to look out for writable states in the 'Objects' section. For a lamp this could be the 'level' entry for example:

How to find the 'internal device ID' in ioBroker

If you're having trouble finding the right entry feel free to post a question in the issues section and we'll look for it together ;-)

Here is the final result:

Example device card for ioBroker connections

You might have noticed that the example above shows an entry for the field 'Custom Config'. SEPIA has a generalized set of states for switching devices 'on', 'off' or setting a state like '70%' or '20°C' based on the device card field 'State type'. For HUBs like openHAB and FHEM these values will be converted into known state commands, but this might not always work since even devices of the same type sometimes require very different commands. In this case you can overwrite the default settings. Let's look at the example a bit more closely:

Example for the 'Custom Config' field

The default commands in SEPIA to enable (switch on/open/etc.) or disable (switch off/close/etc.) devices are "enable":"on" and "disable":"off", but in our specific ioBroker example this will not work. Our device only accepts numbers and interprets them as percentage. So we apply "Custom Config" to overwrite them using "100" (%) for on and "0" (%) for "off". Any values in between will simply be numbers as well "number":"<val>" e.g. for sentences like "Set the lights to 50%". <val> here simply means "value" as given by the user (e.g. 50). In some situations your devices may support more complex input values like "disco" for a special lamp or simply a channel name for your TV. If you need to handle these values you can use the field "raw" together with state type "raw text".

TODO: Add info

TODO: Add info

Example interface for Home Assistant

The Home Assistant interface requires certain additional information about devices to read the correct state and write data using the correct service or intent.

TODO: Add info

Example for the Home Assistant interface device configuration

TBD

Example intent, added to HA configuration.yaml file:

intent:

intent_script:
  SepiaDemoOn:
    action:
      service: persistent_notification.create
      data:
        message: "Hello from SEPIA demo intent ON!\nEntity: **{{ entity_id }}**"
  SepiaDemoSet:
    action:
      service: persistent_notification.create
      data:
        message: "Hello from SEPIA demo intent SET!\nEntity: **{{ entity_id }}**\nState: **{{ state }}**"
  SepiaDemoOff:
    action:
      service: persistent_notification.create
      data:
        message: "Hello from SEPIA demo intent OFF!\nEntity: **{{ entity_id }}**"

TODO: Add info

Here is the final result:

Example device card for Home Assistant connections

The first step to see if your devices are integrated properly should always be to use the "toggle" button on the top right corner of every device card in your SEPIA Control HUB. This button will try to switch between the states "enable" and "disable" which can mean "on/off" or "open/close" etc..

If everything worked out fine open your SEPIA client, log-in with your new smarthomeguest user and tell SEPIA something like Turn on the ceiling lights in the living room or set the heater in bathroom 2 to 21°C ... and wait for SEPIA's reply :-)