Category: Hub Software Website

In a previous post we developed a simple api facility for home-hub slaves to enable remote control. The voice interface will use this api for controlling actuators, but it requires a much richer interface to provide a full interactive voice service.

The following instructions will detail how to modify your home-hub to add a full REST api. This will allow us to read data from any table or view in the hub’s database.

Our REST commands will be of the form:

http://home-hub/rest/zones

Normally, the apache web server would throw a page not found error, but with some additional configuration we can direct all such requests to a specific service page.

The first step is to enable the apache rewrite module:

sudo a2enmod rewrite

Then we need to edit the configuration:

sudo nano /etc/apache2/apache2.conf

and find the document root spec:

<Directory /var/www/>
 Options Indexes FollowSymLinks
 AllowOverride None
 Require all granted
</Directory>

and change AllowOverride from None to All.

Restart apache…

sudo service apache2 restart

Then we can add the following .htaccess file to our document root at /var/www:

<IfModule mod_rewrite.c>
 RewriteEngine On
 RewriteBase /
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule . /rest.php [L]
</IfModule>

and this will send any unfound page requests to rest.php

Now we can fetch the rest php script from the project repository with the following command:

wget -P /var/www/html http://www.warrensoft.co.uk/home-hub/code/website/html/rest.php

The same warning about security applies here. The rest api has no authentication built in. It provides an access-most-areas pass to inspect (but not change) all the hub’s database contents, so if your hub is internet-facing you are strongly advised to add your own security measures.

Finally we can test our rest interface:

http://home-hub/rest/zones

In the next post we will setup a new Raspberry Pi in the role of Voice Assistant.

We already have the facilities to add and edit impulses, within the Organisation menu option.  Select the Add Impulse link and fill in the details. The key field is the BCM Pin. This obviously needs to be the pin that your switch is connected to. The controller is constantly monitoring impulse configurations in the database, in order to set up the necessary event callback hooks.

The next step is to monitor the event queue on the website Statistics page, while pressing the impulse button. As mentioned earlier, debouncing may not be sufficient defence against noise, so the controller code employs an additional lockout mechanism which prevents repeat events within 10 seconds of a button press. The main scheduler module is already optimised to keep a lookout for rules, and to process actuators, so the overall effect is that there should be reasonable response to pressing an impulse button.

The event queue is the place to track impulse events and make sure you are getting the expected results. As with Conditions, Impulses won’t be processed until there is a connected Rule and Action. Make sure you use the toggle_actuator Action Function for impulses, to get the push-on-push-off behaviour, unlike the action_actuator used previously for Conditions.

Impulses will appear as a clickable icon on the Current Values page of the website, within the Zone of their linked Actuator.

There is only one topic left on our project plan to implement – Statistics. This is covered in the next post.

One of the design goals for the home-hub was for it to replace the traditional central heating programmer. I have never found these easy to work with, often tucked away in awkward locations, and had the picture in my mind of reclining on the sofa -tablet in hand – adjusting the programs. I will describe the process of interfacing the hub with a central heating programmer in a later post.

As significant effort had been put into the processing of conditions, rules and actions, I concluded this could be re-purposed for time-based conditions.  If you add a new Time-based condition you will see the following:

You can choose from Daily, Weekdays or Weekend programmes. All that is required is to connect this Condition up to an Actuator Action via a Rule and you can switch devices on schedule.

The next post will introduce the concept of impulses.

Use the following to install the Conditions features for the website:

wget -nH --cut-dirs=4 --reject "index.html*" -P /var/www/html/ -i /var/www/html/manifest6.txt http://www.warrensoft.co.uk/home-hub/manifests/website/manifest6.txt

This provides the menu option to allow you to add add and edit simple Sensor Conditions, Time-based Conditions and Complex Conditions. This is a more user-friendly interface which is applicable to all hub users, not just administrators. If you click the Conditions option you will see there is a sample condition provided, which operates on the sine-wave virtual sensor.

