Luup plugin icons

The Luup plugin static JSON file describes the icon that appears in the dashboard of the UI4 web interface.

Icon format

All of Vera's icons are 42x42 pixel PNGs with transparency. Icons of other sizes will be resized to 42x42.

Configuration

The top-level key flashicon contains a string. This string is the name of an image file. The filename is either a relative path or a URL starting with "http".

Relative paths

If the filename is a relative path, it is relative to the directory /www/cmh/skins/default on the Vera. If the filename ends in the string ".swf", this extension is changed to ".png". (This is presumably a holdover from UI3, which was flash-based. In UI4, there is no reason to maintain this ruse, so just use the ".png" extension.)

Files installed in the "icons" directory are:

• Binary_Light.png
• Binary_Light_0.png
• Binary_Light_100.png
• Dimmable_Light.png
• Dimmable_Light_0.png
• Dimmable_Light_100.png
• Dimmable_Light_25.png
• Dimmable_Light_50.png
• Dimmable_Light_75.png
• Door_Lock.png
• Door_Lock_0.png
• Door_Lock_100.png
• Generic_IO.png
• Humidity_Sensor.png
• IR_Transmitter.png
• Insteon.png
• Ip_Camera.png
• Light_Sensor.png
• Motion_Sensor.png
• Motion_Sensor_0.png
• Motion_Sensor_100.png
• Power_Meter.png
• Scenes.png
• Temperature_Sensor.png
• Thermostat.png
• USB_UIRT.png
• Window_Covering.png
• Zwave.png
• advanced.png
• default.png
• default_device.png
• default_panel.png
• default_plugins.png
• device.png
• devices.png
• energy.png
• findvera.png
• generic_icon.png
• generic_sensor.png
• intro.png
• location.png
• music_audio.png
• plugins.png
• users.png

URLs

If the filename is a URL, it refers to a remote file on a web server.

Constant icons

For an icon that remains the same all the time, the flashicon key is all you need to provide. Ensure that the static JSON file does not contain a DisplayStatus key, and you are done.

Variable icons

For an icon that varies based on the value of a variable, place a DisplayStatus key at the top level of the static JSON file. Its value is a JSON object (associative array) with four keys:

Service

The Service ID of the variable that controls the icon. This can be found in the matching device XML file, under the serviceId element.

Variable

The variable name of the variable that controls the icon.

MinValue

The value that this variable has when it is considered "off" or at "0%". This can even be a string, if the variable is a string that takes two values.

MaxValue

The value that this variable has when it is considered "on" or at "100%". This can even be a string, if the variable is a string that takes two values.

Example for a binary switch:

  "DisplayStatus": {
        "Service": "urn:upnp-org:serviceId:SwitchPower1",
        "Variable": "Status",
        "MinValue": "0",
        "MaxValue": "1"
  }

Example for a variable which takes on a range of values.

  "DisplayStatus": {
        "Service": "urn:upnp-org:serviceId:Dimming1",
        "Variable": "LoadLevelStatus",
        "MinValue": "0",
        "MaxValue": "100" 
  }

The filename in flashicon undergoes a special transformation for variable icons. The extension ".png" is changed to "_0.png", "_25.png", "_50.png", "_75.png" or "_100.png" depending on the value of the service variable, linearly scaled from its range of MinValue:MaxValue to 0:100. Only the five levels 0, 25, 50, 75 and 100 occur; there is no finer-grained control of the images. For images which are not found (for instance, if the web server returns 404 Not Found) the next-higher level is used.

Consequently, at least three images, and as many as six, should be present for variable-icon plugins. For example, if flashicon contains http://example.com/image.png, the web server must be able to serve:

• http://example.com/image.png (for when the plugin is loading in the Luup engine)
• http://example.com/image_0.png
• http://example.com/image_100.png

and it should be able to serve (if the variable is a sliding scale):

• http://example.com/image_25.png
• http://example.com/image_50.png
• http://example.com/image_75.png