Filter results by

Home Assistant

For tying together of all the various wireless IoT technologies, you may want to look into Home Assistant. Running on Python from your ARTIK board, it serves a "master control" Web page covering these and other interfaces:

  • ZigBee HA (zha)
  • Z-Wave
  • Wi-Fi (including HTTP, MQTT, CoAP)
  • Bluetooth

You can then use its Automations feature to allow devices from different networks and technologies to control and monitor each other.

Here we provide instructions for installation on any ARTIK Linux-based system using Fedora 24.

Prerequisites

Have your ARTIK board and development PC both connected to the same Wi-Fi network.

Installation

Home Assistant is a Python-based solution. It runs on a specific Python version that is not the same as the one used by ARTIK modules. You cannot upgrade/downgrade to get them to match, as doing so would negatively impact other Python-based tools.

Therefore, in this procedure you'll be installing Home Assistant within a virtual environment where it can use the version of Python it expects to see. You'll install each related software package in the homeassistant virtual environment.

One-Time Setup

Pay close attention to the installation messages to make sure that the packages are actually getting installed. Time-out conditions can cause installation failure requiring one or more retries.

Install base support packages

dnf -y update
dnf install redhat-rpm-config python-devel python3-devel

Set up user account for virtual environment

Home Assistant cannot run in root because it needs a specific version of Python. It will not work right if you don't set up and run it from a user account as directed below.

  1. Add an account called homeassistant. Since this account is only for running Home Assistant, add the extra arguments of -rm to create a system account and a home directory.

    useradd -rm homeassistant

  2. Make a directory for the installation of Home Assistant and change the owner to the homeassistant account.

    cd /srv
    mkdir homeassistant
    chown homeassistant:homeassistant homeassistant

  3. Make USB and serial ports used to access things like the Z-Wave modem and the ZigBee NCP accessible by this new group.

    usermod -a -G dialout homeassistant

  4. Change to the homeassistant account and set up the virtual Python environment there.

    cd /srv/homeassistant
    su -s /bin/bash homeassistant
    pyvenv-3.5 .
    source bin/activate

Once you have activated the virtual environment, you will notice the prompt change, indicating that you are in the correct account.

(homeassistant) [homeassistant@localhost homeassistant]$

Install Home Assistant

Install Home Assistant by typing:

pip3 install homeassistant
pip install sqlalchemy

If you see an upgrade message type
pip install --upgrade pip

Initialize Home Assistant

Have your ARTIK board and development PC both connected to the same Wi-Fi network. Make sure you know the Wi-Fi IP address assigned to your ARTIK board:

ifconfig wlan0

On your development PC, open a browser to:

http://<ip-address>:8123

You'll need to let Home Assistant initialize itself.

  1. Enter the virtual environment.

    cd /srv/homeassistant
    su -s /bin/bash homeassistant
    source bin/activate

  2. Run this script, which will report an error because initialization has not yet taken place. However, it will also make error logs more colorful in the next step.

    hass --script check_config

  3. Now run the program. The first time you run it, Home Assistant will complete the installation, create the .homeasssistant configuration directory in /home/homeassistant, and will install any dependencies.

    hass

    If there were no blocking issues, you should see the Welcome Home! screen appear in your browser.

  4. Once it stops installing, exit with Ctrl-C.

Running Home Assistant

You must always launch hass from within the virtual environment. If you are there the prompt will look like this:

(homeassistant) [homeassistant@localhost homeassistant]$

To get there, type:

cd /srv/homeassistant
su -s /bin/bash homeassistant
source bin/activate

Whenever you need to leave, type exit.

To start the program once you are in the virtual environment, enter:

hass

You will see lots of information on the terminal emulator screen during load.

If you make a change to the configuration files that causes hass to install new dependencies, the log screen could hang while the installation proceeds. Be patient, or install the noted package before calling hass.

Adding Technologies

Adding new IoT technology support to Home Assistant is surprisingly easy. While it requires manual additions to the configuration file, once the keywords are detected, driver discovery and installation happen with little intervention.

