thingsboard-cli 4.4.0.1__tar.gz → 4.4.0.2__tar.gz

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/CHANGELOG.md

@@ -2,7 +2,135 @@
 
 All notable changes to ThingsBoard CLI are documented in this file.
 
-## [4.4.0.1] — Unreleased
+## [Unreleased]
+
+Connect a real device directly over HTTP, MQTT or CoAP. The agent closes the loop:
+it sends a test value, gives you the device settings, waits for your device,
+and offers the next step.
+
+### Added
+
+- **`tb device connect <name-or-id>`.** Shows the settings a device needs and
+  commands that are ready to run, like the Check connectivity dialog of the
+  ThingsBoard UI: `curl` for HTTP, `mosquitto_pub` for MQTT and `coap-client`
+  for CoAP, Docker variants for MQTT and CoAP, and how to install the client
+  on your OS. The example payload comes from the device's emulator, then from the
+  device's own latest telemetry, then from the telemetry keys of its device
+  profile (not the default profile), and else is `{"temperature": 25}`;
+  `--payload '<json>'` sets it yourself. The MQTT and CoAP hosts come from the server.
+  `--transport http|mqtt|coap` shows one transport, `--tls` uses HTTPS, MQTTS
+  and CoAPs, and `--host` / `--port` are for servers with a different setup. The
+  access token and the MQTT password are hidden unless you add
+  `--show-secrets`, also with `--format json`. For X.509 credentials, the
+  command lists the files the device needs and links to the docs. In a
+  terminal, the command asks whether to send a test value or show the
+  commands.
+- **`tb device connect --send`.** Sends the example payload as the device and
+  checks that ThingsBoard stored it: over HTTP, or with `--transport mqtt` /
+  `coap` through the installed `mosquitto_pub` / `coap-client`. Without that
+  client, it sends over HTTP and says that MQTT or CoAP is not tested. The
+  CLI finds `coap-client` and the `-openssl` / `-gnutls` / `-notls` builds
+  that `libcoap3-bin` installs on Ubuntu 24.04 and Debian 12. The output says that the device
+  itself is not connected yet and shows the dashboard link.
+- **`tb device connect --wait`.** Waits for the first telemetry from the device
+  itself (`--timeout`, default 5 minutes), shows
+  `Data received: temperature=22.5` and the dashboard link. Telemetry that
+  `tb emulator run` or `--send` writes does not count.
+- **`tb device status [--wait]`**, **`tb device set-credentials`**,
+  **`tb device server-cert`**, **`tb device-profile transport`** and
+  **`tb device-profile set-transport`**: device activity and latest
+  telemetry, device credentials, the server CA for TLS, and the profile
+  transport.
+- **`tb device credentials`** accepts a device name.
+- **Agent kit: the `device-connectivity` skill.** After a deploy, the agent
+  asks "Connect a real device?". It runs `tb device connect` itself, sends a
+  test value, gives you only the values to enter on the device, and waits for
+  its data. Then it offers a dashboard from the keys the device really sends,
+  or a full solution. If no data arrives, it checks why. For LoRaWAN, Sigfox,
+  cloud platforms, brokers, IoT Gateway protocols (Modbus, OPC-UA, BACnet,
+  …), LwM2M and SNMP, it explains what to set up and links the guide.
+- **Choices as buttons.** The agent asks with buttons in Claude Code and with
+  numbered options in Antigravity.
+
+### Fixed
+
+- **`tb device connect` finds the device's dashboard on the server** when the
+  device is not in the local solution: a dashboard whose title names the
+  device and whose aliases point to it, with the keys it shows. A timeout
+  of `--wait` for LwM2M and SNMP devices says what to check for them.
+- **`tb device connect --wait` does not miss the first message.** It counts
+  data that the device sent a moment before the wait started, or any time
+  after the last `--send` test value of this device (up to a day back), when
+  the device's activity matches it. The test value itself and emulator data
+  still do not count.
+- **`tb device connect --wait` works for LwM2M and SNMP devices.** It only
+  reads telemetry; the commands are still for HTTP, MQTT and CoAP only. The
+  timeout message now names the token first when ThingsBoard did not see the
+  device connect: it does not show rejected connections. `tb device status`
+  shows local times with "13 minutes ago" (and an `ago` field in JSON).
+- **`tb device connect --send` says how it sent:** "over MQTTS (port 8883)",
+  with `tls` and `port` in the JSON, and how to install the missing client
+  when it falls back to HTTP. Esc in the terminal menu shows the commands,
+  like Ctrl+C.
+- **LwM2M device profiles show their objects.** A resource path in an LwM2M
+  profile needs the object version of the server's resource library, like
+  `/3303_1.1/0/5700`; without it, the profile saved but the UI showed an empty
+  object list. `tb validate` and `tb push` now fail on such a path and name the
+  path to use, or say that the object is not in the library.
+  `tb device-profile set-transport --type LWM2M` adds the version itself, and
+  the new `tb device-profile lwm2m-objects [--ids 3303,3304]` lists the object
+  models of the server with their versions and resources.
+- **`tb device-profile set-transport --type LWM2M` works.** It failed with
+  "LwM2M Server ShortServerId must not be null": the request lost the fields
+  of the bootstrap server entries. LwM2M profiles are now read and saved as
+  the server's JSON.
+- **`tb device set-credentials --type X509_CERTIFICATE` sends only the
+  certificate.** A PEM file with the certificate and its private key (or
+  `openssl pkcs12` headers) sent the whole file: the key reached the server
+  and the device could not authenticate. Now only the certificate block goes.
+- **`--tls` and `--port` of `tb device connect` no longer change the HTTP URL**
+  when they are for MQTT or CoAP. `--port` sets the HTTP port only with
+  `--transport http`, and `--tls` on an `http://host:8080` profile gives
+  `https://host` instead of `https://host:8080`. The Docker variant downloads
+  the server certificate from the URL the CLI is logged in to, like the UI.
+- **Servers that store the device state as telemetry** (`state.persistToTelemetry`):
+  `tb device connect --wait` and `tb device status` read `active` and
+  `lastActivityTime` from the time series, and there these keys no longer go
+  into the example payload or count as data from the device. On other servers
+  a device's own `active` telemetry key still counts.
+- **`tb device connect` refuses MQTT on a Sparkplug B or Protobuf profile**
+  with a docs link, instead of printing or sending a JSON command that the
+  server cannot parse. HTTP still works with `--transport http`.
+- **The terminal menu names the transport it sends over**, like "Send a test
+  value over MQTT now" with `--transport mqtt`.
+- **`tb device status --wait` counts only data from the device**, like
+  `tb device connect --wait`, with the same messages, and its timeout hint fits
+  the profile transport. Unlike `connect --wait`, it ignores data sent before
+  the wait, even after a recent `--send` test value. The default timeout stays
+  120 seconds.
+- **`tb device-profile set-transport` sees devices of customers** when it checks
+  whether the profile is in use.
+- **`tb device-profile lwm2m-objects -H`** shows the API help instead of
+  running the command.
+- **Agent kit:** `--yes` only for `set-credentials` and `set-transport`
+  (`tb device save` has none); the MQTT claim topic is `v1/devices/me/claim`;
+  `getSessionLimits` works only on `v1/devices/me/rpc/request/$id`; the LwM2M
+  and SNMP references check data with `tb device connect --wait`.
+- **HTML pages only on servers that can show them.** The HTML page dashboard
+  layout ships in ThingsBoard 4.4.1, not 4.4.0.1. `tb system info` reported
+  `htmlPageLayout: true` for 4.4.0.1, so the agent built HTML page states
+  that this version shows as blank. It now reports `false`, and the agent
+  uses stock-widget grids there. ThingsBoard Cloud and 4.4 development
+  builds are not affected.
+
+### Known limitations
+
+- `tb device connect --send` passes the access token on the command line of
+  the client it runs: to `mosquitto_pub` (the token, or the MQTT password) and
+  to `coap-client` (inside the `coap://…/api/v1/<token>/telemetry` URL). Other
+  local users can see it with `ps` while the client runs.
+
+## [4.4.0.1] — 2026-10-23
 
 First-run usability release.
 

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thingsboard-cli
-Version: 4.4.0.1
+Version: 4.4.0.2
 Summary: CLI tool for managing ThingsBoard resources
 Project-URL: Homepage, https://github.com/thingsboard/thingsboard-cli
 Project-URL: Source, https://github.com/thingsboard/thingsboard-cli

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
-name: thingsboard_cli-4.4.0.1/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar
+name: thingsboard_cli-4.4.0.2/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar
 size: 39342529 bytes
 sha256: b2a093f7037d1d4fcc9b196d9bd5412a02920a181b39e2d02cf54939630a6d7d

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "thingsboard-cli"
-version = "4.4.0.1"
+version = "4.4.0.2"
 description = "CLI tool for managing ThingsBoard resources"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/scaffold/agent-kit/INSTRUCTIONS.md

