A getting started Guide to controlling

you home appliances with Alexa and

WisCore board

WISCORE

Naresh Krish
Table of Contents

Introduction: ......................................................................................................................................... 2
Pre-requisites: ....................................................................................................................................... 3
Hardware prerequisites .................................................................................................................. 3
Software Pre-requisites:................................................................................................................... 3
Setting up you switches ...................................................................................................................... 4
Notes: ............................................................................................................................................. 4
Downloading the firmware for the Relay board: ........................................................................ 5
Notes: ............................................................................................................................................. 6
Setting up MQTT for the relay module......................................................................................... 7
Notes: ............................................................................................................................................. 9
OpenHAB Setup: ........................................................................................................................ 10
What is OpenHAB?........................................................................................................................ 10
OpenHAB cloud integration and enabling mqtt ....................................................................... 10
Configuring Mqtt in OpenHAB2 ............................................................................................. 11
Adding items to control ............................................................................................................ 12
Showing Items on the UI........................................................................................................... 13
Notes: ........................................................................................................................................... 16
Setting up you WisCore to discover these devices:....................................................................... 18
Installing the Alexa Openhab Skill .............................................................................................. 18
Note: ............................................................................................................................................. 19
To enable a skill in the Alexa app: ............................................................................................... 19
Note: ............................................................................................................................................. 19
Connect The skill to OpenHAB .................................................................................................... 19
Discover your devices: .................................................................................................................. 20

1
Introduction:

This document outlines the steps involved in setting up your very own Alexa enabled home
automation using the wonderful WisCore AVS module from RAK Wireless. I was honored
to have been selected as part of the BETA team working on the initial prototype and I must
say, the module has a lot of potential.

What is defined in this document is a small sample of how to get your ESP8266 based relay
systems (Sonoff, Electrodragon switches etc) to connect to the cloud via the OpenHAB
project and be discoverable by Alexa on the WisCore board

I hope you like this write-up and would definitely want feedback on any future projects that
you may want me to do.

Regards,

Naresh Krish

Mail: k.naresh89@gmail.com

Twitter: @narioinc

2
Pre-requisites:
This project takes into consideration that you have a little bit of knowledge with the ESP8266
C based development and some complexities involved with working on cloud based home
automation services. But dont worry, I have outlined the complex step with some of the
difficulties I and others from the community have faced while setting up such a system. But
hey, its the struggle that keeps Makers going right ??

Hardware prerequisites
1) WisCore board with the latest firmware (firmware @
https://github.com/RAKWireless/WisCore/tree/master/img)
2) Raspberry pi 3 with the latest Jessie release
3) A ESP8266 based relay system like the Sonoff switches or switches from
Electrodragon. I will be concentrating on the switches from electrodragon which
have the Sonoff Tasmote firmware loaded onto them. For details on how to burn the
checkout the Tasmota wiki page here: https://github.com/arendst/Sonoff-
Tasmota/wiki

Software Pre-requisites:
I have been working on a windows based system but a Linux or a Mac system would also
do.

1) ATOM text editor with the Platform.IO plugin enabled: Instructions to install them is
here: http://platformio.org/get-started. Make sure that once installed you also
install the ESP8266 tool chain from the platform menu in Platform IO IDE UI as
explained here: http://docs.platformio.org/en/latest/platforms/espressif8266.html
2) Make sure that the software on the RPi3 is up to date with the latest kernel updates
as well. To setup wifi on the RPi3 and to connect to the web follow the instructions
here:
https://www.raspberrypi.org/documentation/configuration/wireless/wireless-
cli.md
3) The Sonoff or electrodragon switches do not have a wsb to serial interface built in I
used a FTDI bases interface for all my uploading needs. I will add a section in this
document on how to flash the firmware on such switches.

I will divide this document into three parts:

1) Setting up you switches using the tasmota firmware and setting up you preferred
mqtt settings.
2) Setting up OpenHAB on your RPi 3 and connecting the OpenHAB instance to the
cloud
3) Finally, setting up you WisCore to find the switches and control them via Alexa

So Lets Get Started..

3
Setting up you switches

