Skip to end of metadata
Go to start of metadata

Overview


Once a device is in operation in the field, the user needs a means of monitoring the data collected from it with a graphical interface. GadgetKeeper provides several Dashboard Widgets, which can display this collected data in various graphical or tabular formats. There are also several widgets that are not meant to display data graphically, but are used to execute various API interaction functions, similar to the execution procedures described for the UI, REST API, and script functions. These widgets can be used to activate a method/event, get/set a property value, etc.

It is important to note that there are two sources of data which can be used for the graphical "Data Display" widgets:

If using property values as the data source, the device could be programmed to send data values to GadgetKeeper periodically by a schedule or user interaction on the device. A message would be set using the JSON-RPC 2.0 standard. as explained in Messaging API Format. The message contains the ID number of the "thing" and "property", and the data values are given as parameters

If using event values as the data source, this value must be referenced to a property value from a remote device. A method or script property must be created on GadgetKeeper which retrieves data from the device, and then calls an event that contains this data as a value.The device could then be programmed to send data values to GadgetKeeper by a schedule or user interaction using the Messaging API format. The message would contain the ID number of the method to call and the data values are given as the method's arguments. As the method is called, it inserts the arguments in the called event.

It is also possible for GadgetKeeper to periodically call the device by a schedule or user interaction to retrieve data values (using either events or properties as a data source). This can be done manually by UI or a REST API tool, or a method can be coded to call the device by issuing a "GET" request, which is a standard HTTP method on the REST API platform. This is explained in more detail on Scripting Recipes, and the command line would look like:

If "Event" is the data source, the method should also activate the appropriate event with "remoteValue" given as the event value:

Any data values resulting from property updates or event activations can be used by dashboard widgets to create a graph, plot charts, etc.

Creating a dashboard


The user must first have a a dashboard created for the device, which is used to display the widgets.

  • Open the "Dashboards" tab by clicking "Dashboards" in the main menu.
  • Click the green "plus" sign on the top right to open the "Create Dashboard" dialog box:
FieldRequiredDescriptionDialog
Titlex

Name of dashboard

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

 

Description Description of dashboard

 

 

 

 

After a dashboard has been created, it can be edited anytime by:

  1. Selecting the dashboard in the "Dashboards" tab
  2. Clicking "Edit" icon in the top right. A similar dialog box will open with the retained settings:

 

 

 

Note: There a several icons on the top right for changing the format of the dashboard display as shown. The "Edit" icon is the one on the left. There are also icons for adding a column, removing a column, displaying in kiosk mode, and refreshing the display.

The use of these icons allow the user to rearrange the displayed widgets in rows and columns, if desired.

 

Creating a widget


To create a new widget, one of the dashboards in the "Dashboards" tab must have been selected to open its tab

  • Click "Add Widget" to open a drop-down menu where a widget type can be selected.
  • A dialog box for the selected widget will open, and its settings are explained in the following paragraphs:

The "Data Display Widgets" are designed to display the selected data in a graphical or tabular format.

The "API Interface Widgets" are used to perform various user interface functions (activate a method/event, get/set a property value, etc.)

  • After entering in the parameters and clicking "Save", a display panel for the widget will open in the "Dashboard:<dashboard name>" tab

Note: There a several icons on the top right corner of the display panel for each widget as shown on the right. Starting with the first icon, they are used to expand/contract the display panel, refresh the display panel, edit the widget, and delete the widget

There is also a "-" icon on the top left, which is used to hide the display panel. When the display panel is hidden, only the title of the widget and its icons are shown.

 

                                    

Data Display Widgets


GadgetKeeper supports wide set of widgets for displaying data in a graphical or tabular format

Event Data Chart


The "Event Data Chart" is probably the most commonly used widget, as it can display data as a function of time in a wide variety of graphical chart formats

To open a dialog box for this widget, select "Event Data Chart" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New event data chart #1 (#2, #3, etc.)

Chart Type x

Allows one of the following chart types to be selected from the drop-down menu:

  • Area
  • Area_spline
  • Bar
  • Column
  • Line
  • Scatter
  • Spline
ThingxThe selected "thing" provides the source of data for the widget
EventxThe event in the selected "thing" that handles the data. The data values specified when an event is activated are the data source.
Attributes      
xThe type of data to be plotted (the only possible choice is "value" unless a structured data type is used for the event. In this case, the "name" of one or more of the name/value pairs can be chosen. All possible choices are shown in the drop-down menu)
Refresh rate,
seconds
 The time interval used for updating the display panel to the latest values. The default setting is: 0 seconds = no refresh.
Time range The total allowed time span used for plotting data. All data obtained within the time span up to the present is plotted. The default setting is 6 hours.
 

