Framegrab adds two classes to PHP. FrameGrabDevice represents a video capture device and FrameGrabImage an image captured with a FrameGrabDevice.

You can create a new FrameGrabDevice for the default video capture device as follows:

	$device = new FrameGrabDevice();

The extension will iterate through available video devices until it finds one that supports video capture. A FrameGrabDeviceException will be thrown either if no video devices are available or if the available video devices do not support video capture.

You can supply an argument to the constructor (see below) if you want to initialise a specific video device. In this case the FrameGrabDeviceException will be thrown if that specific device does not exist or does not support video capture.

	$device = new FrameGrabDevice('/dev/video1');

Once you have a device you can then grab an image using the grab() method. The method takes no arguments and returns a FrameGrabImage object or false on error. As the FrameGrabImage constructor is a protected method you cannot create objects directly using new.

Once you have the image you can either save the image to the file in PNG format or have it returned as a string in PNG format using the writeAsPNG() and toStringAsPNG() methods respectively. The former takes a filename as the sole argument and returns false on error. The latter takes no arguments and returns either the PNG data as a string or false on error.

The two objects also support a number of properties. The code below demonstrates the extension in use. It returns an image captured from the default video device as a PNG. The image has capture device and image meta data embedded in it visible in the top left corner of the image.

<?php
 