As I cited before, I used the Electrodragon switches for this project. They are relatively
inexpensive and are of good quality.

The picture above shows the relay board and its ping configuration.

Notes:
1) BTN2 is your GPIO0 pin which you need to press before powering on the board to
enter firmware upgrade mode.
2) To connect the board to FTDI board please connect as shown below:
a. TX of board to RX of FTDI board
b. RX of board to TX of FTDI board
c. 5v of board to 5v of FTDI board
d. GND of board to the GND of the FTDI board

Connect the FTDI board to your computer via a USB2.0 port and windows 7 and above
should install the necessary drivers.

Once installed, Go to My Computer - > Device Manager and in The COM Ports section you
should see your board given a COM Port like so:

As you can see I get COM 3. Note this port down as it will be used for the upload.

4
Downloading the firmware for the Relay board:

I used the Sonoff Tasmota firmware as it the most recommended firmware for this device
providing lots of cool functions via a REST and an MQTT based interface. REST is a web
services paradigm aiming to provide a state-full interface to a service. MQTT is a lightweight
messaging protocol aimed at machine to machine communication.

Clone the repository @: https://github.com/arendst/Sonoff-Tasmota.git into your system at

convenient place.

Now open the Platform IO software and go to File -> Add Project folder and add the
recently downloaded git project root folder. This will show up on the Platform Io Software
like so:

Once loaded. Open the user_config.h file and edit these minimal sections:

#define STA_SSID1 "xxxx" // [Ssid1] Wifi SSID

#define STA_PASS1 "xxxx" // [Password1] Wifi password

#define STA_SSID2 "xxx" // [Ssid2] Optional alternate AP Wifi SSID

#define STA_PASS2 xxx

5
Where STA SSID1 and STA SSID2 are two wifi accesses point SSID names at your premises.
You can skip STA2 if you want. And STA-PASS1 and PASS2 are the passwords for the two
access points.

Now your ready to fire up the upload process. Click on PlatformIO - > Run Other Target
and you will see a small window. Scroll till you see the Option PIO Upload (sonoff)

Before clicking this options make sure you relay board in firmware flash mode. In the
electrodragon board, this is easy. Just press the BTN2 on the board while powering on to
enter firmware upgrade mode. For sonoff switches the process is defined here in detail:
https://github.com/arendst/Sonoff-Tasmota/wiki/Upload

Once you select the menu, the platformIO command line will trigger and upload to your
relay board and after 2-3 minutes your relay board should be ready and connected to your
STA-SSID1 AP with the correct password.

Notes:
1) If your relay board connects to your SSID you can check the IP of the board via apps
Like FING available on board Android and iOS app stores. Once you find the IP of
the board (They will come up as Espressif endpoints in the FING app), You can open
a webbrowser on your phone or on your desktop and go to the IP. It will show you a
screen like so:

6
 a.
2) Make sure you change the module type by going to Configuration -> Configure
module and select electrodragon relay if your board is the one I used. Else select
the appropriate sonoff module type.
3) If your module doesnt connect to the network, check the configuration of the SSID
and PWD and then flash the firmware again.

Setting up MQTT for the relay module

These relay modules have a very powerful MQTT based configuration option for controlling
the relays via simple MQTT messages. To setup MQTT please choose a suitable MQTT
broker. You can setup an MQTT broker on your RPi 3 by following the instruction
here:http://www.instructables.com/id/Installing-MQTT-BrokerMosquitto-on-Raspberry-
Pi/

Or you can use one of the public mqtt brokers list available here:

https://github.com/mqtt/mqtt.github.io/wiki/public_brokers

Once you determine you mqtt broker of choice, note down their IP/Hostname, the port
(usually its 1883) and any username or password required. Now with the IP of the relay

7
board in hand open the browser and open the relay configuration page as shown above and
go to Configuration - > Configure MQTT.

Here provide the following:

1) In the Host section, enter the hostname/IP of the broker

