<?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[📡 Quickstart: Device → MQTT → Live Monitor]]></title><description><![CDATA[<h1>Quickstart: Device → MQTT → Live Monitor</h1>
<p dir="auto">This is the shortest path from a terminal to a live value in GrapesIoT.</p>
<p dir="auto">You need:</p>
<ul>
<li>a product with at least one data point,</li>
<li>a device assigned to that product,</li>
<li>the device's MQTT credentials,</li>
<li>a machine with Node.js 18+ (for the sample publisher).</li>
</ul>
<p dir="auto"><img src="https://forum.grapesiot.com/assets/uploads/files/1794556167890-01-credentials.png" alt="Device connection credentials with values masked" class=" img-fluid img-markdown" /></p>
<p dir="auto"><em>Each device gets a unique client ID (also the MQTT username) and password. Treat the password like a secret.</em></p>
<h2>1. Collect the connection details</h2>
<p dir="auto">Open <strong>Devices</strong> and find the device card.</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Setting</th>
<th>Where to find it</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Broker URL</strong></td>
<td>This guide</td>
<td><code>mqtt://dev.grapesiot.com:1883</code></td>
</tr>
<tr>
<td><strong>Device ID</strong></td>
<td>Device route / device record</td>
<td>Used in the topic</td>
</tr>
<tr>
<td><strong>MQTT username</strong></td>
<td>Device card → Client ID</td>
<td>Usually the same as the device ID</td>
</tr>
<tr>
<td><strong>MQTT password</strong></td>
<td>Device card → Password</td>
<td>Secret; do not commit it</td>
</tr>
<tr>
<td><strong>Topic</strong></td>
<td>Built from the device ID</td>
<td><code>1v0/&lt;DEVICE_ID&gt;/uplink</code></td>
</tr>
</tbody>
</table>
<p dir="auto">If your deployment uses a different broker, use that host and port. The public broker above is for the hosted test environment; production deployments should use TLS and your own hostname.</p>
<h2>2. Understand the envelope</h2>
<p dir="auto">Every uplink is a JSON object with four required fields:</p>
<pre><code class="language-json">{
  "type": 0,
  "stype": 0,
  "data": {
    "temp": 25.4,
    "humidity": 60,
    "pump": true
  },
  "dir": 49
}
</code></pre>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>type</code></td>
<td><code>0</code></td>
<td>DATA packet</td>
</tr>
<tr>
<td><code>stype</code></td>
<td><code>0</code></td>
<td>Device-native sensor reading</td>
</tr>
<tr>
<td><code>data</code></td>
<td>object</td>
<td><code>dpcode: value</code> pairs</td>
</tr>
<tr>
<td><code>dir</code></td>
<td><code>49</code></td>
<td>Required direction field. For DATA, the server requires it to be present; it does not use it to route the reading.</td>
</tr>
</tbody>
</table>
<p dir="auto">Rules that matter:</p>
<ul>
<li><code>data</code> keys must exactly match the product's <strong>data point codes</strong>.</li>
<li><code>data</code> can contain one key or many. Unrecognised keys are ignored, so a typo looks like “nothing happened”.</li>
<li>The payload must be smaller than <strong>4,100 bytes</strong>.</li>
<li>Do not use <code>dpid</code> in the payload. Use <code>dpcode</code>.</li>
</ul>
<h2>3. Publish with Node.js</h2>
<p dir="auto">Create a scratch folder and install the MQTT client:</p>
<pre><code class="language-bash">mkdir grapes-mqtt-test
cd grapes-mqtt-test
npm init -y
npm install mqtt
</code></pre>
<p dir="auto">Create <code>publish.mjs</code>:</p>
<pre><code class="language-js">import mqtt from 'mqtt'

const BROKER_URL = process.env.MQTT_URL ?? 'mqtt://dev.grapesiot.com:1883'
const DEVICE_ID = process.env.DEVICE_ID
const MQTT_USERNAME = process.env.MQTT_USERNAME ?? DEVICE_ID
const MQTT_PASSWORD = process.env.MQTT_PASSWORD

if (!DEVICE_ID || !MQTT_PASSWORD) {
  console.error('Set DEVICE_ID and MQTT_PASSWORD first.')
  process.exit(1)
}

const topic = `1v0/${DEVICE_ID}/uplink`

const payload = {
  type: 0,
  stype: 0,
  data: {
    temp: 25.4,
    humidity: 60,
    pump: true,
  },
  dir: 49,
}

const client = mqtt.connect(BROKER_URL, {
  username: MQTT_USERNAME,
  password: MQTT_PASSWORD,
  clientId: MQTT_USERNAME,
  clean: true,
  reconnectPeriod: 0,
})

client.on('connect', () =&gt; {
  console.log('connected to', BROKER_URL)
  client.publish(topic, JSON.stringify(payload), { qos: 1 }, (err) =&gt; {
    if (err) console.error('publish failed:', err)
    else console.log('published to', topic)
    client.end()
  })
})

client.on('error', (err) =&gt; {
  console.error('connection error:', err.message)
  client.end()
})
</code></pre>
<p dir="auto">Run it:</p>
<pre><code class="language-powershell">$env:DEVICE_ID="&lt;your-device-id&gt;"
$env:MQTT_USERNAME="&lt;client-id&gt;"
$env:MQTT_PASSWORD="&lt;device-password&gt;"
node publish.mjs
</code></pre>
<p dir="auto">On macOS or Linux:</p>
<pre><code class="language-bash">DEVICE_ID="&lt;your-device-id&gt;" \
MQTT_USERNAME="&lt;client-id&gt;" \
MQTT_PASSWORD="&lt;device-password&gt;" \
node publish.mjs
</code></pre>
<p dir="auto">A successful run prints:</p>
<pre><code class="language-text">connected to mqtt://dev.grapesiot.com:1883
published to 1v0/&lt;device-id&gt;/uplink
</code></pre>
<h2>4. Verify in the monitor</h2>
<p dir="auto">Open the device and click <strong>Monitor Device</strong>. The connection pill should move to <strong>Live</strong> and any widgets bound to <code>temp</code>, <code>humidity</code>, or <code>pump</code> should update.</p>
<p dir="auto"><img src="https://forum.grapesiot.com/assets/uploads/files/1794556168434-02-monitor-live.png" alt="Live device monitor after an uplink message" class=" img-fluid img-markdown" /></p>
<p dir="auto"><em>When the payload reaches the broker, the monitor switches to Live and the bound widgets update.</em></p>
<p dir="auto">If the pill is live but a widget does not change, the message reached the device but the widget is not bound to the data point you published. Check the binding in UI Studio.</p>
<h2>5. What the server does with the message</h2>
<ol>
<li>Authenticates the MQTT client with the device credentials.</li>
<li>Parses the JSON envelope and requires <code>type</code>, <code>stype</code>, <code>data</code>, and <code>dir</code>.</li>
<li>Matches each <code>data</code> key to a data point code in the device's product.</li>
<li>Updates the device's live state.</li>
<li>Writes history if the data point has <strong>Storage</strong> enabled.</li>
<li>Pushes the update to connected monitors over WebSocket.</li>
</ol>
<p dir="auto">That is why a wrong <code>dpcode</code> can look like a successful publish: the broker accepted it, but the platform had nothing to update.</p>
<h2>Troubleshooting</h2>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Symptom</th>
<th>Likely cause</th>
<th>Fix</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Connection refused</code> or <code>Not authorized</code></td>
<td>Wrong host/port, client ID, or password</td>
<td>Re-copy the credentials; check the broker URL</td>
</tr>
<tr>
<td>Publish succeeds, monitor stays <strong>Not connected</strong></td>
<td>Wrong device ID in the topic</td>
<td>Use the device UUID, not the product name</td>
</tr>
<tr>
<td>Monitor is <strong>Live</strong>, widget does not move</td>
<td>Widget not bound, or wrong <code>dpcode</code></td>
<td>Check the Logic tab binding and the payload key</td>
</tr>
<tr>
<td>Values look like strings</td>
<td>Type mismatch</td>
<td>Send numbers for INT, booleans for BOOL</td>
</tr>
<tr>
<td><code>payload too large</code></td>
<td>Payload over 4,100 bytes</td>
<td>Send fewer fields or split the message</td>
</tr>
</tbody>
</table>
<h2>Security notes</h2>
<ul>
<li>Never commit the device password. Use environment variables or a local <code>.env</code> file that is git-ignored.</li>
<li>Mask credentials before posting screenshots.</li>
<li>Use TLS and a private broker for production. The test broker in this guide is for getting started only.</li>
<li>Rotate a device password immediately if it is exposed.</li>
</ul>
<h2>Next</h2>
<ul>
<li><strong>Data Point Types Explained</strong> for choosing the right type and direction.</li>
<li><strong>Your First Dashboard in UI Studio</strong> for binding the values you just published.</li>
<li>Protocol overview: <a href="https://embiq.grapesiot.com/protocol" rel="nofollow ugc">https://embiq.grapesiot.com/protocol</a></li>
</ul>
]]></description><link>https://forum.grapesiot.com/topic/90/quickstart-device-mqtt-live-monitor</link><generator>RSS for Node</generator><lastBuildDate>Thu, 19 Nov 2026 13:02:46 GMT</lastBuildDate><atom:link href="https://forum.grapesiot.com/topic/90.rss" rel="self" type="application/rss+xml"/><pubDate>Fri, 13 Nov 2026 07:49:27 GMT</pubDate><ttl>60</ttl></channel></rss>