DIO is the Direct IO extension for PHP. I recently took over maintaining this extension and have implemented comprehensive stream support for both POSIX and Windows systems. To demonstrate the use of DIO this post will describe a PHP script that sends an SMS using a USB 3G modem.

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);
}
?>

Tags: DIO, PECL, PHP

This entry was posted on Monday, February 15th, 2010 at 5:36 pm and is filed under C, Geek, PHP. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.