Shion: Web Interface

This document contains information about using a remote web interface with Shion. It assumes an Apache web host with support for executing Ruby CGI scripts.

Setting up the Shion web interface

The Shion web interface is a small Ruby CGI that uses SQLite3 as its backing database. The instructions below describe how to install this package.

1. Download the package. The Shion web interface is available here. Unzip the file and copy the files to the web root on your own web server.

2. Set file permissions. Locate the db folder and set the user that runs your web server as the owner with write permissions. In this case, I use the apache user:

sudo chown -R apache.apache db

4. In your Apache configuration, set up the CGI permissions. You may need to include the following lines in your local Apache configuration files:

AddHandler cgi-script .cgi
ScriptAlias /shion/cgi-bin/ "/WEBROOT/shion/cgi-bin/"

You may wish to password protect this location using a .htaccess file or the equivalent.

Replace WEBROOT with the path to your web files on your local server.

5. Update the database location in the script. Update the cgi-bin/interface.cgi file to point to database file. Replace WEBROOT with the same value used above:

db = SQLite3::Database.new('WEBROOT/shion/db/shion.db')

6. Initialize the database by visiting the following URL:

http://your.web.host/shion/cgi-bin/interface.cgi?do=init_db

your.web.host/shion/cgi-bin/interface.cgi

replacing your.web.host with your actual host. Note that the http:// protocol handler is intentionally omitted. (Presently, the Shion web interface only runs over HTTP.)

http://your.web.host/shion/index.html

To verify that you can manipulate the devices remotely, toggle the device in the interface by clicking the icon next to its name. The icon next to the device will turn into a set of gears:

Ths means that the device has pending instructions. When Shion downloads the instructions, the gears will disappear. When Shion successfully executes the new instructions, the status icon will change.

Note that it may take a a few minutes for this process to complete, depending upon local factors.

How it works

If you are working in an environment where Shion web package can not be run (no Ruby, a web server other than Apache, etc.), the following details explain the underlying architecture so that you can reimplement the web interface to suit your own requirements.

1. Uploading status. When a device's status changes, Shion invokes the following URL using the GET method:

http://USERNAME:PASSWORD@HOST/shion/cgi-bin/interface.cgi?do=upload_status&address=DEVICE_ADDRESS&name=DEVICE_NAME&status=STATUS

The capitalized values are replaced with their local equivalents, save for the status parameter. Currently, a device's status can be either Active or Inactive. The web interface does not yet support intermediate values.

2. To display the status of the devices, the Shion web interface calls the following URL:

http://USERNAME:PASSWORD@HOST/shion/cgi-bin/interface.cgi?do=fetch_status

This returns an XML file that the interface parses when constructing itself.

3. When remotely setting instructions, the calling application invokes

http://USERNAME:PASSWORD@HOST/shion/cgi-bin/interface.cgi?do=upload_instruction&address=DEVICE_ADDRESS&action=ACTION

ACTION can be either on or off. Calling this URL adds the new instruction to a list of instructions that Shion periodically downloads.

4. Shion downloads instructions by calling

http://USERNAME:PASSWORD@HOST/shion/cgi-bin/interface.cgi?do=download_instructions

This returns a list of pending instructions in XML, which Shion parses and executes locally. If the instructions are successfully executed, Shion calls

http://USERNAME:PASSWORD@HOST/shion/cgi-bin/interface.cgi?do=clear_instructions

to reset the remote list.

Questions, comments, corrections?

This is an early version of the web interface instructions and may contain errors, ommissions, or opaque sections. If you need any help or have any suggestions, please e-mail shion@audacious-software.com.