Luup Plugins ByHand

Revision as of 02:29, 12 June 2009

Introduction to UPnP

UPnP (Universal plug and play) is the industry-standard way to communicate with devices. In UPnP the device that is doing the controlling (ie the remote control) is called a UPnP Control Point. The device which can be controlled is the UPnP Device. You describe the capabilities of a UPnP Device and tell the UPnP Control Points what the device can do by creating 2 types of XML files: 1) a single device specification file which has basic information on your device such as the manufacturer and model, and 2) one or more service specification files which describe a service. In UPnP a "service" is a list of variables and actions. Variables describe the current state of the device and actions describe what you can do with the device.

For example, a common service is "SwitchPower". This service describes the ability to turn something on and off. The main variable in the service is called "Status", and it has a value of 0 if the device is currently off or 1 if it's currently on. The main action in the service is called "SetTarget" which is how you turn the power on or off. The "SetTarget" action has an argument called "newTargetValue" which can be either 0 or 1 to indicate if the device should be turned on or off. Variables, then, are outgoing data from the UPnP Device to the UPnP Control Point, and actions are incoming data from the UPnP Control Point to the UPnP Device. Let's say your UPnP device is a light switch. The UPnP Control Point is perhaps a touch-screen web pad, and it will display an icon of a light switch to let the user control your UPnP light switch. The Control Point will first ask the UPnP light switch for the current value of the "Status" variable. If the variable is currently 1, the Control Point will display the light switch in the 'on' position. Now, if the user hits the 'off' button on the UPnP control point it sends the UPnP light switch a "SetTarget" action with the argument "newTargetValue" equals 0. After the light switch successfully turns off, the variable "Status" will change to 0 so anytime a UPnP control point that wants to know if the light is on or off can ask the light switch for the current value of the "Status" variable.

In the UPnP device's device description xml file there is a list of the services that the device implements with a cross reference to the service file. Whenever possible a service should be as small and re-usable as possible so other devices can use the same service file without creating the service's again from scratch. For example, there are both dimmable light switches, and simple on/off switches. Both kinds of switches support the ability to turn on and off, dimmable ones just add the ability to dim also. So, the most efficient thing to do is have a service called "SwitchPower" which describes the action to turn the switch on and off, and to have a separate service called "Dimming" which describes the action to dim the light. The on/off switch will support only the "SwitchPower" service, and the dimmable switch will support both the "SwitchPower" and the "Dimming" service. This is better than creating a "Dimming" service which does both on/off and dimming because if you did that, the maker of a UPnP control point would need to implement 2 different actions for the basic on/off. You do not want to make an individual service do more than one thing.

The UPnP forum is an industry consortium that approves specifications for UPnP devices. They have already approved standards for SwitchPower, Dimming, and so on. We will not want to modify these device or service specifications. We use them as they were ratified by the committee because that is what UPnP Control Points will be expecting. However there are lots of devices which the UPnP forum has not yet come up with a standard for. In this case each vendor can come up with his own solution. However, if there is an existing device+service specification that is already in use, particularly by a large company in the industry, we should use their device+service specifications (ie XML files) whenever possible since there are probably already UPnP Control Points out there that know how to talk to them.

Introduction to Luup plugins

The UPnP specifications define what the XML files look like and how a UPnP Control Point talks to a UPnP Device to get the current Variables and to send the device Actions. But that's where UPnP ends; it does not define the implementation, which is to say, how the device will implement the action. Normally UPnP devices write programming code to handle the implementation. Luup instead lets you store the implementation in a 3rd type of XML file we call the implementation file. In the implementation file you tell Luup what to do when it receives an action from a UPnP Control Point. The implementation file can contain infrared codes which Loop will send when the action comes in, binary data which Luup will send out a serial port, or some Lua code that Luup will run. The Lua code can set the current value of the variables for the device.

Luup handles all the complexities of the UPnP protocol. And the web-based Luup plugin generator handles all the complexities of XML (coming soon). So all you do is fill in the form which has basic information about your device, like the manufacturer and model, and the generator creates the UPnP Device specification for you. You can then check off which services your device implements, such as "SwitchPower" if it's something that can be turned on and off. If your device has new capabilities that aren't already in an existing service, the generator let's you create a new service by describing the actions your device implements, like "Brightness Up", or "Sensor Arm", etc. Lastly, the web generator let's you specify what to do when the action comes in. This is saved in the implementation file.

Description of the XML files

Because the web generator is not yet operational you need to create the XML files by hand. The easiest way to do this is to start with an existing device as a template that you modify to suit your needs.

 Therefore you do not need 

A Luup plugin is a UPnP Device that can be controlled by any UPnP Control Point.