Luup Plugins - Revision history

A-lurker at 04:55, 13 June 2013

2013-06-13T04:55:22Z

A-lurker at 04:54, 13 June 2013

2013-06-13T04:54:56Z

DaveL17: Fixes typo. Luup instead of Loop.

2011-11-22T02:13:12Z

Fixes typo. Luup instead of Loop.

Javier: Category:Development

2010-04-13T05:09:24Z

Category:Development

LibraSun at 16:36, 1 August 2009

2009-08-01T16:36:44Z

Micasaverde: /* Introduction to UPnP */

2009-06-12T18:45:29Z

‎Introduction to UPnP

Micasaverde: /* IO Port */

2009-06-12T16:52:44Z

‎IO Port

Micasaverde: /* The Luup configuration file */

2009-06-12T16:50:04Z

‎The Luup configuration file

Micasaverde at 16:48, 12 June 2009

2009-06-12T16:48:19Z

Micasaverde at 16:15, 12 June 2009

2009-06-12T16:15:55Z

@@ Line 1: / Line 1: @@
 [[Category:Development]]
-If you didn't already come from the [[Luup_Intro]] page, start there to see what Luup Plugins are intended for. If you want to see what the device files do, then go to the [[Plugin_Creation_Tutorial|Plugin Creation Tutorial]]
+If you didn't already come from the [[Luup_Intro]] page, start there to see what Luup Plugins are intended for. If you want to see what the Plugin files do, then go to the [[Plugin_Creation_Tutorial|Plugin Creation Tutorial]]
 ==Introduction to UPnP==

@@ Line 1: / Line 1: @@
 [[Category:Development]]
-If you didn't already come from the [[Luup_Intro]] page, start there to see what Luup Plugins are intended for.
+If you didn't already come from the [[Luup_Intro]] page, start there to see what Luup Plugins are intended for. If you want to see what the device files do, then go to the [[Plugin_Creation_Tutorial|Plugin Creation Tutorial]]
 ==Introduction to UPnP==

@@ Line 16: / Line 16: @@
 == 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.
+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 Luup 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.

← Older revision		Revision as of 05:09, 13 April 2010
Line 1:		Line 1:
		+	[[Category:Development]]
	If you didn't already come from the [[Luup_Intro]] page, start there to see what Luup Plugins are intended for.		If you didn't already come from the [[Luup_Intro]] page, start there to see what Luup Plugins are intended for.

