PlugWeb: Creating the driver

In the previous post I introduced the concepts for the PlugWeb application. In this blogpost I will cover developing the driver for the plugwise network.

The plugwise network
The plugwise network consist of a set wireless devices communicating with each other using the zigbee protocol. The devices are called Circle’s and each network contains one special device, called a Circle+. Communication between the Plugwise network and a computer can be done using the Plugwise USB Stick, which is essentially a serial device.

Device commands
Commands can be sent to the network to switch on/off devices or gather device information. Below are the actions that will be implemented in the PlugWeb system.

  • Device Info: This command retrieves information about the device.
  • Power Info: This command retrieves information the current power consumption.
  • Switch On/Off: This command switches on/off devices.
  • Calibrate Device: This command gets the calibration information needed for calculating historical power consumptions.
  • Historic Usage: This command retrieves information about the historic power consumptions.
  • Init Stick: This command initialises the connection between the usb stick and the Plugwise network.
  • Scan network: This command discovers scans the network for devices.
  • Register device: This command attachs a device to a network.

Plugwise protocol

Driver classes
The driver consists of the following classes:
* Network: This class is the public api for a plugwise network.
* Device: This class is the public api for a plugwise device.
* Serial: This class sends/reads data to/from the plugwise usb stick (serial device like /dev/ttyUSB0).
* Request: This class builds the request string for sending to the serial device.
* Response: This class interprets the received information from the serial class and returns nicely formatted data.
* Utils: This class is used for static methods used in other parts of the driver.

Using the driver
Below is an example how to use the driver for a single device.

{code type=php}
$mac = ‘XXXXXX’;
$device = new \Plugwise\Driver\Device($mac);
$powerInfo = $device->getPowerInfo();
if (isset($powerInfo)) && ($powerInfo[‘state’]==1)) {
$powerInfo->switchOff();
} else {
$powerInfo->switchOn();
}
{/code}

The example below illustrates how to use the driver for querying the plugwise network.

{code type=php}
$network = new \Plugwise\Driver\Network();
$devices = $network->getDevices();
foreach($devices as $device) {
$device->switchOff();
}
{/code}

Example action: Device info
A single action will be shown in more detail; retrieving device information. The action is accessible through deviceInfo method of the device class:

{code type=php}
public function deviceInfo() {
$input = $this->getRequest()->actionDeviceInfo($this->_mac);
$this->getSerial()->sendData($input);
$data = $this->getSerial()->readData();
$out = $this->_formatData($data);
return $out;
}
{/code}

The first step is to create the input string, which is handled by the request object. After that the input string is sent to the serial port and reads data from the serial port. A serial class handles communications with a serial port. The last step interprets the data from the serial port and converts the information into a usable array.

Building the input string
Below is the method actionDeviceInfo of the request class. The _renderActionString method used here finishes the input string by adding a checksum.

{code type=php}
public function actionDeviceInfo($mac) {
// 0012 000D6F0000 729310
$str = self::ACTION_DEVICE_INFO . self::MAC_PREFIX . $mac;
return $this->_renderActionString($str);
}
{/code}

Reading the response
The readString method of the request class reads the first four characters of the string which represents the plugwise device action. Based on the device action the appropiate method for the input string will be invoked. Below is the method for reading the input string of a device info response.

{code type=php}
protected function _processDeviceInfo($string) {
if (strlen($string)!=66) {
return array(‘error’ => ‘Wrong length of Response::DeviceInfo string’);
}
// Prepare output data
$data = array(
‘sequenceNumber’ => hexdec(substr($string, 0, 4)),
‘macAddress’ => substr($string, 14, 6),
‘clockYear’ => hexdec(substr($string, 20, 2)),
‘clockMonth’ => hexdec(substr($string, 22, 2)),
‘clockMinutes’ => hexdec(substr($string, 24, 4)),
‘logAddress’ => hexdec(substr($string, 28, 8)),
‘currentState’ => substr($string, 36, 2),
‘currentFrequency’ => substr($string, 38, 2),
‘currentVersion’ => substr($string, 40, 12),
‘currentFirmware’ => substr($string, 52, 8),
‘unknownParam’ => substr($string, 48, 2),
‘otherParam1’ => hexdec(substr($string, 50, 12)),
‘crcString’ => substr($string, 60, 4)
);
return $data;
}
{/code}