Enable this condition, and click the Update button to save.  Events should now start appearing in our event queue.

How do we know if this is working?

Well, there are 2 ways. The Statistics page has a useful table showing the last 10 events. They will be listed as unprocessed at this stage, as we haven’t installed the rules engine, but you should see them appearing as set/reset pairs. The table is fine for administrators, but we really need a better visual display of our conditions and events, to confirm the logic is meeting our requirements.

This is the purpose of the Condition Graphs website option. This should now be available, so if you select it you should see a graph showing 3 traces:

1.  The sample trace of the condition sensor(s)

2. Any set-points – shown as a dotted/dashed lines

3. Event transitions

This is an invaluable tool for checking and adjusting your condition expressions to get the correct outcomes.

The example condition is a slightly unrealistic scenario, in that we are not switching anything from our events, and so the sensor values do not respond, but shortly we will address that.

We are tantalisingly close to closing the control loop. All we need is to link our events to actuators. This is accomplished with Rules and Actions. These are described in the next post.

The statistics are very useful when configuring sensors and setting up your hub, but for daily use we need a more contextual presentation of temperature readings, etc.

Use the following command to fetch the necessary website files:

wget -r -nH --cut-dirs=4 --reject "index.html*" -P /var/www/html/ -i /var/www/html/manifest3.txt http://www.warrensoft.co.uk/home-hub/manifests/website/manifest3.txt

Now you can refresh the website in your browser and choose the Current Values option.

All Sensors, Actuators and Impulses are assigned to a zone, and will be displayed within that zonal box in this floor plan representation. You will want to make your display mimic the layout of your house, as far as possible.

To achieve this each zone has X, Y and Z co-ordinates, with Z representing the floor number. In addition, each zone has Rowspan and Colspan values which enable the size of the zone to be adjusted relative to neighbouring zones. Anyone familiar with html table construction will quickly be able to model the rooms of their house (which is how the plan is drawn!). If not, then a drawing on squared paper will help. Here is an example:

Zone Name	X	Y	Z	Rowspan	Colspan
Kitchen	1	1	1	1	1
Bathroom	1	2	1	1	1
Lounge	2	1	1	2	1
Bedroom	2	2	1	1	1
Study	3	2	1	1	1

In the next post we will enable sampling, and see our sensor values displayed on a graph.

Now we have a working controller we need a better user interface to enable us to add sensors, modify zones and perform all of the configuration. The hub website uses Google Charts for graphs, and also employs an Org Chart for the Organisation interface. This is more touch-friendly than a table.

Use the following command to fetch the files required for this feature:

wget -nH --cut-dirs=4 --reject "index.html*" -P /var/www/html/ -i /var/www/html/manifest2.txt http://www.warrensoft.co.uk/home-hub/manifests/website/manifest2.txt

Unlike the controller, the website will dynamically update, so you should be able to login, choose the Organisation menu option and view the Zones, Sensors, etc.

At this point, you may want to create a new temperature sensor and restore the virtual sensor that we hijacked for testing. Within the edit forms there is a Duplicate button for all organisation objects, so it is very easy to clone sensors, actuators, etc.

While we are doing some administration,  we can setup some sensor alerts. This is described in the next post.

 

Right, let’s get some code for our website. The following wget shell command will fetch the files for a skeleton website from the project’s code repository, and place them in your html web content directory.

wget -r -nH --cut-dirs=4 --reject "index.html*" -P /var/www/html/ -i /var/www/html/manifest1.txt http://www.warrensoft.co.uk/home-hub/manifests/website/manifest1.txt

The key files are home.php, login.php, logout.php, signIn.php and auth.inc. A bunch of other javascript scripts and css styles will also be downloaded, which are needed for the website. There is a lot of code in this project, so I won’t go into detail about every file, but essentially home.php provides the menu structure based on the jQuery accordion. This is what you should see if you point your browser to http://home-hub/home.php and login.

