<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[🧠 How GrapesIoT Models Your Fleet: Products → Data Points → Devices]]></title><description><![CDATA[<h1>How GrapesIoT Models Your Fleet</h1>
<p dir="auto">Most first-week confusion comes from one question: <strong>what is the difference between a product, a data point, and a device?</strong></p>
<p dir="auto">They are three layers of the same contract.</p>
<pre><code class="language-text">Product  →  what kind of thing am I?
Data point →  what values does it expose?
Device  →  which physical unit is talking right now?
</code></pre>
<p dir="auto">Get those three right and everything else — MQTT, dashboards, history, automation — follows naturally.</p>
<p dir="auto"><img src="https://forum.grapesiot.com/assets/uploads/files/1794556164826-01-products.png" alt="Product card with device count and data point count" class=" img-fluid img-markdown" /></p>
<p dir="auto"><em>A product is the template. The card summarises how many devices use it and how many data points it defines.</em></p>
<h2>Product: the schema, not the hardware</h2>
<p dir="auto">A <strong>product</strong> is a template for a class of device. It is not a physical unit and it does not connect to the broker by itself.</p>
<p dir="auto">A product holds:</p>
<ul>
<li>a name, description, and icon,</li>
<li>the list of <strong>data points</strong> that every device of this type must expose,</li>
<li>product-level metadata used by the UI and by templates.</li>
</ul>
<p dir="auto">Think of it as the firmware interface description. If you are building a greenhouse controller, the product might be <code>Greenhouse Controller v1</code>. Every greenhouse controller you ship uses that same product, so every dashboard, alert, and history query works the same way.</p>
<p dir="auto">Create one product per hardware family. Do not create a product per unit. If two units differ only by serial number, they are devices of the same product.</p>
<h2>Data point: one named value in the contract</h2>
<p dir="auto">A <strong>data point</strong> is one value the product exposes. It has:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Field</th>
<th>Purpose</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Name</strong></td>
<td>Human label</td>
<td>Ambient Temperature</td>
</tr>
<tr>
<td><strong>Identifier (code)</strong></td>
<td>Machine key used in payloads</td>
<td><code>temp</code></td>
</tr>
<tr>
<td><strong>Data type</strong></td>
<td>How the value is interpreted</td>
<td>INT / BOOL / STR / JSON / RAW</td>
</tr>
<tr>
<td><strong>Direction</strong></td>
<td>Who writes the value</td>
<td>Status / Control / Both</td>
</tr>
<tr>
<td><strong>Unit</strong></td>
<td>Display suffix</td>
<td>°C</td>
</tr>
<tr>
<td><strong>Min / max / step</strong></td>
<td>Validation and widget bounds</td>
<td>0 / 60 / 0.1</td>
</tr>
<tr>
<td><strong>Storage</strong></td>
<td>Whether history is retained</td>
<td>on / off</td>
</tr>
</tbody>
</table>
<p dir="auto">Two rules matter more than the rest:</p>
<ol>
<li><strong>The identifier (<code>dpcode</code>) is the key your device publishes.</strong> It is not the numeric data point ID.</li>
<li><strong>The data type and direction are part of the contract.</strong> A dashboard widget that needs a boolean will not bind to a string point, and a control widget will not write to a status-only point.</li>
</ol>
<p dir="auto">The product detail page lists every data point and shows the code, type, unit, and direction in one table.</p>
<p dir="auto"><img src="https://forum.grapesiot.com/assets/uploads/files/1794556165628-02-data-points.png" alt="Data points table on a product detail page" class=" img-fluid img-markdown" /></p>
<p dir="auto"><em>Data points define what a device can report or accept. The identifier becomes the key you publish in MQTT.</em></p>
<h3>Direction: status, control, or both</h3>
<ul>
<li><strong>Status (from device):</strong> the device reports it. Temperature, humidity, battery voltage, fault code.</li>
<li><strong>Control (to device):</strong> the dashboard or an automation writes it. Pump on/off, target temperature, mode selector.</li>
<li><strong>Both:</strong> the value can be reported and written. Use this for things like a setpoint that the device also echoes back.</li>
</ul>
<p dir="auto">Direction is enforced by the UI and by the binding rules. If a widget cannot see a data point, check the direction before you check the network.</p>
<h3>Storage: live vs history</h3>
<p dir="auto">A data point is live by default. Enable <strong>Storage</strong> when you need history for charts, exports, or audits. Storage is a per-data-point decision, so you can keep high-rate telemetry live-only and still retain daily totals.</p>
<h2>Device: one physical unit</h2>
<p dir="auto">A <strong>device</strong> is one unit of a product. It has:</p>
<ul>
<li>a device UUID (used in the MQTT topic),</li>
<li>a client ID / MQTT username and password,</li>
<li>an optional owner assignment,</li>
<li>a live connection state,</li>
<li>a monitor view that renders the product's dashboard with real values.</li>
</ul>
<p dir="auto">When you create a device, assign it to the product. The device then inherits the product's data point schema. If you add a data point later, every device of that product sees it; no per-device schema migration is needed.</p>
<p dir="auto"><img src="https://forum.grapesiot.com/assets/uploads/files/1794556166110-03-devices.png" alt="Device card showing assigned product and connection credentials" class=" img-fluid img-markdown" /></p>
<p dir="auto"><em>A device is one physical unit. It inherits the product schema and gets its own MQTT client ID and password.</em></p>
<h3>Device ID vs client ID</h3>
<p dir="auto">They are related but used in different places:</p>
<ul>
<li>The <strong>device UUID</strong> identifies the device in the topic: <code>1v0/&lt;DEVICE_ID&gt;/uplink</code>.</li>
<li>The <strong>client ID</strong> shown on the device card is the MQTT username. In the standard provisioning flow it is the same UUID.</li>
<li>The <strong>password</strong> is generated with the device. It is a secret.</li>
</ul>
<p dir="auto">If your account shows a client ID that differs from the device UUID, use the client ID as the MQTT username and the device UUID in the topic.</p>
<p dir="auto">The monitor is where the model becomes visible: the device's live state is rendered through the product's dashboard, using the bindings defined in UI Studio.</p>
<p dir="auto"><img src="https://forum.grapesiot.com/assets/uploads/files/1794556166654-04-monitor.png" alt="Device monitor showing live connection status" class=" img-fluid img-markdown" /></p>
<p dir="auto"><em>The monitor is the runtime view: live values arrive over WebSocket as soon as the device publishes.</em></p>
<h2>A worked example</h2>
<p dir="auto">Product: <strong>Greenhouse Controller v1</strong></p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Code</th>
<th>Name</th>
<th>Type</th>
<th>Direction</th>
<th>Unit</th>
<th>Storage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>temp</code></td>
<td>Ambient Temperature</td>
<td>INT</td>
<td>Status</td>
<td>°C</td>
<td>on</td>
</tr>
<tr>
<td><code>humidity</code></td>
<td>Relative Humidity</td>
<td>INT</td>
<td>Status</td>
<td>%</td>
<td>on</td>
</tr>
<tr>
<td><code>pump</code></td>
<td>Pump State</td>
<td>BOOL</td>
<td>Both</td>
<td>—</td>
<td>off</td>
</tr>
<tr>
<td><code>mode</code></td>
<td>Operating Mode</td>
<td>STR</td>
<td>Both</td>
<td>—</td>
<td>off</td>
</tr>
<tr>
<td><code>schedule</code></td>
<td>Schedule</td>
<td>JSON</td>
<td>Both</td>
<td>—</td>
<td>off</td>
</tr>
</tbody>
</table>
<p dir="auto">A device of this product publishes:</p>
<pre><code class="language-json">{
  "type": 0,
  "stype": 0,
  "data": {
    "temp": 25.4,
    "humidity": 60,
    "pump": true
  },
  "dir": 49
}
</code></pre>
<p dir="auto">The keys <code>temp</code>, <code>humidity</code>, and <code>pump</code> are the <strong>data point codes</strong>, not their numeric IDs. The server matches them to the product schema and updates the device's live state.</p>
<h2>The five mistakes to avoid</h2>
<ol>
<li><strong>Putting <code>dpid</code> in the payload.</strong> The payload uses <code>dpcode</code>. Numeric IDs are internal.</li>
<li><strong>Creating a product per unit.</strong> Create a product per hardware family, then add devices.</li>
<li><strong>Renaming a <code>dpcode</code> after deployment.</strong> It is a breaking change for every device and dashboard. Add a new point and migrate instead.</li>
<li><strong>Using a status-only point as a control.</strong> The widget will not bind, or the write will be rejected.</li>
<li><strong>Storing everything.</strong> High-rate telemetry can be live-only. Enable storage only where history is useful.</li>
</ol>
<h2>What to read next</h2>
<ul>
<li><strong>Quickstart: Device → MQTT → Live Monitor</strong> for the exact topic, payload, credentials, and a runnable publisher.</li>
<li><strong>Data Point Types Explained</strong> for choosing the right type.</li>
<li><strong>Your First Dashboard in UI Studio</strong> for binding widgets to the data points you just defined.</li>
</ul>
]]></description><link>https://forum.grapesiot.com/topic/89/how-grapesiot-models-your-fleet-products-data-points-devices</link><generator>RSS for Node</generator><lastBuildDate>Thu, 19 Nov 2026 13:02:44 GMT</lastBuildDate><atom:link href="https://forum.grapesiot.com/topic/89.rss" rel="self" type="application/rss+xml"/><pubDate>Fri, 13 Nov 2026 07:49:23 GMT</pubDate><ttl>60</ttl></channel></rss>