@@ Line 13: / Line 13: @@
 A list of UPnP ratified device and service files is available at [http://upnp.org/resources/default.asp] and the .zip file there includes the complete specs for UPnP in the document: UPnP-arch-DeviceArchitecture-v1 1-20081015.pdf
-==Introduction to Luup plugins==
+== 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.
+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.
+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.
-There is not necessarily a 1:1 relationship between an implementation file and either device or specification files.  For example, you may create a device which has some of the Lua code in one implementation file, and some other Lua code in another implementation file.  The same implementation file can contain both infrared codes, serial data, and Lua code.
+There is not necessarily a 1:1 relationship between an implementation file and either device or specification files. For example, you may create a device which has some of the Lua code in one implementation file, and some other Lua code in another implementation file. The same implementation file can contain both infrared codes, serial data, and Lua code.
-Luup also supports the concept of parent-child, or embedded, devices.  For example, the Global Cache gc-100 is an ethernet device that contains a couple serial ports, some relay switches, some infrared transmit ports, and some on/off input sensors.  Each relay/sensor/ir/serial port is logically a separate device, since each one can do something distinct.  One relay could be connected to a doorbell, the other to a siren.  So, in Luup there is one parent device called the "gc100", which actually doesn't have any UPnP services at all, but it has child devices for each of the sensors/relays/ports.  The relays are logically like on/off switches, so rather than creating our own service, we use the standard UPnP device for a binary switch with the standard UPnP service "SwitchPower".  This way any UPnP control point will see the relays and, without any custom work for the gc100, the control point can show them to the user as an on/off switch.  There are other device+service files for the inputs and ports.  In Luup you have the concept of a parent device being able to be responsible for the child devices.  So, the way we implemented the gc100 is that the parent device has no UPnP services, but it does have a single implementation file "I_GC100.xml", which tells Luup how to implement all the actions from all the services that it's child devices may have.  So in this case, there is one implementation file for many devices and services.  We could have broken this into separate implemenation files, for example one for each service.  However since the implementation is specific to the gc100 and not likely to be re-usable with another device, we just put all the gc100 implementation in a single file.  You may want to add support for some other type of on/off switch and you could do that by using the same standard UPnP device+specification files, but instead you would create your own implementation file.  The UPnP Control Point will never know the difference; it just sees a standard a UPnP light switch device and sends the 'on/off' actions the same way.
+Luup also supports the concept of parent-child, or embedded, devices. For example, the Global Cache gc-100 is an ethernet device that contains a couple serial ports, some relay switches, some infrared transmit ports, and some on/off input sensors. Each relay/sensor/ir/serial port is logically a separate device, since each one can do something distinct. One relay could be connected to a doorbell, the other to a siren. So, in Luup there is one parent device called the "gc100", which actually doesn't have any UPnP services at all, but it has child devices for each of the sensors/relays/ports. The relays are logically like on/off switches, so rather than creating our own service, we use the standard UPnP device for a binary switch with the standard UPnP service "SwitchPower". This way any UPnP control point will see the relays and, without any custom work for the gc100, the control point can show them to the user as an on/off switch. There are other device+service files for the inputs and ports. In Luup you have the concept of a parent device being able to be responsible for the child devices. So, the way we implemented the gc100 is that the parent device has no UPnP services, but it does have a single implementation file "I_GC100.xml", which tells Luup how to implement all the actions from all the services that its child devices may have. So in this case, there is one implementation file for many devices and services. We could have broken this into separate implemenation files; for example, one for each service. However since the implementation is specific to the gc100 and not likely to be re-usable with another device, we just put all the gc100 implementation in a single file. You may want to add support for some other type of on/off switch and you could do that by using the same standard UPnP device+specification files, but instead you would create your own implementation file. The UPnP Control Point will never know the difference; it just sees a standard a UPnP light switch device and sends the 'on/off' actions the same way.
 ==IO Port==

← Older revision		Revision as of 18:45, 12 June 2009
Line 10:		Line 10:

	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.		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.
		+
		+	A list of UPnP ratified device and service files is available at [http://upnp.org/resources/default.asp] and the .zip file there includes the complete specs for UPnP in the document: UPnP-arch-DeviceArchitecture-v1 1-20081015.pdf

	==Introduction to Luup plugins==		==Introduction to Luup plugins==

@@ Line 23: / Line 23: @@
 ==IO Port==
-Most Luup plugins are simply interfaces to talk to an external piece of hardware using infrared (a/v devices like TV's), RS232 (high-end a/v gear, alarm panels, etc.), Network (IP cameras and other IP devices), and a handful of other connections like RS485.  In this case the Luup plugin will effectively act as a translator to go from UPnP to the device's native communication (i/r, RS232, etc.).  All these communication methods (i/r, rs232, network) can be thought of as 'input/output', or IO, because you get data in from the device and send data out to the device.  Infrared is often output-only since generally you can only send i/r codes to the device.  If you're writing a device that does not talk to some piece of external hardware this section doesn't apply to you.
+Most Luup plugins are simply interfaces to talk to an external piece of hardware using infrared (a/v devices like TV's), RS232 (high-end a/v gear, alarm panels, etc.), Network (IP cameras and other IP devices), and a handful of other connections like RS485.  See [[Luup_IO_Device]] to learn how Luup handles automatically sending data to and receiving data from these devices.
-−
-The Luup engine handles all the low-level i/o.  Your plugin only needs to specify what type of i/o to use.  Then, within your plugin, when you want to send something to the device you use one of the Luup send commands, like lu_iop_send.  If the device is using infrared, whatever you send needs to be in pronto format.  If the device is serial/rs232 or network based, you can send anything and Luup will send this data to the device.  Generally serial and network devices have a low-level protocol to organize the data you send/receive into 'chunks'.  The most basic low-level protocol is to send/receive text commands that end with a carriage return+line feed (ie ENTER), such as: PowerOn [ENTER] ChannelUp [ENTER].  Luup handles the low-level protocol for you, meaning that any incoming data is automatically divided into 'chunks' of discrete commands, and handles adding separating characters like carriage return+line feed to anything you send.  This makes it much faster for you to write a plugin.
 ==The Luup configuration file==

@@ Line 29: / Line 29: @@
 ==The Luup configuration file==
-Often times plugins need configuration data that is unique to each user.  Generally I/O devices will have configuration data, such as the IP address if it's a network device, the baud rate and port number for a serial device, and the i/r transmitter to use.  This configuration data is never written into your plugin since that would mean the plugin needed to be modified for each user.  Rather, the plugin defines what type of configuration data it needs, and the Luup user interface let's the user specify this information, which gets saved in the Luup configuration file.
+See [[Luup_Configuration_File]] to learn how data for your Luup plugin, like the IP address, baud rate, values of UPnP Variables, etc., are stored.
-−
-You can view your configuration file by opening your web browser and going to the page: http://myip:49451/data_request?id=user_data&output_format=xml where "myip" is the IP address of your Vera.  Use the Firefox web browser since it has a built-in XML viewer.  Alternatively you can change the 'xml' at the end to 'json' to view the configuration file in it's native JSON format, and the web site [http://jsonlint.com/ jsonlint.com] will format the JSON data nicely so it's easy to read.
-−
-Vera's web-based user interface is the normal way the user specifies configuration data.  When the user goes to the 'devices' tab and adds a device, specifies what room it's in along with other options like the IP address, baud rate, etc., this is all stored in the configuration file.  The configuration file also stores the current value of the UPnP Variables, like the status of a light switch being on or off.  Your Luup plugin has access to all the data in the configuration file.
 ==The web-based Luup plugin generator==
 This is coming soon, and will allow you to create Luup plugins without knowledge of XML or UPnP using a fill-in-the-blanks web form and an infrared learning tool for control audio/video devices.  In the meantime, see [[Luup_Plugins_ByHand]] to see how to create the plugins by hand.

@@ Line 3: / Line 3: @@
 ==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.
+UPnP (Universal plug and play) is the industry-standard way to communicate with devices, see also [http://en.wikipedia.org/wiki/Upnp wikipedia] and [http://upnp.org upnp.org].  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 data files in [http://en.wikipedia.org/wiki/Xml XML] format: 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.
@@ Line 23: / Line 23: @@
 ==The web-based Luup plugin generator==
-This is coming soon.  In the meantime, see [[Luup_Plugins_ByHand]] to see how to create the plugins by hand.
+This is coming soon, and will allow you to create Luup plugins without knowledge of XML or UPnP using a fill-in-the-blanks web form and an infrared learning tool for control audio/video devices.  In the meantime, see [[Luup_Plugins_ByHand]] to see how to create the plugins by hand.