login, logout, signIn and auth provide the authentication framework, in conjunction with the Users table in the database. The skeleton database already has the hub user ‘pi’ set up as an administrator, with the password ‘raspberry’ . We can use this login to complete most of the tasks in upcoming posts, but you should change the password as soon as possible!.  Each of the menu items, when selected, reads in the relevant feature file. The only file provided in this first skeleton website download is statistics.php

The Statistics page provides tables of technical data such as sensor values, actuator states, alert states, maximum/minimum values, queued messages and system information. We have implemented this first, so we have a simple view of our sensor values, but there are many other ways to view data which we will implement in later posts.

The skeleton database has one sensor pre-configured, the Sinewave Angle virtual sensor, but as we have no controller software running it is stuck at its last reading.  This is our next task.

The website database access will be performed by a shared script, hub_connect.php, in the /var/www/private_html directory. This script has login details, so is placed in a new directory outside of the publicly accessible directory tree.

sudo mkdir /var/www/private_html

give pi ownership over public and private directories…

sudo chown -R pi:pi /var/www/

create file…

cd /var/www/private_html
nano hub_connect.php

 

<?php

//require the PEAR::MDB2 classes.

require_once 'MDB2.php';

//Makes resultsets into column-name-addressable dictionaries
define("DICTCURSOR", MDB2_FETCHMODE_ASSOC);

//Define some constants
$db_engine = "pgsql";
$db_user = "postgres";
$db_pass = "raspberry";
$db_host = "localhost:5432";
$db_name = "hub";

//Assemble datasource name
$datasource = $db_engine.'://'.$db_user.':'.$db_pass.'@'.$db_host.'/'.$db_name;
//Define connection options
$options = array(
 'debug' => 2,
 'result_buffering' => true,
 'portability' => MDB2_PORTABILITY_NONE
);

$db_object = MDB2::connect($datasource, $options);

if (PEAR::isError($db_object)) {
 die($db_object->getMessage());
}

?>

Now we can test the database access from a PHP script, but first we need to enable Display Errors .

sudo nano /etc/php5/apache2/php.ini

Find the line display_errors = Off and change to display_errors = On. Then restart the apache web server…

sudo service apache2 restart

Place the following script in the /var/www/html directory.

<?php

 //
 // hellodb.php script to show PostgreSQL and PHP working together
 //

 // Required scripts
 require_once '../private_html/hub_connect.php';

 $qry = "SELECT * FROM \"Zone\"";

 $result = $db_object->query($qry);

 if (MDB2::isError($result)) {
   die($result->getMessage());
 }//end db error

 echo "Show me the zones:<br />";
 while ($row = $result->fetchRow(DICTCURSOR)) {
   print $row["ZoneID"].' '.$row["ZoneName"].'<br />';
 }//end while row

?>

Open it with your browser:

http://home-hub/hellodb.php

You should see the following output:

Any PHP errors will be logged in the following location:

/var/log/apache2/error.log

This completes the setup of the core hub components. In the next post we will consider the plan for the remaining parts of the project.

Use the following to install apache:

sudo apt-get install apache2

Add the following to your samba configuration, if you want to manage the website from your desktop, and restart samba:

[www] comment = /var/www on Raspberry Pi
path = /var/www
writeable = yes
guest ok = no

sudo /etc/init.d/samba restart

Give the pi user access:

sudo chown -R pi:pi /var/www/html

Confirm that you can browse to your website    http://home-hub

and create and edit files in the html document root.

The next task is to install PHP, PEAR, MDB2 and MDB2 pgsql.

sudo apt-get install php5 libapache2-mod-php5 php-pear php5-pgsql

sudo pear install MDB2

sudo pear install pear/MDB2#pgsql

The best way to check that PHP is correctly installed is to create a small script, info.php, that runs the phpinfo() function and place it in the var/www/html directory.

<?php

 // Show all information
 phpinfo();

?>

Browse to this page and if PHP is working you will see a long list of details about the installation.

If all that checks out we can move on to testing database access from our website.