diff --git a/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-1.png b/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-1.png new file mode 100644 index 000000000..822175723 Binary files /dev/null and b/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-1.png differ diff --git a/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-2.png b/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-2.png new file mode 100644 index 000000000..6e21c0c5c Binary files /dev/null and b/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-2.png differ diff --git a/src/assets/images/user-guide/ai-assistant/ai-credits-1.png b/src/assets/images/user-guide/ai-assistant/ai-credits-1.png new file mode 100644 index 000000000..90417f791 Binary files /dev/null and b/src/assets/images/user-guide/ai-assistant/ai-credits-1.png differ diff --git a/src/assets/images/user-guide/ai-assistant/api-usage-ai-credits.png b/src/assets/images/user-guide/ai-assistant/api-usage-ai-credits.png new file mode 100644 index 000000000..e9ae68ce7 Binary files /dev/null and b/src/assets/images/user-guide/ai-assistant/api-usage-ai-credits.png differ diff --git a/src/content/_includes/docs/user-guide/ai-assistant.mdx b/src/content/_includes/docs/user-guide/ai-assistant.mdx index f3f2fdeba..697eded51 100644 --- a/src/content/_includes/docs/user-guide/ai-assistant.mdx +++ b/src/content/_includes/docs/user-guide/ai-assistant.mdx @@ -1,12 +1,152 @@ -import { Aside } from '@astrojs/starlight/components'; import DocLink from '@components/DocLink.astro'; import Banner from '~/components/Banner.astro'; +import ImageGallery from '~/components/ImageGallery.astro'; import { Products } from '~/models/site.models'; +import { Steps, Aside } from '@astrojs/starlight/components'; AI Assistant is available in ThingsBoard Professional and ThingsBoard Cloud only. -The **AI Assistant** is built into the ThingsBoard UI. It edits **calculated fields** and **alarm rules** in natural language, and generates ready-to-use **dashboards** for any device or asset in one click. +{props.product === Products.PE && ( + Available from ThingsBoard PE 4.3.1.2 and later. +)} + +The AI Assistant is a built-in assistant that lets you configure Alarm Rules and Calculated Fields by describing what you want in plain language — no ThingsBoard expertise required. It knows the platform, sees your data, and proposes every change for your approval before applying it. + +AI Assistant is currently integrated into two sections: +- Alarm Rules — rules that monitor telemetry and attributes, and trigger alarms when configured conditions are met. +- Calculated Fields — real-time computations on telemetry and attributes that produce new data keys. + +## How to Start + + + 1. Go to **Alarms ⇾ Alarm rules** (or **Calculated fields**). + 2. Click the **Configure with AI** button in the upper right corner. + 3. The AI Assistant panel opens on the right, alongside your configuration. + 4. Start typing. Conversations are saved automatically — use the chat menu to rename, switch, or delete them. + + +Configure with AI on the Calculated fields page to open the AI Assistant and create or manage calculated fields using natural language.', + }, + { + src: '/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-2.png', + alt: 'AI Assistant panel on the Calculated fields page', + caption: 'The AI Assistant opens in a side panel where you can describe the calculated field you want to create and receive AI-generated configuration suggestions.', + }, +]} /> + +## How the Assistant Works + +### Context Awareness + +The Assistant has access to your tenant data — devices, assets, profiles, customers, telemetry keys, and entity relations. This means you can describe what you want in natural terms and the Assistant figures out the rest: + +- Say _"my pumps"_ instead of listing device IDs. +- Reference a building, floor, or zone — the Assistant traces the relations automatically. +- If something is missing (a relation, a data key), it tells you what to set up before proceeding. + +### Approval Before Changes + +The Assistant never modifies your tenant without your confirmation. Before applying any change — creating, updating, or deleting a Calculated Field or Alarm Rule, or recalculating historical data — it shows an approval card in the chat that describes exactly what will be done and to which entity. No change is applied until you click **Approve**. + +If a proposal isn't quite right, click **Deny** and say what to change. + +## Using the Assistant + +The Assistant performs different types of tasks. You can freely combine them in the same chat. + +### Ask Questions + +Not sure how to implement what you have in mind? Or don't understand why something isn't working? Just ask. The Assistant knows Calculated Fields and Alarm Rules inside out and can see your actual devices, profiles, and data — so questions can be about the platform in general or your specific setup: + +> _"I want to know when one pump is drawing more power than the others on the same line — can ThingsBoard detect that, and how?"_ + +> _"The High Temperature alarm on my Chiller profile never triggers, even though the temperature clearly goes above the threshold — what's wrong?"_ + +### Create and Manage Configurations + +Describe what you want to end up with, and the Assistant creates it — Calculated Fields, Alarm Rules, or both, including any TBEL scripts. No need to pick field types, condition modes, or write logic yourself. + +> _"On each floor's meter I collect raw water-flow readings. Derive hourly and daily consumption per floor, roll them up into a building-wide total, and raise a warning alarm on any floor whose daily use runs more than 50% above its weekly average."_ + +The same approach works for changes and deletions: + +> _"We're switching the energy meters from kWh to MWh. Update the consumption calculated fields to the new unit, and adjust every alarm rule whose threshold depends on them so the limits still mean the same thing."_ + +## How to Get the Best Results + +The Assistant asks clarifying questions when something is unclear, so vague requests still work. That said, a well-formed request gets to the result faster. A few things that help: + +**Name the entity clearly.** The Assistant can find entities from partial clues — a name, type, profile, or location. The more specific you are, the fewer back-and-forth questions you'll get. + +> Instead of: _"Create a temperature alarm."_ +> +> Try: _"Create a temperature alarm for the Cold Storage device profile."_ + +**Describe the goal, not the steps.** Focus on what you want to achieve — not how to build it. The Assistant picks the right approach on its own. + +> Instead of: _"Create a calculated field on each tank that divides the level key by the maxLevel attribute and multiplies by 100."_ +> +> Try: _"I want to know how full each storage tank is as a percentage, not just its raw level reading."_ + +**Include the numbers.** Thresholds, units, time windows, and severities are the only details the Assistant cannot infer. Providing them upfront skips a round of clarifying questions. + +> Instead of: _"Alert me when the freezer gets too warm."_ +> +> Try: _"Raise a critical alarm when freezer temperature stays above -15 °C for more than 10 minutes; clear it below -18 °C."_ + +**Stay in the same chat.** The Assistant remembers everything from the current conversation — entities, choices, context. Follow-ups can be short: _"Do the same for the Warehouse profile"_ or _"Lower that threshold to 80"_. Start a new chat only for a completely unrelated task. + +## Scope and Limitations + +The Assistant configures **Alarm Rules** and **Calculated Fields** only. Everything else — Dashboards, Device Profiles, Relations, Rule Chains — remains outside its scope. If your request depends on something missing (a relation, a profile), the Assistant tells you what to set up manually and continues from there. + +**Raised alarms are read-only:** the Assistant can find and inspect them, but acknowledging, clearing, and assigning alarms remain manual actions. + +## AI Credits + +Each request to the Assistant consumes AI credits — the amount varies by complexity. + +{(props.product === Products.CE || props.product === Products.PE) && ( + <> +

