thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/resources/prompts/solutions/solution-ba/resources/solution-capabilities.md

@@ -0,0 +1,403 @@
+## Platform Capabilities
+
+The platform supports various advanced capabilities demonstrated in the READY examples:
+* Indoor positioning of devices and assets on image maps
+* Outdoor GPS tracking and geofencing with zone-based alerts
+* Multiple metric types: math, script, time series aggregation, related-entity aggregation, propagation, delta
+* Advanced alarm patterns: multi-severity thresholds, duration-based conditions, consecutive occurrences
+* Flexible threshold configuration: static values, per-entity attributes, or customer-level attributes
+
+## Visualization Capabilities
+
+### Indoor positioning
+
+When a container asset profile **directly owns** asset/device profiles that have a physical position within a space (sensors, meters, actuators, or sub-assets such as Rooms or Desks — not GPS-tracked vehicles or outdoor mobile equipment):
+  * The container **MUST** have a floor plan image attribute (e.g., `floorPlan`, `facilityPlan`, `warehousePlan`, `storagePlan`).
+  * All direct child device/asset profiles **MUST** have indoor position keys (e.g., `xPos`/`yPos` or `positionX`/`positionY`).
+  * These always come as a pair. Do **NOT** add one without the other. 
+  * Do **NOT** skip them just because the user didn't ask for visualization — this rule is structural: it applies whenever the containment relation exists.
+  * Do **NOT** add position keys or a floor plan when there is no parent container asset (standalone devices with no grouping asset).
+
+* **Device/Asset markers**: Add two position keys per profile (e.g., `xPos` and `yPos`, or `positionX` and `positionY`).
+
+* **Indoor zones** (operational areas within a space): 
+  * Add an `indoorZone` attribute to zone asset profiles (e.g., `WarehouseSection`, `RestrictedArea`). 
+  * Visualization only — no automatic zone-entry tracking; geofencing logic is for outdoor GPS only. 
+  * Common use cases: warehouse sections, office zones, restricted areas. Add when the solution involves distinct named areas users need to identify on the floor plan.
+
+### Outdoor positioning
+
+* **GPS-tracked mobile entities** (vehicles, containers, drones): add `latitude` and `longitude` timeseries keys.
+* **Fixed-location assets with an `address`** (buildings, facilities, warehouses, sites): add `latitude` and `longitude` attributes for map visualization.
+* **Outdoor geofencing zones**: add a `perimeter` attribute.
+
+### Combining indoor and outdoor positioning
+
+Having outdoor coordinates does **NOT** exempt a container from also needing a floor plan and child device position keys — both rules apply independently when both conditions are met. 
+See READY example 3: ColdStorage has `address`, `latitude`, `longitude`, `storagePlan`; child devices have `positionX`, `positionY`.
+
+## IoT Solution Description structure
+
+An IoT solution description in ThingsBoard must contain (See the READY examples for reference):
+* concise, human-readable description of the solution up to 100 words
+* the following key blocks that are described below.
+
+### Customers and Users
+
+This must contain a brief description of user roles in the solution. The solution may be tenant-only (no customer hierarchy) or include customer hierarchy.
+
+**General rules**: 
+ * You **MUST** always include at least one tenant-level user with a solution-domain-specific name (e.g., "Fleet Solution Administrator", "Smart Building Administrator", "Cold Chain Platform Administrator") — never a generic name like "Solution Administrator" or "Tenant Admin" that could conflict across solutions.
+ * When using customer hierarchy, you **MUST** explicitly name the customer profile (e.g., "CaféOwner", "ParkingOperator"). 
+ * Customer-level users cannot exist without a named customer profile. 
+ * For customer-level roles, use domain-specific names (e.g., "Fleet Manager", "Store Supervisor") — never generic names like "Customer Administrator" or "Customer User". Distinguish the access level in the description: management access vs. view-only access.
+
+A ThingsBoard solution can be structured as **tenant-only** or with a **customer hierarchy**.
+Choose the structure that best fits the use case — customer hierarchy is a powerful platform differentiator
+and should be used whenever the solution naturally serves multiple independent parties or requires isolation between groups.
+
+#### Tenant-only solutions
+Best for: internal monitoring where a single organization manages everything.
+- One operator, one team, or a single company managing their own devices
+- No need to isolate data between separate parties
+- Examples: a factory monitoring its own production line, an engineer monitoring their own pump, a team tracking their company vehicles
+
+#### Solutions with customer hierarchy
+Best for: solutions designed to serve multiple independent organizations, tenants, or clients —
+or when the platform is used as a product or managed service rather than purely for internal use.
+
+**Use customer hierarchy when:**
+- The solution is a product or managed service delivered to multiple separate organizations
+  (e.g., a SaaS platform for parking lot owners, a fleet tracking service sold to transport companies)
+- The use case involves distinct organizations (cafés, shops, offices, hospitals, construction sites)
+  that each need isolated access to their own data and devices
+- Different roles exist at the customer level (manager vs. operator vs. viewer per customer)
+- Thresholds or settings vary per customer and should be configured independently
+- The user mentions: customers, clients, tenants, organizations, franchises, branches, sites operated by different parties
+
+**Consider customer hierarchy even if not explicitly requested when** (no first-person ownership signal present):
+- The solution description resembles a managed service or product deployed to multiple independent clients
+- Multiple locations are operated by different responsible parties (not one central team)
+- The prompt implies serving separate organizations even without using the word "customers"
+
+**Omit customer hierarchy when:**
+- The user uses first-person ownership language: "my machine", "our factory", "I want to monitor" — **this overrides any commercial inference**
+- No mention of serving separate organizations or isolating data between parties
+- Simple standalone or single-operator monitoring
+
+**Important — commercial telemetry ≠ customer hierarchy:**
+A device reporting commercial metrics (revenue, transaction counts, sales data) does NOT imply that multiple independent customers own or operate the device. These are device-level telemetry keys. A single operator monitoring their own device is a tenant-only solution.
+
+**Customer-level configuration**: If thresholds or parameters are configured per customer, describe this explicitly: "configured at the customer level" / "stored in the customer profile". Do **NOT** use vague phrases like "for all sensors" — these imply device-level attributes.
+
+### Device and Asset profiles
+
+Each entry is a **profile** — a template that defines the metrics, relations, and alarms for all its instances. 
+Every instance of a profile behaves identically: same telemetry keys, same relations to parent/child profiles, same metrics, same alarms. There is no per-instance variation.
+
+* **Device profiles**: physical IoT entities that send telemetry (e.g., sensor, actuator). List the telemetry keys collected for each profile.
+* **Asset profiles**: entities used to group or relate devices and other assets (e.g., Factory, Room, Vehicle). List the attributes set by the system or user, and any computed timeseries keys produced by metrics.
+
+Do NOT merge devices into a single profile if different instances connect to different parent profile types — even if the devices collect the same telemetry. Metrics and relations are defined once per profile and apply to every instance; an instance that lacks an expected relation will fail when a metric executes against it.
+  * *Wrong (instance divergence):* A factory has Compressor and StorageTank asset profiles, each with one PressureSensor. One `pressureSensor` profile with relations to both Compressor and StorageTank. At instance level, each sensor connects to only one parent — but metrics are profile-level, so every sensor gets metrics targeting both parents. Sensors missing the expected relation fail when the metric executes.
+  * *Correct:* Two profiles: `compressorPressureSensor` (relates to and propagates to Compressor) and `tankPressureSensor` (relates to and propagates to StorageTank).
+
+#### Telemetry Key Constraints
+
+Each key entry has a required `name` field and optional constraint fields. Capture constraints **only** when explicitly stated by the user:
+
+* **`allowedValues`**: Capture only when the user explicitly lists the possible string/enum values for a key.
+  * ✅ User says: "error codes: X1, X2, X3" → `{"name": "errorCode", "allowedValues": ["X1", "X2", "X3"]}`
+  * ✅ User says: "mode can be: auto, manual, standby" → `{"name": "mode", "allowedValues": ["auto", "manual", "standby"]}`
+  * ❌ Do NOT infer enum values from domain knowledge alone.
+* **`min`/`max`**: Capture only when the user explicitly states numeric bounds for a key. These represent the widget display range (the full operational range of the profile), NOT a data generation constraint.
+  * ✅ User says: "boiler temperature: 0–100°C" → `{"name": "boilerTemp", "min": 0, "max": 100}`
+  * ✅ User says: "fill level is always between 0 and 500 liters" → `{"name": "fillLevel", "min": 0, "max": 500}`
+  * ❌ Do NOT add `min`/`max` based on domain knowledge alone — that is handled downstream.
+* When the user does not specify constraints for a key, use `{"name": "keyName"}` with no extra fields.
+
+### When to use asset hierarchy
+
+**Add asset hierarchy when:**
+- Devices belong to a named physical space (building, floor, warehouse, parking lot, site) and location context adds meaningful value (e.g., aggregate metrics per floor, compare performance between sites)
+- There is a logical grouping with its own attributes or alarms (e.g., Fleet with aggregate utilization stats, Zone with geofencing perimeter)
+- Relations are needed for metric aggregation (`relatedAggregation`, `propagate`) across multiple devices
+
+**Omit asset hierarchy when:**
+- The user is monitoring a single device or a homogeneous set of standalone devices without location grouping
+- No aggregation, comparison, or isolation between device groups is needed
+- The only reason to add a location asset is that the device is physically installed somewhere — **physical installation alone does NOT justify a location asset**
+
+**Rule:** Do not create a Location, Building, Site, or similar parent asset just because a device is deployed at a venue. 
+Only add a parent asset when the container itself carries meaningful data, participates in relations, or provides access control value.
+
+### Relations
+
+This must contain a concise description of the **structural relations** (hierarchy, containment, or ownership) between asset and device profiles. For each relation, indicate the cardinality — whether a parent profile can have many children of a child profile type or exactly one:
+* *1:M*: "Farm owns Tractors" (can have many) — default when plural or not specified.
+* *1:1*: "Each Room has exactly one EnvironmentSensor" — only when the solution explicitly implies a dedicated, single-instance assignment.
+
+**Logical Relations constraint**: Do NOT describe logical monitoring checks (e.g., "Vehicle is checked against AllowedZone") as relations. Only describe a relation if there is a direct, permanent assignment (e.g., "Site has Environment Sensors").
+
+**Zone Profile Modeling**: When a solution involves **multiple distinct zone types** (e.g., Allowed, Restricted, Parking), each zone type **MUST be its own asset profile** (e.g., `AllowedZone`, `RestrictedZone`, `ParkingZone`). Do **NOT** consolidate zone types into a single `Zone` profile with a `zoneType` attribute — the geofencing engine identifies zone sources by **profile-to-profile relations**, not attribute values. Each zone profile requires a `perimeter` attribute.
+
+**Geofencing Hierarchy patterns**: Determine the relation based on the zone's scope:
+  1. **Shared Scope (Default)**: Treat zones as infrastructure shared by multiple tracking entities (devices or assets). Define the relation from the Parent Asset (e.g., `Fleet`, `Site`) to the Zones.
+     * *Example*: "Fleet owns Vehicles. Fleet also owns RestrictedZones."
+  2. **Individual Scope (Exception)**: Only define the relation from the individual entity (e.g., `Pet Tracker`) to the Zone if the request explicitly states the zones are "personal", "individual", or "assigned to each device".
+     * *Example*: "Each Pet has a unique HomeZone."
+
+**Relation constraints:**
+* Relations represent permanent structural assignments. Do **NOT** create relations for transient states or logical checks (e.g., do not link a Vehicle profile to a Zone profile just because a vehicle is currently inside the zone).
+* Propagation is upward only (child → parent). Do **NOT** create propagation metrics to copy data from a parent asset profile down to a child device profile.
+* Aggregation is upward only (children → parent). Do **NOT** create relatedAggregation metrics to aggregate data from a parent down to a child.
+* Avoid 1:1 relations between a Customer profile and an asset profile.
+
+### Metrics
+
+Metrics are profile-level calculations — each metric is defined on an entity profile and executes on every instance of that profile. They can derive values from raw telemetry, attributes, or outputs of other metrics (chaining).
+
+**General constraints that apply to all metric types:**
+* The `calculation` string **MUST** explicitly name all input keys.
+* A maximum of **10** metrics per entity profile — use them sparingly for high-value derived data.
+* Prefer telemetry keys and attributes **already defined** in entity profiles. Avoid inventing new input fields unless absolutely necessary.
+
+The following types of calculations are supported:
+
+#### math
+
+Arithmetic operations or simple math formulas (linear operations) producing a **single output** key.
+
+**When to use:**
+* Simple arithmetic on existing keys: addition, subtraction, multiplication, division.
+* Unit conversions, linear formulas.
+
+**Constraints:**
+* Exactly one output key per metric.
+
+**Examples:**
+* Sum volumes: `tank1Volume + tank2Volume + tank3Volume` as `totalTankVolume`.
+* Convert units: `speed * 1.60934` as `speedInKmh`.
+* Apply formula: `(temperature * 1.8) + 32` as `temperatureF`.
+
+#### script
+
+Script-based calculations producing **one or multiple output** keys.
+
+**When to use:**
+* The calculation isn't a simple linear formula.
+* You need multiple derived values from the same inputs.
+* Conditional logic or branching is required.
+* You need to analyze multiple historical readings with custom logic (filtering, conditional counting, duration tracking) — not just simple aggregation (use `tsAggregation` for that).
+
+**Examples:**
+* Multiple outputs: Calculate battery status producing both `batteryPercentage` and `batteryStatus` ("Low"/"Normal"/"High").
+* Conditional logic: Derive `operatingMode` as "Eco" if power < 100, "Normal" if power < 500, else "Turbo".
+* Complex algorithm: Calculate Air Quality Index `aqi` by comparing `PM2.5` and `Ozone` levels against EPA breakpoint tables.
+* Rolling window — duration tracking: "Calculate `complianceBreachDuration` as the cumulative time in minutes where `temperature` exceeds `maxStorageTemp`, max breach duration 2 hours".
+* Rolling window — stability monitoring: "Calculate `voltageStability` as the standard deviation of `voltage` readings over the last 1 hour".
+* Rolling window — per-instance threshold analysis: "Calculate `vibrationExceedanceRate` as the percentage of `vibration` readings that exceeded `maxAllowedVibration` over the last 1 hour".
+
+**Rolling window scripts:**
+When a script metric needs access to historical readings over a time period (not just the latest value), the calculation description **MUST** include the time window or maximum expected duration. Without this, the downstream system cannot configure the data retrieval window.
+* Always specify the period: "in the last 1 hour", "over the last 4 hours", "max cycle duration 2 hours".
+* Use rolling window scripts for custom logic over historical data: per-instance threshold analysis, conditional counting, duration tracking, stability monitoring (std dev), min-max spread.
+* Use `tsAggregation` instead when you only need simple aggregation (AVG, SUM, MIN, MAX, COUNT) over a fixed interval.
+
+#### tsAggregation
+
+Aggregate a **single entity's own** time series data over a time window (temporal aggregation — one entity, many readings over time).
+
+**When to use:**
+* You need a daily or hourly average, sum, min, max, or count of a device's own telemetry.
+
+**When NOT to use:**
+* You need to aggregate across multiple entities — that's `relatedAggregation`.
+* You need arithmetic inside the aggregation — compute first with `math` or `script`, then aggregate.
+
+**Constraints:**
+* Only count, min, max, average, or sum of numeric telemetry. No arithmetic expressions inside the aggregation.
+* Up to 10 input keys and 10 output metrics per entry.
+* When multiple output keys share the same source profile and aggregation type, merge them into a single metric.
+
+**Examples:**
+* Calculate daily average `aqi` as `dailyAvgAqi` on EnvironmentSensor.
+* Calculate daily sum of energy rate as `dailyEnergyConsumption`.
+
+#### relatedAggregation
+
+Compute an aggregate (average, sum, count, min, max) **across multiple related entities** (spatial aggregation — many entities, one reading each). 
+The metric is always defined on the parent entity profile, aggregating data from child entity profiles related to that parent.
+
+**When to use:**
+* Multiple child entities of the same profile report a key you need to roll up to the parent (e.g., average AQI across Rooms for a Building, total offline count across devices for a Site).
+* Multiple child profiles of the same functional category share the aggregated key (e.g., Tractor, Sprayer, Harvester all report `dailyFuelConsumption`) — a single metric can aggregate from all of them. Reference all child profiles in the calculation string (e.g., "from Tractors, Sprayers, and Harvesters").
+* Conditional counting or filtering: use `where` to count or aggregate only children matching a condition. Use this instead of creating intermediate boolean/numeric script metrics just for counting. The `where` clause references a key on the child entity profile.
+
+**When NOT to use:**
+* A parent has only one child entity total for this relation (not multiple profiles of the same category — just genuinely one entity) — that's `propagate`, not aggregation.
+* You need a time-based aggregate of a single child's own telemetry — that's `tsAggregation` on the child.
+
+**Constraints:**
+* Same arithmetic limits as `tsAggregation` — only count, min, max, average, or sum. No arithmetic expressions.
+* Can only pull from **direct children** (one level below). If your calculation references entities that are not direct children (grandchildren or deeper), you MUST split it into intermediate metrics — one per level (see Pattern 5 in Combination patterns). Never write a single `relatedAggregation` that skips levels.
+  * *1:1 leaf — Wrong:* Site → Equipment (1:M) → Engine (1:1), metric on Site: "Calculate COUNT of Engines where `status` is 'RUNNING' as `activeEngines`" — Engine is a grandchild of Site.
+  * *1:1 leaf — Correct:* (1) `propagate` on Engine: "Propagate `status` from Engine to Equipment", then (2) `relatedAggregation` on Site: "Calculate COUNT of Equipment where `status` is 'RUNNING' as `activeEngines`".
+  * *1:M leaf — Wrong:* Building → Floor (1:M) → Sensor (1:M), metric on Building: "Calculate AVG of `temperature` from all Sensors as `avgBuildingTemp`" — Sensor is a grandchild of Building.
+  * *1:M leaf — Correct:* (1) `relatedAggregation` on Floor: "Calculate AVG of `temperature` from all Sensors as `avgFloorTemp`", then (2) `relatedAggregation` on Building: "Calculate AVG of `avgFloorTemp` from all Floors as `avgBuildingTemp`".
+* Up to 10 input keys and 10 output metrics per entry. When multiple output keys share the same source profile and aggregation type, merge them into a single metric.
+* When child profiles measure fundamentally different things (e.g., EnergyMeter vs WaterMeter), create **separate** metrics — one per child profile.
+
+**Examples:**
+* *Same-category children:* Farm has Tractor, Sprayer, and Harvester children, all with `dailyFuelConsumption` (derived via delta → tsAggregation). One metric:
+  * "Calculate SUM of `dailyFuelConsumption` from Tractors, Sprayers, and Harvesters as `totalFleetFuelConsumption`" on **Farm** profile.
+* *Different-role children:* Building has EnergyMeter and WaterMeter. Two separate metrics:
+  * "Calculate SUM of `dailyEnergy` from EnergyMeters as `totalDailyEnergy`" on **Building** profile.
+  * "Calculate SUM of `dailyWater` from WaterMeters as `totalDailyWater`" on **Building** profile.
+* *Conditional counting:* ParkingLot has ParkingSensor children with an `occupied` boolean key. One metric:
+  * "Calculate COUNT of ParkingSensors where `occupied` is true as `occupiedSpaces`" on **ParkingLot** profile.
+  * No intermediate script metric needed — the `where` clause filters directly on the child key.
+
+#### propagate
+
+Copy data from one entity to a related entity. The metric is always defined on the **source** entity profile (where data originates), NOT on the destination.
+
+**When to use:**
+* A 1:1 child needs to push its data up to a parent (e.g., Tracker pushes GPS to Container).
+* Attributes or telemetry must be visible on a parent entity without aggregation.
+
+**When NOT to use:**
+* The parent has multiple children of this profile, or multiple children across same-category profiles that share the key — use `relatedAggregation` instead (multiple children pushing to the same key overwrite each other).
+
+**Constraints:**
+* Each propagation metric targets exactly one parent profile using the "from [Source] to [Destination]" pattern.
+* Group all **timeseries** keys into one metric; group all **attribute** keys into a separate metric. Do not mix.
+* Keys are copied exactly — no renaming allowed.
+
+**Examples:**
+* Propagate `latitude`, `longitude` timeseries from Tracker to Container — metric on **Tracker** profile.
+* Propagate `fwVersion`, `serialNumber` attributes from Thermostat to Room — metric on **Thermostat** profile.
+* Propagate `dailyEnergy` from EnergyMeter to Office — metric on **EnergyMeter** profile.
+
+#### geofencing
+
+Evaluate an entity's GPS coordinates (`latitude` and `longitude`) against predefined geometric zones. Zones are typically defined as a `perimeter` attribute of a related asset profile.
+
+**When to use:**
+* A tracked entity (vehicle, person, asset) needs zone-entry/exit detection against one or more geographic areas.
+
+**Constraints:**
+* Create **one metric per zone profile type**. Do NOT combine multiple zone types in a single metric.
+* Each metric evaluates against zones of exactly one profile and produces exactly one output status key.
+
+**Examples:**
+* *Wrong*: one metric calculating both `allowedZoneStatus` and `restrictedZoneStatus`.
+* *Correct*: Metric 1 calculates `allowedZoneStatus` against `AllowedZone` perimeters; Metric 2 calculates `restrictedZoneStatus` against `RestrictedZone` perimeters.
+
+#### delta
+
+Compute the difference between two consecutive readings of a timeseries key. Two modes:
+* **increase** — for cumulative counters that go up (engine hours, energy registers, odometers).
+* **decrease** — for gauges that go down when consumed (fuel level, battery level, tank fill level).
+
+**When to use:**
+* Derive a rate or increment from a cumulative counter or a depleting gauge.
+* Often chained with `tsAggregation` to get daily totals (see Pattern 1).
+
+**Constraints:**
+* Exactly **one** input key and **one** output key per metric. Multiple counters = multiple `delta` metrics.
+* Do NOT embed the `tsAggregation` step in the delta's calculation string — each metric describes one operation.
+
+**Examples:**
+* Increasing counter: "Calculate `engineHourIncrement` from `totalEngineHours`"
+* Decreasing gauge: "Calculate `fuelConsumptionRate` from `fuelLevel`"
+
+**Wrong** (do **NOT** do this — groups two counters into one metric):
+* "Calculate `waterConsumptionRate` from `waterPulse` and `energyConsumptionRate` from `energyPulse`"
+
+**Correct** (one metric per counter):
+* Metric 1: "Calculate `waterConsumptionRate` from `waterPulse`"
+* Metric 2: "Calculate `energyConsumptionRate` from `energyPulse`"
+
+#### Choosing between propagate and relatedAggregation
+
+Evaluate each parent-child relationship independently based on cardinality:
+
+| Cardinality                                | Metric type                             | Defined on     | Why                                                                                                  |
+|--------------------------------------------|-----------------------------------------|----------------|------------------------------------------------------------------------------------------------------|
+| **1:1**                                    | `propagate`                             | Child profile  | Pushes data up. `relatedAggregation` on a single value is meaningless.                               |
+| **1:N** (same profile)                     | `relatedAggregation`                    | Parent profile | Aggregates across children. `propagate` from multiple children overwrites.                           |
+| **1:N** (same category, multiple profiles) | `relatedAggregation`                    | Parent profile | Single metric aggregates across all same-category children (e.g., Tractors + Sprayers + Harvesters). |
+| **1:N** (different roles)                  | Separate `relatedAggregation` per child | Parent profile | Different data → separate metrics (e.g., EnergyMeter vs WaterMeter).                                 |
+
+**1:1 + time-based aggregate**: When 1:1 AND you need a daily/hourly aggregate — use `tsAggregation` on the child first, then `propagate` the result. Do NOT use `relatedAggregation` on the parent.
+* *Example*: Room has one EnvironmentSensor → `tsAggregation` on sensor computes `dailyAvgAqi` → `propagate` pushes it to Room.
+
+#### Combination patterns
+
+Metric types are often chained:
+
+**Pattern 1 — Derive then aggregate (delta → tsAggregation)**
+
+Use when a device reports a cumulative counter or a depleting gauge and you need a daily/hourly total.
+
+1. `delta`: per-reading change.
+   * Increasing counter: `"Calculate \`engineHourIncrement\` from \`totalEngineHours\`"`
+   * Decreasing gauge: `"Calculate \`fuelConsumptionRate\` from \`fuelLevel\`"` (decrease mode)
+2. `tsAggregation`: daily total (e.g., `"Calculate daily SUM of \`fuelConsumptionRate\` as \`dailyFuelConsumption\`"`).
+
+**Pattern 2 — Compute then roll up (math/script → tsAggregation → relatedAggregation)**
+
+Use when raw telemetry needs transformation, time-windowed aggregation, and then a parent-level rollup.
+
+1. `math` or `script`: derive a key per device (e.g., AQI from PM2.5 and Ozone).
+2. `tsAggregation`: daily average or sum on the device.
+3. `relatedAggregation`: roll up to the parent asset.
+
+**Pattern 3 — Propagate then aggregate (tsAggregation → propagate → relatedAggregation)**
+
+Use when a 1:1 child computes a time-window aggregate that must surface on its parent and be rolled up further.
+
+1. `tsAggregation`: aggregate on the device (e.g., daily max speed on Tracker).
+2. `propagate`: push to direct parent (e.g., Tracker → Container, 1:1).
+3. `relatedAggregation`: aggregate across all parents at the fleet level.
+
+**Pattern 4 — Cross-profile aggregation (delta → tsAggregation → relatedAggregation)**
+
+Use when multiple child profiles of the same category share a key and you need a fleet/site-level total.
+
+1. `delta` on each child profile: derive per-reading change (e.g., `fuelConsumptionRate` from `fuelLevel` on Tractor, Sprayer, Harvester).
+2. `tsAggregation` on each child profile: daily total (e.g., `dailyFuelConsumption`).
+3. `relatedAggregation` on parent: single metric aggregates from all same-category children (e.g., "Calculate SUM of `dailyFuelConsumption` from Tractors, Sprayers, and Harvesters as `totalFleetFuelConsumption`" on Farm).
+
+**Pattern 5 — Multi-level chaining**
+
+`relatedAggregation` can only pull from **direct children** — it cannot skip levels. When data must travel multiple levels up, create one intermediate metric per level.
+
+* *1:1 leaf*: Building → Office → Room → EnvironmentSensor (one sensor per room):
+  1. `propagate` on EnvironmentSensor → pushes `dailyAvgAqi` to Room (1:1).
+  2. `relatedAggregation` on Office → averages `dailyAvgAqi` from Rooms (1:N).
+
+* *1:N at every level*: Building → Floor → Room → TemperatureSensors:
+  1. `relatedAggregation` on Room → averages `temperature` from sensors (1:N).
+  2. `relatedAggregation` on Floor → averages `avgRoomTemp` from Rooms (1:N).
+  3. `relatedAggregation` on Building → averages `avgFloorTemp` from Floors (1:N).
+
+Do **NOT** skip any level in either pattern. Every `relatedAggregation` calculation must reference only the **direct child** profile — if you find yourself naming a grandchild entity in the calculation string, stop and add the intermediate metrics first.
+
+### Alarms
+
+Alarms are profile-level rules — each alarm is defined on one or more entity profiles and evaluates on every instance of those profiles. Alarms are automatically delivered to users; you do NOT need to ask about notification channels.
+
+To define an alarm, provide: the alarm name, the profile names it applies to, and the condition.
+
+**Alarm constraints:**
+* **Threshold sources**: Alarm conditions can **ONLY** compare telemetry against:
+  * Static values (e.g., `temperature > 30`, `restrictedAreaStatus` = "INSIDE").
+  * Attributes on the **source entity** (e.g., `speed` > `maxSpeedLimit`).
+  * Attributes on the **Customer** (e.g., `dailyAvgTemperature` > `maxTemperatureThreshold`, `occupied` = true for more than `maxStayDuration`).
+  **Constraint**: You **MUST NOT** label whether an attribute belongs to the source entity or customer.
+* **No parent access**: Alarms **CANNOT** access attributes from a parent entity profile (e.g., Building, Floor, Fleet). Do **NOT** work around this by creating a propagation metric to push a parent attribute down to a child for alarm evaluation. Use a customer attribute or a static value instead.
+* **Shared thresholds**: If a threshold attribute is shared across multiple device profiles, define it as a **customer attribute**.
+* **Existing telemetry**: Prefer referencing telemetry keys and attributes already defined in entity profiles. Avoid inventing new input fields unless necessary.
+

