Disable configuration options (stateTypes) for a plugin


Is it possible to disable configuration options (stateTypes in .json file), depending on other options or combinations thereof?

Simple example e.g. for a lighting solution:
If the user configures a solid color, just one “color” property is needed.
If the user goes for some fading effect between two colors, a 2nd color - e.g. “alternative color” - is needed. But this later option would only be active if the fading effect option is selected.



That is not possible at this point. The thingClass definition is quite static. We’ll probably add some more dynamic stuff in there in the future, but so far enabling/disabling stateTypes didn’t come up in those thoughts. I’ll have to think about this…

One option I could think of would be to have an action like “fade” with parameters like “fromColor” and “toColor”. Not sure if that’s feasible for all the effects… Would that solve your use cases?

Also we’re thinking about an effectlight interface but not really sure yet how that would look like either. We’d need some more real world examples on what would be needed in order to define such an interface.

Then one other thing to consider is maybe the ScriptEngine. With nymea scripts one can run a ColorAnimation on a color state. Meaning, the plugin doesn’t need to implement such a loop itself but the user can enable a script which runs the animation, regardless of the actual plugin used. Right now one has to write the script manually but the plan is to have templates for that so the user would be able to enable such a color loop via the app and it would generate a script for it. This already works great when it comes to animating a single color on a light bulb (or an entire LED strip) but ideally I’d like also provide a mechanism for scripts to control multiple colors, for example on a WS2812 strip where each LED could be addressed individually. So far I was thinking of something like a state of type string which would take an array of RGB color values… But I haven’t tried that yet so not sure how well that would work.

Thank you!

In my case, it’s not critical for the functionality. I’m just exploring the interface and came to that question. Just thought it might help to guide users, if there was something to gray out options that are not used at the moment. It could also make sense to provide some grouping mechanism to e.g. separate lower level parameters like a GPIO pin number or IP address of a client from application-related parameters like a user-defined color or something similar.

I will look into the script engine then. Sounds like this would do what I’m thinking of.

The GPIO configuration should be in the paramTypes definition of the thing, not in the stateTypes. Also there are “settingsTypes” if you happen to need them…

  • paramTypes: Everything needed for setupThing, i.e. for connecting to the hardware. Changing a param requires a re-setup of the thing.
  • settingsTypes: Some user settings that can be changed at runtime. For instance a sensor could have a refresh interval setting here… Or a light could have a fade-duration setting when turning on/off
  • stateTypes: The actual states of a thing, like power state, current color, a sensor value etc…

Thank you for pointing that out! I was not aware of that.

When modifying my code, I ran into some issues:

If I define one of my settings (the SPI pin, so hardware related) as settingsType, the nymea-plugininfocompiler shows metadata errors.
“id”: “…”,
“name”: “spiPin”,
“displayName”: “SPI Pin”,
“defaultValue”: 10,
“type”: “int”,
“possibleValues”: [

It complains about the “possibleValues” part. Is there no option to restrict the selection for settings?

Hmm… I see…

So, first of all. Thank you very much for pointing this stuff out here. It clearly highlights where we need to improve on the documentation.

It’s allowedValues… The rationale behind that is that when looking at this from a client app point of view, a plugin would accept “allowed values” as parameters and needs to be prepared for “possible values” a state might have…

While one could argue about this wording (we actually did :)) I think the issue here is clearly that it’s not documented well enough.

I’ll create myself a task to document a) the usage of paramTypes vs settingsTypes and b) the meaning of allowedValues vs possibleValues.

As a kind of follow-up question:

There does not seem to be an ActionTypeId defined for settingsTypes, after running the nymea-plugininfocompiler. What would be the best way to propagate settings to a controller class, which (at least in my opinion) should not rely on having access to a Thing* pointer, therefore not access to thing->setting. Correct me, if you have other concepts here, but I think this translation should be handled within the IntegrationPlugin… class rather than whichever hardware-related classes.

I just realized that this is probably explained at the bottom of this page.

Are the settingChanged events called upon plugin-loading or only at a later point, when the user changes something?

When the setupThing() method is called for the thing in question, the settings will already be initialized (e.g. defaults on a newly set up thing or whatever the config holds on restarts). You can read the values there. The changed event is only emitted when a value changes at runtime.

Hey @hd512

Yesterday I did some work on the documentation and improved the bits and pieces that were not clear to you. It’s not published yet (I want to work a bit more on it) but you can see it on https://preview.nymea.io/documentation/developers/integrations/thing-class

I hope things are not more clear.