2) In the port, enter the MQTT broker port.
3) You can leave client ID as it is
4) If you have a username and password for accessing the mqtt broker, enter them in
the User and Password section./
5) Finally, provide a topic name for this board. Each board will listen to messages on
this topic and respond accordingly. For eg if topic is xxx then to turn on relay 1 on
the board you can send the message ON to the topic cmnd/xxx/POWER1. For
more details on the mqtt commands available checkout the Tasmota wiki here:
https://github.com/arendst/Sonoff-Tasmota/wiki/Commands

8
Once done click save. This will restart the device and you can again open the boards IP on a
browser. Try switching on the Toggle X switches on the web gui to here the relay click.

Notes:
1) Make sure that your able to see the board connect to an MQTT broker successfully
and is responding to your MQTT messages like cmnd/xxxx/POWER1 ON (where
xxx is the topic you give as explained before.)
2) If not connected, make sure the hostname of the mqtt broker and port are correct and
that the credentials you gave are also correct.
3) A good mqtt test app is the MyMQTT
https://play.google.com/store/apps/details?id=at.tripwire.mqtt.client&hl=en.
Using the app connect to the same broker as the relay board and send the test
command ON to the topic cmnd/xxxx/POWER1 and see if the relay responds
4) For connecting the relay board to mains here is a sample pic. ALWAYS BE
CAREFUL WHILE PLAYIGN WITH AC MAIN VOLTAGE AS THEY ARE FATAL
WHEN YOU COME IN DIRECT CONTACT. ALWAYS WORK UNDER ADULT
SUPERVISION AT ALL TIMES AND IF POSSIBLE A HAVE A TECHNICIAN DO
THE CONNECTION FOR YOU.

Courtesy: http://blog.kodeten.com/

With this your relay is setup. Now lets move on to OpenHAB.

9
OpenHAB Setup:

What is OpenHAB?
OpenHAB is software for integrating different home automation systems and technologies
into one single solution that allows over-arching automation rules and that offers uniform
user interfaces.

This means that OpenHAB

is designed to be absolutely vendor-neutral as well as hardware/protocol-agnostic

can run on any device that is capable of running a JVM (Linux, Mac, Windows)
lets you integrate an abundance of different home automation technologies into one
has a powerful rule engine to fulfill all your automation needs
comes with different web-based UIs as well as native UIs for iOS and Android
is fully open source
is maintained by a passionate and growing community
is easily extensible to integrate with new systems and devices
provides APIs for being integrated in other systems

One of the coolest things with OpenHAB is the Alexa integration. That is the meat of this
project.

TO get started with Open HAB just follow the instructions here:
http://docs.OpenHAB.org/installation/rasppi.html

The steps are fairly straightforward and will get you up and running in no time.

Once installed the OpenHAB portal should be available at the address

http://raspberrypi.local:8080

OpenHAB has a number of UI option ranging from BASIC UI, REST API to Paper UI. Paper
UI is coming up to be the defacto admin console for OpenHAB and we will be referring to it
often in the sections to follow.

OpenHAB cloud integration and enabling mqtt

Now, that you have OpenHAB, its time for your OpenHAB to talk to your switches via
Mqtt. According to the OpenHAB documentation, each device or Item is an entry in the
xxx.items file present inside the /etc/OpenHAB2/items folder on the raspberry pi. A typical
item entry will be

itemtype itemname ["labeltext"] [<iconname>] [(group1, group2, ...)]

[{bindingconfig}]

10
This line is self explanatory and more details about each part of the string is explained in
details @: https://github.com/OpenHAB/OpenHAB1-addons/wiki/Explanation-of-items

Configuring Mqtt in OpenHAB2

We are more interested in the item name and the binding config. Bindings are a way for
OpenHAB to connect to the item for sending commands. Binding can be HTTP, MQTT,
ZWAVE etc.

In our case we will install the mqtt binding in OpenHAB. Keep in mind that mqtt is
OpenHAB 1.x binding and once installed will not show up in the OpenHAB Paper UI.
Rather Mqtt will get its own conf file in /etc/OpenHAB2/services/ called mqtt.conf.

For example here is a sample mqtt.conf file:

# Define your MQTT broker connections here for use in the MQTT Binding or MQTT

# Persistence bundles. Replace <broker> with an ID you choose.

