π‘ Quickstart: Device β MQTT β Live Monitor
-
Quickstart: Device β MQTT β Live Monitor
This is the shortest path from a terminal to a live value in GrapesIoT.
You need:
- a product with at least one data point,
- a device assigned to that product,
- the device's MQTT credentials,
- a machine with Node.js 18+ (for the sample publisher).

Each device gets a unique client ID (also the MQTT username) and password. Treat the password like a secret.
1. Collect the connection details
Open Devices and find the device card.
Setting Where to find it Notes Broker URL This guide mqtt://dev.grapesiot.com:1883Device ID Device route / device record Used in the topic MQTT username Device card β Client ID Usually the same as the device ID MQTT password Device card β Password Secret; do not commit it Topic Built from the device ID 1v0/<DEVICE_ID>/uplinkIf 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.
2. Understand the envelope
Every uplink is a JSON object with four required fields:
{ "type": 0, "stype": 0, "data": { "temp": 25.4, "humidity": 60, "pump": true }, "dir": 49 }Field Value Meaning type0DATA packet stype0Device-native sensor reading dataobject dpcode: valuepairsdir49Required direction field. For DATA, the server requires it to be present; it does not use it to route the reading. Rules that matter:
datakeys must exactly match the product's data point codes.datacan contain one key or many. Unrecognised keys are ignored, so a typo looks like βnothing happenedβ.- The payload must be smaller than 4,100 bytes.
- Do not use
dpidin the payload. Usedpcode.
3. Publish with Node.js
Create a scratch folder and install the MQTT client:
mkdir grapes-mqtt-test cd grapes-mqtt-test npm init -y npm install mqttCreate
publish.mjs: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', () => { console.log('connected to', BROKER_URL) client.publish(topic, JSON.stringify(payload), { qos: 1 }, (err) => { if (err) console.error('publish failed:', err) else console.log('published to', topic) client.end() }) }) client.on('error', (err) => { console.error('connection error:', err.message) client.end() })Run it:
$env:DEVICE_ID="<your-device-id>" $env:MQTT_USERNAME="<client-id>" $env:MQTT_PASSWORD="<device-password>" node publish.mjsOn macOS or Linux:
DEVICE_ID="<your-device-id>" \ MQTT_USERNAME="<client-id>" \ MQTT_PASSWORD="<device-password>" \ node publish.mjsA successful run prints:
connected to mqtt://dev.grapesiot.com:1883 published to 1v0/<device-id>/uplink4. Verify in the monitor
Open the device and click Monitor Device. The connection pill should move to Live and any widgets bound to
temp,humidity, orpumpshould update.
When the payload reaches the broker, the monitor switches to Live and the bound widgets update.
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.
5. What the server does with the message
- Authenticates the MQTT client with the device credentials.
- Parses the JSON envelope and requires
type,stype,data, anddir. - Matches each
datakey to a data point code in the device's product. - Updates the device's live state.
- Writes history if the data point has Storage enabled.
- Pushes the update to connected monitors over WebSocket.
That is why a wrong
dpcodecan look like a successful publish: the broker accepted it, but the platform had nothing to update.Troubleshooting
Symptom Likely cause Fix Connection refusedorNot authorizedWrong host/port, client ID, or password Re-copy the credentials; check the broker URL Publish succeeds, monitor stays Not connected Wrong device ID in the topic Use the device UUID, not the product name Monitor is Live, widget does not move Widget not bound, or wrong dpcodeCheck the Logic tab binding and the payload key Values look like strings Type mismatch Send numbers for INT, booleans for BOOL payload too largePayload over 4,100 bytes Send fewer fields or split the message Security notes
- Never commit the device password. Use environment variables or a local
.envfile that is git-ignored. - Mask credentials before posting screenshots.
- Use TLS and a private broker for production. The test broker in this guide is for getting started only.
- Rotate a device password immediately if it is exposed.
Next
- Data Point Types Explained for choosing the right type and direction.
- Your First Dashboard in UI Studio for binding the values you just published.
- Protocol overview: https://embiq.grapesiot.com/protocol
Hello! It looks like you're interested in this conversation, but you don't have an account yet.
Getting fed up of having to scroll through the same posts each visit? When you register for an account, you'll always come back to exactly where you were before, and choose to be notified of new replies (either via email, or push notification). You'll also be able to save bookmarks and upvote posts to show your appreciation to other community members.
With your input, this post could be even better π
Register Login