Controlling External Hardware with CLIO

This section contains CLIO documentation.

Overview

While running a web server locally on the hardware that is powering the CLIO exhibit, it is possible to control the hardware through the web application interface.  Hardware control can be achieved through a combination of JavaScript, PHP and Python scripting.   

Note: This should only be done when the web server is running on a kiosk that has no access to the world wide web.

By using JavaScript and AJAX, we can asynchronously call a PHP script as part of an event or the initialization script of an activity type.  When this PHP script is called, it is used to run terminal commands or initialize a Python script stored locally on the hardware.  PHP and Python can be used to manipulate Raspberry Pi hardware, execute console commands or run prepared code to control lights, speakers or other electronics attached to a Raspberry Pi GPIO port.

Method

Asynchronous JavaScript

Within any JavaScript function, you can use an AJAX (Asynchronous JavaScript and XML) call to load an external PHP page. This page can always return a set output, such as the command used below to populate the kiosk computer system information on the Settings menu when loaded.

$.ajax({
  url: "command/model.php",
  success: function(data) {
      $("#kiosk_model span").html(data)				
  }
});

Alternatively, this PHP page can take input by passing them through URL parameters. The script below is used to change the Raspberry Pi Official 7" touchscreen's brightness through the Settings menu.

$.ajax({
  url: "command/brightness.php?level=10",
  success: function(data) {
    console.log('Set display brightness to 10')
  }
});

PHP

When loaded in a web browser, these PHP pages will show unformatted text information or nothing at all. This is because they are not meant to be used as Human-readable interface. Instead, they are acting as an API (Application Programming Interface). These APIs allow us to execute operating level functions on the kiosk hardware through the CLIO Exhibit web interface.

Generally, these PHP pages are used to execute predefined terminal commands at the operating system level through the Apache2 web server. These terminal commands can be operating system calls, such as rebooting the system. They can also execute further scripts, such as those in the Python scripting language. Many Python libraries are available to facilitate the direct interaction with Raspberry Pi hardware.

Below, you can see an exampled based on the brightness.php script. This code will retrieve the URL parameter with the name 'level' and execute a different command based on the value of this parameter. This script uses the rpi-backlight library to change the Raspberry Pi Official 7" Touchscreen's brightness with a slight fade effect.

<?php

$level = $_GET['level'];

switch ($level) {
  case 1:
    shell_exec("rpi-backlight -b 10 -d 0.1");
    print "10% brightness";
    break;

  case ...:
    break;
}

?>

Resource: rpi-backlight – Python Library

Alternatively, you can also the PHP page to execute a Python script directly. This is completed through the same shell_exec function, except it is pointed directly to the Python script to be run.

<?php

$command = escapeshellcmd('command/script.py');
$output = shell_exec($command);
echo $output;

?>

Python

Every script is required to start with a declarative statement that is used by the system to interpret how to execute it. This is sometimes called the 'shebang line' because it starts with #!.

#!/usr/bin/env python

Additionally, you may be required to allow the script to be executable. This can be done through the terminal using the chmod command.

chmod +x myscript.py

Documentation
Installation	Look and Feel
Interaction Modes	Developing Activity Types
Creating an Interactive	Framework
Integrating CLIO	Contribute