Skip to Content
CloudDashboardWidget guide

Widget guide

This guide provides an overview of the different types of widgets available for your dashboard, along with examples and key settings to configure for each widget type.

1. Single Value Widget

  • Purpose: To display a single, current, or aggregated piece of information from a device. This is great for at-a-glance readings.
  • Examples:
    • Current temperature in a room.
    • Total items produced by a machine today.
    • The minimum battery level recorded for a device in the last 24 hours.
  • Key Settings You’ll Configure:
    • Title: e.g., “Current Office Temperature”
    • Description: e.g., “Displays the latest temperature reading from the office thermostat.”
    • Data Source (Device ID / Bundle ID): Choose the specific device or group of devices.
    • Data Field (field): The specific sensor reading you want to see (e.g., temperature, battery_level).
    • Data Aggregation (aggregateType): How to summarize the data. For a “current” value, you’d often use LATEST. For “total items today,” you might use SUM with a since of “Last 24 hours.”
    • Time Range (since): How far back to look for the data.
    • Suffix: Unit to display (e.g., “°F”, “volts”, “units”).

2. Multiple Value / Chart Widget

  • Purpose: To display trends of one or more data fields over time, usually as a line chart or bar chart. This is excellent for seeing patterns, comparisons, and history.
  • Examples:
    • A line chart showing temperature and humidity trends over the last day.
    • A bar chart comparing the average power consumption of three different machines over the last week.
  • Key Settings You’ll Configure:
    • Title: e.g., “Sensor Readings - Last 24 Hours”
    • Description: e.g., “Tracks temperature, humidity, and pressure from the weather station.”
    • Time Range (since): The overall period the chart will cover (e.g., “Last 7 days”).
    • Bucket Size / Interval (bucketSize): This determines how data is grouped on the chart. For example, if since is “Last 24 hours” and bucketSize is “HOUR,” you’ll see 24 data points, each representing an aggregation (like average, max) for that hour. Options include: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, etc.
    • Fields to Display (fields): This is where you define what data lines or bars appear on your chart. For each piece of data you want to plot, you’ll specify:
      • Label: How this data series will be named in the chart’s legend (e.g., “Internal Temp,” “External Temp”).
      • Data Field (field): The sensor reading (e.g., internal_temp_celsius, external_temp_celsius).
      • Data Aggregation (aggregateType): How to summarize the data for each bucketSize (e.g., AVG, MAX).
      • Color: The color of the line or bar for this data series on the chart.
      • Data Source (Bundle ID / Device ID): You can specify a device/bundle for each field individually if needed, or it can use a general one for the widget.
    • Important Note: You can’t add the exact same data field with the exact same aggregation type from the exact same device more than once to the same chart. Each line needs to be unique in what it’s representing.
    • Suffix: A general unit that might apply to values on the Y-axis (e.g., “°C”).

3. State Widget

  • Purpose: To display a status or condition based on a numerical value from a device. It changes color and label depending on the value.
  • Examples:
    • A temperature status: “Cold” (blue) if below 18°C, “Normal” (green) if 18-24°C, “Hot” (red) if above 24°C.
    • Machine status: “Idle” (grey), “Running” (green), “Warning” (yellow), “Error” (red).
  • Key Settings You’ll Configure:
    • Title: e.g., “Server Room Temperature Status”
    • Description: e.g., “Indicates if the server room temperature is within acceptable limits.”
    • Data Source (Device ID / Bundle ID): Choose the relevant device.
    • Data Field (field): The sensor reading that determines the state (e.g., temperature).
    • Data Aggregation (aggregateType): How to get the value to check (often LATEST or AVG).
    • Time Range (since): How far back to look for the data to determine the current state.
    • Minimum Value (minValue) & Maximum Value (maxValue): The overall expected range for your data field. The maxValue must be greater than the minValue.
    • States (states): This is where you define the different conditions. For each state, you’ll set:
      • Value: The threshold value at which this state begins. For example, if you have states for “Cold” starting at 0, “Normal” starting at 18, and “Hot” starting at 25, a reading of 20 would fall into the “Normal” state. The first state’s value should generally match your minValue.
      • Color: The color to display for this state.
      • Label: The text to display for this state (e.g., “Cold,” “Optimal,” “High”).
    • Important Note: Each state must have a unique “Value.”