@@ -11,9 +11,12 @@ Before working with entities — especially fetching/pulling them from an instan
 ## Constraints
 
 - **Local mode only** — always verify local mode is active before creating entities: `tb config mode local`. All entity creation must go through `tb <entity> save --json` commands — never write JSON files directly.
+  - **Exception — device connectivity.** Connecting a real device, its credentials, connection details and status live on the server, so the `device-connectivity` skill works against the server (`--remote` saves, server reads) after the user approves its plan. Only that skill does this.
 - **Never `cd` into solution directories** — always use `--solution <name>` to target a solution. Do not use `cd` to change into solution directories.
 - **Push only after the user confirms** — follow *Deploy after confirmation* below. Subagents never push. Running `tb validate` is safe (dry-run) and should be run after creating entities.
 - **Never modify profiles** — never run `tb config set`, `tb config add`, `tb config use`, or `tb config remove`. Authentication is the user's responsibility.
+- **The user sees only your visible text.** Command output is collapsed and your thinking is hidden. Text right before a question in the same turn may not be shown either: put what the user must see (results, settings) into the question text, or end the turn with it as text.
+- **Choices as buttons.** Wherever these instructions or a skill say `AskUserQuestion`: if your agent has no such tool, ask one short question with numbered options (`1.`, `2.`, …, the recommended one first) and wait for the user's answer.
 - **`tb feedback` is allowed** — running `tb feedback` (to record user feedback, see below) is safe and expected; it is not a config or push command.
 
 ## Built-in tenant administrator (quick builds, standalone dashboards)
@@ -43,7 +46,9 @@ Then:
 - If the request already asks to deploy or to see the result in ThingsBoard ("…and deploy it", "show it on a dashboard"), skip the question: deploy, and start the live stream when emulator tasks exist. Always use the active profile.
 - If `tb push` fails, show the error verbatim and stop.
 
-**Reply after a deployment — short.** One sentence on what is live, the dashboard link(s), and one line on the live stream ("Demo data streams for 5 minutes."). Write every dashboard as a Markdown link with its title — `[Office Air Quality](https://thingsboard.cloud/dashboards/all/<id>)` — never as a bare URL or a title followed by a URL in parentheses. The same applies to any other ThingsBoard page you link (device, profile, alarm list). Add a next action only when the user must act, with its exact command. Do not list what was created, do not repeat design details, and do not mention internal tooling limits. Details belong in the solution README.
+**Reply after a deployment — short.** When the turn ends with a question (below), this reply moves into the question and the next message. Otherwise: one sentence on what is live, the dashboard link(s), and one line on the live stream ("Demo data streams for 5 minutes."). Write every dashboard as a Markdown link with its title — `[Office Air Quality](https://thingsboard.cloud/dashboards/all/<id>)` — never as a bare URL or a title followed by a URL in parentheses. The same applies to any other ThingsBoard page you link (device, profile, alarm list). Add a next action only when the user must act, with its exact command. Do not list what was created, do not repeat design details, and do not mention internal tooling limits. Details belong in the solution README.
+
+**Then offer to connect a real device.** When the deployed solution has devices, end the turn with one `AskUserQuestion` (`header: "Real device"`) instead of the reply text: text right before a question may not be shown, so the question carries it — "<solution title> is live with demo data (streams for 5 minutes). Connect a real device to it?" with **Yes** · **Later**. The dashboard link goes into the message that ends the next turn: **Yes** → use the `device-connectivity` skill for a device of this solution (its settings message links the dashboard). **Later** → one line: "Dashboard: [<title>](<url>). Ask me any time to connect a device." Skip the question when the deploy did not happen (**Not now**) or the solution has no devices.
 
 ## Feedback
 
@@ -80,6 +85,10 @@ Ask at most once per reminder; do not ask when no reminder is present. Feedback
 
 Decide the path before you generate anything. Going off-path and hand-building what should have been a solution is much more expensive to undo than a short clarifying question.
 
+### Device connectivity comes first
+
+**When the user wants a real device connected or diagnosed, your first tool call MUST be `Skill device-connectivity`.** Triggers: a **Yes** to "Connect a real device?" after a deploy, "check my sensor" / "is my device sending data?", "how do I connect my sensor", "send real data to my dashboard", "how do I connect an ESP32 over MQTT", "what are the connection settings for Pump-42", "show device settings", "switch my device to X.509 / MQTT username+password", "set MQTT topics on my profile", "my device is offline / doesn't send data", and questions on connecting LoRaWAN, Modbus, a cloud platform or another protocol. It takes precedence over the standalone-vs-solution gate and the build/update paths below — connecting a device is not entity design. Don't read `thingsboard-concepts` or other skills first: the skill has everything it needs. Emulators and generated demo data are not connectivity: those stay with the solution skills.
+
 ### First decide intent: fetch vs. targeted vs. build vs. update
 
 Route by **intent**, then by existence/completeness. Check the paths **in this order** — the first match wins:

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/scaffold/agent-kit/agents/dashboard-generator.md

