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

Prerequisites

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

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.

Step 1. Install base support packages

We've put these packages on separate lines for clarity. You may find you do not need all of them for your ultimate application.

apt update
apt upgrade
apt install build-essential
apt install libffi-dev
apt install zlib1g-dev
apt install libreadline-gplv2-dev
apt install libncursesw5-dev
apt install libsqlite3-dev
apt install tk-dev
apt install libgdbm-dev
apt install libc6-dev
apt install libbz2-dev

Step 2. Download and prepare Python 3.6 for installation

cd /usr/src
wget https://www.python.org/ftp/python/3.6.4/Python-3.6.4.tar.xz
tar xvf Python-3.6.4.tar.xz
cd Python-3.6.4

Install security headers.
apt install libssl-dev

You'll also need to make sure the setup routine can find your SSL headers.

  1. Open the setup routine for editing.
    vi setup.py
  2. Search for "ssl" and add in the highlighted include path as shown.
    # Detect SSL support for the socket module (via _ssl)
            search_for_ssl_incs_in = [
                          '/usr/local/ssl/include',
                          '/usr/include/openssl/',
                          '/usr/contrib/ssl/include/'
                         ]
  3. Save the changes and continue.

Step 3. Install Python 3.6

This procedure assumes you currently have only Python 2.7 installed (it is part of the ARTIK build configuration). If you have any other earlier 3.X versions of Python installed, you must remove them and upgrade to at least 3.5.3. Here we use 3.6.

Home Assistant requires Python 3.5.3 or later. The newer versions are not yet in the repo so you cannot use apt install python3 to install it.

Configure and compile Python 3.6.
./configure --enable-optimizations
make altinstall

Now type
python3.6
just to verify that you can run it without problems.

Use Ctrl-D to exit, and continue Python setup.
apt install python3-setuptools

Step 4. 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 the 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
    python3.6 -m venv .
    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]$

If you type
python -V
you can see that you are now using Python 3.6.

Step 5. Install Home Assistant

Install Home Assistant by typing:

pip3 install homeassistant

This command runs quickly as it only puts the basic program in place; it will finish the job during the initialization sequence below.

Step 6. Initialize Home Assistant

Have your ARTIK board and development PC both connected to the same router network. Make sure you know the IP address assigned to your ARTIK board, typically using eth0 or wlan0.

ifconfig

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 create the /.homeasssistant configuration directory in /home/homeassistant, install dependencies, and complete the installation.

    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.

During initial installation (or if you later make a change to the configuration files), hass installs new dependencies. The log screen could hang while the installation proceeds.

hass may time out for slow sites and fail to install on the first try. Pay close attention to the log information for problematic packages. If needed, install the packages separately and then re-run hass.

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 to the Python 3.6 virtual environment, type:

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

Whenever you need to leave the environment, 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 that gives you clues to whether devices were installed successfully.

To exit, type Ctrl-C and wait for the program to shut down gracefully.

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 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 HA (Home Automation) 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.

apt remove zigbeed

Home Assistant supports EZSP mode with XON-XOFF flow control to the NCP, so you will need to follow the NCP Update instructions to install a suitable image.

With an EZSP image loaded, you can no longer use libzigbee or ARTIK SDK ZigBee-based programs.

A710, A520, A1020: Use the A710 class .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.

A530: Use the A530 class .ebl file that has SWFC (software flow control) in the name. Note that the interface runs at a higher baud rate (see below).

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

zha:
  usb_path: /dev/ttyXXXX
  baudrate: BBBBBB
  database_path: /home/homeassistant/.homeassistant/zigbee.db

where:
XXXX is specified in the NCP port table for your module type
BBBBBB is 57600 except for A530, which is 115200.

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.

To test: Go back to the overview page, and look for your added device. Components such as temperature reporting devices may take some time to show their value.
To remove a device:
1. Under Domain select zha
2. Under Service select remove
3. For Service Data, put the MAC address in the format {"ieee_address":"ff:ff:ff:ff:ff:ff:ff:ff"}
4. Click CALL SERVICE
 

Troubleshooting ZigBee issues. Home Assistant installs the Python bellows program to communicate with the NCP using EZSP. Use the program from outside Home Assistant, but within the Python 3.6 virtual environment, to troubleshoot issues. For example, try the following command to return ZigBee configuration information from an ARTIK 530 board.

bellows -v DEBUG -b 115200 -d /dev/ttyAMA1 config --all

Use bellows by itself to get a list of available commands and options.

Z-Wave