# URL to the MQTT broker, e.g. tcp://localhost:1883 or ssl://localhost:8883

ioteclipse.url=tcp://broker.hivemq.com:1883

# Optional. Client id (max 23 chars) to use when connecting to the broker.

# If not provided a default one is generated.

#ioteclipse.clientId=narekriOpenHAB2

# Optional. User id to authenticate with the broker.

#ioteclipse.user=xxxx

# Optional. Password to authenticate with the broker.

#ioteclipse.pwd=t-xxxx

# Optional. Set the quality of service level for sending messages to this broker.

# Possible values are 0 (Deliver at most once),1 (Deliver at least once) or 2

# (Deliver exactly once). Defaults to 0.

ioteclipse.qos=1

# Optional. True or false. Defines if the broker should retain the messages sent to

# it. Defaults to false.

11
#<broker>.retain=<retain>

# Optional. True or false. Defines if messages are published asynchronously or

# synchronously. Defaults to true.

#<broker>.async=<async>

# Optional. Defines the last will and testament that is sent when this client goes offline

# Format: topic:message:qos:retained <br/>

#<broker>.lwt=<last will definition>

You can use this .cfg file content as it is to connect you instance to a public broker as hivemq

Once you put this content in the mqtt.cfg file save it and restart the OpenHAB2 service but
typing:

$> Sudo service OpenHAB2 restart

This should restart the service and mqtt service should start along with OpenHAB.

Adding items to control

Now we need to add an item that will connect with this MQTT binding and let us control it
from the internet. To add an item to OpenHAB you have to create a xxx.items file in the
/etc/OpenHAB2/items folder. Xxx can be any name you give.

For example here is a sample switches.items file. Here the id of the switch is the second
string After the word Switch. So Switch1, Switch2, Switch3 are all ID. They will be used in
sitemaps so name them carefully and consistently.

/* Groups */

Group Lab_Switches "Lab Switches" [ "Lighting" ]

Switch Switch1 "Computer Lights" <light> [Lighting]

{mqtt=">[ioteclipse:cmnd/xxx/Power1:command:ON:1],>[ioteclipse:cmnd/n$

Switch Switch2 "Computer Fan" <light> [Switchable]

{mqtt=">[ioteclipse:cmnd/xxx/Power2:command:ON:1],>[ioteclipse:cmnd/na$

Switch Switch3 "Bedroom Lights" <light> [Lighting]

{mqtt=">[ioteclipse:cmnd/xxx/Power1:command:ON:1],>[ioteclipse:cmnd/n$

Switch Switch4 "Bedroom fan" <light> [Switchable]

{mqtt=">[ioteclipse:cmnd/xxx/Power2:command:ON:1],>[ioteclipse:cmnd/na$

12
Note here we have four items in a single file. You can create as many items inside a items file
and you can have as many items file in the /etc/OpenHAB2/items folder as you wish.
OpenHAB2 will load them dynamically.

In this items file few things are worth to note:

1) You need to give tags to the items. Tags means the words inside the [] brackets. Only
then will Alexa voice service be able to discover the device.
2) The name of the broker config..in this case ioteclipse should be the same as the name
you gave in the mqtt.cfg file a few steps back.
3) Remember we had talked about the topic cmnd/xxx/POWER1 to power a switch on
and off on the relay board. Thats the one that is being denoted in the file as the first
info in the binding section of the item string.

Exit this sample to make sure the xxx string is replaced by topic name you gave to you
relay board MQTT configure menu

Showing Items on the UI

Once done. You are ready to show this item to the UI. But wait, not so fast. UI in OpenHAB2
need a definition file called Sitemap. A Sitemap tells how to render a UI for an item. It is
very very easy to set a sitemap. Here is a sample sitemaps called default.sitemap file for the
switches I mentioned in the switches.items

sitemap default label="My Home"

Switch item=Switch1 label="Computer Lights"

Switch item=Switch2 label="Computer Fan"

Switch item=Switch3 label="Bedroom Lights"

Switch item=Switch4 label="Bedroom Fan"

Switch item=TestSwitch1 label="Kitchen Switch"

Switch item=TestSwitch2 label="Bathroom Switch"

Text item=Computer_Room_RSSI label="Computer room WiFi strength"

Text item=Bedroom1_Room_RSSI label="Bedroom One WiFi strength"

Text item=Bedroom1_Room_Humidity label="Bedroom One humidity"

Text item=Bedroom1_Room_Temperature label="Bedroom One temperature"

13
So here is a small breakdown of the sitemap file:

1) The first line if the display name for this sitemap. Here is it My Home.
2) Each line inside the label is a UI item corresponding to the Items ID specified in the
item=xxx parameter.
3) Label is the test that will be shown in the UI.
4) Make sure you set the sitemap you created as the default sitemap but going to
OpenHAB2 local website at raspberrypi.local:8080 -> click Basic Ui as shown below
an then click configure. In the Popup that comes up, make sure you give the same
sitemap file name you created for the section that says Default Sitemap

