2013-11-04

Carica Chip 101 - Controlling An LED With PHP

Some time ago, in this blog post, I explained the basic stuff about Arduino, Firmata and PHP. Now it is time for the next step. Carica Io and Carica Firmata have grown and got a third layer called Carica Chip.
  1. Carica Io - Non-Blocking I/O for PHP
  2. Carica Firmata - An implementation of the Firmata protocol
  3. Carica Chip - PHP classes representing hardware devices
Carica Chip provides an easy way to control a device. So let's start with an "Interactive LED" example.

First Step: Project Initialization

Carica Chip uses Composer. Make sure that it is installed and open a console. Go into your projects directory and execute the following line (it will create a new subdirectory "led"):

composer create-project carica/chip-skeleton led \
  --stability=dev

Second Step: Create An HTML Interface

For the interface a simple html file is used. Just two links with an iframe set as the target. This is a basic version, some Javascript and CSS should be used to make it nicer and more usable.

<html>
  <head>
    <title>Led Switch</title>
  </head>
  <body>
    <a href="./switch/on" target="iframe">
      On
    </a>
    <a href="./switch/off" target="iframe">
      Off
    </a>
    <iframe name="iframe" src="about:blank"></iframe>
  </body>
</html>

Store the html source as "index.html" in the project root.

Third Step: Create The PHP Server

This will be a step by step description, the complete file is below and on Gist.

The skeleton includes a bootstrap file that returns a board depending on your configuration. Copy "dist.configuration.php" to "configuration.php" and change it if needed.

Now open "server.php". At the top "bootstrap.php" is included to fetch a Firmata board. If the board is activated, it executes a callback. Carica Chip provides a "Led" class. For the example an instance is created. The constructor needs the pin the led is connected to. Most Arduinos have a led that is connected to pin #13 on board.
$led = new Chip\Led($board->pins[13]);

We need to deliver the html interface to the browser. Carica Io includes a http server and file routings. Add "use Carica\Io\Network\Http as Http;" to the namespace definition, create a new route and add a file delivery for "index.html".
$route = new Http\Route();
// Define html file delivery for /
$route->match(
  '/', 
  new Http\Route\File(__DIR__.'/index.html')
);

A second route defines the switch actions. This is specific and not much source, so an anonymous function is used. For more extensive logic I suggest functors, objects that implement the magic method "__invoke()", like the file handler. The state parameter is fetched from the path. Depending on the parameter the led is switched on or off. A response is created and a string with the new state is used as content. If you don't return a response, a 404 would be send to the browser.
$route->match(
  '/switch/{state}',
  function (Http\Request $request, array $parameters)
    use ($led) {
    $ledOn = ($parameters['state'] == 'on');
    if ($ledOn) {
      $led->on();
    } else {
      $led->off();
    }
    $response = $request->createResponse(
      new Http\Response\Content\String(
        $ledOn ? 'ON' : 'OFF', 
        'text/plain; charset=utf-8'
      )
    );
    return $response;
  }
);

Last the http server is created and started.
$server = new Carica\Io\Network\Http\Server($route);
$server->listen(8080);

Finished!

That's all. You can now start the script on the command line and open the URL in a browser. Clicking the links will (de)activate the led.

I posted the full source of "server.php" including comments on Gist.