thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/resources/prompts/solutions/dashboard/resources/states/dashboard-states-schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Dashboard states overview",
+  "description": "A schema for generating dashboard states overview.",
+  "type": "object",
+  "properties": {
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique state identifier in kebab-case (e.g. root, customer-details, facility-overview)"
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable state name (e.g. Root, Customer Details, Facility Overview)"
+          },
+          "description": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["collection", "standardDetail", "switcherDetail", "overview", "statistics"],
+            "description": "Type of this state. collection: root state showing all entities. standardDetail: entity detail with header and data body. switcherDetail: entity navigation hub with header and navigation widgets only, no data. overview: sibling state with entity overview. statistics: sibling state with entity analytics/statistics."
+          },
+          "rootStateEntity": {
+            "type": "string",
+            "description": "camelCase name for the entity passed to this state via drill-down (e.g. selectedCustomer, selectedBuilding). Null for root state."
+          },
+          "widgets": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/widget" }
+          },
+          "backgroundColor": {
+            "type": "string",
+            "description": "State background color as a hex code (e.g. '#EEEEEE'). Default is '#EEEEEE'. Only set a different value if userRequirements specifies a background color."
+          },
+          "userRequirements": {
+            "type": "string",
+            "description": "User requirements for this state — layout directives (widget sizes, positions), appearance, or any other state-level preferences. Omit if no requirements apply to this state."
+          }
+        },
+        "required": ["id", "name", "description", "type", "widgets"]
+      }
+    }
+  },
+  "$defs": {
+    "widget": {
+      "type": "object",
+      "properties": {
+        "widgetName": {
+          "type": "string"
+        },
+        "widgetClass": {
+          "type": "string",
+          "enum": [
+            "entityTable",
+            "headerCard",
+            "infoCard",
+            "outdoorMap",
+            "indoorMap",
+            "horizontalValueCard",
+            "actionButton",
+            "navigationWidget",
+            "simpleGauge",
+            "progressBar",
+            "batteryLevel",
+            "signalStrength",
+            "valueChartCard",
+            "chart",
+            "stateChart",
+            "rangeChart",
+            "alarmTable",
+            "pieChart",
+            "barChart",
+            "alarmCount",
+            "connectRealDevices"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "keys": {
+          "type": "string",
+          "description": "Comma-separated list of entity fields, attributes, and telemetry keys used by this widget (e.g. 'name, label, address, capacity, dailyConsumption'). Use empty string for widgets that don't require any data keys"
+        },
+        "requirements": {
+          "type": "string",
+          "description": "Widget-specific user requirements (styling, colors, display behavior). Omit if no user requirements apply to this widget."
+        }
+      },
+      "required": [ "widgetName", "widgetClass", "description", "keys" ]
+    }
+  }
+}

thingsboard_cli/resources/prompts/solutions/data-generator/resources/customer-and-users-generator-schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Users and Customers Generator Schema",
+  "description": "Schema for generating users and customers",
+  "type": "object",
+  "properties": {
+    "customer": {
+      "anyOf": [
+        {"$ref": "#/$defs/customer"},
+        {"type": "null"}
+      ]
+    },
+    "users": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/user"
+      }
+    }
+  },
+  "required": ["customer", "users"],
+  "$defs": {
+    "customer": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "profile": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        },
+        "timeseries": {
+          "type": "array",
+          "description": "Constant initial values for TIMESERIES keys on this customer. Empty array if the customer profile has no TIMESERIES telemetry.",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        }
+      },
+      "required": ["name", "profile", "attributes", "timeseries"]
+    },
+    "user": {
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string"
+        },
+        "firstName": {
+          "type": "string"
+        },
+        "lastName": {
+          "type": "string"
+        },
+        "profile": {
+          "type": "string"
+        },
+        "customer": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        },
+        "timeseries": {
+          "type": "array",
+          "description": "Constant initial values for TIMESERIES keys on this user. Empty array if the user profile has no TIMESERIES telemetry.",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        }
+      },
+      "required": ["email", "firstName", "lastName", "profile", "attributes", "timeseries"]
+    },
+    "kv": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        }
+      },
+      "required": ["key", "value"]
+    }
+  }
+}