Note that "Property" cannot be used as the data source for this widget because the data values must be tracked for a time period, and property values don't include timestamps, whereas event values include them

The dialog box for every widget has a "Size" tab as shown. When this tab is opened, it's possible to set a vertical height for the widget's display panel. The default value is "1", which is about 2 inches. Other possible settings are 2, 3, 4, and 5.

After a widget has been created, it can be edited anytime by clicking the "Edit" icon in the top right corner of the widget's display panel. A similar dialog box will open with the retained settings:

 

 

The display panel for the "Spline" version of the "Temperature chart" widget will appear as shown below, and shows temperature as a function of time for the last 5 minutes. All datapoint values are obtained from the timestamp and value given when events were activated within the 5 minute span. Note that an algorithm is used that smoothly interpolates the slope between the datapoints.


Event/Property Gauge


The "Event/Property Gauge" shows the current (or most recent) value from a data source in an analog-type circular gauge format

To open a dialog box for this widget, select "Event/Property Gauge" in the drop-down menu for "Add Widget"


FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New event/property gauge #1 (#2, #3, etc.)

 

Thing
xThe selected "thing" provides the source of data for the widget
Data Source
x

The drop-down menu shows two possible choices for data source: "Event" or "Property". The default setting is "Event".

Event 

If "Event" is selected as the data source, the selected event handles the data which is specified when the event is activated. These data values are the source of data for the widget.

(Property) If "Event" is not selected as the data source, "Property" is shown instead. The current value of the selected property will become the data source for the widget
Attributes      xThe type of data to be plotted (the only possible choice is "value" unless a structured data type is used for the property or event. In this case, the "name" of one or more of the name/value pairs can be chosen. All possible choices are shown in the drop-down menu)
Refresh rate,
seconds
 The time interval used for updating the display panel to the latest values. The default setting is: 0 seconds = no refresh.

 

 

The "Event/Property Gauge" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for the "Temperature gauge" widget will appear as shown below, and shows the temperature based the current value of the "Temperature" property or the value obtained with the most recent "temperatureChanged" event:


Thing Property Values


The "Thing Property Values" widget lists only the current values for the selected properties. Each item in the list includes the property name and its value.

To open a dialog box for this widget, select "Thing Property Values" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New thing property values #1 (#2, #3, etc.)

 

Thing
xThe selected "thing" provides the source of data for the widget
Properties       x

If "All" is checked, the widget will list current values for all properties in the selected thing

If "All" is unchecked, only those properties selected in the drop-down menu are listed

Refresh rate,
seconds
 The time interval used for updating the display panel to the latest values. The default setting is: 0 seconds = no refresh.

 

 

 

The "Thing Property Values" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for the "Temperature properties" widget will appear as shown below, and lists all of the properties in the "Thermometer" thing as <name/value> pairs  


Thing Event Log


The "Thing Event Log" widget logs recent values and timestamps for the selected events. The data is listed in order for previous event activations up to the present. The "Entries" amount determines the number listed. Each entry in the list includes the name of the event, a timestamp, and a value

To open a dialog box for this widget, select "Thing Event Log" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New thing event log #1 (#2, #3, etc.)

 

Thing
xThe selected "thing" provides the source of data for the widget
Eventsx

If "All" is checked, the widget will list recent data obtained for all events in the selected thing

If "All" is unchecked, the widget will list data for only those events selected in the drop-down menu.

(Data values specified when events are activated is the data source)

Entries            

The number set is the maximum number of data values that can be listed for the selected events. Data from previous event activations up to the present are listed in order. The default setting is 100.

Refresh rate,
seconds
 The time interval used for updating the display panel to the latest values. The default setting is: 0 seconds = no refresh.

 

 

The "Thing Event Log" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for  the "Temperature Log" widget will appear as shown below, and shows recent values of temperature and humidity with a timestamp. All event data is given as "value" and "at" parameters when events are activated


Thing Last Events


The "Thing Last Events" widget is similar to the "Thing Event Log" widget, but only displays the most recent values and timestamps for the selected events. Each entry in the list includes the name of the event, a timestamp, and a value

To open a dialog box for this widget, select "Thing Last Events" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New thing last events #1 (#2, #3, etc.)

 

Thing
xThe selected "thing" provides the source of data for the widget
Eventsx

If "All" is checked, the widget will list the most recent values obtained for all events in the selected thing

If "All" is unchecked, the widget will list values for only those events selected in the drop-down menu.

(The most recent data values from the selected events is the data source)

Refresh rate,
seconds
 The time interval used for updating the display panel to the latest values. The default setting is: 0 seconds = no refresh.

 

 