thingsboard_cli/resources/prompts/solutions/solution-ba/resources/solution-in-progress-example.json

@@ -0,0 +1,6 @@
+{
+  "title": "Generic IoT Solution",
+  "status": "IN_PROGRESS",
+  "skipInterviewAllowed": false,
+  "assumptionsAndQuestions": "Happy to help design this IoT solution! Here are my initial assumptions and a few questions to make sure the design fits your needs.\n\n### Assumptions\n\n1.  **Deployment scope**: I'm assuming this is an internal monitoring solution for your own operation (tenant-only, no customer hierarchy). If you're building a product or managed service for multiple independent organizations that each need isolated access to their own data, let me know and I'll add a customer hierarchy.\n2.  **Asset hierarchy**: I'll keep the structure flat unless you manage devices across multiple named physical locations — in that case I'll add a location container asset.\n3.  **Core focus**: The primary goals are monitoring environmental conditions (e.g., temperature, humidity) and tracking critical boolean states (e.g., leak detected, smoke detected).\n\n### Questions for You\n\n1.  **What are the key priorities for this solution?** Are you focusing more on environmental quality, safety alerts from state sensors, or operational efficiency?\n2.  **What specific types of data points will be monitored?** For example, are you interested in numerical telemetry (like temperature), simple boolean states (like `stateDetected`), or more complex calculated values?\n3.  **Will the solution need to cover any outdoor areas?** This is important for deciding whether to use indoor coordinates (xPos, yPos) or outdoor GPS tracking (latitude, longitude) for assets and devices."
+}