try {
	// Get the default frame grabber device.  Throws an exception if a device
	// cannot be found.
	$device = new FrameGrabDevice();
 
	// Grab am image.
	$fgimage = $device->grab();
	if ($fgimage) {
		// Create a GD image from a frame grab image
		$gdimage = imagecreatefromstring($fgimage->toStringAsPNG());
 
		// Output data about the image on to the image
		$font  = 1;
		$black = imagecolorallocate($gdimage, 0, 0, 0);
		$fh    = imagefontheight($font);
		$x     = 10;
		$y     = 10;
		imagestring($gdimage, $font, $x, $y, "Device: ".$device->device, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Card: ".$device->card, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Width: ".$fgimage->width, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Height: ".$fgimage->height, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Format: ".$fgimage->format, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Bytes per line: ".$fgimage->bytes_per_line, $black);
 
		// Output the image
		header('Content-Type: image/png');
		imagepng($gdimage);
		imagedestroy($gdimage);
	}
} catch (Exception $e) {
	// Handle the FrameGrabDevice exception here.
}
 
?>

The extension is available at the PECL site.

To make control of modems easier over twenty years ago the Hayes Corporation developed a serial command protocol, the Hayes or AT command set. Many other modems adopted the protocol and now its a de-facto standard. Over the years as modem functionality expanded so did the command set. Now it supports FAX, cell phone address books, SMSes and so on. The AT command set comprises a set of text based commands terminated with CRLF. The responses are similarly text strings terminated with CRLF. Typically the modem responds with “OK”, “ERROR” or a setting value.

DIO currently provides two stream types raw and serial. Raw streams provide low level access to operating system devices. Serial streams provide access to, and abstract, serial ports. DIO stream support is accessed just like any other PHP streams. The appropriate URI is fopened. The relevant URIs are:

dio.raw://[device]

for raw streams and

dio.serial://[device]

for serials streams. In both cases [device] is the device name to open. For example this could be /dev/random for the random device on Linux; or /dev/ttyS0 for a comms port on Linux; or COM1 for a comms port on Windows. We’ll be using the later form of the URI as we’re opening a serial port.

The example code opens the serial port as follows:

$f = fopen("dio.serial:///dev/tty.ZTEUSBATPort_", "r+", false, $c);

The first argument is the device to open. In this case a serial port to the USB 3G modem connected to my MacBook. The second is the open mode, in this case read/write. The third is an optional argument that comprises a flag that indicates whether to search the include path for the file to open. We don’t want this. The final optional argument is a stream context which is a collection of stream specific additional parameters.

A stream context is created using stream_context_create(). The code in the example that creates the context, prior to opening the port, is shown below.

$c = stream_context_create(array('dio' => 
	array('data_rate' => 9600, 
		  'data_bits' => 8, 
		  'stop_bits' => 1, 
		  'parity' => 0, 
		  'flow_control' => 0,
		  'is_blocking' => 0,
		  'canonical' => 1)));

The first four context options are pretty obvious. The serial port is being configured for 9600 bits per second, 8 bits per byte with 1 additional stop bit per byte and no parity checking.

The next option disables hardware flow control. Serial ports are relatively slow so they often have hardware control lines which indicate when there is data ready to be sent and space in the buffer ready to receive data. My USB modem does not have these so the hardware flow control is disabled.

Next we turn off blocking. With blocking function calls the operating system waits for data and only returns when it is ready to return the data that was requested i.e. the operating system blocks on the data. Non-blocking function calls return whether there is data or not. The POSIX open call also blocks on the state of the Data Carrier Detect (“DCD”) hardware control line. Some modems have this control line and use it to indicate there’s a carrier signal on the telephone line. Again since the USB modem does not have this we disable it.

Finally we enable canonical mode. Canonical IO on POSIX means that the serial port driver will wait for a line of text ending in a newline (or the internal buffer being full) before returning. If less characters than were entered on the line were requested the driver buffers the data for subsequent reads until the entire line is returned. In canonical mode you can actually connect a terminal to the serial port as line editing is supported. Since Windows does not have a canonical mode DIO provides an implementation on top of the Windows driver. The alternative to canonical mode is byte mode where by DIO waits until the requested number of bytes have been read and returns regardless of whether there are more bytes available.

If all that sounds a little complicated think of it like this. If you’re reading strings terminated with a new line use canonical mode otherwise use byte mode.

Remember that blocking was disabled so that opening the serial device did not block. This isn’t desirable when actually reading data. Blocking mode can be re-enabled on an open stream using stream_set_blocking as follows:

stream_set_blocking($f, true);

Once the serial port has been opened with the appropriate port settings and blocking re-enabled the port can be written and read using the standard fprintf and fgets PHP functions.

There are two AT commands related to sending an SMS. The first is “AT+CMGF=1″ which tells the modem to operate in SMS text mode. This should respond with “OK”. The second is “AT+CMGS=” which is followed by a string comprising a telephone number. This accepts the text of an SMS which is sent when CTRL-Z is entered.

There’s a little bit of additional work in the example as the modem echos data sent to it back to the sender so the PHP code consumes data after a command is sent until it sees the sent command echoed back. The full example follows.

<?php 
 
define('PHONE_NUMBER', '5551234');
define('SMS_TEXT', 'Hello world!');
 
/**
 * Sends data to the modem
 */
function send_data($f, $string) {
	echo "< $string\n";
	fprintf($f, "$string\r\n");
}
 
/**
 * Reads lines from the serial port.  It reads until a non blank line is
 * received then returns it.
 */
function get_string($f) {
	do {
		// remove carriage returns, line feeds and excess white space
		$response = trim(str_replace(array("\r\n","\r","\n"), '', fgets($f)));
	} while ($response == '');
 
	return $response;
}
 
/**
 * Waits for OK to be sent back by the modem.
 */
function wait_for_ok($f) {
	do {
		$response = get_string($f);
		echo "> $response\n";
	} while ($response != "OK");
}
 
// MAIN CODE
 
// Create the context
$c = stream_context_create(array('dio' => 
	array('data_rate' => 9600, 
		  'data_bits' => 8, 
		  'stop_bits' => 1, 
		  'parity' => 0, 
		  'flow_control' => 0,
		  'is_blocking' => 0,
		  'canonical' => 1)));
 
// Open the port
$f = fopen("dio.serial:///dev/tty.ZTEUSBATPort_", "r+", false, $c);
 
if ($f) {
	// Re-enable blocking
	stream_set_blocking($f, true);
 
	// Set SMS text entry mode
	send_data($f, "AT+CMGF=1");
	wait_for_ok($f);
 
	// Send an SMS
	send_data($f, "AT+CMGS=\"" . PHONE_NUMBER . "\"");
	send_data($f, SMS_TEXT);
	// Send CTRL-Z to end SMS text entry
	fprintf($f, chr(26));	
	wait_for_ok($f);
 
	// Close the port
	fclose($f);
}
?>

The original DIO API is very basic and POSIX oriented. Serial support is not very configurable and doesn’t work at all on Window platforms. So I have been working on implementing PHP stream extensions that allow you to do raw and serial IO via streams. Anyway its ready for testing by people other than me on POSIX (Linux, OS X etc) and Windows platforms so I’m looking for beta testers.

Where to get it

The release candidate is downloadable as a package from:

http://www.cyberspice.org.uk/downloads/dio-0.0.4rc3.tgz

And directly from SVN at:

http://svn.php.net/repository/pecl/dio/tags/RELEASE_0_0_4RC3

Documentation

While I write proper PHP documentation below is a brief over view of how you use DIO.

Streams

DIO streams are just PHP streams. You use fopen() to open them and fread(), fwrite(), fgets(), stream_set_blocking() etc. There are two DIO streams, dio.raw and dio.serial.

dio.raw is as it sounds, raw streams. It uses the low level OS streams such as open(), read(), write(), close() etc. on POSIX and CreateFile(), OpenFile(), ReadFile(), WriteFile(), CloseFile() on Windows. It does not buffer except the internal PHP buffering.

dio.serial is full serial support. It allows setting of data rates, data size, stop bits, handshaking and raw/canonical modes etc.

Both stream types support timeouts and blocking/non-blocking use.

Example code

Below is a small example that opens a serial port, configuring it with a stream context, and then reads and writes from it before closing it.

<?php 
	// Create a stream context that configures the serial port
	// And enables canonical input.
	$c = stream_context_create(array('dio' => 
		array('data_rate' => 115200, 
		      'data_bits' => 8, 
		      'stop_bits' => 1, 
		      'parity' => 0, 
		      'is_canonical' => 1)));
 
	// Are we POSIX or Windows?  POSIX platforms do not have a
	// Standard port naming scheme so it could be /dev/ttyUSB0
	// or some long /dev/tty.serial_port_name_thingy on OSX.
	if (PATH_SEPARATOR != ";") {
		$filename = "dio.serial:///dev/ttyS0";
	} else {
		$filename = "dio.serial://COM1";
	}
 
	// Open the stream for read only and use it.
	$f = fopen($filename, "r+", false, $c);
	if ($f) {
		echo "Writing to port...\n";
		fprintf($f,"Hello world\n");
		echo "Reading from port...\n";
		$data = fgets($f);
		if ($data) {
			echo $data;
		}
		fclose($f);
	}
?>

Stream context

DIO uses the stream context to obtain the port configuration settings. There are settings which are common to all DIO streams and settings which are sub-stream specific. The common settings are:

Both the blocking setting and the timeout settings can changed after the stream is open using the PHP functions stream_set_blocking() and stream_set_timeout() respectively.

The serial stream has the following additional configuration settings.

Finally

So there you are. Any results, good or bad, are useful. DIO has error checking and will return useful warnings if you try and feed it silly values. Logs, PHP versions, etc. would be useful diagnosing issues. Thanks.

I will be bringing a long several Arduino-a-likes together with a variety of components and CDs of the IDE so that we can get together in groups, code and play.

I am intending to take along items which are a mix of traditional crafts such as knitting and jewellery making combined with tech. For example programmable earrings, a temperature sensing hat and a bag that has a proximity detector and RFID tag so it can detect its owner.

I am also going to show off a couple of my other projects like an ethernet adapter for a BBC microcomputer and a “Mood Wall” (It analyses twitter tweets for the mood of the content displaying patterns and colours which reflect the prevailing mood).

Hopefully I will see you there!

In order to record my achievements or otherwise I have created a new blog at http://www.cyberspice.org.uk/101in1001/. And my (growing) list of goals with links to pages that describe each goal is here.

The first goal is “A photo a day for at least 365 days”. Basically I have set myself the task of taking, and posting to a blog, a photo each day for at least a year. So I’ve created a new blog for that too at http://www.cyberspice.org.uk/oneaday/. Below is my photo for Jan 1, 2010.

I have given it to one of my my sister’s as a gift. For the other sister I made her some beaded jewelery.

There are other shells which have a completely different syntax and other scripting languages such as Perl and PHP so when writing a shell script you can indicate the correct interpreter using the ‘hash bang bin bash’ comment to indicate you are using bash. I.e.

#!/bin/bash

Some lazy programmers don’t indicate the exact shell they require and use

#!/bin/sh

to mean bash when it means sh.

Ubuntu, in their wisdom, have decided to go for dash as their shell. It is an evolution of the Almquist shell and is smaller and lighter weight than bash however they install bash anyway. dash and bash have the common subset of sh commands but are different. So if you find you have a problem building or similar on Ubuntu it may be that the wrong shell is being used. Ubuntu has a symlink as follows:

lrwxrwxrwx 1 root root       4 Mar 29  2009 sh -> dash

You may need to change this to point to dash as follows:

$ cd /bin
$ sudo rm sh
$ sudo ln -s bash sh

While we’re handling Ubuntu oddities building against NCurses, the terminal output library, can also be problematical. A little while ago NCurses was split in to two libraries, libncurses.so and libtinfo.so. Some badly written software will try and link explicitly with libtinfo.so directly rather than trying libncurses.so first. Ubuntu does not split these two libraries but provides just the one libncurses.so library so if you have an issue with a missing libtinfo.so you will need to add symlinks in to your library directory as follows:

$ cd /usr/lib
$ ln -s libncurses.so.5 libtinfo.so.5
$ ln -s libtinfo.so.5 libtinfo.so

It has a couple of things I could improve on. I put the cutout for the headphone cable on the wrong side and you have to take it out to charge. The next one will have a button hole type slot in the bottom for the charging cable.

Knowing Purl has meant I can do ribbing so I’ve started knitting a ribbed scarf out of some great multicolour yarn.

PHP Warning:  PHP Startup: Unable to load dynamic library 'modules/gd.so' -
modules/gd.so: cannot open shared object file: No such file or
directory in Unknown on line 0

Warning: PHP Startup: Unable to load dynamic library 'modules/gd.so' -
modules/gd.so: cannot open shared object file: No such file or
directory in Unknown on line 0

The default PHP package on Ubuntu 9.10 is fairly minimalist. Most extensions are provided as separate packages which include an INI file and a dynamic library. The dynamic library is stored in:

/usr/lib/php5/20060613+lfs

And the INI file for each extension is in:

/etc/php5/conf.d.

The make tests rule in the generated Makefile in the extension you are compiling modifies the path that PHP searches for extensions by to point to the modules directory within the extension source. So PHP, which is used to run the tests, cannot find the extensions.

I’ve found the easiest way (if slightly hacky) to fix the make test failure is just to copy the .so files from the PHP5 extension directory in to the modules directory within the extension source.