The "Thing Last Events" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for  the "Weather Info" widget will appear as shown below, and shows temperature and humidity values obtained from the most recent events. Event data is given as "value" and a timestamp is given as the "at" parameter when events are activated


Log


The "Log" widget provides a list of recent warning messages associated with the selected "things". The messages are displayed according to the selected level of severity. Previous messages are listed in order up to the present. The "Entries" amount determines the number listed. Each item in the list includes the name of the thing, a timestamp, and a message

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New thing property values #1 (#2, #3, etc.)

Things            
x

If "All" is checked, the widget will list recent recent messages for all things on GadgetKeeper

If "All" is unchecked, the widget will list recent messages only for those things selected in the drop-down menu.

Log Level      The drop-down menu show several choices for Log Level: NONE, FATAL ,ERROR, INFO, and DEBUG. The default setting is DEBUG.
Entries The number set is the maximum number of messages that can be listed for the selected things. Previous messages are listed in order up to the present. The default setting is 100.
Refresh rate,
seconds
 The time interval used for updating the display panel to the latest values. The default setting is: 0 seconds = no refresh.

 

 

The "Log" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for "Message log" widget will appear as shown below, and shows the latest "DEBUG" messages for the selected "things"

  

Map Position


The "Map Position" widget can pinpoint your exact location on a map based on the most recent "Location" data structure value (latitude and longitude)

To open a dialog box for this widget, select "Map Position" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New thing property values #1 (#2, #3, etc.)

Thing
xThe selected "thing" provides the "Location source" data for the widget
Location Source
 xThe drop-down menu shows two possible choices for Location source: "Event" or "Property", The default setting is "Event".
Event 

If "Event" is selected as the Location source, the selected event handles the data which is specified when the event is activated. These data values become the "Location source" for the widget.

(Property) If "Event" is not selected as the Location source, "Property" is shown instead. The current values of the selected property will become the "Location source" for the widget
Map Layer                         

Several choices for "Map Layer" characteristics are shown in the drop-down menu: Map, Satellite, Hybrid, and Terrain. The default setting is "Map".

Map Zoom The "Map Zoom" can be set to any value from 1 to 20, or "AUTO", which takes care of map scaling adjustments automatically. The default setting is "AUTO".
Refresh rate,
seconds
 The time interval used for updating the map to include the latest "Location" values. The default setting is: 0 seconds = no refresh.

 

The "Map Position" widget can be set to a size and edited as explained for the Event Data Chart widget

The event or property used as the "Location Source" must refer to a structured data type called "Location", which contains data values for longitude and latitude according to the JSON format:

The "Location" data structure is one of the built-in data types on GadgetKeeper, as described on Working with Location.

If "Event" is selected as the Location source, the "Location" data structure is set as the "value" parameter and a timestamp is the "at" parameter when the event is pushed.


The display panel for "GPS Position" widget will appear as shown below, and shows the current position on a map based on the most recent "Location" data.


Map Trait


The "Map Trait" widget can plot your route on a map based on the most recent "Location" values (longitude and latitude). All values obtained within the "Trait history" time span are plotted.

To open a dialog box for this widget, select "Map Trait" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New map trait #1 (#2, #3, etc.)

Thing
xThe selected "thing" provides the "Location source" data for the widget
Event
 x

The event in the selected "thing" that handles the data. The data values specified when an event is activated are the "Location source" for the widget

