Runnr App

Installation

Installation is extremely simple, just go throught the following instructions.

NPM install

npm install -g runnr-app will install Runnr App in your preferred global folder.

Usually this is under /usr/lib/node_modules.

Reverse Proxy (other port than 80)

If you wish to setup Google Assistant or IFTTT proxying you will need to expose your Runnr App to the internet.

We strongly advise you to use a server software (like nginx) and a reverseproxy, and get a domain name to set https. As a matter of fact, Runnr Servers will only perform requests on your webhook if they are https, if not an error will occur.

Nginx + NAT

A "normal" configuration will require you to enable NAT features on your home router or modem. Most modems/routers have a dedicated web interface where you can set this up (usually by the name Port Redirection). You may want to redirect ports 80 and 443 to your Runnr App instance (ie:Raspberry Pi).

On your Raspberry Pi you can then install nginx (apt-get update; apt-get install nginx) and configure it to listen on those ports and with a domain if you set that up (there a thousands of tutorials to set up DNS for domains and nginx configs, Google them ;)).

Ngrok

Another alternative is to use ngrok. Bear in mind that this cannot be considered a safe, secure, long-term solution.

ngrok is a tunneling service, that creates a tunnel between your local machine and a domain at *.ngrok.com.

To use ngrok on your machine please launch it by using

ngrok http -bind-tls=true localhost:PORT

You will then receive a ngrok URL that you can use on the administration iterface.

After setting up your https configuration, be sure to enter your IP or domain into your settings on the website.

Configure

Go to your installation folder and find the queries.dist.json and scripts.dist.json along with the config.dist.json. These are distribution files, hence the dist in their names.

You can just copy them using the following commands: cp queries.dist.json queries.json cp scripts.dist.json scripts.json cp config.dist.json config.json and edit them.

config.json

This file only contains one element, app_key. You can delete it or set an app key.

Be aware that setting an app key means using it for API calls and you must set it on the website if using Google Assistant or IFTTT Proxying.

queries.json

This file is used along with Google Assistatn proxying. Google Assistant takes input in the form of free text. It treats this text to understand what the user means and sends a request to Runnr servers.

Because of this, Runnr proxy can only send you text or an intent (more on that on the bottom) provided that you set up an agent via Dialogflow. You can use any NLP provider if you go through the default_handler and make the requests yourself.

Query

A query looks like the following

[{
    "id":"OPEN_DOOR_SCRIPT",
    "intent":"open_door",
    "script":"open_door.js"
}, {
    "id":"MAKE_COFFEE_SCRIPT",
    "intent": "make_coffee",
    "command":"python /home/pi/scripts/coffe_maker.py"
}, {
    "id":"SOME_SCRIPT_SCRIPT",
    "regex": "launch some script",
    "script": "some_script.js"
}, {
    "id":"WEIRD_COMMAND",
    "regex":[
        "execute weird command",
        "do super command",
        "have some fun"
    ],
    "command":"this would be | some command"
}, {
    "id":"MAKE_COFFEE",
    "regex":"coffee",
    "script": "make_coffee.js"
}]

Notice that every query in the array has a different configuration. Queries are defined by the following params

Name	Required	Description
id	true	The ID that will be used by the app + on the API
intent	false	Required if the script/command will be called upon arrival of given intent (case sensitive)
regex	false	(Array or String) Required if no intent expected (no Dialogflow integration), the app will try to find a match to
the message received via these RegExp
script	false	Required if a script must be launched from the scripts.json config file
command	false	Required if a command must be executed on request

Note that even though most properties are not required, a combination of them must be as the example.

A query script file is defined as:

// MUST export a function
module.exports = (message, entities) => {
    console.log('Message received', message);
    console.log('It contains', entities);
};

Queries scripts go into the queries folder.

scripts.json

This file tells Runnr App what scripts to load on boot and on request.

Script

A script looks like this

[{
    "id": "coffee-maker",
    "name": "Super Coffee Maker Script",
    "command": "php /home/pi/PHP/is/for_dummies/coffee_maker.php"
}, {
    "id": "laundry-maker",
    "name": "Super Laundry Maker Script",
    "file": "laundry_maker.js"
}]

Name	Required	Description
id	true	The ID that will be used by the app + on the API
file	false	The file to load (must be JS)
command	false	A command if the script must be launched from a command

A file script is defined as :

module.exports = () => {
    console.log('Whatever you want in here');
};

Normal Scripts go into the scripts folder.

API

An API is also available, that will allow you to create Rooms and Devices, and link them together:

                        ____________
                        |			|
 ___________	 _______|	Device1	|----- Script
|			|	/		|___________|
|	ROOM 	|---		____________
|___________|	\_______|			|
                        |	Device2 |----- Script
                        |___________|

This allows you to request the API to switch individual devices, or entire rooms. Note that this is hierarchichal:

• Turning OFF a room turns OFF all linked devices
• Turning ON a room turns ON all linked devices
• Switching a room switches all devices (from on to off and vice versa)

Devices : /api/devices

Rooms : /api/rooms

Scripts : /api/scripts

Commands : /api/commands