You'll be editing the configuration.yaml file in the Home Assistant environment. You must enter that environment (as explained earlier) before doing this, or you will be editing the wrong copy of the file.

cd /home/homeassistant/.homeassistant

vi .homeassistant/configuration.yaml

Make sure your indents are correct, or Python will not interpret them correctly.

After exiting the editor, use this command to verify your changes.
hass --script check_config

Refer to the relevant instructions below for adding each type of functionality.

Troubleshooting Tip: If you add a new technology and hass hangs during load, there is likely a problem with the communications to the modem device or NCP. Review the technology installation steps carefully.

ZigBee

Home Assistant does a good job recognizing many common ZigBee devices.

Daemon. If you plan to support ZigBee devices under Home Assistant, you will need to disable zigbee-daemon used by the ARTIK API as the two cannot share the same resource.

systemctl disable zigbee-daemon

Note that Home Assistant supports only the XON-XOFF flow control method to the NCP at this time, so you will need to follow the NCP Update instructions to install the correct image. Use the .ebl file that has xon-xoff in the name. It is specified for the ARTIK 710, but also works on the ARTIK 520 and 1020.

No xon-xoff NCP image is available for the ARTIK 530 at this time.

To configure ZigBee operation, add to the end of the configuration.yaml file :

1
2
3
zha:
  usb_path: /dev/ttyXXXX
  database_path: zigbee.db

where XXXX is specified in the NCP port table for your module type.

Adding a new device. ZigBee uses "permit join" on the Coordinator to allow adding of new devices to the network.



1. In Home Assistant, click this icon
2. Under Domain select zha
3. Under Service select permit
4. Click CALL SERVICE

You are now in Permit Join mode, and can join a ZigBee Device to the network in the usual manner. Make sure you have commanded the device to network leave any previous networks so that it can join the new one.

Z-Wave

If you plan to support Z-Wave devices:

  1. Follow the Z-Wave article to install the correct drivers. (Do this from outside the Python virtual environment.) Make sure you can run MinOZW and see your devices before proceeding.

  2. Within the virtual environment, you'll want to run
    pip install python_openzwave==0.4.0.31
    Note that this install may take a very long time to complete.

  3. After that installation, follow the instructions below.

To configure Z-Wave operation, add to the end of the configuration.yaml file :

1
2
zwave:
  usb_path: /dev/ttyACM0

where you need to replace ACM0 with the USB port where your Z-Stick will be inserted. If in doubt, do
ls /dev/tty*
and identify the device that appears/disappears when you plug/unplug the Z-Stick.

Subscribe with MQTT

You'll need to set up an MQTT broker, as described in the ARTIK MQTT Broker article. You can instead use the broker internal to Home Assistant.

To configure MQTT operation, add to the end of the configuration.yaml file :