(Note that "Property" cannot be used as the "Location source" because the location must be tracked for a time period, and property values don't include timestamps, whereas event values include them)

Trait history
 

One of two starting points can be selected for plotting the route on the map:

  • Starting now - the "Location" value in the next event will determine the starting point
  • Starting the last event - the "Location" value from the last event determines the starting point

The default setting is "Starting now"

Trait history, hours The number of hours set is the time range up to the present from which "Location" datapoints are plotted. The timestamps of "Location" data within this range determines the order of the route. The default setting is 1 hour.
Map Layer       
 Several choices for "Map Layer" characteristics are shown in the drop-down menu: Map, Satellite, Hybrid, and Terrain. The default setting is "Map".
Map Zoom The "Map Zoom" can be set to any value from 1 to 20, or "AUTO", which takes care of map scaling adjustments automatically. The default setting is "AUTO".
Refresh rate, seconds 

The time interval used for updating the map to include the latest "Location" values. The default setting is: 0 seconds = no refresh.

 

The "Map Trait" widget can be set to a size and edited as explained for the Event Data Chart widget

The event used as the "Location Source" must refer to a structured data type called "Location", which contains data values for longitude and latitude according to the JSON format:

The "Location" data structure is one of the built-in data types on GadgetKeeper, as described on Working with Location.

A JSON array structure is used when an event is pushed with the "Location" data structure set as the "value" parameter and a timestamp set as the "at" parameter

The display panel for "GPS Trait" widget will appear as shown below, and charts the route taken by a user based on recent "Location" datapoints. The route is plotted sequentially for all "Location" datapoints obtained within the "Trait history" time range up to the current position:

Note that the vertical size was increased to 2 to get more detail on the trait map. (Editing and sizing are explained in the Event Data Chart widget section)

For this example, all of the "Location" datapoints were sent in one JSON array structure when the event was pushed. It is also possible to send each datapoint one at a time in separate events, as shown in Map Position.

API Interaction Widgets


GadgetKeeper also provides several widgets for performing various user interface functions (activate a method/event, get/set a property value, etc.) These widgets are described here:

Html


The "Html" widget provides a convenient way to jot down notes in a note-pad text area on GadgetKeeper.

To open a dialog box for this widget, select "Html" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New execute method #1 (#2, #3, etc.)

 

Value
 The text area where the user can enter text in any format. The entered text will be shown on the widget. The text can be edited later as needed.

 

 

 

The "Html" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for the "scratchPad" widget will appear as shown below, and contains a text area with the most recent text entered in for the widget. Note that the text can't be modified directly on the widget. In order to modify it, the user must click the Edit button, enter in the changes, and then click "Save"


Get/set properties


The "Get/set properties" widget provides a convenient way for a user to get or set property values on GadgetKeeper. This would eliminate the need to call property get/set functions through the UI, REST API, or script code.

To open a dialog box for this widget, select "Get/set Properties" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New get/set properties #1 (#2, #3, etc.)

 

Thing
xThe selected "thing" that contains the property for the widget
Propertiesx

If "All" is checked, the widget will provide get/set capability for all properties in the selected thing

If "All" is unchecked, the widget will provide get/set capability only for those things selected in the drop-down menu.

AllowxThe allowable options for getting/setting property values are: Get, Set, or Get/set. The "Get/set" option is chosen here, and allows both getting and setting of property values.

 

 

The "Get/set Properties" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for  the "Get/Set Temperature" widget will appear as shown below, and shows the current value of the temperature property. "Get" must be clicked to retrieve property value. Clicking "Set" will assign an entered value to the property. "Reset" clears the entry. Other properties can be selected from the drop-down menu.


Execute method


The "Execute method" widget provides a quick way to execute a method on GadgetKeeper. The alternative way would be to implement execute method functions through the UI, REST API, or script code.

To open a dialog box for this widget, select "Execute method" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New execute method #1 (#2, #3, etc.)

 

Thing
xThe selected "thing" that contains the method(s) for the widget
Methodsx

If "All" is checked, the widget will allow any method in the selected thing to be executed

If "All" is unchecked, the widget will only allow those methods selected in the drop-down menu to be executed

Default Arguments 

This widget allows a user to enter arguments for the method's function. If a Default argument is entered here, it will appear in the widget unless the user decides to modify it.

If the "Hide arguments input" box is checked, the "Arguments" text-box is not shown on the widget. This is usually checked if there are no arguments needed or the default arguments will always be used.

 

 

The "Execute method" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for the "sendUpdate" widget will appear as shown below, and contains the name of the method's function, a text-box for arguments (if enabled), an "Execute" button, and a "Reset" button. Other methods can be selected from the drop-down menu.


Push event


The "Push event" widget provides a handy way to fire an event on GadgetKeeper. The alternative way would be to activate push event functions through the UI, REST API, or script code.

To open a dialog box for this widget, select "Push Event" in the drop-down menu for "Add Widget"

FieldRequiredDescriptionDialog
Titlex

Name of widget

  • Must be unique within the dashboard list
  • Can contain: 
    Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Constraint - thing event name'.

The default name is "New push event #1 (#2, #3, etc.)

 

Thing              
xThe selected "thing" that contains the event(s) for the widget
Eventsx

If "All" is checked, the widget will allow any event in the selected thing to be activated

If "All" is unchecked, the widget will only allow those events selected in the drop-down menu to be activated

Default Value
 

This widget allows a user to enter a default value for the event when activated. A JSON data structure must be used with "value" and "at" (timestamp) parameters.

A Default argument is generated automatically when an event is selected, and this will be the default argument for the widget unless the user decides to modify it.

 

 

The "Push event" widget can be set to a size and edited as explained for the Event Data Chart widget

The display panel for the "setTemperature" widget will appear as shown below, and contains the request/response format (currently supported format is json), a check-box for "Async" (for asynchronous operation), the default value (which can be pushed unless the user decides to modify it), and buttons for "Push", "Generate", and "Reset". Clicking "Generate" will insert a new "value", and update the "at" time to the current time. Other events can be selected from the drop-down menu.

 

 

 

 

 

 

 

 

  • No labels