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.

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 / Bundle): Choose the specific device or group of devices.
- Data Field: The specific sensor reading you want to see (e.g., temperature, battery_level).
- Aggregate: How to summarize the data. For a “current” value, you’d often use LATEST. For “total items today,” you might use SUM with a Time Range of “Last 24 hours.”
- Time Range: How far back to look for the data.
- Suffix: Unit to display (e.g., “°F”, “volts”, “units”).
- Decimal Points: Number of decimal places to show for the value. (defaults to 2 if left blank)

Purpose: To display trends of one or more data fields over time, usually as a line chart or area chart. This is excellent for seeing patterns, comparisons, and history.
Examples:
- A chart showing temperature and humidity trends over the last day.
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: The overall period the chart will cover (e.g., “Last 7 days”).
- Group Time Range: This determines how data is grouped on the chart. Basically how many data points to show.
- 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:
  - Field: The sensor reading (e.g., internal_temp_celsius, external_temp_celsius).
  - Legend: How this data series will be named in the chart’s legend (e.g., “Internal Temp,” “External Temp”).
  - Aggregate: How to summarize the data for each Interval (e.g., AVG, MAX).
  - Color: The color of the line or bar for this data series on the chart.
  - Data Source (Bundle / Device): You can specify a device/bundle for each field individually if needed, or it can use a general one for the widget. This will override the widget-level device/bundle if set.
- 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”).
- References: Optional horizontal lines on the chart to indicate important thresholds. For each reference line, you’ll set:
  - Value: The Y-axis value where the line should appear.
  - Label (Optional): Text to describe what this line represents (e.g., “Max Safe Temp”). If left blank, no label will be shown.
  - Color: The color of the reference line.

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 / Bundle): Choose the specific device or group of devices.
- Field: The sensor reading that determines the state (e.g., temperature).
- Aggregate: How to get the value to check (often LATEST or AVG).
- Time Range: How far back to look for the data to determine the current state.
- Minimum Value & Maximum Value: The overall expected range for your data field. The max must be greater than the min.
- 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 minimum value.
  - 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.”

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 / Bundle): Select the device.
- Field: The sensor reading for the gauge (e.g., pressure, fill_level).
- Aggregate: How to get the value to check (often LATEST or AVG).
- Time Range: Time period for the data.
- Minimum Value & Maximum Value: The start and end points of your gauge scale. Maximum value must be greater than minimum value.
- Display as Percentage: If checked, the gauge will show the value as a percentage.
- Thresholds: Define color-coded zones on your gauge. For each threshold, you set:
  - Value: The value at which this color zone begins. First threshold needs to match minimum value. Must be less than maximum value and greater than the previous threshold value.
  - Color: The color for this zone on the gauge.

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).

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.

Widget guide

1. Single Value Widget

2. Graph Widget

3. State Widget

4. Gauge Widget

5. Trigger Widget

6. Histogram Widget