Blueprint Dashboard: multi-slot setup guide and end-to-end example

[Freddyminu]

Closes #88

Summary

Rewrites the Blueprint Dashboard doc to cover multi-slot configuration and adds a water treatment facility end-to-end example. The previous version only described a single Blueprint Device slot with no setup walkthrough.

Test plan

• Read through in the docs preview for rendering (tables, admonitions, code blocks)
• Verify internal links resolve (blueprint-devices-entities, tags-system, managing-devices, entities)

Risk (CIA)

Likelihood: ⚪ None | Impact: ⚪ None | Exposure: ⚪ None
Documentation-only change; no behavior change.

[vitorfdl]

1. Intro is clear, but “each seeing their own data” needs qualification

Current:

The same dashboard can serve hundreds of users, each seeing their own data, without creating separate dashboards per user or device.

This is a good value statement, but it may imply that Blueprint Dashboards automatically handle user-level data isolation.

Suggested revision:

A Blueprint Dashboard links widgets to devices dynamically. Instead of creating one dashboard per device or user, you create one reusable layout and let each blueprint slot resolve to a real device at runtime.

This makes it easier to scale the same dashboard across many devices, sites, or customers. When sharing dashboards with end users, make sure your access rules and device tags only expose the devices each user should see.

Why: this keeps the benefit clear while avoiding a possible security/access misunderstanding.

---

2. Add a “Before you start” section

This would help new users understand the prerequisites before they get into slots and widget binding.

Suggested section after the intro:

## Before you start

Before creating a Blueprint Dashboard, make sure you have:

- Devices already created in TagoIO.
- Tags applied to the devices you want to show in each slot.
- Consistent variable names across devices that use the same slot.
- The right access rules if the dashboard will be shared with end users.

For example, if a widget uses the variable `pressure`, every pump device selected in that slot should send data using the `pressure` variable. If one device uses `pump_pressure` instead, that widget will not show data when that device is selected.

This is especially important for technical users. The variable consistency point is likely one of the most common causes of “the dashboard works for one device but not another.”

---

3. Define “slot” more explicitly early on

The document uses “slot” well, but new users may not immediately understand that a slot is a placeholder data source.

Suggested addition under Concepts:

A blueprint slot is a placeholder data source inside the dashboard. Instead of pointing a widget to one fixed device, you point it to a slot. The slot is then filled by the device selected in the dashboard dropdown.

This makes the mental model clearer.

---

4. “How slot resolution works” is useful, but could be more precise

Current:

Two slots bound to different tag filters resolve to different devices. Widgets bound to Slot A never pull data from the device selected in Slot B.

This is mostly clear, but “resolve to different devices” may not always be true if tag filters overlap. Also, some widgets may support multiple data sources.

Suggested revision:

Each slot keeps its own selected device. When the user changes the device in one slot, TagoIO reloads the widgets or widget series that use that slot.

A widget connected only to the `Pump` slot will not read data from the device selected in the `Tank` slot. If a widget supports multiple data sources, each data source follows the slot selected for that specific series or variable.

This is clearer for both beginners and technical users.

---

5. The examples are good, but there are two competing scenarios

The document first uses:

• Pump devices
• Compressor devices

Then the end-to-end example uses:

• Pump
• Tank

Both examples are understandable, but switching scenarios adds some extra cognitive load.

Recommendation: use one scenario throughout.

The water treatment example is stronger because it naturally shows why multiple slots matter: one slot for pump data, another for tank data.

Suggested direction:

• Use the water treatment example in the tagging section.
• Keep the same devices in the slot setup section.
• Keep the same variables in the widget binding section.

Example:

| Device       | Variables               | Tags        |
| ------------ | ----------------------- | ----------- |
| Main Pump    | `pressure`, `flow_rate` | `type=pump` |
| Backup Pump  | `pressure`, `flow_rate` | `type=pump` |
| Tank 1       | `level`, `temperature`  | `type=tank` |
| Tank 2       | `level`, `temperature`  | `type=tank` |

This also fixes the later mention of “Backup Pump,” which is currently referenced but not included in the device table.

