1. Installing Virtual Devices

1.1 Download the repository

In order to use the virtual devices, you need to deploy the Virtual Devices software on the side of the emoncms.

1.2 Setting up the virtual devices database

copy the Virtual Devices repository to the top of your web application folder together with the emoncms, for example /var/www, so that the code would be on /var/www/virtualDevices and the emoncms on /var/www/emoncms
create the virtual devices database (called trials) and give privileges to the db user managing emoncms as per the shell mysql invocations below (replacing MYSQL_PASSWORD and USERNAME with the adequate values)

#!shell

mysql -uroot -pMYSQL_PASSWORD -e "CREATE DATABASE trials;"
mysql -uroot -pMYSQL_PASSWORD -e "GRANT ALL PRIVILEGES ON trials.* TO 'USERNAME'@'%' WITH GRANT OPTION;FLUSH PRIVILEGES;"

* unzip and copy the database of virtual devices to the newly created database

#!shell
unzip -p /var/www/virtualDevices/new_trials.sql.zip | mysql -uroot -p$MYSQL_PASSWORD  trials

updated the connectDB.php file with the db information.

2. Using virtual devices in emoncms

2.1 Configure virtual driver module

access emoncms and create and admin account (this will trigger the creation of the emoncms database)
Then, run the script emoncms/Modules/driver/driver.sql on the emoncms database. You can do that by typing in the following command console, where PASSWORD must be replaced my the root mysql password (and there is no space in between -p and the PASSWORD):
```
 mysql -uroot -pPASSWORD emoncms < /var/www/emoncms/Modules/driver/driver.sql
```

2.2 Create a virtual device by the GUI

It is possible to create a virtual device by using the GUI or by using the API.

This part describes how to create a virtual device using GUI. In /emoncms/driver/node there are two links:

Virtual Meters: it creates the virtual device, its device template into emoncms, related inputs and feeds, but does not assign the template to an emoncms device node. The device discover of CoSSMic works so that the software detects automatically the plugging of smart meters and create nodes representing them. The user then, goes to the appliance pages and maps the meters to a device template. In order to emulate the plugging of smart meters corresponding to a device in a virtual house, you can use the GUI on http://HOSTINGIP:HOSTINGPORT/emoncms/cossmiccontrol/view/addMeter to create the meters.

After that step, you need to go back to the Appliances page emoncms/cossmiccontrol/view/appliances and map the meters to a device template, just like one would do it in a real household

Virtual Device: it creates the virtual device, its device template into emoncms, related inputs and feeds, and it assignes the template to an emoncms device node, so it is not necessary to add and configure virtual drivers for the virtual devices.

2.3 Create a Virtual House Meter

In order to add virtual devices to this cossmic emoncms instance you need first to create a house meter by calling the following rest api

http://HOSTINGIP:HOSTINGPORT/emoncms/driver/vdevice.json?template= {'type':'VH Meter','id':0,'name':'VirtualHMeter'}&deviceName=preferred_name

replacing:

the HOSTINGIP and HOSTINGPORTS by the IP where the cossmic application is running and the port exposing the webserver. And use a simple name (without spaces) for the deviceName

Note: * Virtual devices can be used together with real deivices. The VHM behaviour could not be the same of a real global meter.*

2.4 Create a virtual device by the API

It is possible to create a virtual device by using the API as described here.

###List device Type:

To get a list of device type:

http://cloud.cossmic.eu/cossmic/marco/virtualDevices/device.php?json={'cmd': 'types'}

The response is a json with all types:

{ "types":[ { "id": 1, "name": "Battery", "type": 2}, { "id": 2, "name": "Bulb", "type": 0}, { "id": 3, "name": "Solar Panel", "type": 1}, { "id": 4, "name": "Household Workload", "type": 0}, { "id": 5, "name": "Dishwasher", "type": 0}, { "id": 6, "name": "Refrigerator", "type": 0}, { "id": 7, "name": "Freezer", "type": 0}, { "id": 8, "name": "Boiler", "type": 0}, { "id": 9, "name": "TV", "type": 0}, { "id": 10, "name": "Video", "type": 0}, { "id": 11, "name": "PC", "type": 0}, { "id": 12, "name": "Washing machine", "type": 0}, { "id": 16, "name": "Clothes Dryer", "type": 0}, { "id": 18, "name": "Air Conditioner", "type": 0}, { "id": 19, "name": "Water Heater", "type": 0}, { "id": 20, "name": "Oven", "type": 0}, { "id": 21, "name": "Smart Meter", "type": 0}]}

###List Templates To have the list of all templates (i.e. the models of virtual devices) currently present:

http://cloud.cossmic.eu/cossmic/marco/virtualDevices/device.php?json={'cmd': 'templates'}

Response:

{ "templates":[ { "id": 81, "type": "Air Conditioner", "name": "Bryant 697CN030B_AirCond"}, { "id": 82, "type": "Air Conditioner", "name": "LG LW1212ER _AirCond"}, { "id": 62, "type": "Boiler", "name": "boiler1"}, { "id": 59, "type": "Bulb", "name": "simplebulb"}, { "id": 70, "type": "Bulb", "name": "bulb1"}, { "id": 73, "type": "Clothes Dryer", "name": "GEWSM2420D3WW-Regular"}, { "id": 75, "type": "Clothes Dryer", "name": "GEWSM2420D3WW-PermPress"}, { "id": 76, "type": "Clothes Dryer", "name": "GEWSM2420D3WW-Timed"}, { "id": 42, "type": "Dishwasher", "name": "dw1"}, { "id": 43, "type": "Dishwasher", "name": "virginia d"}, { "id": 69, "type": "Dishwasher", "name": "dw3"}, { "id": 71, "type": "Dishwasher", "name": "dw4"}, { "id": 61, "type": "Freezer", "name": "freezer1"}, { "id": 44, "type": "Household Workload", "name": "CS14"},…]}

###Particular Template To get only a particular type of template:

http://cloud.cossmic.eu/cossmic/marco/virtualDevices/device.php?json={'cmd': 'templates', 'type': '12'}

Parameter:

type: the type of the template

Response (example for washing machine):

{ "templates":[ { "id": 66, "type": "Washing machine", "name": "washm1"}, { "id": 72, "type": "Washing machine", "name": "wm4"}, { "id": 74, "type": "Washing machine", "name": "LGWM2016CW-Regular"}, { "id": 78, "type": "Washing machine", "name": "LGWM2016CW-PermPress"}, { "id": 79, "type": "Washing machine", "name": "LGWM2016CW-Delicates"}]}

###Particular Template Information To get information about a particular template:

http://cloud.cossmic.eu/cossmic/marco/virtualDevices/device.php?json={'cmd': 'templateinfo', 'id': '43'}

Parameter

Id: the id of the particular template

Response (example for dishwasher):

{ "templateinfo":[ { "parameter": "manufacturer", "value": "Kenmore"}, { "parameter": "sampling_period", "value": "60sec"}]}

###Create a device To create a device:

http://cloud.cossmic.eu/cossmic/marco/virtualDevices/device.php?json={'cmd': 'add', 'template': '50', 'name': 'sm1', 'user': '0'}

Parameters:

template: the template of device you want to add.
Name: the name you want to assign to device
User: the user who owns the device

Response (the id of the device created):

{"id": "1333"}

###List devices of a particular user To get the list of devices of a particular user.

http://cloud.cossmic.eu/cossmic/marco/virtualDevices/device.php?json={'cmd': 'list', 'user': '1'}