Interface Blocks


A device's interface consist of the device's functional blocks and their datapoints (see Datapoint Objects). Most devices present a static interface. Tools cannot change the static interface directly, but can change aspects within the interface (such as a light’s brightness).  Advanced devices can support the ability to have their interface changed after the device has been created. This is known as a dynamic interface. Datapoints and blocks that are added to a dynamic interface after the device has been created behave in exactly the same way as the static portions of an interface, except for the fact that dynamic items can also be removed after they have been added.

The Device Interface Object (if), reports the device’s interface in blocks of functionality. Interface block objects are published in the feedback channel and can be written to in the request channel.

Each functional block implements a profile.  Profiles and the datapoints and properties they contain are described through the IAP data type system, see Data Type Definitions.

A profile describes what can be implemented, while an IAP device interface in the feedback channel describes what has been implemented. For example, one profile may list a number of mandatory and optional datapoints, or may define other degrees of freedom, such as the size of an array of calibration points.  A block implementing the profile must implement the mandatory aspects, but has a certain amount of freedom for the implementation of optional items or other implementation-specific details, such as selecting a size of a calibration point array within the rules detailed within the profile.

Interface Topics

Topics under the Interface Object, if, follow the Block_Type/Block_Handle scheme. The Block_Type is a short name for the block’s principal function, such as “light” or “luminosity”.  The Block_Handle is a Block_Index within this Block_Type, in this device. A Block_Handle consists of an integer number between 0 (zero) and N-1, where N is the maximum number of blocks within this Block_Type, in this device.  For example, a device with two lights and one occupancy sensor might report these as:




Block_Index values must meet the general rules for IAP handles described in IAP/MQ Topic Syntax.

Blocks do not report status. Status is reported through the Events channel, and the Device Status object.

Blocks typically provide a principal Datapoint object (see Datapoint Objects)

Block Object Properties

Each block has properties that implement profile datapoint or property members, and plain properties which are not governed by the profile. The desc, href, or loc properties shown in the example below are examples of plain properties. 

Applications can identify properties that implement profile datapoint and property members using different strategies: 

  • Many applications have intimate knowledge of the device type that the application manages, and therefore have detailed knowledge about the profiles and profile members implemented. Such an application has built-in knowledge to distinguish plain block properties from those implementing profile datapoint and property members.
  • Generic applications may need to distinguish block properties from those implementing profile datapoint and property members at runtime. Such an application can inspect the profile that governs the block, and infer that any block property that is listed as a profile member with the same name, implements that member. Another method identifies block properties as datapoint properties if they have a value property, a type property, and a property property which is set to the Boolean constant false. Properties implementing a property member also have value, type, and property properties, where the latter is set to the Boolean constant true.

Properties that implement a profile datapoint and property members have special qualities, discussed in Datapoint Objects.

The following is an example of a block object.

Field Name   




A datapoint within this block (here: "cv" is short for "control value").


         type: "0/light-hlsb",
         cat: "out",
         value: {
             h: 48,
             l: 0.6,
             s: 0.67,
             b: 0.7



(Optional) Human-readable description.

Example: “Ceiling light by the window”



An optional URL to documentation in HTML format. This must be reachable via HTTP or HTTPS, and must be provided in HTML. A CMS can embed this human-readable documentation within its user interface.



Location object

Identifies the location of the edge device.  See Location Object.

     {   /* location: */
        desc: "pole W8N1", 
        lat: 51.5059,
        lng: -0.33302

pvdatapointA datapoint within this block (here: "pv" is short for "process value").



A datapoint within this block (here: "sp" is short for "setpoint").



The IAP type reference to the profile implemented with this block. Changes to block type are ignored.

Example: cm/light