thingsboard_cli/resources/prompts/solutions/data-generator/resources/devices-and-assets-generator-schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Assets, Devices and Generator Overviews Schema",
+  "description": "Schema for generating assets, devices and simplified generator overviews",
+  "type": "object",
+  "properties": {
+    "assets": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/asset"
+      }
+    },
+    "devices": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/device"
+      }
+    },
+    "generatorOverviews": {
+      "type": "array",
+      "description": "One entry per device — must contain exactly as many entries as the devices array, with no duplicate names",
+      "items": {
+        "$ref": "#/$defs/generatorOverview"
+      }
+    }
+  },
+  "required": ["assets", "devices", "generatorOverviews"],
+  "$defs": {
+    "asset": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "customer": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "profile": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        },
+        "timeseries": {
+          "type": "array",
+          "description": "Constant initial values for TIMESERIES keys on this asset. Empty array if the asset profile has no TIMESERIES telemetry.",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        }
+      },
+      "required": ["name", "profile", "attributes", "timeseries"],
+      "additionalProperties": false
+    },
+    "device": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "customer": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "profile": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/kv"
+          }
+        }
+      },
+      "required": ["name", "label", "profile", "attributes"]
+    },
+    "generatorOverview": {
+      "type": "object",
+      "required": ["name", "telemetryProfiles"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Device name this generator is for — must be unique across all generatorOverviews (exactly one overview per device)"
+        },
+        "telemetryProfiles": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/telemetryProfileOverview"
+          }
+        }
+      }
+    },
+    "telemetryProfileOverview": {
+      "type": "object",
+      "required": ["key", "valueStrategyType", "dataType", "ctx"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Telemetry key name (e.g., temperature, battery)"
+        },
+        "valueStrategyType": {
+          "type": "string",
+          "enum": ["COUNTER", "NATURAL", "EVENT", "SEQUENCE", "CONSTANT", "COMPOSITE", "SCHEDULE", "INCREMENT", "DECREMENT"],
+          "description": "Type of value generation strategy"
+        },
+        "ctx": {
+          "type": "string",
+          "description": "Optional context for value strategy generation (e.g., coordinate bounds, constraints)"
+        },
+        "dataType": {
+          "type": "string",
+          "enum": ["boolean", "double", "integer", "string", "enum"],
+          "description": "Data type of the telemetry key"
+        }
+      }
+    },
+    "kv": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        }
+      },
+      "required": ["key", "value"]
+    }
+  }
+}

thingsboard_cli/resources/prompts/solutions/data-generator/resources/entity-relations-schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Entity Relations Schema",
+  "description": "Schema for generating specific entity-to-entity relations",
+  "type": "object",
+  "properties": {
+    "relations": {
+      "type": "array",
+      "description": "List of parent entities with their relations",
+      "items": {
+        "$ref": "#/$defs/parentRelations"
+      }
+    }
+  },
+  "required": ["relations"],
+  "$defs": {
+    "parentRelations": {
+      "type": "object",
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Parent entity name"
+        },
+        "fromType": {
+          "type": "string",
+          "enum": ["CUSTOMER", "ASSET", "DEVICE"],
+          "description": "Parent entity type"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/childRelation"
+          }
+        }
+      },
+      "required": ["from", "fromType", "children"],
+      "additionalProperties": false
+    },
+    "childRelation": {
+      "type": "object",
+      "properties": {
+        "to": {
+          "type": "string",
+          "description": "Child entity name"
+        },
+        "type": {
+          "type": "string",
+          "description": "Relation type (e.g., Contains, Manages, Uses)"
+        }
+      },
+      "required": ["to", "type"],
+      "additionalProperties": false
+    }
+  }
+}

thingsboard_cli/resources/prompts/solutions/data-generator/resources/generator-guidelines.md