@@ -113,7 +113,7 @@ The available names are listed in dashboard-foundations. Pull each needed templa
 ### C1 — Build structure and the validated plan
 
 1. Using dashboard-foundations, decide the states/navigation and build the global `entityAliases` map (allocate UUIDs per the UUID conventions).
-2. Produce a COMPACT render-plan. **First apply the server version gate** from the dashboard-foundations core ("Layout policy" — `tb system info --format json`, once per run) and plan in the mode it selects. **HTML page mode (ThingsBoard 4.4.0.1+, or version unknown — the default):** plan every state a user navigates to as an HTML page — `{stateId, host: "page", contentSpec}`, no widgets — with `contentSpec` per the shape in `references/custom-html-path.md`. Plan a grid state only as an **embedded helper** that a page hosts via `<tb-dashboard-state>`: stock maps (`outdoor-map`, `indoor-map`, `trip-map`) and the stock alarm table when users acknowledge or clear alarms — `{stateId, host: "helper", widgets: [...]}`, never a navigation target. Stock entity dialogs (create/edit/delete) are page actions, not helper states: list them in the page's `contentSpec` as JavaScript-source actions in `htmlPageConfig.actions`, opened from page buttons. **Grid mode (`htmlPageLayout: false`, server older than 4.4.0.1):** plan per state each widget as `{widgetType, title, aliasRef, dataKeys, layout {x,y,w,h}, actions}`; stock widgets are the default; when a grid-mode trigger fires (explicit custom-HTML/composite ask, visual-upgrade ask, a use case no stock widget expresses, a grid-bound limitation), use an htmlContainer region `{widgetType: "htmlContainer", title, contentSpec, layout}`, and for a whole-state custom view the full-state htmlContainer fallback. No widget JSON yet.
+2. Produce a COMPACT render-plan. **First apply the server version gate** from the dashboard-foundations core ("Layout policy" — `tb system info --format json`, once per run) and plan in the mode it selects. **HTML page mode (ThingsBoard 4.4.1+, or version unknown — the default):** plan every state a user navigates to as an HTML page — `{stateId, host: "page", contentSpec}`, no widgets — with `contentSpec` per the shape in `references/custom-html-path.md`. Plan a grid state only as an **embedded helper** that a page hosts via `<tb-dashboard-state>`: stock maps (`outdoor-map`, `indoor-map`, `trip-map`) and the stock alarm table when users acknowledge or clear alarms — `{stateId, host: "helper", widgets: [...]}`, never a navigation target. Stock entity dialogs (create/edit/delete) are page actions, not helper states: list them in the page's `contentSpec` as JavaScript-source actions in `htmlPageConfig.actions`, opened from page buttons. **Grid mode (`htmlPageLayout: false`, server older than 4.4.1):** plan per state each widget as `{widgetType, title, aliasRef, dataKeys, layout {x,y,w,h}, actions}`; stock widgets are the default; when a grid-mode trigger fires (explicit custom-HTML/composite ask, visual-upgrade ask, a use case no stock widget expresses, a grid-bound limitation), use an htmlContainer region `{widgetType: "htmlContainer", title, contentSpec, layout}`, and for a whole-state custom view the full-state htmlContainer fallback. No widget JSON yet.
 3. VALIDATE the plan before pulling any template or emitting any JSON (this is where correctness is won):
    - Every widget's `aliasRef` resolves to an alias in the map that OWNS the keys in `dataKeys` (Rule: alias-owns-keys).
    - Every drill-down/navigation action's source kind matches the target state's primary alias kind (Rule: drill-down kind-match).
@@ -216,7 +216,7 @@ These invariants apply per-state and can be verified from the assembled state ou
 6. **typeFullFqn** — must match the `typeFullFqn` value in the matching `widget-*` catalog skill exactly; never invent values.
 7. **alarmTable datasource** — alarm data goes into `alarmSource`, not `datasources`. `datasources` must be `[]`.
 8. **alarmCount datasource** — uses `"type": "alarmCount"` (not `"entity"`) with `dataKeys: [{name:"count", type:"count"}]`.
-9. **No empty content shipped — the #1 failure.** Every `htmlContainer` (`config.settings`) and every HTML page (`htmlPageConfig.settings`) must have **non-empty** `html` AND `js` (and `css` unless trivially styled); empty `html`/`js` renders a blank widget or a blank state. No grid state may consist of a single htmlContainer covering the whole state — that state must be an HTML page — except on a server older than ThingsBoard 4.4.0.1 (`tb system info` → `htmlPageLayout: false`), where it is the required fallback. Every `system.map`/outdoor-map widget must have at least one configured `markers` layer (with `xKey`/`yKey` bound to position keys on a real alias) or `polygons` layer (with `polygonKey`) — an empty `markers: []` + `polygons: []` shows a blank map. If a widget you assembled has empty content/datasources, STOP and fill it before saving — never save a structural skeleton.
+9. **No empty content shipped — the #1 failure.** Every `htmlContainer` (`config.settings`) and every HTML page (`htmlPageConfig.settings`) must have **non-empty** `html` AND `js` (and `css` unless trivially styled); empty `html`/`js` renders a blank widget or a blank state. No grid state may consist of a single htmlContainer covering the whole state — that state must be an HTML page — except on a server older than ThingsBoard 4.4.1 (`tb system info` → `htmlPageLayout: false`), where it is the required fallback. Every `system.map`/outdoor-map widget must have at least one configured `markers` layer (with `xKey`/`yKey` bound to position keys on a real alias) or `polygons` layer (with `polygonKey`) — an empty `markers: []` + `polygons: []` shows a blank map. If a widget you assembled has empty content/datasources, STOP and fill it before saving — never save a structural skeleton.
 10. **Landing state is not empty.** The root state must render the primary view on load. If the root is a composite HTML page (or htmlContainer) that embeds states, its own `html` is non-empty AND every `embeddedStateIds` state it shows exists and is populated — a root that resolves to an empty container or an empty embedded state means "nothing visible on landing."
 11. **Map position keys are resolvable.** For every map marker layer, the `xKey`/`yKey` (lat/lng) and any polygon `polygonKey` must be keys that actually exist on the bound alias's profile (in the `entityProfiles` input, projected from the overview). Flag in the save report when those keys are TIMESERIES (markers only render once telemetry/emulator data populates them) so the caller knows demo data must be pushed.
 

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/scaffold/agent-kit/skills/dashboard-dark-mode/SKILL.md

