List of variables for each plugin

Plugins & Plugin Development General Plugin Discussion
1

A list of all the variables for each plugin would be extremely helpful for those of us who are Luup-challenged.

I’m learning to script scenes using luup but I frequently find myself (and a lot of other folks in the forum) using the wrong serviceID and or variable name. If the list were published in the help for the plugin, it would be a huge help.

Thanks!

2

I do think it would be a good idea to standardize the documentation of plugins.

My solution to find what I want until that dream comes true:
With the following link and your vera’s ip address you get an overview of all devices and their variables and service id’s on your vera:
http://VERAIPADRESS:3480/data_request?id=user_data&output_format=xml

3

Sounds very cool. It doesn’t work for me. ???

4

Just change your Net setup settings to allow any connections.

5

Thanks, but I guess I need to add “Net setup challenged” to the previous “luup challenged” description of my skill set. :-\

6

@CMRancho,

Try using a different browser.

JOD.

7

You could use this page as a reference: http://wiki.micasaverde.com/index.php/Luup_UPNP_Files

8

Also using link:

[b]http://veraipadress:3480/data_request?id=lu_device[/b] will also output the device data. It will be much smaller than user_data.

  • Garrett
9

[quote=“JOD, post:6, topic:170486”]@CMRancho,

Try using a different browser.

JOD.[/quote]
Switched to Firefox and it worked. Thanks!

And thanks to mcvflorin for the link to the UPNP files and to Garret for the simpler device list.

I really appreciate all the help, guys. This stuff is clearly not for the old, weak, and faint of heart!

10

I took a stab at jazzing up the existing documention for the “Lighting” devices that were on the original page created by MCV:
http://wiki.micasaverde.com/index.php?title=Luup_Variables

it by no means contains all the devices, and all their variables, but it contains some formatting ideas including:

[ul][li]a sub-section for the Service Variables[/li]
[li]a sub-section to place examples[/li]
[li]a table-format for the Service Variables to make them really stand out, since this has caused loads of headaches lately[/li][/ul]

I did a few to get feedback on the format, and the examples I’ve placed there (or edited from their originals). If people like the general model, community members can create similar ones for the other devices that are out there.

The big question I have is more of the appropriate granularity. Once we have a few 100 devices listed, this is going to get unruly, so what’s the “right” level for a single Wiki page:

eg. a Single device-Type
eg. a Cluster of pseudo-related / Categorized device-Types
eg. one big-fat searchable list

11

Just some remarks:

Most of [tt]http://wiki.micasaverde.com/index.php?title=Luup_Variables[/tt] is duplicating the UPnP specification.

Actions should be documented, too. [tt]http://192.168.x.y:3480/data_request?id=invoke&DeviceNum=z[/tt] could be used to get a list of the actions provided by a specific device. If the wiki would allow for JavaScript, we could provide an online ‘http style to luup.call_action style’ translator (and vice versa).

12

And I’m guessing that was done somewhat intentionally when it was originally setup. There’s method in that madness as:

[ul][li]a) It creates a one-stop shop for MiOS programmers to see stuff, without finding and trudging through various UPnP spec documents that, in some cases MiOS doesn’t implement, or doesn’t implement correct semantics[/li]
[li]b) You can hang examples off of it, ones that are specific to the MiOS environment (aka Luup)[/li]
[li]c) You can list the additional domain-values that some of these variables have, that aren’t in the raw spec (for better or worse)[/li]
[li]d) You can list the non-standard Variables that the MiOS team appears to have added, that also aren’t in the spec[/li][/ul]

Actions should be documented, too.
I agree. I started by providing examples that demonstrate the more common actions, but overall I believe these need to be documented/exampled also. I wasn't sure if there was a duplicate for that also, since I really don't want to create duplication within the Wiki pages, there's enough of that going around already.

We could also end up obsoleting [tt]Luup_Variables[/tt] as a page (so we don’t have duplicate pages all over the Wiki) and creating something more appropriately named to represent Luup Device programming behaviors.

It’s why I was looking for feedback on my original a/b/c items, so the appropriate Wiki page naming structure could be derived before we did that, along with what functional sub-sections people really need to see for each type of devices (variables, actions, parameters, domain-values, behaviors)… everything except bugs, as that’ll clutter stuff faster than you can imagine given the various product versions out there.

Of course, the bottom of each device defn could contain a “References” block, similar to what @Henk did for the HowTo pages, these could be used to link to related reference material (including UPnP documentation links, if folks felt strongly about it)

[tt]http://192.168.x.y:3480/data_request?id=invoke&DeviceNum=z[/tt] could be used to get a list of the actions provided by a specific device. If the wiki would allow for JavaScript, we could provide an online 'http style to luup.call_action style' translator (and vice versa).
As a one-time generator, perhaps. But ultimately we need real-users to document the real semantics of any State Variable and/or Action, along with the parameters, domain-values, error behavior, and sample snippets.

The generator will get you maybe 10% of that, the rest just requires folks to rollup their sleeves (the existing descriptions for Variables are woeful)

13

Services defined by the UPnP Forum are somewhat static, but UPnP services defined by Luup developers might change over time. Would you expect the Luup developers to synchronize the Wiki page with their documentation?

14

The [MiOS implemented] UPnP devices haven’t changed in eons, so the practical impact is low, relative to the benefits of not answering the same questions over and over again.

If they change in the MiOS implementation, then yes the documentation would need to be upgraded. If anything, the most likely source of change is MiOS, since they appear to hack-away at some of these items (without giving thought to documenting that)

eg. LastTrip, on a SecuritySensor1
eg. on ZWaveDevice1
eg. on HaDevice1

Which leads to another question. Documenting “by device”, doesn’t really handle some of these common service (like ZWaveDevice1, HaDevice1, et-al) which would need a model.

15

btw, what are you proposing as an alternative to the handling problem?

16

My recommendation is: use automatic creation of documentation as much as possible and delegate the creation of documentation to the plugin developers.

The syntax is there and easily parsable:

S_.xml, D_.json for variables/action not listed in S_.xml, even the I_.xml file could be parsed for variables and actions, the UPnP page in the wiki, …

The semantics for standard UPnP devices is there and the UPnP specification might be parsable without too much hassle.

What is really missing is a standard for documenting the semantics of status variables and actions for non-UPnP Forum Luup devices. I don’t know whether the UPnP specification allows for inline documentation. If it does, that would be the way to go. You could even think about adding UPnP actions like [tt]GetSemantics[|][/tt]. ;D

My approach might sound like serious overkill, but: how long did it take to jazz up the documentation for the ‘Lighting’ devices? And how much time will be needed to keep the documentation up to date, especially for Luup devices under development?

17

The bulk of the time was a one-time cost in creating the “look”. The rest was trivial.

18
I took a stab at jazzing up the existing documention for the "Lighting" devices that were on the original page created by MCV:

BTW, is there a stealth mode for editing the Wiki? :slight_smile: I cannot find your edit on [tt]http://wiki.micasaverde.com/index.php?title=Special:RecentChanges&days=30[/tt].

19
BTW, is there a stealth mode for editing the Wiki? :) I...
LOL! Yes, I'm visible in [i]bot-mode[/i], as are several others ;-)