Getting the source
The source is available on GitHub as a seperate project: PlugWeb-Driver. The driver library will be included within the PlugWeb application.

Future blog posts in this series
Next time I will blog about the following aspects of the PlugWeb system.
* Plugweb introduction
* Creating the driver
* Unit testing the driver
* Designing the sqlite database
* Creating background daemon
* Creating a service layer with zend framework
* Designing the website interface with javascript/css
* Creating a PlugWeb Android application

protected function _processDeviceInfo($string) {
if (strlen($string)!=66) {
return array(‘error’ => ‘Wrong length of Response::DeviceInfo string’);
}

// Prepare output data
$data = array(
‘sequenceNumber’ => hexdec(substr($string, 0, 4)),
‘macAddress’ => substr($string, 14, 6),
‘clockYear’ => hexdec(substr($string, 20, 2)),
‘clockMonth’ => hexdec(substr($string, 22, 2)),
‘clockMinutes’ => hexdec(substr($string, 24, 4)),
‘logAddress’ => hexdec(substr($string, 28, 8)),
‘currentState’ => substr($string, 36, 2),
‘currentFrequency’ => substr($string, 38, 2),
‘currentVersion’ => substr($string, 40, 12),
‘currentFirmware’ => substr($string, 52, 8),
‘unknownParam’ => substr($string, 48, 2),
‘otherParam1’ => hexdec(substr($string, 50, 12)),
‘crcString’ => substr($string, 60, 4)
);
return $data;
}

Website Pin Facebook Twitter Myspace Friendfeed Technorati del.icio.us Digg Google StumbleUpon Premium Responsive

Share/Bookmark
This entry was posted in Open Source, PHP, PlugWeb, Projects and tagged , , , , , . Bookmark the permalink.

6 Responses to PlugWeb: Creating the driver

  1. Jakob says:

    When can we expect a (beta) release of the project?
    Will all parts be open source?

    • admin says:

      Hi Jakob,

      The PlugWeb project is open source! I already released the PHP PlugWeb-Driver, which can be found at: https://github.com/DirkEngels/PlugWeb-Driver. With a little clean up I can release a development version of the PlugWeb web application, but it only contains the basic components, but not a fully working version yet. Send me an e-mail if you have interesting idea’s or would like to contribute to the project.

      Dirk

  2. Nico says:

    Hallo Dirk,

    Interesant project!
    Voor meer info of vragen over plugwise kun je ook Plugwise sectie gebruiken, mocht je die nog niet gevonden hebben.

    Aangezien de Source application data naar Plugwise stuurt denk ik dat er wel veel mensen dit project zullen gaan volgen. Ik gebruik zelf geen linux maar wel xamp onder windows, hopelijk gaat daar in de loop der tijd ook een driver voor komen. Mocht desondanks iets kunnen testen laat het maar weten.

    • admin says:

      Hoi Nico,

      Dank je voor je interesse in het project. De laatste tijd heeft het beetje stil gelegen i.v.m. werk en enkele andere IT hobby projecten. Door de toegenome aandacht van de afgelopen tijd, ben ik langzaam weer aan de gang met het PlugWeb project. Wat betreft de web applicatie ben ik reeds al aardig op weg naar een werkende versie (met de basis functionaliteit (aan/uit + beetje info). Ik zal wat ik nu heb z.s.m. op GitHub plaatsen.

      Dirk Engels

  3. marco says:

    Beste Dirk,

    Van de week ben ik op je site terecht gekomen en ben zeer geinteresserd in je project!
    Echter wel jammer om te zien dat het na het opzetten van de driver redelijk stil is gevallen.

    Oktober vorig jaar gaf je aan de je bezig bent met een webapplicatie. Kun je al een ALPHA,ALPHA,ALPHA versie met mij/ons delen?

    Ben zeer benieuwd naar je vorderingen!

    Mvg,
    Marco

  4. Hallo Dirk,

    Ik heb kort geleden plugwise home pakket gekocht, en heb jouw driver hier gevonden.
    Ik hoop, dat je deze drivers van een mysql database wil voorzien en een webpagina.
    Het zou gelijk meer gebruikers aantrekken.

    vr.gr. Jan

Leave a Reply

Your email address will not be published. Required fields are marked *