Controls

What is a "Control" on the AllThingsTalk platform?

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 onoff 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 control 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.

  1. "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

Comparison chart

You can use a Comparison chart control to visualise and compare historical data coming from multiple numerical assets. Only assets within a chosen ground are available.
When pinning control you have these options:

  • Manually choose which assets do you want to compare
  • Choose the time range from last 1 hour, 1 day, 1 week or 1 month of historical data.

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

Location

Show single asset location on a map. Your device needs to have an asset with location profile to use this control.

"control": {

"name": "map",

"extras": { "zoomLevel": 14 }

}

Supported profiles

  • Array of two numbers, for example [22.2100, 43.1229]
  • Object with specific format, for example { "lat": 22.2100, "long": 43.1299 }
  • Location

Example

Map

Use Map to show multiple device locations on a single map. Whenever a device changes it’s location, the map will auto-refresh so you don’t have to do it manually. When pinning this control, you won;t be asked for any input. Map will show all devices with location profile asset.

Example

JSON

Show JSON text in an object-formatted manner

  1. "control": { "name": "json" }

Example

Image

Use URL or base64 encoded string as value to show an image. Use refreshRate extras to refresh image (type: number, unit: second, default: 5 seconds).

"control": {

"name": "image",

"extras": {

"refreshRate": 0.2

}

}

Example

Image-Enum

Displays a an URL-linked image based on asset value. Use image-enum to hack a custom control with showing images that are hosted externally.

"control": {

"name": "image-enum",

"extras": {

"values": ["yes", "no"],

"imageUrls": [

"http://www.yesnobutton.com/yes1.gif",

"http://www.yesnobutton.com/no1.gif"

]

}

}

Example

Data log

Data log control shows historical asset data in a tabular view. Optionally, timestamp display can be turned off.

"control": {

"name": "asset-log",

"extras": {

"timestamp": false

}

}

 

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

Dropdown

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

Text editor

Allows you to input multiple lines of text.

"control": { "name": "text-editor" }

Example