@@ -0,0 +1,280 @@
+# Generator Demo Data Guidelines
+
+---
+
+## 1. Strategy Selection
+
+### Quick Reference
+
+| Strategy  | Description                                                                       | Supported dataType            |
+|-----------|-----------------------------------------------------------------------------------|-------------------------------|
+| NATURAL   | Fluctuating values oscillating within a range (temperature, humidity, pressure)   | double, integer               |
+| COUNTER   | Continuously increasing, resets after max (energy meters, odometers)              | double, integer               |
+| EVENT     | Binary toggle with configurable probability per tick (motion detected, door open) | boolean                       |
+| CONSTANT  | Fixed value that never changes (firmware version, enum state, alarm demo)         | any                           |
+| SEQUENCE  | Predefined list played sequentially or randomly (GPS tracks, enum cycles)         | double, integer, string, enum |
+| COMPOSITE | Two EVENT strategies with different probabilities for day vs. night               | boolean                       |
+| SCHEDULE  | Switches between INCREMENT/DECREMENT sub-strategies on a time-of-day schedule     | double, integer               |
+| INCREMENT | Steadily increases to end value then stops (tank filling, battery charging)       | double, integer               |
+| DECREMENT | Steadily decreases to end value then stops (battery drain, fuel consumption)      | double, integer               |
+
+### Data-Type Constraints (CRITICAL)
+
+- **boolean**: ONLY `COMPOSITE`, `EVENT`, or `CONSTANT` — never `SCHEDULE`, `NATURAL`, `COUNTER`, `INCREMENT`, or `DECREMENT`
+- **double / integer**: `NATURAL`, `COUNTER`, `INCREMENT`, `DECREMENT`, `SCHEDULE`, `CONSTANT`, or `SEQUENCE`
+- **string**: `CONSTANT` or `SEQUENCE` only
+- **enum**: `CONSTANT` or `SEQUENCE` only — values must be string literals from the defined enum list, not numbers
+
+---
+
+## 2. Per-Strategy ctx Reference
+
+Write `ctx` as a concrete, natural-language sentence. Avoid vague words ("rare", "frequent") and avoid restating just the key name or location without behavioral meaning.
+
+### NATURAL
+Fluctuating numeric values that oscillate between thresholds. Include sensor purpose, environment, and any alarm thresholds so oscillation naturally crosses them.
+
+**ctx examples:**
+- `"Indoor office temperature sensor"`
+- `"Humidity sensor in desert climate"`
+- `"IAQ sensor, CO₂ 400–900 ppm normal range, alarms at >1000 ppm (HighCo2Warning) or >2000 ppm (HighCo2Critical)"`
+
+### COUNTER
+Continuously increasing value. Describe what is being measured, units, and usage pattern.
+
+✅ `"Water usage meter in liters for high-traffic office floor with kitchen facilities"` — behavioral context
+❌ `"Water usage meter in liters for Executive Floor 5"` — location only, no useful context
+
+**ctx examples:**
+- `"Building energy consumption meter in kWh, increments faster during work hours"`
+- `"Vehicle odometer in miles for delivery truck with daily 50–100 mile routes"`
+- `"Production counter in units, 24/7 operation with shift changes"`
+
+### EVENT
+Binary toggle. `anomalyChance = N` means the event fires on average **1 in every N ticks**.
+
+**Tick math** — telemetry uploads every **30 minutes**, so:
+- 1 day = **48 ticks**, 1 week = **336 ticks**
+- Formula: `anomalyChance = 48 ÷ desired_fires_per_day`
+- Example: 3 times/day → `48 ÷ 3 = 16`
+
+**Do not write** vague words like "rare" or "frequent". **Do write** concrete frequency ("3 times per day", "once a week").
+
+**Frequency reference:**
+
+| Real-world frequency | anomalyChance |
+|----------------------|---------------|
+| ~10 times per day    | ~5            |
+| ~5 times per day     | ~10           |
+| ~2–3 times per day   | ~16–24        |
+| Once per day         | ~48           |
+| Every 2–3 days       | ~100–150      |
+| Once per week        | ~336          |
+
+**ctx examples:**
+- `"Motion sensor in office hallway, triggers 3–5 times per day during working hours"`
+- `"Door open/close sensor on a loading dock, opens roughly 10 times per day"`
+- `"Smoke detector — should almost never trigger, at most once a week"`
+- `"Vibration anomaly sensor on rotating equipment, 1–2 anomalies per day"`
+
+### CONSTANT
+Fixed value that never changes. For **enum** dataType: pick ONE appropriate value from the enum list.
+
+**ctx examples:**
+- `"Firmware version string"` → value: `"1.2.3"`
+- `"Device model identifier"` → value: `"SensorPro-X100"`
+- `"Machine status, enum values: [Ready, Brewing, Maintenance, Error]"` → pick one value
+
+### SEQUENCE
+Predefined list played back. For **enum**: values must be strings from the enum list. For GPS/indoor positioning: always include perimeter bounds (see Spatial Coherence for coordinate rules).
+
+**ctx format — GPS:**
+`"GPS tracking for <device> in <asset-name>, perimeter: [[lat,lng], [lat,lng], ...]"`
+
+**ctx format — indoor (xPos/yPos):**
+`"Indoor movement path for <device> on <asset-name>, perimeter: [[x,y], [x,y], ...], range: [0.0, 1.0]"`
+
+**ctx format — enum:**
+`"Operational state cycle, enum values: [Ready, Brewing, Maintenance, Error]"`
+
+**ctx examples:**
+- `"GPS tracking for delivery vehicle in Delivery Zone West, perimeter: [[37.77,-122.42], [37.78,-122.42], [37.78,-122.41], [37.77,-122.41]]"`
+- `"Indoor movement path for robot on Floor 1, perimeter: [[0.1,0.1], [0.9,0.1], [0.9,0.9], [0.1,0.9]], range: [0.0, 1.0]"`
+- `"Coffee machine operational state cycle, enum values: [Ready, Brewing, Maintenance, Error]"`
+
+### COMPOSITE
+Two EVENT strategies with different day vs. night probabilities. For boolean keys only. Describe the time-of-day behavioral contrast.
+
+**ctx examples:**
+- `"Motion sensor with active detections during business hours, quiet at night"`
+- `"Parking occupancy sensor with high activity during the day, near-empty overnight"`
+
+### SCHEDULE
+Switches between INCREMENT/DECREMENT on a time-of-day schedule. Describe the daily ramp-up/ramp-down pattern.
+
+**ctx examples:**
+- `"Office occupancy count with morning arrival ramp-up and evening departure ramp-down"`
+- `"HVAC temperature with scheduled heating in the morning, cooling in the afternoon"`
+- `"Parking lot occupancy with commuter patterns"`
+
+### INCREMENT
+Steadily increases to an end value then stops. Describe process and approximate start/end values.
+
+**ctx examples:**
+- `"Water tank filling from 0% to 100%"`
+- `"Battery charging from 20% to full"`
+- `"Warehouse capacity filling from 0 to 1000 pallets"`
+
+### DECREMENT
+Steadily decreases to an end value then stops. Describe process and approximate start/end values.
+
+**ctx examples:**
+- `"IoT device battery draining from 100% to 0%"`
+- `"Fuel tank decreasing from 100 gallons to empty"`
+- `"Cooling system temperature dropping from 80°C to ambient"`
+
+---
+
+## 3. Per-Device Context for Realistic Values
+
+### Profile-level Operational Range vs. Instance-level Demo Range
+
+Telemetry keys in the entity profile may include `minValue` and `maxValue`. These represent the **profile-level operational range** (used for widget display) — they cover the full range across all possible deployment contexts of that profile type. Do **NOT** use them as rigid generation bounds for individual devices.
+
+Instead, derive the realistic value range for each specific device from:
+1. The device's **name and label** (e.g., "Cold Room A" → -25 to -15°C; "Freezer Unit" → -40 to -30°C)
+2. The **asset the device relates to** (e.g., parent zone type, asset label)
+3. **Domain knowledge** about what the device is monitoring in that specific context
+
+Write these instances-specific bounds as concrete behavioral context into the `ctx` field of each device's `generatorOverview` entry.
+
+**Example** — same `TemperatureLogger` profile, different deployment contexts:
+- "Cold Room A" → ctx: `"Temperature logger in cold room, range -25 to -15°C"` (NATURAL strategy)
+- "Cold Room B" → ctx: `"Temperature logger in cold room, range -28 to -18°C"` (NATURAL strategy)
+- "Freezer Unit" → ctx: `"Temperature logger in deep freezer, range -40 to -30°C"` (NATURAL strategy)
+
+### Enum Keys
+
+For `enum` dataType keys: use the `enumValues` list from the telemetry key definition. Pick values via SEQUENCE (cycling through states) or CONSTANT (fixed demo state) as appropriate.
+
+## 4. Spatial Coherence
+
+### Using Relations to Determine Spatial Context
+
+Trace the relation chain to find the spatial container for each device:
+- **GpsTracker → Vehicle → Zone**: tracker coordinates should be within that Zone's perimeter
+- **TemperatureSensor → Room → Floor**: sensor coordinates should be within that Room's indoorPolygon
+
+### Customer Spatial Context
+
+Use `customer.name` to anchor real-world locations:
+- `"San Francisco Building Management"` → generate GPS coordinates near San Francisco
+- `"Texas Logistics Company"` → use Texas-area coordinates
+
+If the customer name implies no specific location, use generic but realistic coordinates appropriate for the solution type (parking lot, warehouse, office building, etc.).
+
+### Indoor Coordinates (xPos/yPos, positionX/positionY)
+
+All indoor position values are normalized in the range **[0.0, 1.0]** — MUST NOT exceed 1.0 or go below 0.0. This applies to both device attribute values and SEQUENCE waypoints for indoor positioning keys.
+
+- Follow relations to find the asset with `indoorPolygon`
+- Generate coordinates INSIDE or NEAR that perimeter
+- Ensure logical placement (sensors in rooms, equipment on floors)
+
+### Indoor Perimeters (indoorPolygon)
+
+- Represent as a JSON array of `[x, y]` pairs: `[[0.1, 0.1], [0.9, 0.1], [0.9, 0.9], [0.1, 0.9]]`
+- Same [0.0, 1.0] range constraint as device position keys
+- Generate non-overlapping polygons with a realistic layout across the parent space
+- Ensure device positions within a zone fall inside that zone's polygon
+
+### Outdoor Coordinates (latitude/longitude)
+
+- Follow relations to find the asset with `perimeter`
+- Generate coordinates INSIDE or NEAR that perimeter
+- Avoid cross-region incoherence (e.g., device in Texas, zone in New York)
+
+### Outdoor Perimeters (outdoorPolygon)
+
+- Represent as a JSON array of `[latitude, longitude]` pairs
+- Generate realistic polygons around real-world areas with scale appropriate to the use case (small parking area vs. city-wide delivery zone)
+- Ensure GPS coordinates of devices inside a zone fall within or near its polygon
+
+### Multiple Zones/Areas
+
+When multiple zones exist, each device belongs to ONE specific zone via relations. Coordinates must be coherent with that specific zone, not the collection of all zones.
+
+### Indoor Position Uniqueness
+
+When multiple devices in the same space each have CONSTANT xPos/yPos, they MUST have different coordinates so they don't overlap on the floor plan.
+
+Compute a grid layout and embed the exact coordinate value in `ctx` so the downstream assistant uses it verbatim:
+
+```
+10 sensors in a 2-row × 5-column grid on Downtown Lot:
+- Sensor 01: ctx = "xPos = 0.10 (col 1/5, row 1/2), Indoor xPos for Parking Sensor 01 on Downtown Lot, range: [0.0, 1.0]"
+- Sensor 02: ctx = "xPos = 0.30 (col 2/5, row 1/2), Indoor xPos for Parking Sensor 02 on Downtown Lot, range: [0.0, 1.0]"
+- Sensor 06: ctx = "xPos = 0.10 (col 1/5, row 2/2), Indoor xPos for Parking Sensor 06 on Downtown Lot, range: [0.0, 1.0]"
+```
+
+---
+
+## 4. Alarm Demo Assignment
+
+### General Rules
+
+- For each alarm, designate alarm-demo devices using this rule: **max(1, round(25% of affected devices))** — always at least one, never zero, regardless of fleet size
+- Different alarms can be demonstrated by different devices; a single device can demonstrate multiple alarms
+- Never indicate alarm-demo status in device names — encode it only in the `ctx` field of a CONSTANT strategy
+- If an alarm threshold references an attribute name (e.g., `temperature > maxTemperatureThreshold`), resolve its value from `customer.attributes` or entity profile attributes and include it in `ctx`
+
+### Demo Data Period
+
+All demo data spans **one calendar week** — 7 days, with telemetry uploaded every **30 minutes** (48 uploads/day, **336 uploads total**). This determines which strategies are safe for normal devices:
+
+| Strategy                     | Safe for normal devices?                                             |
+|------------------------------|----------------------------------------------------------------------|
+| NATURAL, SCHEDULE, COMPOSITE | ✅ Oscillate or repeat within bounds — naturally safe                 |
+| SEQUENCE                     | ✅ Loops the path — naturally safe                                    |
+| DECREMENT from 100%          | ❌ Crosses a 20% threshold around day 5–6                             |
+| INCREMENT, COUNTER           | ❌ Continuously grows — exceeds any reachable threshold within a week |
+
+### Per-Strategy Alarm Guidance
+
+#### NATURAL
+Use on all normal devices. Include alarm thresholds in `ctx` — oscillation naturally crosses and recovers, producing realistic transient alarms across the fleet.
+
+`"IAQ sensor, CO₂ 400–900 ppm normal range, alarms at >1000 ppm (HighCo2Warning) or >2000 ppm (HighCo2Critical)"`
+
+#### DECREMENT, INCREMENT, COUNTER
+One-way strategies: over a week, every device eventually crosses the threshold — the alarm fires on all devices, not just the demo ones.
+
+- **Normal devices**: switch to **NATURAL** with `ctx` describing a healthy range away from the threshold
+- **Alarm-demo devices** (~25%): **CONSTANT** at a value inside the alarm zone — `ctx`: `"Fixed at [value] to trigger [AlarmName] in demo"`
+
+**Exception**: if the alarm fires on a *derived* key (e.g., `dailyEnergyConsumption` aggregated from raw `energyKwhTotal`), the raw COUNTER is safe for all devices — the alarm never sees the accumulating total directly.
+
+Example (LowFuel alarm, `fuelLevel < 15%`, 5 machines):
+- Machines 1–4: NATURAL — `"Fuel level fluctuating 40–80%, above the 15% LowFuel threshold"`
+- Machine 5: CONSTANT — `"Fixed at 8% to trigger LowFuel alarm in demo"`
+
+#### EVENT (boolean — duration-based alarms)
+EVENT toggles on/off and cannot hold a value long enough for duration-based alarms. A very low anomalyChance also makes devices appear permanently inactive, which is unrealistic.
+
+- **Normal devices**: prefer **COMPOSITE** or **SCHEDULE** for time-of-day patterns; use EVENT only for genuinely rare one-off states (e.g., tamper, fire)
+- **Alarm-demo devices** (~25%): **CONSTANT** at the triggering value — `ctx`: `"Fixed at [value] to trigger [AlarmName] in demo"`
+
+Example (DoorLeftOpen alarm, `doorOpen = true`, 6 freezing units):
+- Unit 1: SCHEDULE — `"Door opens during loading hours 6–10 am, closed otherwise"`
+- Units 2–3: COMPOSITE — `"More active weekday mornings, quiet overnight"`
+- Units 4–5: EVENT — `"Brief openings a few times per day"`
+- Unit 6: CONSTANT — `"Fixed at true to trigger DoorLeftOpen alarm in demo"`
+
+#### SCHEDULE, COMPOSITE
+These oscillate and naturally cross threshold alarms during peak periods — desirable for most cases.
+
+If only a minority of devices should trigger the alarm, tune `ctx` for normal devices to describe patterns that stay within the safe range, and use **CONSTANT** for alarm-demo devices.
+
+#### SEQUENCE (geofencing)
+- **Normal devices**: paths that stay within the allowed zone
+- **Alarm-demo devices** (~25%): **CONSTANT** at coordinates inside the alarm zone — `ctx`: `"Fixed position inside [ZoneName] to trigger [AlarmName] in demo"`

thingsboard_cli/resources/prompts/solutions/data-generator/resources/value-strategies/composite-value-strategy-example.json

@@ -0,0 +1,15 @@
+{
+  "type": "COMPOSITE",
+  "defaultHours": {
+    "type": "EVENT",
+    "normalValue": false,
+    "anomalyValue": true,
+    "anomalyChance": 30
+  },
+  "nightHours": {
+    "type": "EVENT",
+    "normalValue": false,
+    "anomalyValue": true,
+    "anomalyChance": 10000
+  }
+}