14
Once you have created a items file and a sitemap file. Restart the OpenHAB2 service again:

$> sudo service OpenHAB2 restart

Once it restarts. Go to the OpenHAB2 webpage but now instead of going to Paper UI, Go to
Basic UI. You should be able to see the Switched you create in the Items and Sitemap. Toggle
the switches. It should toggle the relay in your relay board.

15
Sample Items UI in Paper UI:

Sample Sitemap view in Basic UI:

Notes:
1) Sometimes the toggle switch may not control the relay board. In such cases make
sure that the OpenHAB2 MQTT binding is working properly by seeing the logs at
/var/log/OpenHAB2/OpenHAB2.log. The log should not show a connection failure
when invoking the mqtt binding. If all is well you should be able to send MQTT
messages successfully from the Toggle UI in OpenHAB2

16
Once this is done, Its time for WisCore to show its magic. But before that we need to setup
OpenHAB2 to connect itself to the cloud service called MyOpenHAB.org First we need to
install the MyOpenHAB cloud connector plugin and configure it as explained here:

http://docs.OpenHAB.org/addons/io/OpenHABcloud/readme.html

Once done. Login at myOpenHAB.org site with your credential. You should be able to see
you local OpenHAB2 instance now connected to the cloud myOpenHAB2.org site like so
below:

You can now click the link that says Click here to access your OpenHABs
dashboard to quickly access your OpenHAB setup on your raspberry pi in the cloud
via secure connection. Neat right???

17
Setting up you WisCore to discover these devices:

Now lets delve into the world of Amazon Alexa and setup your board to control your
home. As part of the setup, Make sure your WisCore board is on the latest firmware release.
The release firmware can be found here:
https://github.com/RAKWireless/WisCore/tree/master/release

Once updated and synced to the Amazon account using the WisCore app as explained here:
https://github.com/RAKWireless/WisCore/wiki/WisAvs Test your board by asking
Alexa a question and see if she responds.

Installing the Alexa OpenHAB Skill

Now comes the interesting part. The Alexa service support what Amazon calls Skills. Skills
extend the functionality of Alexa to take complex requests and process them. One such Skill
is the OpenHAB Skill in the Alexa Smart home index.

Items that you wish to expose to Alexa will need to be tagged to identify what type of device
Alexa will see them as. See http://docs.openhab.org/addons/io/homekit/readme.html1.3k
for more information. Lighting, switchable and thermostat tags are currently supported
(although not limited to those types of items). Thermostat control must use the Homekit
style grouping to associate temperature, mode and set point, see the Homekit binding
ReadMe above.

Some examples of tagged items are:

Switch KitchenLights "Kitchen Lights" <light> (gKitchen) [ "Lighting" ]

Dimmer BedroomLights "Bedroom Lights" <light> (gBedroom) [ "Lighting" ]

Group gDownstairsThermostat "Downstairs Thermostat" (gFF) ["Thermostat","Fahrenheit"]

Number DownstairsThermostatCurrentTemp "Downstairs Thermostat Current Temperature"

(gDownstairsThermostat) [ "CurrentTemperature" ]

Number DownstairsThermostatTargetTemperature "Downstairs Thermostat Target Temperature"