If you plan to support Z-Wave devices:

  1. From outside the Python 3.6 virtual environment:
    1. Follow the Z-Wave article to install the correct drivers. Make sure you can run MinOZW and see your devices before proceeding.

    2. Set up the necessary links to the library by running
      ldconfig

    3. Manually fix references to openzwave header files.
      cd /usr/local/include/openzwave
      ln -s value_classes/* .
      ln -s platform/* .

    4. Install Cython packages.
      apt install cython3

  2. From within the Python 3.6 virtual environment:

    1. Install Cython.
      pip install Cython --install-option="--no-cython-compile"

    2. Install OpenZWave.
      pip install python_openzwave

    3. Check your installation.
      pyozw_check

    Note that each install may seem to hang – wait a few minutes before giving up.

  3. Configure Z-Wave operation. Add to the end of the configuration.yaml file :

    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-----
-----BEGIN CERTIFICATE-----
MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD
QTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT
MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB
CSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97
nh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt
43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P
T19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4
gdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO
BgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR
TLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw
DQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr
hMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg
06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF
PnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls
YSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk
CAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4=
-----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.

GPIO Multiplexer

A common HA use case involves retrofitting an existing home alarm sensor monitoring station to interface with the cloud. Many older homes that were wired for alarms still have the existing wiring in place, with contact sensors on each door and window.

For the cost of a single wireless sensor, you can monitor 30-40 existing hard-wired contacts. A multiplexing solution is convenient for bringing the signal states to the ARTIK module by way of USB. The "GP Wiz" is one example of such a device.

Preparation. Connect a piece of wire stripped on both ends to the ground screw-down terminal for testing. Leave the other end free for now. Plug the GP Wiz into the USB port on the ARTIK board and power up the board. Open a PuTTY terminal and access your ARTIK board.

Installation. You'll be installing the evdev package to manage the inputs.

apt get install evdev

Initial Test. You'll want to try out the device to make sure it is working. Run:

evtest

From the test output prompt, choose 1.

Touch the free end of the ground wire to one of the A-Z terminals and note the output of the available device /dev/input/event1

Note the EV_KEY code 709 is for button number 6 (shown as BTN_TRIGGER_HAPPY6).

Home Assistant Installation. Our example here will be used later with Automations to trigger a light on or off based on input from the GP Wiz multiplexer.

  1. Add this section to the configuration.yaml file.
    
    keyboard_remote:
    - device_descriptor: /dev/input/event1
      type: key_up
    
    
  2. Add permissions. homeassistant will require access to the device. Set permissions in the folder /dev/input/event1
    1. Go to
      cd /etc/udev/rules.d
    2. Use your editor to modify the input rules.
      sudo vi 99-userdev-input.rules
    3. Paste in this line, changing your username to, in this case, homeassistant

      KERNEL=="event*", SUBSYSTEM=="input", RUN+="/usr/bin/setfacl -m u:homeassistant:rw $env{DEVNAME}"

    4. Save and exit.
  3. Reboot the ARTIK board and remember to return to the virtual environment.

Before you launch Home Assistant, you can check the ACLs permission.
getfacl /dev/input/event*

Note that under user: it now is populated with homeassistant read write permission.

Use this at your own risk, as a keyboard would expose key strokes.

Proceed now to the GPIO multiplexer automations section to complete the setup.

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, where it can be evaluated by a Rule
  • Based on the Rule, send an Action to turn on/off a Z-Wave relay controlling a fan.

You'll find the 'Automation' selection on the Configuration page. You can use its script generation facility, or you can edit the automations.yaml file directly. We'll show you both ways in the examples below.

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

Once a device is recognized and incorporated, Home Assistant can handle it in a particularly generic manner that makes automation a breeze. Here we'll set up a ZigBee door contact sensor to control a Z-Wave heavy-duty contactor/relay.

For this trivial example, you can edit the ~/.homeassistant/automations.yaml file directly. The first automation takes off-to-on input from the door contact sensor as its trigger, and turns on the relay as its action. The second one does the opposite.

Note that the service for the action is simply homeassistant.turn_on or _off, and does not need to specify zwave – Home Assistant takes care of abstracting devices on the Z-Wave and ZigBee networks, so you only need to specify the entity_id.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
- alias: Turn off
  trigger:
    platform: state
    entity_id: binary_sensor.centralite_3320l_057d30ec_1
    to: 'on'
  action:
    service: homeassistant.turn_on
    entity_id: switch.intermatic_unknown_type4341_id3750_switch

- alias: Turn on
  trigger:
    platform: state
    entity_id: binary_sensor.centralite_3320l_057d30ec_1
    to: 'off'
  action:
    service: homeassistant.turn_off
    entity_id: switch.intermatic_unknown_type4341_id3750_switch

Publishing to ARTIK Cloud

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 so we end up with:

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

where you replace Entity_ID with the entity value from the Tools States page. 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 automations.yaml file created by the actions editor (or manually created by you) would look like this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- action:
  - data:
      payload_template: '{"refOpen": {% if is_state(''binary_sensor.centralite_3320l_0bbe2747_1'',''on'') %} false  {% else %} true {% endif %} }'
      topic: /v1.1/messages/_your_DEVICE_ID_here_
    service: mqtt.publish
  alias: Contact sensor
  id: '1501541144629'
  trigger:
  - entity_id: binary_sensor.centralite_3320l_0bbe2747_1
    from: 'on'
    platform: state
    to: 'off'
  - entity_id: binary_sensor.centralite_3320l_0bbe2747_1
    from: 'off'
    platform: state
    to: 'on'

Actions from ARTIK Cloud

An Action from ARTIK Cloud is not the same as an action in Home Assistant, although the concepts are similar.

To act on an Action sent by ARTIK Cloud, you must define an automation in Home Assistant. You might generate an immediate Home Assistant action, or you might just store the received data from ARTIK Cloud for later use.

Controlling GPIO output pins

Controlling pins through the sysfs interface is a very accessible way to do it in Linux, even if it's a bit clunky.

We'll provide this information based on the blue LED of the ARTIK 530 or 710 development board; you'll need to fill in your own GPIO numbers for other pins and boards. First off, go to the GPIO LED tutorial and make sure you are able to manually turn the blue LED on and off.

To make this happen under Home Assistant will be a little more difficult – it operates within a virtual environment that does not, by default, have write privileges to the GPIO pins. You'll need to fix that on a per-pin basis.

One-time operation. Create a new group, which we'll call gpio, that we'll eventually give special permissions to. This is similar to what you did in step 4.3, except you're creating a new group instead of using an existing one (dialout in that case).

groupadd gpio
usermod -a -G gpio homeassistant

Outside virtual environment. Before entering the virtual environment, you'll need to create the pin and set its direction as output. You can do this manually or through a startup script, but it needs to happen after every board reset.

  1. Pick the pin you want to use, and export it. Here we'll follow the original example and use GPIO 38 (controlling the blue LED).
    echo 38 > /sys/class/gpio/export

  2. Configure the GPIO pin to be an output. Note that this "subdirectory" didn't exist until you exported the pin, and will exist only until the next reboot.
    echo out > /sys/class/gpio/gpio38/direction

  3. Assign your new group to refer the GPIO pin you are planning to use.
    chown -R root:gpio /sys/class/gpio/gpio38/value
    chmod -R ug+rw /sys/class/gpio/gpio38/value

Repeat these steps for each of the GPIO pins you plan to control from within Home Assistant.

Within virtual environment. You've done all the hard work ahead of time. Now, after entering the virtual environment, you need to call shell commands from Home Assistant to turn the GPIO pin on and off.

Before you actually run hass, let's do a quick check within the virtual environment to ensure you have access to the pin control.
echo 1 > /sys/class/gpio/gpio38/value

If you can turn the LED on and off, then so can Home Assistant.

You'll put these command definitions in your configuration.yaml file. Put them at the bottom of the file or at least outside of other sections.

shell_command:
  turn_on_led: 'echo 1 > /sys/class/gpio/gpio38/value'
  turn_off_led: 'echo 0 > /sys/class/gpio/gpio38/value'

Feel free to change the service names to something meaningful for your application.

Now, anywhere in your automations.yaml file that you need to change the GPIO as the result of some trigger, just put in a line like this.

  - action:
      - service: shell_command.turn_on_led

Note that the first line of a group starts with the "dash" (–) but not the second one. Just try to follow the format of the existing automations.

Before starting the program, do a sanity check on your .yaml files. It's almost certain that Home Assistant will find something for you to fix.

hass --script check_config

Miscellaneous hints. If it gets confusing figuring out what groups you have assigned, use these commands to help.

Find out what groups homeassistant currently has access to.
groups homeassistant

Find out the name of all groups on the system.
getent group

Actions from GPIO Multiplexer

This automation uses inputs from the "GP Wiz" device you installed here.

To the automations.yaml file, add a section for every input button you want to utilize. In this example, we're using one input to turn the light on and another to turn it off.


- id: 'button709'
  alias: 709 Tripped
  trigger:
    platform: event
    event_type: keyboard_remote_command_received
    event_data:
      device_descriptor: /dev/input/event1
      key_code: 709    # inspect log to obtain desired keycode
  action:
    service: switch.turn_on
    entity_id: switch.aeotec_micro_switch_2nd_edition_switch_3

- id: 'button708'
  alias: 708 Tripped
  trigger:
    platform: event
    event_type: keyboard_remote_command_received
    event_data:
      device_descriptor: /dev/input/event1
      key_code: 708 
  action:
    service: switch.turn_off
    entity_id: switch.aeotec_micro_switch_2nd_edition_switch_3

Copy and paste the above code over and over for each input, changing the fields in green to correspond to the buttons on the GP Wiz and whichever device you wish to trigger in the action.

Now type hass to launch Home Assistant and view your buttons. The log file clearly posts all the actions, and the response of the device is instantaneous.

From the Home Assistant console, you can readily see the state of the inputs.

Last updated on: