[HC2/HCL] Creating Virtual Devices

HTTP (string) method of creating Virtual Devices

Introduction

Virtual devices can use LUA coding or HTTP (string) method for interacting with smart devices in your local network. It is worth mentioning that LUA language is available only on Fibaro Home Center 2, so Virtual Devices build in LUA will not work on Home Center Lite.
In this short description we are focusuing on creating universal Virtual Device build on HTTP communication method with use of Firebug add-on to Mozilla Firefox. In this way, we can find all commands send by web browser to other devices for Audio-Video Systems, Cameras and so on.
 

Requirements

• Home Center Lite or Home Center 2 gateway,
• Mozilla Firefox browser,
• Firefox add-on – Firebug – https://addons.mozilla.org/pl/firefox/addon/firebug/.

User interface of Virtual Device

1. If we have all required to create our first Virtual Device, start with logging in to our Fibaro gateway as a Super User.
2. Click on the “Devices” tab in top panel and then on “Add or remove device” button in left sidebar.
3. We will see a menu from which we can add the Virtual Device or upload it the file. Click on “Add” button in Virtual Device section.
4. New device window will appear as it is shown below.



Description of menu:
• Name: the name of the Virtual Device
• Room: room to which Virtual Device will be assigned
• IP Address: Internet Protocol address of host device
• TCP Port: Transmission Control Protocol of host device

5. Next click on “Advanced” tab to see window below.

In advanced options, we can choose a set of buttons which will be visible as our Virtual Device. After we marked boxes of buttons, click on “Save” icon on the right side.
Few features of user interface:

• We can move up and down each set of buttons and at any time add next one.
• Each click on button will trigger compilation of code which is assigned to it.
• Name of each button can be change at any time.
• We can change icon for each button, which will be visible in the interface of VD.

After setting proper composition of the buttons please add proper setting for specific buttons. Each button can be configured separately. Moreover, each button can be configured with following settings:

• Button Label – dynamic text-based message. Can be used as dynamic feedback with devices states or any other network based text content.

• Button – Each button can be used as a trigger of the scene or as a trigger of sending the string command.

• Slider – can be used for dynamic changing of parameters.

• Label – defines description of the specific button (e.g., ON, OFF). That text will be visible in the interface of VD.

• ID – defines unique ID for using in LUA scenes or Block Scenes.


• Empty – allows to hide particular button.


• Main – particular button will be visible in the Your house tab.

• Main loop – as description says, any code written here will be executed continuously in a loop. Worth mentioning is command – fibaro:sleep which terminates main loop code execution. Variables that are defined in main loop cannot be reused in the buttons.

• Debug – option on Main loop or Button to execute code.

• Change Icon – option of uploading own icon which will be visible after you press this button. An icon must be 128×128 pixels, with transparent background.

Creating code behind User Interface

We know how to set buttons in our Virtual Device so now it is time to write code for each button. Start with opening web browser with Firebug add-on and log as a Super User in our Fibaro gateway. Thanks to Firebug we will be able to see what commands are send by the controller, then we will just copy them and paste into our code for Virtual Devices.

1. Icon of Firebug is placed in the right top corner. Click it to start.



2. To find out which commands are send by controller, open the “Console” tab, then “Persist” and “All”. Also remember to clean console from unwanted data by clicking on “Clear” button.



3. Now we have everything settled to generate code for our Virtual Device. As a first example, we want to see what code is send after we click “ON” in the interface of Fibaro Wall Plug. Click “Clear” in Firebug console before clicking Fibaro Wall Plug to clear unwanted information.



4. After turning Fibaro Wall Plug on through the web interface, we see few commands appear on console of Firebug. It is easy to find appropriate code. Point your mouse at the line and use right click to copy. Then you can paste it anywhere. In our case command is: http://10.1.6.210/api/devices/1513/action/turnOn



5. Before going to the next step, it is wise to check if the command sends any additional arguments. To do so, a drop-down list should open after you click one the command line. If in “Post” command under “Source” appears “{“args”:[]}” then there are no arguments to send. Otherwise, everything under “Source” should be also copied.



6. We have already main command send to turn on our Wall Plug. Now it is time to create code which will be triggered by clicking on our Virtual Device. In this case we will have only one button in our Virtual Device. After we set that one button, in advanced options we should see window as below.



Description of labels:
• Label: name of a button; will be shown on a button 

• ID: programming name for the created button; default ID will appear after making button 

• String to send: a box where we write the code 

• String/LUA code: option of changing programming language

7. Now we will create a body of code. Fibaro Home Center understands string code send by certain pattern.

First part of the code should include one of three operations:
• GET: usually used to take device status/values
• PUT: used to modify values
• POST: used to change state/create new data

Next, we will have IP address for host to which command will be send. In our case it will be IP address of gateway.

Last part is authorization of credentials, which in this case will be login and password encoded in base64 code. To properly convert Super User login and password details to string we should use proper encoder: http://www.motobit.com/util/base64/encoder.

The example below shows how “login: admin, password: admin” is converted to string after using “Convert the source data” option.



An output (YWRtaW46YWRtaW4NCg==) should be pasted after “Basic” command in the Virtual Device.

As a summary, pattern of code in this case should look as below:
Command (GET, PUT, POST) command address without IP address HTTP/1.1
Host: IP address of Home Center

Authorization: Basic your Super User credentials login:password converted to string (see below) empty line
optional parameters to send

8. According to pattern our code and general window should look like below. Please notice that if send any commands to Fibaro API, IP address and Port should have numbers as below. If you make Virtual Device for other device, then IP Address should have number of that device in LAN network. Same with TCP Port.





After saving the changes (save button on right panel) we can test the Virtual Device. If everything works properly, the Virtual Device should send exact commands as those send by use of web browser interface. Also, now it can be used as an actor in block scenes on Home Center.

Tips for using LUA language in Virtual Devices

Introduction

This guide is dedicated for writing Virtual Devices using LUA Scripts. Please keep in mind that this kind of Virtual Devices is limited to Fibaro Home Center 2 (will not work with Fibaro Home Center Lite).
With LUA programming language you can build advanced algorithms for your integrations. More info about LUA you can find at http://developer.fibaro.com.

Requirements

• Home Center 2 gateway,

Code writing

Within begin to this section you will be guided through some basics of LUA and using it with Virtual Devices.
 
• Pressing button of Virtual Device in Scenes

fibaro:call(10, "pressButton",1)

10 – Virtual Device ID
1 – button of Virtual Device ID
 
• Executing requests

In the advanced options of a Virtual Device you can define an IP address and Port of device in LAN network to which commands will be send. By placing below code in a main loop, Button or Label, you can refer to that defined IP address and Port.

local device = fibaro:getSelfId();
local ipaddress = fibaro:getValue(device, "IPAddress");
local port = fibaro:getValue(device, "TCPPort");
FIBARO = Net.FHttp(ipaddress, port)


If we have above code as a header, we can now POST, GET, PUT by using FIBARO command which have already defined IP and Port of Host. So for example the code for sending command to host will look like below:

response = FIBARO:GET(setPower?power=on),
 
• Showing log

fibaro:log('Standby')

This command will show message ‘Main Standby’ on Virtual Device icon when defined button was triggered
 
• Displaying a text value in a VD label

fibaro:call(selfId, "setProperty", "ui.label1.value", "Standby")

This command will show “Standby” value on label1