1
2
3
4
5
6
7
8
mqtt:
  broker: (broker_address) 
  (leave this line off if you want to use HA's internal mqtt broker)

device_tracker:
  - platform: mqtt
    devices:
      (friendly_name): /(topic_name)

For example:

1
2
3
4
5
6
7
8
mqtt:
  broker: 10.0.0.13


device_tracker:
  - platform: mqtt
    devices:
      whoknows: /artik
To test, just set up a publisher and send a message. Device Tracker will
capture messages published to the topic of /artik and will show
the messages with the other icons.

Publish to ARTIK Cloud with MQTT

You'll probably want to be able to send the data from other devices to ARTIK Cloud. Publishing it over MQTT is the simplest approach.

To configure Home Assistant operation with ARTIK Cloud over MQTT, add this MQTT section to the configuration.yaml file :

1
2
3
4
5
6
mqtt:
  broker: api.artik.cloud
  username: _your_DEVICE_ID_here_
  password: _your_DEVICE_TOKEN_here_
  port: 8883
  certificate: /home/artikcloud.crt

For the artikcloud.crt certificate, use the following. Make sure you are saving it in the homeassistant environment home directory, not the root directory.

Certificate

-----BEGIN CERTIFICATE-----
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
uW7KrUwGg+cPXREDasEb
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFODCCBCCgAwIBAgIQUT+5dDhwtzRAQY0wkwaZ/zANBgkqhkiG9w0BAQsFADCB
yjELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL
ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJp
U2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxW
ZXJpU2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0
aG9yaXR5IC0gRzUwHhcNMTMxMDMxMDAwMDAwWhcNMjMxMDMwMjM1OTU5WjB+MQsw
CQYDVQQGEwJVUzEdMBsGA1UEChMUU3ltYW50ZWMgQ29ycG9yYXRpb24xHzAdBgNV
BAsTFlN5bWFudGVjIFRydXN0IE5ldHdvcmsxLzAtBgNVBAMTJlN5bWFudGVjIENs
YXNzIDMgU2VjdXJlIFNlcnZlciBDQSAtIEc0MIIBIjANBgkqhkiG9w0BAQEFAAOC
AQ8AMIIBCgKCAQEAstgFyhx0LbUXVjnFSlIJluhL2AzxaJ+aQihiw6UwU35VEYJb
A3oNL+F5BMm0lncZgQGUWfm893qZJ4Itt4PdWid/sgN6nFMl6UgfRk/InSn4vnlW
9vf92Tpo2otLgjNBEsPIPMzWlnqEIRoiBAMnF4scaGGTDw5RgDMdtLXO637QYqzu
s3sBdO9pNevK1T2p7peYyo2qRA4lmUoVlqTObQJUHypqJuIGOmNIrLRM0XWTUP8T
L9ba4cYY9Z/JJV3zADreJk20KQnNDz0jbxZKgRb78oMQw7jW2FUyPfG9D72MUpVK
Fpd6UiFjdS8W+cRmvvW1Cdj/JwDNRHxvSz+w9wIDAQABo4IBYzCCAV8wEgYDVR0T
AQH/BAgwBgEB/wIBADAwBgNVHR8EKTAnMCWgI6Ahhh9odHRwOi8vczEuc3ltY2Iu
Y29tL3BjYTMtZzUuY3JsMA4GA1UdDwEB/wQEAwIBBjAvBggrBgEFBQcBAQQjMCEw
HwYIKwYBBQUHMAGGE2h0dHA6Ly9zMi5zeW1jYi5jb20wawYDVR0gBGQwYjBgBgpg
hkgBhvhFAQc2MFIwJgYIKwYBBQUHAgEWGmh0dHA6Ly93d3cuc3ltYXV0aC5jb20v
Y3BzMCgGCCsGAQUFBwICMBwaGmh0dHA6Ly93d3cuc3ltYXV0aC5jb20vcnBhMCkG
A1UdEQQiMCCkHjAcMRowGAYDVQQDExFTeW1hbnRlY1BLSS0xLTUzNDAdBgNVHQ4E
FgQUX2DPYZBV34RDFIpgKrL1evRDGO8wHwYDVR0jBBgwFoAUf9Nlp8Ld7LvwMAnz
Qzn6Aq8zMTMwDQYJKoZIhvcNAQELBQADggEBAF6UVkndji1l9cE2UbYD49qecxny
H1mrWH5sJgUs+oHXXCMXIiw3k/eG7IXmsKP9H+IyqEVv4dn7ua/ScKAyQmW/hP4W
Ko8/xabWo5N9Q+l0IZE1KPRj6S7t9/Vcf0uatSDpCr3gRRAMFJSaXaXjS5HoJJtG
QGX0InLNmfiIEfXzf+YzguaoxX7+0AjiJVgIcWjmzaLmFN5OUiQt/eV5E1PnXi8t
TRttQBVSK/eHiXgSgW7ZTaoteNTCLD0IX4eRnh8OsN4wUmSGiaqdZpwOdgyA8nTY
Kvi4Os7X1g8RvmurFPW9QaAiY4nxug9vKWNmLT+sjHLF+8fk1A/yO0+MKcc=
-----END CERTIFICATE-----

Publishing Data. Once you are in Home Assistant, you can publish a test message using Developer Tools – Services.

ARTIK Cloud depends on a "manifest" describing the data types it can expect for each device. In our Publish to ARTIK Cloud tutorial, we show you how to set up such a manifest. Done? Run a test using Home Assistant to update the insTemp value.


1. In Home Assistant,
click this icon
2. Under Domain select mqtt
3. Under Service select publish
4. Under Service Data,
cut and paste in
{
  "topic": "/v1.1/messages/_your_DEVICE_ID_here_",
  "payload": "{\"insTemp\": 19.3}"
}
5. Replace _your_DEVICE_ID_here_ with your own Device ID
(your ARTIK Cloud username in the configuration.yaml file)
6. Click CALL SERVICE

On your my.artik.cloud/data page, you'll see the insTemp data come through as always.

Automation

With Home Assistant, you'll be able to easily create automation associations that tie 'data in' from one technology to 'data out' of another. For example:

  • Receive temperature from a ZigBee sensor
  • Send the temperature to ARTIK Cloud

Setting Triggers. Any of the input devices you see can be used as Triggers for your automation. You can trigger on things like

  • exact match (state)
  • range (numeric_state)
  • formula (event)

You can also set multiple Triggers, such as one for on-to-off transitions and another for off-to-on transitions.



1. In Home Assistant, click this icon (Tools "States" page)
2. Scroll down to an entity you installed, and click on it binary_sensor.centralite_3320l_0bbe2747_1
3. Copy the entity name from where it populates at the top  
4. Go to the Automations page and click +
5. Paste the Entity ID in the Trigger binary_sensor.centralite_3320l_0bbe2747_1
5. Set other parameters as necessary Name – Trigger Type – From – To – Above – Below

Setting Actions. Now it's time to associate Actions with the Triggers. Here, the procedure becomes more technology-specific. Go to the section below to specify the device that will receive the Action.

The Automations facility is relatively new and is still working through issues. One to note: It can be difficult to get an Action section set up. If it becomes unresponsive, delete the Action, Save, and add a new one.

Actions involving ZigBee

Data from ZigBee devices is recoverable using Templates.

{{states.Entity_ID.state.name}} – the device friendly name
{{states.Entity_ID.state.state}} – the status or measurement being returned

where Entity_ID can be found in the Tools - States table. Refer to the Templates page in Home Assistant for a good illustration of the concept – make sure you have some ZigBee reporting devices connected so you can see the output!

Actions involving Z-Wave

TBD

Publishing to ARTIK Cloud

Note that Actions from Home Assistant are not the same as Actions ARTIK

Setting Simple Action. This part may look familiar to you. It's basically the same information that you used here to test the MQTT connection to ARTIK Cloud.

1. Scroll to the Actions section If not already open, click ADD ACTION
2. Under Action Type, select Call Service
3. Under Service, type mqtt.publish
4. Under Service Data, cut and paste in (editing DEVICE_ID) {
  "topic": "/v1.1/messages/_your_DEVICE_ID_here_",
  "payload": "{\"insTemp\": 19.3}"
}
5. Click the Save icon.

Setting Action by Template. To dynamically create the payload based on the current state or sensed value of another device, you'll send

payload_template

and use a template that can be evaluated in the scripting language used by Home Assistant.

For example, let's send the status (on or off) of the contact sensor from the Trigger example we used above. According to the manifest we set up in ARTIK Cloud, refOpen is expecting a Boolean value of true or false

{% if is_state('Entity_ID', 'on') %} false {% else %} true {% endif %}

where you replace Entity_ID with the entity value from the Tools States page.

Note that you choose the association to meet your needs; in the case of our sensor, it's on when the contact sensor door is open, which we've associated with false.

In our example the Service Data might look like this.

{
  "payload_template": "{\"refOpen\":  {% if is_state('binary_sensor.centralite_3320l_0bbe2747_1', 'on') %} false  {% else %} true {% endif %} }",
  "topic": "/v1.1/messages/1592840934852342340b9b"
}
Last updated on: