Luup Plugins ByHand - Revision history

A-lurker: /* */

2015-02-16T21:37:29Z

‎

A-lurker: /* */

2014-02-03T23:41:44Z

‎

A-lurker: /* */

2014-02-03T23:28:24Z

‎

A-lurker: /* */

2014-02-03T23:25:11Z

‎

A-lurker at 23:01, 3 February 2014

2014-02-03T23:01:46Z

A-lurker at 08:52, 12 July 2013

2013-07-12T08:52:47Z

Gengen: Add description of element.

2013-07-07T20:01:06Z

Add description of <files> element.

A-lurker at 00:50, 17 June 2013

2013-06-17T00:50:49Z

A-lurker: /* Walkthrough to create a device */

2013-06-12T10:55:27Z

‎Walkthrough to create a device

A-lurker at 10:20, 12 June 2013

2013-06-12T10:20:37Z

@@ Line 39: / Line 39: @@
 === <handleChildren> ===
 If this flag is 1, then any actions that are sent to one of this device's children will be handled within this devices implementation file. Look at the I_GC100.xml file to see how this is done. The GC100 is a parent device which has no services or actions, but has child devices like IR transmitters and relays. This implementation file handles the SwitchPower/SetTarget action for the relays, as well as the SendProntoCode action for the ir transmitters, even though those actions will be sent to the GC100's child device--not the device GC100 itself.
 === <functions> ===

@@ Line 30: / Line 30: @@
 *<tt>raw</tt> - makes no modifications to outgoing data, and calls your incoming data callback for each byte received.  This adds more overhead since the engine needs to call your Luup function for every character, and makes your code complex.  So, generally avoid using '<tt>raw</tt>' and let us add support for your protocol if you have a new one we don't yet support.
-Caution: The <protocol> tag can be either in the I_xxxx file or the D_xxxx file or both. If the latter, they must be identical.
+Caution: the <protocol> tag can be either in the I_xxxx file or the D_xxxx file or both. If the latter, they must be identical.
-Hint: With verbose logging enabled - log lines starting with "52" are RX data, those with "51" are TX data.
+Hint: with verbose logging enabled - log lines starting with "52" are RX data, those with "51" are TX data.
 === <ioPort> ===

← Older revision		Revision as of 23:28, 3 February 2014
Line 31:		Line 31:

	Caution: The <protocol> tag can be either in the I_xxxx file or the D_xxxx file or both. If the latter, they must be identical.		Caution: The <protocol> tag can be either in the I_xxxx file or the D_xxxx file or both. If the latter, they must be identical.
		+
		+	Hint: With verbose logging enabled - log lines starting with "52" are RX data, those with "51" are TX data.

	=== <ioPort> ===		=== <ioPort> ===

@@ Line 29: / Line 29: @@
 *<tt>stxetx</tt> - all incoming commands are surrounded by STX and ETX characters.  If you send the string "test" the framework will add the STX before and the ETX at the end, and if the string "<tt>''<stx>''test''<etx>''</tt>" is received, the framework will strip the STX and ETX and pass the string "test" to your incoming data handler.
 *<tt>raw</tt> - makes no modifications to outgoing data, and calls your incoming data callback for each byte received.  This adds more overhead since the engine needs to call your Luup function for every character, and makes your code complex.  So, generally avoid using '<tt>raw</tt>' and let us add support for your protocol if you have a new one we don't yet support.
 === <ioPort> ===

@@ Line 25: / Line 25: @@
 Valid values for this tag are:
-*<tt>crlf</tt> - all incoming commands are terminated with a carriage return+line feed character, and all outgoing data should have a cr+lf appended.
+*<tt>cr</tt> - all incoming commands are terminated with a carriage return+line character, and all outgoing data should have a cr appended. Incoming data will have the cr stripped off.
 *<tt>stxetx</tt> - all incoming commands are surrounded by STX and ETX characters.  If you send the string "test" the framework will add the STX before and the ETX at the end, and if the string "<tt>''<stx>''test''<etx>''</tt>" is received, the framework will strip the STX and ETX and pass the string "test" to your incoming data handler.
 *<tt>raw</tt> - makes no modifications to outgoing data, and calls your incoming data callback for each byte received.  This adds more overhead since the engine needs to call your Luup function for every character, and makes your code complex.  So, generally avoid using '<tt>raw</tt>' and let us add support for your protocol if you have a new one we don't yet support.
@@ Line 95: / Line 96: @@
 ==== <ir> ====