(gDownstairsThermostat) [ "TargetTemperature" ]

String DownstairsThermostatHeatingCoolingMode "Downstairs Thermostat Heating/Cooling Mode"

(gDownstairsThermostat) [ "homekit:HeatingCoolingMode" ]

18
You can search for and enable skills in the Alexa app or from the Alexa Skills store on the
website. To use an Alexa skill, first enable the skill, and then make your request based on the
example phrases shown in the app. If you know the exact name of the skill you want, you
can say, "Enable [skill name] skill." Some skills may require you to link to an existing
account and a separate subscription in order to use the skill.

Note:
For information about setting up or using a smart home skill, go to Connect a Smart Home
Device to Alexa.

To enable a skill in the Alexa app:

From the Menu, select Skills.

Use the search bar to enter keywords Openhab or select Categories to browse through
skill categories.

When you see the OpenHAB skill you want to use, select Enable Skill.

To enable skills from the Alexa Skills store on the website, go to

https://www.amazon.com/skills.

After you enable a skill, you can ask Alexa to open and use it. For example, say, "Open [skill
name]." There may be different or additional instructions for using the skill. You can refer to
the skill's detail page to learn more, or say, "[Skill name] help." When you no longer want to
use a skill say, "Disable [skill name] skill," or select Disable in the Alexa app.

Note:
Some skills may request access to your devices address or location. This access will be
requested during install, and can be approved/revoked at any time via the Manage Settings
button on the relevant skill's page on the Alexa app.

Connect the skill to OpenHAB

Once you get the OpenHab Skill, click on the button that requests access to the openhab API.

1) This will redirect you to the myopenhab.org account that you created in the first
section of this tutorial. Enter you credential.
2) The next page after login will ask you if you wish to give the OAUTH cred access to
the Alexa Skill. Click yes
3) Then you should see that Alexa is now a connected app in your openhab dashboard
like so:

19
Discover your devices:

Before ordering Alexa to discover your home devices, Make sure your able to see your items
in the myopenhab.org UI. It should look something likely this under the Items Tab:

If you go this far, Then AWESOMEEEEE. Let the Magic begin. Now Say the words with me

Alexa Discover Devices!!

And Alexa should respond that she has found n number of devices. Once she says that, tell
her to control a light with the Name you gave to the light in the items text file while
configuring Openhab on the raspberry Pi 3.

20
Resources and troubleshooting links:

1) Sonoff Module
a. https://github.com/arendst/Sonoff-Tasmota/wiki
b. https://github.com/arendst/Sonoff-Tasmota/wiki/Commands
c. https://nathan.chantrell.net/20160422/esp8266-relay-modules-from-itead-
and-electrodragon/
d. http://blog.kodeten.com/experimenting-with-a-new-gadget-electrodragons-
relay-board/
2) OpenHab2 resources
a. http://docs.openhab.org/installation/rasppi.html
b. http://docs.openhab.org/tutorials/beginner/uis.html
c. http://docs.openhab.org/tutorials/beginner/configuration.html
d. http://docs.openhab.org/tutorials/beginner/sitemap.html
e. https://community.openhab.org/t/amazon-echo-alexa-dont-find-any-
devices/23624
f. https://community.openhab.org/t/official-alexa-smart-home-skill-for-
openhab-2/23533?page=4
g. https://community.openhab.org/t/alexa-cant-find-any-devices-with-hue-
emulation/15527
3) WisCore
a. https://github.com/RAKWireless/WisCore/wiki
b. https://github.com/RAKWireless/WisCore/wiki/Access-serial-console
c. https://github.com/RAKWireless/WisCore/wiki/Burn-firmware-to-
MT762x-Board
d. https://github.com/RAKWireless/WisCore/wiki/Control-Gpio

Presented By:
Shenzhen Rakwireless Technology Co., Ltd. (RAK)
Room 1007, Hangsheng Technology Building, South Four Road,
Science and Technology Park, Nanshan District, Shenzhen
Zip Code: 518000
Email: ken.yu@rakwireless.com
TEL: 0755-86108311
Fax: 0755-86152201
Website: http://www.rakwireless.com/en/

21