Revision as of 08:08, 5 June 2013

Starting in UI4, Luup plugins can specify a static JSON file. This file describes how the plugin appears in the web interface.

What the static JSON file controls

• The icon used by the plugin in the dashboard.
• The text that displays in the one-to-two-row status message in the dashboard.
• Whether the icon changes depending on the value of a variable in the device (for example, a binary light's icon changes from lit to unlit).
• The tabs that appear in the device's detail dialog (when you click the wrench/spanner).
• The content of these tabs.
• The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.

Referencing the static JSON file from the Device XML file

The device XML file (customarly D_PluginName.xml) contains a reference to the static JSON file, in the staticJson element. Place the element as a child of the device element:

  <?xml version="1.0"?>
  <root xmlns="urn:schemas-upnp-org:device-1-0">
    <specVersion><!-- ... --></specVersion>
    <device>
      <deviceType>urn:schemas-futzle-com:device:holidayvirtualswitch:1</deviceType>
      <staticJson>D_HolidayVirtualSwitch1.json</staticJson>
      <!-- ... -->

Capitalization is important, as with all XML.

The static JSON file is customarily called D_PluginName.json.

The static JSON file

The static JSON file is a single JSON object (associative array).

Root keys

These keys have been seen at the top level in static JSON files in the wild:

flashicon

The device's icon, as a string. Despite the name, the icon is not related to Flash in UI4. See Luup plugin icons.

imgIconBody

A string which appears to have no effect.

imgIconDimmable

A string which appears to have no effect.

imgIconTurnable

A string which appears to have no effect.

imgIconMin

A string which appears to have no effect.

imgIconMax

A string which appears to have no effect.

halloIconsDir

A string which appears to have no effect. Usually contains "pics\/hallo", for reasons unknown.

inScene

When included and set equal to one, it enables any buttons, etc located on the "dashboard box", so they can be selected in the scene editor for use in scenes, rather than being grayed out.

DisplayStatus

A JSON object (associative array). For devices where the icon changes based on a variable's value, describes which variable, and the range of values that produce different icon images. See Luup plugin icons.

state_icons

A JSON array. For devices where the icon changes based on a variable's value, describes which icon files exist. See Luup plugin icons. Used only in firmware 1.5.401 or later.

doc_url

A JSON object (associative array). Appears to have no effect.

Tabs

A JSON array. Describes the tabs in the detail dialog, and what subset of the first tab appears in the dashboard. See Luup plugin tabs.

DeviceType

A JSON string. Must match the deviceType element in the corresponding device XML (D_PluginName.xml) file.

eventList

A JSON object (associative array). Describes the events that this plugin can produce. Events are triggers that can fire off actions in scenes. This key is required for UI4, and obsoleted in UI5. For UI5, use the eventList2 tag, which has a different format. For compatibility with both UI4 and UI5 you need the same information in both keys. See UI4 UI5 Migration for more information.

eventList2

see eventList, above.

sceneList

A JSON object (associative array). Describes the actions that this plugin can perform (for instance, as the action in a scene). This key is not required and is ignored in UI5, however it is needed for UI4 compatibility. See UI4 UI5 Migration for more information about its format.

sceneList2

see sceneList, above.