4. Gauge Widget

  • Purpose: To display a single data point on a gauge, like a speedometer or a progress bar. It visually shows where the current value falls within a minimum and maximum range, often with color-coded thresholds.
  • Examples:
    • A radial (speedometer-style) gauge showing current machine pressure from 0 to 100 PSI, with green, yellow, and red zones.
    • A fill (bar-style) gauge showing tank fill level as a percentage.
  • Key Settings You’ll Configure:
    • Title: e.g., “Water Tank Level”
    • Description: e.g., “Shows current water level as a percentage of capacity.”
    • Data Source (Device ID / Bundle ID): Select the device.
    • Data Field (field): The sensor reading for the gauge (e.g., pressure, fill_level).
    • Data Aggregation (aggregateType): How to get the value for the gauge (e.g., LATEST, AVG).
    • Time Range (since): Time period for the data.
    • Minimum Value (minValue) & Maximum Value (maxValue): The start and end points of your gauge scale. maxValue must be greater than minValue.
    • Display as Percentage (metadata.isPercentage): If checked, the gauge will show the value as a percentage of the maxValue.
    • Thresholds (metadata.thresholds): Define color-coded zones on your gauge. For each threshold, you set:
      • Value: The value at which this color zone begins.
      • Color: The color for this zone on the gauge.
    • Important Notes:
      • Threshold values must be unique.
      • The first threshold value usually matches minValue.

5. Map Widget

  • Purpose: To display the geographical location of one or more devices on a map.
  • Examples:
    • Showing the current location of all delivery vehicles.
    • Pinpointing the location of a lost asset.
  • Key Settings You’ll Configure:
    • Title: e.g., “Delivery Fleet Locations”
    • Description: e.g., “Real-time map of all active delivery trucks.”
    • Latitude Field (latField): The name of the data field from your device that contains the latitude information (e.g., gps_latitude, lat).
    • Longitude Field (lonField): The name of the data field from your device that contains the longitude information (e.g., gps_longitude, lon).
    • Data Source (Bundle ID / Device ID): You’ll typically want to select a bundleId to show multiple devices, or a specific deviceId to track a single one. If these are not set at the widget level, the dashboard might use global settings or show all available devices with location data.

6. Trigger Widget

  • Purpose: To send a command or change a setting on a specific device directly from your dashboard.
  • Examples:
    • A button to turn a light on/off.
    • A switch to enable/disable a feature on a machine.
    • A button to remotely reboot a device.
  • Key Settings You’ll Configure:
    • Title: e.g., “Office Light Control”
    • Description: e.g., “Switch to turn the main office lights on or off.”
    • Device ID (deviceId): This is crucial. You must select the specific device you want to control.
    • Trigger Name (triggerName): The name of the command or action you want to send to the device (e.g., toggle_light, set_mode_standby, reboot_device). This name must be something your device is programmed to understand.
    • Control Type (metadata.type):
      • Button (button): A simple press-to-activate button. Sends the triggerName command when clicked.
      • Switch (switch): An on/off toggle.
        • Field for Switch State (metadata.field): If it’s a switch, you need to specify a data field on the device that represents the current state of what you’re controlling (e.g., light_status). This allows the switch on the dashboard to reflect the actual state of the device (e.g., show ‘on’ if the light is actually on).

7. Histogram Widget

  • Purpose: To display the distribution of a numerical data field over a specified time range. This is useful for understanding how often certain values occur within your data set.
  • Examples:
    • A histogram showing the distribution of temperature readings over the last week.
    • A histogram displaying the frequency of different humidity levels recorded by a sensor.
  • Key Settings You’ll Configure:
    • Bucket Count: The number of bars (buckets) to display in the histogram. More buckets provide a more detailed view of the distribution.
    • Min Bucket Threshold: The minimum value for the first bucket. This sets the second point of your histogram. the first bucket is all values under this value.
    • Max Bucket Threshold: The maximum value for the last bucket. This sets the second to last point of your histogram. the last bucket is all values over this value.
    • Count Type: Choose between COUNT (number of readings) or SUM (sum of readings) to determine how the data is aggregated within each bucket.
    • Display Type: Choose between SIDE BY SIDE (bars next to each other) or STACKED (bars on top of each other) for visualizing multiple fields.
Last updated on
Code NodeREST API Integration