---

6. Review the final facility tip carefully

Current:

To extend this dashboard to multiple facilities, add a third blueprint slot for the facility itself. Tag every device with a facility_id value... The operator selects the facility first, then picks the pump and tank from the devices tagged to that facility.

This may be misleading if Blueprint slots are independent and do not support cascading/dependent dropdowns.

Earlier, the doc says:

Each slot is independent: changing one does not affect the others.

Those two ideas appear to conflict. The tip suggests that selecting a facility filters the Pump and Tank dropdowns dynamically.

Recommendation: either remove the tip or rewrite it depending on the actual platform behavior.

If cascading slot filtering is not supported, suggested rewrite:

:::tip

To organize the same dashboard across multiple facilities, include a facility tag in your device tag scheme, such as `facility_id=site_a`.

You can then create separate blueprint slots or dashboards based on the facility structure you need. Blueprint slots are independent, so selecting one slot does not automatically filter the options in another slot.

:::

If cascading slot filtering is supported, the doc should explain the mechanism clearly. For example, say exactly where the selected facility value is used to filter the Pump and Tank slots.

---

Inline link review

The document already includes useful links for:

• Dashboard
• Widgets
• Blueprint Devices
• Entities
• Tags system
• Devices

Suggested additional links, if these docs exist:

1. Variables
   First occurrence in the examples:

   Variables

   This term matters because Blueprint Dashboards depend on consistent variable names.

2. Tag access / user permissions / TagoRUN access
   If this documentation is used by people building dashboards for end users, link to the relevant access-control documentation near the intro or “Before you start.”

3. Blueprint Settings anchor
   Current:

   [**Blueprint Settings**](/docs/tagoio/devices/blueprint-devices-entities.md)

   This points to the Blueprint Devices and Entities doc, not necessarily to a Blueprint Settings section. If an anchor exists, use it. If not, consider wording it as:

   Open the dashboard edit page and go to **Blueprint Settings**. For more details, see [Blueprint Devices and Entities](/docs/tagoio/devices/blueprint-devices-entities.md).

4. Devices link consistency
   Current:

   [**Devices**](/docs/tagoio/devices)

   Check whether the docs convention uses a trailing slash:

   /docs/tagoio/devices/

   Not a content issue, but worth keeping consistent.

---

Suggested structure

I would restructure the article like this:

# Blueprint Dashboard

Short intro:
- What it is.
- Why it helps.
- Important access note.

## Before you start
- Devices created.
- Tags applied.
- Variables consistent.
- Access configured if shared with users.

## Concepts

### Blueprint slots
Explain slot, identifier, tag filter, runtime selection.

### Blueprint Devices and Blueprint Entities
Explain both briefly.

### Data scope across slots
Explain independence, widget binding, multiple data sources if supported.

## Example: water treatment facility

### 1. Tag your devices
Use one consistent table.

### 2. Create the blueprint slots
Pump and Tank.

### 3. Bind widgets to slots
Use the same Pump and Tank variables.

### 4. Test the dashboard
Select each slot and verify widgets update correctly.

## Troubleshooting
- Selector is empty.
- Widget shows no data.
- User sees the wrong devices.
- Changing one dropdown does not update the expected widget.

This would make the doc easier for new users and more complete for technical users.

---

Recommended troubleshooting section

This would add practical value without making the article too long.

## Troubleshooting

### The device selector is empty

Check that the devices have the tags required by the blueprint slot. The tag key and value must match the slot configuration.

### A widget does not show data after selecting a device

Check that the selected device contains the variable used by the widget. Devices assigned to the same slot should use the same variable names.

### A user sees devices they should not access

Review the dashboard sharing settings, device tags, and user access rules. Blueprint slots control which devices can appear based on tags, but access rules should define which devices each user is allowed to see.

### The wrong widgets update when I change a slot

Open the widget settings and confirm that each widget is bound to the correct blueprint identifier.

This section would make the article more useful in real implementation work.

[vitorfdl]

Looks to be missing documentation about the Filter Conditions