What is a Control?

How to setup Pinboard Controls or UI Elements?

Omar Cruz avatar
Written by Omar Cruz
Updated over a week ago

Controls

Controls are web UI elements, like a LED image or a button, that graphically represent your asset state or data. Pinboards are a collection of controls.
You can simply set them in the control section of an asset. Just make sure the values your asset uses match the ones the control needs. For example, to show asset with profile "type": "number" and values 3.4 or 5.0 etc. as values, you should use a circle-progress or line-progress control rather than an on-off button.

Note that although there is a separation between Actuator and Sensor controls, you are free to use sensor controls for an actuator; for example if an actuator is updated using a rule. You might want the value to actuate the device without being able to edit it manually on a Pinboard.

Below you will find an overview and plenty of examples to make sure you set your profile and Controls the right way.

Sensor controls

On-Off

Shows boolean or two-member enum (of integer or string) as on or off LED-a-like control.

"control": { "name": "onoff" }

Example

{ "type": "boolean" }{ "type": "integer", "enum": [0, 1] }{ "type": "string", "enum": ["on", "off"] }

Line progress

Shows numerical value as a line progress.

"control": { 
    "name": "line-progress"
}

Example

Circle progress

Shows numerical value as a circle progress.

"control": { "name": "circle-progress" }

Example

Color

Show color for string or object asset.

"control": { "name": "color" }

String asset will work if it’s value matches a RGB color regular expression, for example:

"profile": { 
    "type": "string",
    "pattern":"^#([a-fA-F0-9]{6})$"
}

Object asset needs to follow the RGB form:

"profile": {
    "type": "object",
    "properties": {
        "r": { "type": "integer", "minimum": 0, "maximum": 255 },
        "g": { "type": "integer", "minimum": 0, "maximum": 255 },
        "b": { "type": "integer", "minimum": 0, "maximum": 255 }
    }
}

Similar works for color picker control.

Example

Chart

Show numerical data in a historical chart.

"control": { "name": "chart" }

Additional type and timeScale fields are available:

  • "type": "line-chart"  sets graph type to line chart

  • "type": "bar-chart"  sets graph type to bar chart

  • "timeScale": "<60m, 24h, 7d, 30d>"  sets the time window:

  • 60m : 60 minutes (1 hour)

  • 24h : 24 hours (1 day)

  • 7d : 7 days

  • 30d : 30 days

Example

Label

Show short in-line text.

"control": { "name": "label" }

Example

Showing colored label

Label control can be (background) colored by defining colors array field in extras:

"control": {
    "name": "label",
    "extras": {
        "values": [0, 1],
        "colors": ["red", "green"]
    }
}

Label gets green when asset state is "ok", yellow when it’s "warning" and red when it’s "danger":

"control": {
    "name": "label",
    "extras": {
        "values": ["ok", "warning", "danger"],
        "colors": ["#00ff00", "#ffff00", "#ff0000"]
    }
}

Showing text instead of raw value

Label control can show text that better explains the asset state than showing just it’s value:

"control": {
    "name": "label",
    "extras": {
        "values": [0, 1],
        "labels": ["Off", "On"],
        "colors": ["red", "green"]
    }
}

Text

Use text control to show textual data. Supported asset profiles are string and object. Optionally use extras to format text as json

"control": {   
    "name": "text",
    "extras": { "format": "json" }
}

Example

Lorem ipsum

Map

Show coordinates on a map.

"control": { 
    "name": "map",
    "extras": { "zoomLevel": 14 }
}

Supported profiles

  • Array of two numbers, for example [22.2100, 43.1229]

  • Location object, for example { "lat": 22.2100, "long"; 43.1299 }

Example

Actuator controls

Actuator controls allow user to send a command to an asset.

Toggle

Shows a toggle for a boolean or two-member enum.

"control": { "name": "toggle" }

Example

Push button

Allows you to push a button for boolean actuator

"control": { "name": "push-button" }

Extras

  • "type": "push-to-make" sends first value when pressed, second value when depressed (default)

  • "type": "push-to-break" sends second value when pressed, first value when depressed

Example

Slider

Allows you to slide to a numeric value.

"control": { "name": "slider" }

Example

Knob

Allows you to use a knob to set a numeric value.

"control": { "name": "knob" }

Example

Spinner

Spin to a numeric value. Additional step field is available ("step": <number>) to set the stepper increment or decrement. Default step is 1.

"control": { 
    "name": "spinner",
    "extras": {
        "step": 15
    }
}

Example

Color picker

Allows you to choose a color from a pallete.

"control": { "name": "color-picker" }

Example

Shows a dropdown selector for enum-based assets.

"control": { "name": "dropdown" }

Example

Input

Allows you to input one line of text.

"control": { "name": "input" }

Example

Related articles:

Did this answer your question?