#*************************************************************************
#  Copyright (C) 2015 by Fernando M. Silva   fcr@netcabo.pt                
#*************************************************************************

Last update: 13 October 2015

DISCLAIMER:

     This program was developed independently and it is not
     supported or endorsed in any way by Orvibo (C).

ACKNOWLEDGMENTS:
      This software was based on the information originally published 
      by Andrius Stikonas on 

https://stikonas.eu/wordpress/2015/02/24/reverse-engineering-orvibo-s20-socket/	
      and on comments and discussions by many other users. 

SUMMARY:
  This code implements a web interface to control Orvibo S20 sockets 
  attached to the local network. 

  The S20 switch can be operated  in the local network using the freely
  available WiWo app. However, it is behavior is much less convenient
  when the user is outside the local network. Only switch on and switch off
  operations are remotely supported, and remote operations often fail due to
  timeout. In fact, remote operations through the WiWo app use a remote 
  Orvibo proxy which is often out of service or possibly blocked(?). The purpose of 
  this software is to setup a web interface in some server in the local network, 
  which may be accessed from the  external network and, at the same time, 
  to have access to the local network, enabling easy and fast remote operation of 
  the S20. The web server can be installed on any computer always on or 
  on a cheap mini server (a Raspberry Pi, for example).

  This web interface provides status report of all S20 attached to the 
  network and supports ON/OFF actions of the detected devices. It features
  a responsive behavior to changing viewport sizes, including smartphones. It 
  divides the viewport in N horizontal buttons, each one labeled with the 
  name automatically retrieved from the connected S20s. Each button is 
  shown in green or red according to the current S20 state (green = ON).  
  The included php Library orvfms.php also supports programming count down 
  timer operations on/off, but theses are not yet supported by the
  web interface.
 
CONTENTS :
The code contained herein includes:
    orvfms/lib
    -  a php library with a set of simple functions to discover S20 devices
       attached to the local network and retrieve of S20 names, addresses 
       and switch state. It also include simple functions to switch ON/OFF 
       each device.

    orvfms/s20/index.php
    -  A php page that implements a web interface to monitor and 
       control S20 sockets attached to the local network. 

       The web interface provides status report of all S20 attached to the 
       network and supports ON/OFF actions of each S20. It features a 
       responsive behavior to changing viewport sizes, therefore being 
       well suited to both smartphones and desktops. It divides 
       the viewport in N horizontal buttons, each one labeled with the 
       name automatically retrieved from each S20s. Each button is 
       shown in green or red according to the current S20 state 
       (green = ON).  

       An example of the web interface is available on 
       orvfms/web_screenshot.png
 
    orvfms/css
    - The css stylesheet used by index.php

TESTING THE CODE:

Before installing this code on a web server, please test if the library 
recognizes and is able to operate your S20s. For this purpose, run the 
test script test.php available in the lib directory from the command line. It 
looks for S20 devices connected to the local network, retrieves relevant data 
and  dump all collected information in readble format to the console.
Moreover, it makes a full power on  / power off cycle to all your S20s and
tests the timer with two 10 seconds countdowns cycles usin a randomly 
choosed device. PLEASE TAKE INTO  ACCOUNT POSSIBLE SAFETY ISSUES  of the 
switching on/off cycle!  Uplug any devices or appliances that nay be affected by 
this test cycle before running test.php.

In order to test this library in command line, just open a  terminal or 
console and take the following steps: 

1. Change the working directory (cd) to the orvfms/lib  directory;
2. Check the file globals.php and please confirm (or update) the broadcast 
   address. Unappily, there is no portable and "clean" way of finding it 
   automatically in the general case, since the host may have more than one 
   network interface. In many cases, the default setting (192.168.1.255)
   will do the job, but please confirm your local address. It will probably 
   be something similar to 192.168.XX.255 or, in rare cases 172.16.XX.255.
3. Check if you do not have appliances connected that may be affected
   by the power on/off cycle. Unplug any devices that you want to spare.
4. Just type in the command line:

prompt> php-cgi test.php

(or replace php-cgi with the name of your php interpreter).

The output is quite straightforward, and possibly you are immediately able
to recognize most of it. You should also see/hear the usual switching on and 
off of the nearby S20s.  An example of the output of this script is included 
in the file orvfms/example.out.

INSTALLATION OF THE WEB PAGE:

The main web page is located in s20/index.php. 

The details of the installation will slightly depend on your HTTP server 
configuration and your own preferences. Anyway, just move the index.php, 
css/orvfms.css and  orvfms/lib/* to the directories that suit the local 
hierarchy and configuration of your HTTP server. Just check/update in  
index.php (1) the relative location of the orvfms lib directory (2)  
the relative location  of the css/orvfms.css file. These two lines are 
well marked in index.php with "UPDATE THE PATH".

In order to use the web server software, you may of course run  both the 
server and the  browser in your desktop or laptop when you are connected 
to the local network where the S20s are installed. However, in order to be 
able to operate the S20s from any Internet location, the server must be 
installed in a permanent host attached to the S20s network. For domestic 
applications, a good option is to set up the server on a Raspberry 
Pi, which can be kept powered on with minimal energy consumption and which 
can be simultaneously used by other applications (e.g., media center). 
Of course, if the server has a private address, as it usually happens in 
domestic networks, it will be required to configure the home router with Dynamic 
DNS and to add appropriate  port forwarding rules to the router. These 
operations are router and network dependent and are beyond the scope of this 
document.