thingsboard_cli/resources/prompts/solutions/solution-ba/resources/solution-ready-example-1.json

@@ -0,0 +1,26 @@
+{
+  "title": "Fleet GPS Tracking",
+  "status": "READY",
+    "summary": "A logistics company tracks its delivery vehicles across multiple regions using GPS trackers. Vehicle locations are shown on an outdoor map in real time, and daily speed statistics are aggregated at both vehicle and fleet level. Restricted zones define areas where vehicles are not permitted to enter — violations trigger alerts if the vehicle stays inside beyond the allowed duration. Customer fleet managers oversee their own fleet independently, with operators monitoring daily activity.",
+  "demoRequirements": "For demo purposes: 1 fleet with 3 vehicles, 1 GPS tracker per vehicle, 2 restricted zones",
+  "deviceAndAssetProfiles": [
+    {"name": "GpsTracker", "type": "DEVICE", "keys": [{"name": "latitude"}, {"name": "longitude"}, {"name": "speed"}, {"name": "battery", "min": 0, "max": 100}]},
+    {"name": "Vehicle", "type": "ASSET", "keys": [{"name": "latitude"}, {"name": "longitude"}, {"name": "speed"}, {"name": "dailyMaxSpeed"}, {"name": "restrictedZoneStatus"}, {"name": "licensePlate"}]},
+    {"name": "RestrictedZone", "type": "ASSET", "keys": [{"name": "perimeter"}]},
+    {"name": "Fleet", "type": "ASSET", "keys": [{"name": "address"}, {"name": "latitude"}, {"name": "longitude"}, {"name": "dailyFleetMaxSpeed"}]}
+  ],
+  "customerAndUsers": "Tenant's **Technical User** provisions customers and monitors connectivity across all fleets.\nCustomer **TransportCompany** owns one or more fleets with all vehicles and trackers. The `lowBatteryThreshold`, `maxStayDuration`, `maxSpeedLimit`, and `offlineThreshold` are configured at the customer level.\n**Fleet Manager** is a Customer Administrator who manages all vehicles, user access and thresholds configuration.\n**Fleet Operator** is a Customer User who monitors vehicle locations and active alerts.",
+  "relations": "Fleet owns Vehicles and RestrictedZones. Each Vehicle has one GpsTracker assigned for positioning.",
+  "metrics": [
+    {"profileName": "GpsTracker", "metricType": "tsAggregation", "calculation": "Calculate daily maximum `speed` as `dailyMaxSpeed`"},
+    {"profileName": "GpsTracker", "metricType": "propagate", "calculation": "Propagate `latitude`, `longitude`, `speed`, `dailyMaxSpeed` from GpsTracker to Vehicle"},
+    {"profileName": "Vehicle", "metricType": "geofencing", "calculation": "Calculate vehicle status against RestrictedZones as `restrictedZoneStatus` (INSIDE or OUTSIDE)"},
+    {"profileName": "Fleet", "metricType": "relatedAggregation", "calculation": "Calculate maximum `dailyMaxSpeed` from all child Vehicles as `dailyFleetMaxSpeed`"}
+  ],
+  "alarms": [
+    {"profileNames": ["Vehicle"], "alarmName": "VehicleInRestrictedZone", "condition": "restrictedZoneStatus = INSIDE for more than maxStayDuration"},
+    {"profileNames": ["Vehicle"], "alarmName": "SpeedLimitExceeded", "condition": "speed > maxSpeedLimit"},
+    {"profileNames": ["GpsTracker"], "alarmName": "LowBattery", "condition": "battery < lowBatteryThreshold"},
+    {"profileNames": ["GpsTracker"], "alarmName": "TrackerOffline", "condition": "no telemetry for offlineThreshold"}
+  ]
+}

thingsboard_cli/resources/prompts/solutions/solution-ba/resources/solution-ready-example-2.json

@@ -0,0 +1,26 @@
+{
+  "title": "Smart Warehouse Indoor Monitoring",
+  "status": "READY",
+  "summary": "A warehouse operator monitors environment conditions across indoor storage sections. EnvironmentSensors are placed on the floor plan image using indoor coordinates (xPos, yPos). WarehouseSections (e.g., Storage, Shipping, Production) are highlighted as indoor zone polygons on the floor plan for visual orientation. Alarms trigger on poor air quality, high temperature, and sensor connectivity issues.",
+  "demoRequirements": "For demo purposes: 1 warehouse with 3 sections (storage, shipping, production), 2 environment sensors per section",
+  "deviceAndAssetProfiles": [
+    {"name": "EnvironmentSensor", "type": "DEVICE", "keys": [{"name": "temperature"}, {"name": "humidity", "min": 0, "max": 100}, {"name": "co2"}, {"name": "battery", "min": 0, "max": 100}, {"name": "xPos"}, {"name": "yPos"}, {"name": "dewPoint"}, {"name": "aqi"}, {"name": "avgHourlyAqi"}, {"name": "lowBatteryThreshold"}, {"name": "consecutiveAlertCount"}]},
+    {"name": "Warehouse", "type": "ASSET", "keys": [{"name": "address"}, {"name": "latitude"}, {"name": "longitude"}, {"name": "floorPlan"}]},
+    {"name": "WarehouseSection", "type": "ASSET", "keys": [{"name": "indoorZone"}, {"name": "sectionType"}, {"name": "avgHourlySectionAqi"}]}
+  ],
+  "customerAndUsers": "Tenant's **Warehouse Manager** oversees all warehouse operations — manages devices, monitors environment across all zones, and resolves alarms. The `lowBatteryThreshold` and `consecutiveAlertCount` are configured per sensor by the Warehouse Manager. No customer hierarchy is required.",
+  "relations": "Warehouse has WarehouseSections. Each WarehouseSection has EnvironmentSensors installed in it.",
+  "metrics": [
+    {"profileName": "EnvironmentSensor", "metricType": "math", "calculation": "Calculate `dewPoint` based on `temperature` and `humidity`"},
+    {"profileName": "EnvironmentSensor", "metricType": "script", "calculation": "Calculate Air Quality Index `aqi` from `co2` and `humidity`"},
+    {"profileName": "EnvironmentSensor", "metricType": "tsAggregation", "calculation": "Calculate hourly average `aqi` as `avgHourlyAqi`"},
+    {"profileName": "WarehouseSection", "metricType": "relatedAggregation", "calculation": "Calculate average `avgHourlyAqi` for WarehouseSection from all child EnvironmentSensors as `avgHourlySectionAqi`"}
+  ],
+  "alarms": [
+    {"profileNames": ["EnvironmentSensor"], "alarmName": "HighCo2", "condition": "co2 > 1000 (warning); co2 > 2000 (critical)"},
+    {"profileNames": ["EnvironmentSensor"], "alarmName": "HighTemperature", "condition": "temperature > 35"},
+    {"profileNames": ["EnvironmentSensor"], "alarmName": "PersistentHighTemperature", "condition": "temperature > 30 for consecutiveAlertCount consecutive readings"},
+    {"profileNames": ["EnvironmentSensor"], "alarmName": "LowBattery", "condition": "battery < lowBatteryThreshold"},
+    {"profileNames": ["EnvironmentSensor"], "alarmName": "SensorOffline", "condition": "no telemetry for 10 min"}
+  ]
+}

thingsboard_cli/resources/prompts/solutions/solution-ba/resources/solution-ready-example-3.json

@@ -0,0 +1,24 @@
+{
+  "title": "Cold Chain Temperature Monitoring",
+  "status": "READY",
+  "summary": "A cold chain logistics provider ensures temperature compliance across refrigerated storage facilities operated for multiple food retailers. Freezing units and auxiliary temperature loggers are physically installed inside each facility and visible on the storage floor plan. A math metric tracks each unit's deviation from its configured setpoint, and a rolling-window script metric tracks the cumulative time temperature exceeds the retailer's max storage threshold (max breach duration 2 hours). Alerts fire when temperature falls outside the retailer's permitted range, when the deviation persists beyond the retailer's allowed duration, or when a door is left open.",
+  "demoRequirements": "For demo purposes: 1 cold storage facility with 2 freezing units and 2 temperature loggers",
+  "deviceAndAssetProfiles": [
+    {"name": "FreezingUnit", "type": "DEVICE", "keys": [{"name": "temperature"}, {"name": "doorOpen"}, {"name": "battery", "min": 0, "max": 100}, {"name": "tempDeviation"}, {"name": "complianceBreachDuration"}, {"name": "setpointTemperature"}, {"name": "positionX"}, {"name": "positionY"}]},
+    {"name": "TemperatureLogger", "type": "DEVICE", "keys": [{"name": "temperature"}, {"name": "battery", "min": 0, "max": 100}, {"name": "positionX"}, {"name": "positionY"}]},
+    {"name": "ColdStorage", "type": "ASSET", "keys": [{"name": "address"}, {"name": "latitude"}, {"name": "longitude"}, {"name": "storagePlan"}]}
+  ],
+  "customerAndUsers": "Tenant's **Technical User** provisions customers and monitors device connectivity across all facilities.\nCustomer **FoodRetailer** owns multiple cold storage facilities with all devices inside. The `minStorageTemp` and `maxStorageTemp` temperature bounds, `maxTempDeviation` tolerance, and `driftAlarmDurationMinutes` are configured at the customer level to enforce their compliance standard.\n**Cold Chain Manager** is a Customer Administrator who manages all storage units and user access.\n**Store Supervisor** is a Customer User who monitors unit conditions and responds to alerts.",
+  "relations": "ColdStorage has FreezingUnits and TemperatureLoggers installed inside.",
+  "metrics": [
+    {"profileName": "FreezingUnit", "metricType": "math", "calculation": "Calculate `tempDeviation` as the absolute difference between `temperature` and `setpointTemperature`"},
+    {"profileName": "FreezingUnit", "metricType": "script", "calculation": "Calculate `complianceBreachDuration` as the cumulative time in minutes where `temperature` exceeds `maxStorageTemp`, max breach duration 2 hours"}
+  ],
+  "alarms": [
+    {"profileNames": ["FreezingUnit"], "alarmName": "TemperatureDriftAlert", "condition": "tempDeviation > maxTempDeviation for more than driftAlarmDurationMinutes"},
+    {"profileNames": ["FreezingUnit"], "alarmName": "DoorLeftOpen", "condition": "doorOpen = true"},
+    {"profileNames": ["FreezingUnit", "TemperatureLogger"], "alarmName": "TemperatureOutOfRange", "condition": "temperature < minStorageTemp OR temperature > maxStorageTemp"},
+    {"profileNames": ["FreezingUnit", "TemperatureLogger"], "alarmName": "LowBattery", "condition": "battery < 20"},
+    {"profileNames": ["FreezingUnit", "TemperatureLogger"], "alarmName": "DeviceOffline", "condition": "no telemetry for 15 min"}
+  ]
+}

thingsboard_cli/resources/prompts/solutions/solution-ba/resources/solution-ready-example-4.json

@@ -0,0 +1,23 @@
+{
+  "title": "Solar Inverter Monitoring",
+  "status": "READY",
+  "summary": "Monitor a solar inverter to track energy generation, detect grid anomalies, and catch faults early. The inverter reports real-time AC and DC electrical parameters, temperature, and cumulative energy yield. Conversion efficiency and daily yield totals are derived automatically. Alerts fire when grid voltage or frequency drifts outside configured limits, the inverter overheats, or a fault is reported.",
+  "demoRequirements": "For demo purposes: 1 solar inverter",
+  "deviceAndAssetProfiles": [
+    {"name": "SolarInverter", "type": "DEVICE", "keys": [{"name": "totalYield"}, {"name": "acPower"}, {"name": "dcVoltage"}, {"name": "dcCurrent"}, {"name": "acVoltage"}, {"name": "frequency"}, {"name": "temperature"}, {"name": "status", "allowedValues": ["normal", "fault", "offline"]}, {"name": "efficiency", "min": 0, "max": 100}, {"name": "yieldIncrement"}, {"name": "dailyYield"}, {"name": "minAcVoltage"}, {"name": "maxAcVoltage"}, {"name": "minFrequency"}, {"name": "maxFrequency"}, {"name": "maxWarningTemperature"}, {"name": "maxCriticalTemperature"}]}
+  ],
+  "customerAndUsers": "Tenant's **Solar System Operator** monitors the inverter, reviews daily yield trends, and responds to fault alerts. The `minAcVoltage`, `maxAcVoltage`, `minFrequency`, `maxFrequency`, `maxWarningTemperature`, and `maxCriticalTemperature` thresholds are configured on the inverter by the operator. No customer hierarchy is required.",
+  "relations": "No relations — inverter is a standalone device managed directly by the tenant.",
+  "metrics": [
+    {"profileName": "SolarInverter", "metricType": "math", "calculation": "Calculate conversion `efficiency` (%) from `acPower` divided by the product of `dcVoltage` × `dcCurrent`"},
+    {"profileName": "SolarInverter", "metricType": "delta", "calculation": "Calculate `yieldIncrement` from `totalYield`"},
+    {"profileName": "SolarInverter", "metricType": "tsAggregation", "calculation": "Calculate daily SUM of `yieldIncrement` as `dailyYield`"}
+  ],
+  "alarms": [
+    {"profileNames": ["SolarInverter"], "alarmName": "VoltageOutOfRange", "condition": "acVoltage < minAcVoltage OR acVoltage > maxAcVoltage"},
+    {"profileNames": ["SolarInverter"], "alarmName": "FrequencyOutOfRange", "condition": "frequency < minFrequency OR frequency > maxFrequency"},
+    {"profileNames": ["SolarInverter"], "alarmName": "Overtemperature", "condition": "temperature > maxWarningTemperature (warning); temperature > maxCriticalTemperature (critical)"},
+    {"profileNames": ["SolarInverter"], "alarmName": "InverterFault", "condition": "status == \"fault\""},
+    {"profileNames": ["SolarInverter"], "alarmName": "InverterOffline", "condition": "no telemetry for 5 min"}
+  ]
+}