@@ -21,7 +21,7 @@ Skip the background fix → "the page went dark but the widgets are still white.
 
 - `userRequirements` asks for a "dark dashboard", "dark mode", "dark theme", "night mode", or names a dark palette for the whole view.
 
-Apply this **independently of the widget mix**. The layout policy (HTML pages on 4.4.0.1+, stock-widget grids on older servers) is unchanged — the design may still include an htmlContainer (for custom layout, a composite view, a branded header, etc.) and that's fine. The bug this skill fixes is the *inconsistent* result: a dark htmlContainer sitting next to stock widgets that stayed white. `settings.dashboardCss` is the page-wide layer that turns the **stock** widgets dark too, so the whole dashboard — stock widgets and htmlContainers alike — comes out dark together. Set it whenever dark mode is requested, whether or not the dashboard also has an htmlContainer.
+Apply this **independently of the widget mix**. The layout policy (HTML pages on 4.4.1+, stock-widget grids on older servers) is unchanged — the design may still include an htmlContainer (for custom layout, a composite view, a branded header, etc.) and that's fine. The bug this skill fixes is the *inconsistent* result: a dark htmlContainer sitting next to stock widgets that stayed white. `settings.dashboardCss` is the page-wide layer that turns the **stock** widgets dark too, so the whole dashboard — stock widgets and htmlContainers alike — comes out dark together. Set it whenever dark mode is requested, whether or not the dashboard also has an htmlContainer.
 
 ## Two modes
 

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/scaffold/agent-kit/skills/dashboard-foundations/SKILL.md

@@ -26,7 +26,7 @@ Actions: drill-down, change-state, create-entity-dialog, edit-entity-dialog, del
 
 | File (`references/…`) | Read when |
 |---|---|
-| `custom-html-path.md` | HTML page mode (every create on 4.4.0.1+), a grid-mode trigger fires, or the dashboard already has an HTML page or htmlContainer you are changing — host rules, `contentSpec`, composite-page structure. |
+| `custom-html-path.md` | HTML page mode (every create on 4.4.1+), a grid-mode trigger fires, or the dashboard already has an HTML page or htmlContainer you are changing — host rules, `contentSpec`, composite-page structure. |
 | `aliasing.md` | You create or change aliases or datasources: display-name fields, `resolveMultiple`, alias-owns-keys, drill-down entity passing, multi-hop navigation, `currentCustomer` scoping, entity alias JSON structure. **Create mode: always.** |
 | `navigation.md` | The dashboard has `switcherDetail` states (state switching) or any "Back" control. |
 | `validation-checklists.md` | **Always — every mode — but read it last:** once every state is built and assembled, right before writing the JSON. Then run the per-state checklist on every state you built or touched and the pre-write checklist on the whole dashboard. Never read it at the start. |