-Put an ir code in pronto format in this tag. Luup will send a SendProntoCode action to whatever device is specified as the [[Luup IO Device]] in the [[Luup Configuration File]].
+Put an ir code in pronto format in this tag. Luup will send a SendProntoCode action to whatever device is specified as the [[Luup IO Device]] in the [[Luup Configuration File]]. Note that other formats besides pronto format can be used. Refer to the [[Luup_Declarations#<ir>|IR tag]]
 ==Walkthrough to create a device==

@@ Line 20: / Line 20: @@
 The settings node contains various settings for the implementation.
-protocol: Is the protocol to use to talk to the device if you'll be sending data over the network or a serial port. The protocol tag tells Luup what's considered a single ''chunk'' of data. By using a format, from the supported list below, you avoid byte-by-byte processing on input streams as the Luup engine will ''chunk'' the data to you and pass it to your Lua code handling <tt><incoming></tt> requests.
+=== <protocol> ===
 Lua code is much cleaner when it handles data in chunks.  If you have a protocol that's not natively supported, and is likely to be used by other devices, let us know and we'll add it to the Luup engine so you don't need to mess with it.
@@ Line 28: / Line 29: @@
 *<tt>raw</tt> - makes no modifications to outgoing data, and calls your incoming data callback for each byte received.  This adds more overhead since the engine needs to call your Luup function for every character, and makes your code complex.  So, generally avoid using '<tt>raw</tt>' and let us add support for your protocol if you have a new one we don't yet support.
-ioPort: One way to have the device talk to another device on the internet. If you put a TCP port number here, an outgoing connection attempt is made automatically when the device initializes. (The remote IP address should be placed in the 'ip' box in the device's advanced configuration tab.)
+=== <ioPort> ===
+=== <handleChildren> ===
-handleChildren: If this flag is 1, then any actions that are sent to one of this device's children will be handled within this devices implementation file. Look at the I_GC100.xml file to see how this is done. The GC100 is a parent device which has no services or actions, but has child devices like IR transmitters and relays. This implementation file handles the SwitchPower/SetTarget action for the relays, as well as the SendProntoCode action for the ir transmitters, even though those actions will be sent to the GC100's child device--not the device GC100 itself.
+If this flag is 1, then any actions that are sent to one of this device's children will be handled within this devices implementation file. Look at the I_GC100.xml file to see how this is done. The GC100 is a parent device which has no services or actions, but has child devices like IR transmitters and relays. This implementation file handles the SwitchPower/SetTarget action for the relays, as well as the SendProntoCode action for the ir transmitters, even though those actions will be sent to the GC100's child device--not the device GC100 itself.
 === <functions> ===
 Put here the Lua code for functions you want to be able to use in other places in your Lua code. You can also declare local variables here before the functions are described. Watch out for XML syntax. In particular, the > and >= comparison operators should be escaped.

@@ Line 14: / Line 14: @@
 == The Luup XML implementation file ==
-I_GC100.xml is a full featured, functional implementation for the Global Cache GC100, which is an ethernet device with relay switches, input sensors, infrared transmitters and serial ports. I_GC100.xml shows a complete Luup plugin with parent/child devices. The corresponding UPnP Device specification file is D_GC100.xml. In all the implementation files the top-level XML tag (ie root node) is called "implementation". It contains the following nodes:
+I_GC100.xml is a full featured, functional implementation for the Global Cache GC100, which is an ethernet device with relay switches, input sensors, infrared transmitters and serial ports. I_GC100.xml shows a complete Luup plugin with parent/child devices. The corresponding UPnP Device specification file is D_GC100.xml. In all the implementation files the top-level XML tag (ie root node) is called "implementation". It contains the following elements:
 === <settings> ===
@@ Line 35: / Line 35: @@
 === <functions> ===
-Put here the Lua code for functions you want to be able to use in other places in your Lua code. You can also declare local variables here before the functions are described.
+Put here the Lua code for functions you want to be able to use in other places in your Lua code. You can also declare local variables here before the functions are described. Watch out for XML syntax. In particular, the > and >= comparison operators should be escaped.
 === <startup> ===

@@ Line 59: / Line 59: @@
 In the case of the GC100, (see: I_GC100.xml), on/off of the relays happens immediately. So the implementation is inside a 'run' tag, which sets the "Status" variables. In the case of SendProntoCode, the implementation is inside a 'job' tag since the pronto commands may take time.
-When you have Lua code inside a 'job' tag, Luup will return 'OK' to the Control Point in response to the action, and then queues up the job and runs the Lua in your 'job' code. The job code returns 2 values: 1) the status of the job, and 2) how long to wait before the job times out in seconds. The status can be:
+When you have Lua code inside a 'job' tag, Luup will return 'OK' to the Control Point in response to the action, and then queues up the job and runs the Lua in your 'job' code. The job code returns 2 values:
-=job_WaitingToStart: In vera's UI a job in this state is displayed as a gray icon. It means it's waiting to start. If you return this value your 'job' code will be run again in the 'timeout' seconds
+) the status of the job
-=job_Error, or 3=job_Aborted: In vera's UI a job in this state is displayed as a red icon. This means the job failed. Your code won't be run again.
+) how long to wait before the job times out in seconds.
-=job_Done: In vera's UI a job in this state is displayed as a green icon. This means the job finished ok. Your code won't be run again.
+The status can be:
+*0=job_WaitingToStart: In vera's UI a job in this state is displayed as a gray icon. It means it's waiting to start. If you return this value your 'job' code will be run again in the 'timeout' seconds
-=job_WaitingForCallback: In vera's UI a job in this state is displayed as a moving blue icon. This means the job is running and you're waiting for return data. Any data that comes in while the job is in this state will go to the lua code in the job's 'incoming' tag. If no data comes in before the number of seconds you return in the timeout, then the code in the job's 'timeout' tag is run.
+*2=job_Error, or 3=job_Aborted: In vera's UI a job in this state is displayed as a red icon. This means the job failed. Your code won't be run again.
 So in the SendProntoCode job code for the I_GC100, we return 5,10 which means we're waiting for data and should wait up to 10 seconds.

@@ Line 101: / Line 101: @@
 Modify the UPnP device specification file as needed, such as changing the manufacturer and model.  Do not worry about the UDN tag as Luup will create a UDN for you automatically.  If your device is functionally the same as the template you started from, leave the deviceType the same.  If it's different, modify the deviceType replacing the "schemas-upnp-org" or "micasaverde-com" with some domain that you have, or if you don't have one, just use your name.  Leave the :device: but change the word after it to describe your device.  The deviceType must contain only a-z, 0-9, : and -.
-In the serviceList tag, add all the services you will implement.  You can also create new services at this time.  Save your new device file and service files as D_[some name] and S_[some name].  This is not mandated by UPnP, but is a convention we use so it's easy to recognize the file type by the name.
+In the '''<serviceList>''' tag, add all the services you will implement.  You can also create new services at this time.  Save your new device file and service files as D_[some name] and S_[some name].  This is not mandated by UPnP, but is a convention we use so it's easy to recognize the file type by the name.
 Now refer to "The Luup XML implementation file" section above to learn how to create an implementation file.

@@ Line 45: / Line 45: @@
 This is where you specify what to do when an action comes in. Create an "action" node for each action, which contains "serviceId" and "name" tags to indicate what action is being implemented. The "name" tag refers to the name of the Action as defined in the UPnP Service Specification file.
-There are several different nodes you can put within the "action" node.
+==== function declarations ====
-==== <ir> ====
+Whatever Lua code you create in the tags will be put inside a function automatically by the Luup engine, and your code will be passed variables that are relevant to whatever the code needs to do. For example, the code inside the 'run' tag is passed lul_device,lul_settings where lul_device is the id of the device the action was sent to, and lul_settings has the arguments to the UPnP action. See: [[Luup Declarations]] for details.
-Put an ir code in pronto format in this tag. Luup will send a SendProntoCode action to whatever device is specified as the [[Luup IO Device]] in the [[Luup Configuration File]].
+There are several different nodes you can put within the "action" node.
 ==== <run/job/incoming/timeout> ====
@@ Line 87: / Line 87: @@
 [[Luup Declarations]] lists what variables this Lua code receives and what it should return.
-=== function declarations ===
+==== <ir> ====
-Whatever Lua code you create in the tags will be put inside a function automatically by the Luup engine, and your code will be passed variables that are relevant to whatever the code needs to do. For example, the code inside the 'run' tag is passed lul_device,lul_settings where lul_device is the id of the device the action was sent to, and lul_settings has the arguments to the UPnP action. See: [[Luup Declarations]] for details.
+Put an ir code in pronto format in this tag. Luup will send a SendProntoCode action to whatever device is specified as the [[Luup IO Device]] in the [[Luup Configuration File]].
 ==Walkthrough to create a device==