To check your usage and available credits, go to API Usage in your ThingsBoard instance and find the AI credits row. The page also shows your hourly, daily, and monthly activity charts.

+

The number of available AI credits is defined by your subscription plan and may be further limited by your system administrator in the Tenant Profile.

+ + +)} + +{(props.product === Products.PAAS || props.product === Products.PAAS_EU) && ( + <> +

To check your balance, click the AI Credits indicator in the Assistant panel. The pop-up shows your usage, monthly limit, and reset date:

+

"You've used 9.8K of your 4M AI Credits this month. Limit resets on Jun 29, 2026."

+

If your credits are exhausted, click Update to upgrade your plan.

+

For a full breakdown of limits per plan, see API Limits.

+ + +)} + +## Next Steps + +- Calculated Fields and Alarm Rules — explore the features the Assistant configures, and fine-tune them by hand when needed. +- AI Solution Creator — generate a complete IoT solution from a plain-language description: entities, Dashboards, Alarm Rules, and Calculated Fields in one go. +- ThingsBoard CLI — run AI-driven workflows from the command line, with full support for coding agents. diff --git a/src/content/_includes/docs/user-guide/alarm-rules.mdx b/src/content/_includes/docs/user-guide/alarm-rules.mdx index 1469f9324..b69055a49 100644 --- a/src/content/_includes/docs/user-guide/alarm-rules.mdx +++ b/src/content/_includes/docs/user-guide/alarm-rules.mdx @@ -8,8 +8,9 @@ import MultiProductImageGallery from '~/components/MultiProductImageGallery.astr Rules can be defined for Devices, Assets, their profiles, or Customers. For an overview of alarm concepts, states, and severity levels, see Alarms. -