@@ -39,11 +39,11 @@ In **Update mode**, read only the files for what the change touches (plus `valid
 
 ## Layout policy — HTML pages first (full rules: `references/custom-html-path.md`)
 
-**Server version gate — first, once per run, before planning any state.** Run `tb system info --format json` (it always queries the profile's server, also in local mode) and read `htmlPageLayout`: `true` → **HTML page mode**; `false` → the server is older than ThingsBoard 4.4.0.1 → **grid mode**; `null`, or the command fails (no profile, server unreachable) → version unknown, use HTML pages (**HTML page mode**). Record the mode in the save report.
+**Server version gate — first, once per run, before planning any state.** Run `tb system info --format json` (it always queries the profile's server, also in local mode) and read `htmlPageLayout`: `true` → **HTML page mode**; `false` → the server is older than ThingsBoard 4.4.1 → **grid mode**; `null`, or the command fails (no profile, server unreachable) → version unknown, use HTML pages (**HTML page mode**). Record the mode in the save report.
 
 **HTML page mode (default).** Build **every state a user navigates to** as an HTML page: `layouts.main.gridSettings.layoutType: "html"`, `widgets: {}`, all content in `htmlPageConfig` — custom HTML/CSS/JS on the `widget-html-container` content model. Grid states with stock widgets remain only as **embedded helper states** inside a page (`<tb-dashboard-state>`), never as navigation targets: stock maps — `outdoor-map` (`system.map`), `indoor-map`, `trip-map` (`system.trip_map`, with timeline scrolling) (a page never draws its own map or loads Leaflet from a CDN; ThingsBoard ships its own, and a second copy breaks every stock map) — and the stock alarm table when users acknowledge or clear alarms. Stock entity dialogs (create/edit/delete) need no helper state: put the action in `htmlPageConfig.actions` as a JavaScript-source action and open it from a page button with `ctx.actionsApi.invokeAction` (`widget-html-container` → `references/platform-calls.md`).
 
-**Grid mode (servers before 4.4.0.1).** Stock catalog widgets are the default. Plan custom content only when a trigger fires: (1) explicit ask — custom HTML, free-form or composite layout, a third-party library; (2) visual-upgrade ask beyond stock styling fields (dark mode alone does not count); (3) gap-filler — no stock widget expresses the use case (**Maps are never a gap**); (4) grid-bound limitation — end-user resize/move/drag, overlays, drawers, splitters. A trigger is **mandatory** (never approximate with the nearest stock widget). **Pick the host:** one region of a grid → htmlContainer widget; the whole state → the **full-state htmlContainer fallback** (SKILL.md → "Full-state htmlContainer fallback").
+**Grid mode (servers before 4.4.1).** Stock catalog widgets are the default. Plan custom content only when a trigger fires: (1) explicit ask — custom HTML, free-form or composite layout, a third-party library; (2) visual-upgrade ask beyond stock styling fields (dark mode alone does not count); (3) gap-filler — no stock widget expresses the use case (**Maps are never a gap**); (4) grid-bound limitation — end-user resize/move/drag, overlays, drawers, splitters. A trigger is **mandatory** (never approximate with the nearest stock widget). **Pick the host:** one region of a grid → htmlContainer widget; the whole state → the **full-state htmlContainer fallback** (SKILL.md → "Full-state htmlContainer fallback").
 
 Then `Read` `references/custom-html-path.md` before planning any `contentSpec`.
 
@@ -250,9 +250,9 @@ A state built as an HTML page (see "Layout policy") replaces the grid with one c
 - `htmlPageConfig.settings` is exactly an htmlContainer's `config.settings` and `htmlPageConfig.actions` is exactly its `config.actions` — author both per `widget-html-container`.
 - `widgets` is always `{}`; nothing for this state goes into the top-level `widgets` map. `gridSettings` holds only `layoutType` and `htmlPageConfig` — no columns, margins, row height, or background (the page paints its own), and no `right` layout or `breakpoints`.
 - The page renders without a widget frame: no title bar, transparent background, zero padding, full state height on desktop and mobile. Design the page's own header, padding, and surfaces in its CSS.
-- Requires ThingsBoard 4.4.0.1+; an older UI cannot render this layout type. Use it only when `tb system info` reports `htmlPageLayout: true` or the version is unknown — otherwise use the fallback below.
+- Requires ThingsBoard 4.4.1+; an older UI cannot render this layout type. Use it only when `tb system info` reports `htmlPageLayout: true` or the version is unknown — otherwise use the fallback below.
 
-### Full-state htmlContainer fallback (server older than 4.4.0.1)
+### Full-state htmlContainer fallback (server older than 4.4.1)
 
 When `tb system info --format json` reports `htmlPageLayout: false`, a state planned as an HTML page is built as a **grid state holding one htmlContainer that covers the whole state** instead — the only shape that renders on those servers. The content is identical: the page's `htmlPageConfig.settings` / `htmlPageConfig.actions` become the widget's `config.settings` / `config.actions` unchanged.
 

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/scaffold/agent-kit/skills/dashboard-foundations/references/custom-html-path.md

@@ -6,7 +6,7 @@
 
 Custom HTML/CSS/JS content has two hosts that share one content model (`widget-html-container` catalog skill — same `settings.type/html/css/js/resources`, same `ctx` APIs, subscriptions, embedded states, and actions):
 
-- **HTML page** — a dashboard state whose layout type is `html` (`layouts.main.gridSettings.layoutType: "html"`, content in `gridSettings.htmlPageConfig`). The state has **no widget grid**: the page fills the whole state area by itself. ThingsBoard 4.4.0.1+.
+- **HTML page** — a dashboard state whose layout type is `html` (`layouts.main.gridSettings.layoutType: "html"`, content in `gridSettings.htmlPageConfig`). The state has **no widget grid**: the page fills the whole state area by itself. ThingsBoard 4.4.1+.
 - **htmlContainer widget** — a widget placed in a state's grid, sharing the grid with other widgets.
 
 Below, "the container" means the custom content in either host; "Pick the host" decides which one. It is the dashboard's open canvas — it fills its area with whatever HTML/CSS/JS you write, so it stretches to fit almost any idea. Its range:
@@ -23,7 +23,7 @@ These are starting points, not boundaries — anything expressible in HTML/CSS/J
 
 **Generation is craft, not slot-filling.** Treat building a dashboard as design work where the full palette is yours to use as the result demands: stock widgets, from-scratch htmlContainer widgets, embedded states, composition, and custom code — mixed however serves the best dashboard. Nothing here limits you to one tool or one shape; reach for whatever expresses the idea most faithfully. The rules that follow are technique for wielding that palette well — don't rebuild what stock widgets already give you, validate data keys, states, and permissions — not a cage on what you may create.
 
-**Which mode applies** — decided by the server version gate (SKILL.md → "Layout policy"). In **HTML page mode** (ThingsBoard 4.4.0.1+, the default) every state a user navigates to is an HTML page, without any trigger; the triggers below are not consulted for that choice, and stock widgets appear only in embedded helper states (maps; the alarm table when users acknowledge or clear alarms). Stock entity dialogs are page actions opened from page buttons, not helper states. In **grid mode** (older servers) custom content is the pipeline's escape hatch from the widget grid. In grid mode, reach for it when the user wants **custom logic or interaction** a stock widget doesn't offer (bespoke controls, RPC panels, drag-and-drop, custom forms, client-side computation); when a **design or layout can't be reached with the default implementation** — free-form / overlaid / composite arrangements, a structure the dashboard grid system can't express, or **runtime interaction the locked grid can't give** (end-user resizing, moving, dragging, or freely positioning content; overlays or drawers floating over the dashboard; resizable splitters); when the user asks for a **special, branded, or modern custom-designed view**; or when **no stock widget fits the need** — the container is fully configurable, so it can be built to spec rather than forcing an ill-fitting stock widget. Outside those, grid mode keeps stock catalog widgets as the default. Concretely, in grid mode the plan includes custom content when one of these triggers fires:
+**Which mode applies** — decided by the server version gate (SKILL.md → "Layout policy"). In **HTML page mode** (ThingsBoard 4.4.1+, the default) every state a user navigates to is an HTML page, without any trigger; the triggers below are not consulted for that choice, and stock widgets appear only in embedded helper states (maps; the alarm table when users acknowledge or clear alarms). Stock entity dialogs are page actions opened from page buttons, not helper states. In **grid mode** (older servers) custom content is the pipeline's escape hatch from the widget grid. In grid mode, reach for it when the user wants **custom logic or interaction** a stock widget doesn't offer (bespoke controls, RPC panels, drag-and-drop, custom forms, client-side computation); when a **design or layout can't be reached with the default implementation** — free-form / overlaid / composite arrangements, a structure the dashboard grid system can't express, or **runtime interaction the locked grid can't give** (end-user resizing, moving, dragging, or freely positioning content; overlays or drawers floating over the dashboard; resizable splitters); when the user asks for a **special, branded, or modern custom-designed view**; or when **no stock widget fits the need** — the container is fully configurable, so it can be built to spec rather than forcing an ill-fitting stock widget. Outside those, grid mode keeps stock catalog widgets as the default. Concretely, in grid mode the plan includes custom content when one of these triggers fires:
 
 1. **Explicit ask** — `userRequirements` (or the use-case text itself) requests custom HTML, free-form layout, a specific composite experience (tabs-in-one-widget, slide-over drawer, master-detail split, kanban), or a third-party visualization library. An explicit ask wins even when a stock widget could cover the use case.
 2. **Visual upgrade ask** — `userRequirements` asks for a noticeably prettier / branded / custom-designed view beyond what stock widget styling fields can express (custom typography, hero headers, card compositions, bespoke color systems). A preference the stock styling fields already cover — a single color, a theme, a chart palette — stays on stock widgets. **A dark theme / dark mode is handled separately and additively** — whatever widget mix the dashboard ends up with (stock widgets, htmlContainers, or both), a dark request also adds dashboard-wide dark CSS (`settings.dashboardCss`) so the stock widgets go dark alongside any htmlContainer. See "Dark mode" in `theme-and-dark-mode.md`; it is not an either/or with the Custom HTML path.
@@ -40,7 +40,7 @@ These are starting points, not boundaries — anything expressible in HTML/CSS/J
 
 - **The custom content is the whole state → HTML page.** A complete custom screen (landing page, branded overview, bespoke analytics view), a composite shell (custom tabs / sidebar / drawer / master–detail embedding other states), or any state that would otherwise be a single full-width htmlContainer. The page has no grid to size, no widget frame, and fills the state on desktop and mobile alike.
 - **The custom content is one region of a state that also shows stock widgets in the same grid → htmlContainer widget.** A bespoke KPI strip, RPC control panel, or custom visual sitting next to stock charts/tables/maps on one state, and the mid-generation swap of a single slot (below). This is the rarer case.
-- **Never** emit a state whose grid holds a single htmlContainer covering the whole state (e.g. one `sizeX: 24` container and nothing else) — that is an HTML page. **The one exception is a server older than ThingsBoard 4.4.0.1** (gate below), where the full-state htmlContainer is the required fallback for a whole-state custom view. Do not mix the two in one state either: an HTML page state has no grid, so it cannot also hold widgets; when custom content and stock widgets must share one view, either build the state as a grid with an htmlContainer region, or make it an HTML page that **embeds** a state holding the stock widgets (`<tb-dashboard-state>`).
+- **Never** emit a state whose grid holds a single htmlContainer covering the whole state (e.g. one `sizeX: 24` container and nothing else) — that is an HTML page. **The one exception is a server older than ThingsBoard 4.4.1** (gate below), where the full-state htmlContainer is the required fallback for a whole-state custom view. Do not mix the two in one state either: an HTML page state has no grid, so it cannot also hold widgets; when custom content and stock widgets must share one view, either build the state as a grid with an htmlContainer region, or make it an HTML page that **embeds** a state holding the stock widgets (`<tb-dashboard-state>`).
 
 **Server version gate.** Apply it as the SKILL.md core states it ("Layout policy" → "Server version gate") — that paragraph is the one definition; this file does not repeat it. The fallback shape is in SKILL.md → "Full-state htmlContainer fallback"; the rest of this file applies to it as written for HTML pages.
 

{thingsboard_cli-4.4.0.1 → thingsboard_cli-4.4.0.2}/scaffold/agent-kit/skills/dashboard-foundations/references/validation-checklists.md

@@ -83,7 +83,7 @@ For every state you built or touched, verify:
 | Header zone only | `headerCard`, `navigationWidget`, `actionButton`, `connectRealDevices` appear only at `row: 0`. |
 | Color ranges | Every `"type": "range"` color with `rangeList.advancedMode: true` has BOTH `from` and `to` on every `rangeAdvanced` entry (open side = `{"type": "constant"}`) — a missing side crashes the widget on every update (`color-ranges.md`). `latestKey` bounds name keys that exist on the widget's datasource profile. |
 | Layout mode | HTML page mode (`tb system info` → `htmlPageLayout` `true`/`null`/failed): every state reachable by navigation is an HTML page; grid states exist only as embedded helper states (maps; the alarm table for acknowledge/clear) and are never navigation targets; stock entity dialogs are `htmlPageConfig.actions` opened from page buttons. Grid mode (`false`): stock widgets by default. The save report states the mode. |
-| HTML page state | A state built as an HTML page has `layouts.main.widgets: {}` and `gridSettings` = `{layoutType: "html", htmlPageConfig: {settings, actions}}` only, no `right` layout or `breakpoints`; the grid rows below (row budget, row coverage, overlaps, header zone, widget↔layout sync) do not apply to it. A grid state is never a single htmlContainer covering the whole state — that is an HTML page — except on a server older than ThingsBoard 4.4.0.1 (`tb system info` → `htmlPageLayout: false`), where it is the required fallback (SKILL.md → "Full-state htmlContainer fallback"). |
+| HTML page state | A state built as an HTML page has `layouts.main.widgets: {}` and `gridSettings` = `{layoutType: "html", htmlPageConfig: {settings, actions}}` only, no `right` layout or `breakpoints`; the grid rows below (row budget, row coverage, overlaps, header zone, widget↔layout sync) do not apply to it. A grid state is never a single htmlContainer covering the whole state — that is an HTML page — except on a server older than ThingsBoard 4.4.1 (`tb system info` → `htmlPageLayout: false`), where it is the required fallback (SKILL.md → "Full-state htmlContainer fallback"). |
 | htmlContainer checklist | Every HTML page and every `htmlContainer` passes the pre-save checklist in `widget-html-container` (keys exist on profile, stateIds exist, mode matches template, bindings exposed, cleanup registered, permission gating). State-content rows below exempt `htmlContainer` per the Custom HTML path. |
 | switcherDetail body | Exactly one `stateSwitcher` is present at `{ row: 1, col: 0, sizeX: 24, sizeY: 14 }` (REQUIRED whenever the state has navigationWidget tabs — without it the tabs do nothing), and no other body widgets. |
 | typeFullFqn | Must match the typeFullFqn in the matching `widget-*` catalog skill exactly. |

thingsboard_cli-4.4.0.2/scaffold/agent-kit/skills/device-connectivity/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: device-connectivity
+description: "Connect a real device to ThingsBoard so its data reaches the dashboard, or check why a device sends nothing. Use when the user agrees to connect a real device after a deploy, asks how to send real data or connect a sensor ('how do I connect my sensor?', 'connect my ESP32 over MQTT'), says the device is on ('check my sensor', 'is my device sending data?', 'чи шле мій девайс дані'), asks for a device's connection settings or token ('show device settings', 'покажи налаштування'), or reports that a device is offline / not sending data. Covers devices that send directly over HTTP, MQTT or CoAP; for LoRaWAN, Sigfox, cloud platforms, brokers, Modbus/OPC-UA/BACnet and other gateway protocols, LwM2M, SNMP and many devices at once it gives the exact docs link. Works directly against the ThingsBoard server, not in local mode."
+user-invocable: true
+---
+
+# Device connectivity
+
+Closes the loop from "I have a device" to "its data is on my dashboard" with as few actions from the user as possible. **You run every command yourself.** The user only enters the settings on the device and powers it on.
+
+## Ground rules
+
+- **Be fast.** On the main path (steps 1–5) run only the commands this skill names and read nothing else: no `references/*.md`, no other skills, no entity files beyond the solution's `devices/` folder. Everything you need is in the JSON of `tb device connect`. Read a reference only for "Something else", diagnosis or a question the JSON does not answer.
+- **The user sees only your visible text.** The user does NOT see the output of the commands you run (it is collapsed) and does NOT see your thinking. Everything the user must read — values, settings, tokens, commands, links — goes into a visible text message. "I've provided the settings" in your thinking is not providing them.
+- **Text right before a question in the same turn may not be shown.** Put what the user must see into the question text, or end the turn with it. Dashboard links go into the message that ends the turn.
+- **You run the commands.** Never ask the user to run a command, except the one test command you show under the settings table.
+- **Choices are buttons.** Ask every choice with `AskUserQuestion` (2–4 options, the recommended one first and marked "(Recommended)"). If your agent has no such tool, ask one short question with numbered options (`1.`, `2.`, …) and wait for the answer. One question at a time.
+- **Always link the dashboard.** Every time you mention the dashboard — after `--send`, after data arrived, in a summary — write the first entry of `dashboards` as a Markdown link with its title, like `[Office Air Quality](https://…/dashboards/all/<id>)`. Never only its name. When `dashboards` has only the "Device page" (no dashboard yet), write it as `Device page: [<device name>](<url>)`, never "Dashboard: [Device page](…)".
+- **Show the device credentials.** The access token (and the MQTT password) is the device's own credential, the same one the "Check connectivity" dialog of the UI shows. Run `tb device connect` with `--show-secrets` and put the real values in the settings table. Never show the user's API key or anything from `tb config`.
+- **Server, not local mode.** Entity writes use `--remote`; don't switch modes, don't create solutions, never run `tb push` or `tb config …`. `--send` writes one test value as the device once the user agreed to connect it. Creating a device, `set-credentials` and `set-transport` happen only after the user approved them; `set-credentials` and `set-transport` then run with `--yes` (`tb device save` has no `--yes`).
+- **Say what really happened.** After `--send`, say what `sent.note` says: "The CLI sent a test value as the device. The device itself is not connected yet." If `sent.transport` differs from `sent.requestedTransport`, the client was not installed and the value went over HTTP: say that the chosen transport is not tested yet. Say the device is connected only after `--wait` received its data.
+- **The CLI sets up only direct HTTP, MQTT and CoAP, one device at a time.** For everything else, give the row of `references/other-connections.md`: what to set up and the docs link. No advice for specific device models.
+- Reply in the user's language; keep command output out of the reply except the values the user needs.
+
+## Commands
+
+| Need | Command |
+|---|---|
+| Send a test value **and** get the settings with real credentials, the test command and the dashboard links — one call | `tb device connect "<device>" --send --show-secrets --transport <mqtt\|http\|coap> --format json` |
+| Settings without sending (X.509, "show device settings") | `tb device connect "<device>" --show-secrets --transport <t> --format json` |
+| Wait for data from the device itself ("check my sensor") | `tb device connect "<device>" --wait --format json` (up to 300 s; exit 1 on timeout, with a hint) |
+| Activity and latest telemetry | `tb device status "<device>" --format json` |
+| Create a device | `tb device save --name "<D>" --type "<profile>" --remote` |
+| Replace credentials | `tb device set-credentials "<device>" --type ACCESS_TOKEN --generate`, `--type MQTT_BASIC --client-id … --username … --password …` |
+| Profile MQTT topic | `tb device-profile set-transport "<profile>" --type MQTT --telemetry-topic …` |
+
+`dashboards` entries found on the server (a device outside the local solution) also carry `keys`: the telemetry and attribute keys the dashboard shows.
+
+JSON fields you use: `commands[0].settings` (HTTP: `url`; MQTT: `host`, `port`, `topic`, `clientId`, `username`, `password`; CoAP: `url`; with TLS `caCertificate`), `commands[0].command` (the test command with real credentials), `commands[0].install`, `payload`, `x509`, `sent` (`transport`, `requestedTransport`, `client`, `stored`, `note`), `received`, `dashboards`.
+
+## Workflow
+
+### 1. Which device
+
+- After a deploy the user agreed to connect a device: list the solution's `devices/` names. One device → take it. Up to 4 → ask (`header: "Device"`) with the names as options. More than 4 → list them briefly and ask the user to name one.
+- The user names a device → use that name.
+- No device in ThingsBoard yet → propose to create one (name, profile) and create it after a yes.
+- The user wants to connect **many identical devices at once** → say that the CLI connects one device at a time for now, link <https://thingsboard.io/docs/paas/user-guide/provisioning/> for bulk provisioning, and offer to connect one device now.
+- **"Check my sensor" / "is my device sending data?"** about a device you already set up → go straight to step 4.
+- **"Show device settings"** → "Show the settings again".
+- **"It is offline / sends nothing"** → step 6.
+
+### 2. How the device sends data
+
+Ask (`header: "Connection"`): "How does your device send data?"
+
+1. **MQTT** (Recommended): most firmware and dev boards (ESP32, Arduino, Raspberry Pi) and devices with an MQTT settings page. Also when the user is not sure.
+2. **HTTP**: the device posts JSON to a URL.
+3. **CoAP**: constrained devices, often NB-IoT.
+4. **Something else**: LoRaWAN, Sigfox, a cloud platform, Modbus, BACnet, OPC-UA, LwM2M, SNMP, …
+
+For **Something else**, read `references/other-connections.md`, give the matching row (what to set up and the docs link), and stop.
+
+### 3. Test value and settings — one command, the turn ends with the table
+
+If a live demo stream (`tb emulator run`, started in the background after the deploy) is still running, stop that background command first: its data is not from the device, and it would overwrite the test value.
+
+Run `tb device connect "<device>" --send --show-secrets --transport <t> --format json`. (X.509 credentials: the same without `--send`, and skip the "Sent" line.) The `payload` in this JSON is the one that `--send` sent and the test command sends.
+
+Then **end the turn with one visible message**, exactly this template for MQTT with an access token, replacing every `<…>`:
+
+````markdown
+Sent a test value as the device: <key>=<value>, <key>=<value>. The device itself is not connected yet. Dashboard: [<dashboards[0].title>](<dashboards[0].url>)
+
+Enter these settings on your device:
+
+| Setting | Value |
+|---|---|
+| Host | `<commands[0].settings.host>` |
+| Port | `<commands[0].settings.port>` |
+| Topic | `<commands[0].settings.topic>` |
+| Username | `<commands[0].settings.username>` (access token) |
+| Payload | `<payload, as JSON, copied as is>` |
+
+To test from your computer:
+
+```bash
+<commands[0].command>
+```
+
+Enter these settings on your device and power it on. When it's on, say "check my sensor" and I'll wait for its data.
+````
+
+Variants:
+
+- MQTT_BASIC: add Client ID and Password rows.
+- HTTP: rows URL (`commands[0].settings.url`, it contains the token), Method `POST`, Content type `application/json`, Payload.
+- CoAP: rows URL (`commands[0].settings.url`), Method `POST`, Content format `application/json`, Payload.
+- With TLS: add a CA file row — run `tb device server-cert --protocol <mqtts|coaps> -o tb-server-ca.pem` yourself (before the message) and give the file path. X.509: the files from `x509.files` and the link `x509.docs`.
+- When the client may be missing, add `commands[0].install` under the code block.
+- `sent.transport` differs from `sent.requestedTransport` → add to the first line that the value went over HTTP and the chosen transport is not tested yet.
+
+Payload is exactly `payload` from the JSON. Never round it or invent example values.
+
+**Dashboard offer.** When no dashboard shows this device's keys — `dashboards` has only the "Device page" (a standalone or new device), or `payloadSource` is `default` — add one more last line to the message, as text, not a question:
+
+```markdown
+Want a dashboard? Tell me which keys your device will send (for example <k1>, <k2>) and I'll build it now, or I'll offer one when its data arrives.
+```
+
+Take the example keys from the context: what the user named, the profile, or `payload`. Never invent them from the device model. Skip the line when the solution's dashboard already shows these keys.
+
+**After this message: no tool call, no question, no background `--wait`.** The user needs minutes or days to enter the settings on the device; the next step starts when they say "check my sensor".
+
+If `--send` fails, show the error and go to step 6.
+
+### Show the settings again
+
+"Show settings", "show device settings", "покажи налаштування", "what's the token?" → run `tb device connect "<device>" --show-secrets --transport <t> --format json` **without `--send`** (no new test value) and end the turn with the table, the test command and the last line of the step 3 template (no "Sent" line). Use the transport chosen earlier; if none was chosen, ask step 2 first.
+
+### 4. Wait for data ("check my sensor")
+
+The user says "check my sensor", "is my device sending data?", "my device is on" → stop a live demo stream if one runs, then run `tb device connect "<device>" --wait --format json` as a **background** command when you can (it waits up to 5 minutes), otherwise in the foreground with `--timeout 110` and rerun once. Say in one line that you are waiting for its data. This works for every transport, LwM2M and SNMP too: `--wait` only reads the telemetry. Data received → step 5. Timeout → step 6.
+
+### Keys before the data ("temperature, humidity, battery")
+
+The user answers the dashboard offer with keys → build the dashboard now, as **Dashboard** in step 5 with these keys (use the `standalone-dashboard` skill for this device). End the turn with the dashboard link, the keys it shows, and one line: "The key names in your firmware must match exactly: <k1>, <k2>, …". Then "check my sensor" works as usual.
+
+### 5. Data received
+
+Build on the **real keys** from `received`, never on the test payload. Pick the first case that applies:
+
+- **Nothing to ask** (the solution's dashboard already shows these keys and the solution has no other unconnected device) → end the turn with: "Data received from <device>: <k>=<v>, <k>=<v>. <device> is connected. Dashboard: [<title>](<url>)"
+- **A dashboard of this device exists, but lacks some received keys** (a `dashboards` entry with `keys`, or the solution's dashboard file) → ask (`header: "Next step"`): "Data received from <device>: <k>=<v>, …. Add <missing keys> to <dashboard title>?" with **Add to <dashboard title>** (Recommended) · **Not now**. Add the widgets to that dashboard (`update-solution` for a solution's dashboard, otherwise `tb dashboard` on the server); never build a second dashboard for the device.
+- **The device has no dashboard** (`dashboards` has only the "Device page") → ask (`header: "Next step"`) with the result **in the question text**: "Data received from <device>: <k>=<v>, <k>=<v>. What next?" with **Dashboard for this device** (Recommended) · **Full solution** · **Not now**.
+  - **Dashboard**: ask (`header: "Keys"`) "Which keys go on the dashboard?" with **All keys: <k1, k2, …>** (Recommended) · **Choose keys**. For **Choose keys**, ask again with `multiSelect: true` (up to 4 keys; with more, list them and let the user name the ones they want). Then use the `standalone-dashboard` skill for this device and these keys.
+  - **Full solution**: use the `create-solution` skill with the device and its real keys as the starting point.
+  - **Not now** → 5b, or end the turn with "<device> is connected. Dashboard: [<title>](<url>)".
+- **The dashboard shows these keys, and the solution has other unconnected devices** → 5b with the result in the question text.
+
+If the user wants a dashboard but only the CLI test value arrived, ask (`header: "Keys"`) with **Wait for real data** (Recommended) · **Tell what the device measures**.
+
+**5b. Another device.** Only after the data of this device arrived (and after the dashboard or solution of step 5, if the user chose one), and only if the solution has more devices that are not connected yet. Ask (`header: "Next device"`): "Data received from <device>: <k>=<v>, <k>=<v>. Connect another device of <solution> (<names of all unconnected devices, up to 3; with more, "and N more">)?" with **Yes** · **No**. (After a dashboard or solution was built, drop the "Data received" part.)
+
+- **Yes** → step 1 for the remaining devices; that turn ends with the step 3 message of the next device, with its dashboard link.
+- **No** → end the turn with: "<device> is connected. Dashboard: [<title>](<url>)"
+
+### 6. No data: diagnose
+
+The `--wait` timed out. **First timeout** of this device in a row: ask (`header: "No data"`) with what happened **in the question text**: "No data from <device> in 5 minutes (<last activity, as `ago` from `tb device status` like "13 minutes ago", or "it has not connected">). Check why?" with **Check the connection** (Recommended) · **Wait 5 more minutes** · **Stop**.
+
+**Timeout again right after a wait that already timed out** (the user chose **Wait 5 more minutes**, or said "check my sensor" again without changing anything): no question; run **Check the connection** at once and end the turn with the verdict.
+
+Times: always relative ("13 minutes ago", from the `ago` field of `tb device status --format json`) or in the user's local time. Never show UTC or epoch milliseconds.
+
+**Check the connection**: run `tb device status "<device>" --format json` and find the verdict. What counts is **only what happened during the wait**: older data, earlier test values (`--send`, `curl`) and activity before the wait prove nothing about the device. ThingsBoard rejects a connection with a wrong or old token and keeps **no trace** of it, so "data arrived before" never means the token on the device is right.
+
+- "…but not from the device" in the wait error → something else writes telemetry, usually the live demo stream. Stop it and wait again.
+- **No activity and no new telemetry during the wait** (the wait error says "ThingsBoard did not see the device connect") → the device did not reach ThingsBoard or was rejected. The first cause is the settings on the device: show them again as the step 3 table (run `tb device connect "<device>" --show-secrets --transport <t> --format json`, the real token) and ask to check the **access token**, then host, port and transport (and TLS). Say that ThingsBoard does not show rejected connections. On MQTT, "not authorised" / CONNACK 5 means a wrong token; "connection refused" or a timeout means host, port or network. Only as a second cause: the device sent once and stopped, or it is off. Never say the token or host "is correct".
+- Active during the wait, no new telemetry → it connects but publishes wrong: check the topic or URL; the payload must be a JSON object. Now read Troubleshooting in `references/mqtt.md`, `references/http.md` or `references/coap.md` if needed.
+- `--send` failed with HTTP 401 → the access token is wrong: check the device and its credentials type.
+
+End the turn with the verdict as text: what is wrong, the one likely cause to fix on the device (with the settings table when it is the settings), and "When it's fixed, say "check my sensor"." (step 4). If you ask a question instead, put the verdict into the question text.
+
+**Stop** → end the turn with: "Stopped waiting. When the device is on, say "check my sensor". Dashboard: [<title>](<url>)"
+
+## References (only off the main path)
+
+- `references/other-connections.md`: integrations, IoT Gateway connectors, LwM2M, SNMP, Sparkplug: what to set up and the docs link.
+- `references/mqtt.md`, `references/http.md`, `references/coap.md`: device APIs and troubleshooting.
+- `references/lwm2m.md`, `references/snmp.md`, `references/sparkplug.md`: details for those device APIs.