Skip to content
  • Categories
  • Recent
  • Tags
  • Popular
  • World
  • Users
  • Groups
Skins
  • Light
  • Brite
  • Cerulean
  • Cosmo
  • Flatly
  • Journal
  • Litera
  • Lumen
  • Lux
  • Materia
  • Minty
  • Morph
  • Pulse
  • Sandstone
  • Simplex
  • Sketchy
  • Spacelab
  • United
  • Yeti
  • Zephyr
  • Dark
  • Cyborg
  • Darkly
  • Quartz
  • Slate
  • Solar
  • Superhero
  • Vapor

  • Default (No Skin)
  • No Skin
Collapse

Embiq Community

  1. Home
  2. Get Help
  3. MQTT & Connectivity
  4. πŸ“‘ Quickstart: Device β†’ MQTT β†’ Live Monitor

πŸ“‘ Quickstart: Device β†’ MQTT β†’ Live Monitor

Scheduled Pinned Locked Moved MQTT & Connectivity
mqttgetting-starteddevicesdata-points
1 Posts 1 Posters 34 Views 1 Watching
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • A Offline
    A Offline
    admin
    wrote last edited by admin
    #1

    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).

    Device connection credentials with values masked

    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:1883
    Device 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>/uplink

    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.

    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
    type 0 DATA packet
    stype 0 Device-native sensor reading
    data object dpcode: value pairs
    dir 49 Required direction field. For DATA, the server requires it to be present; it does not use it to route the reading.

    Rules that matter:

    • data keys must exactly match the product's data point codes.
    • data can 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 dpid in the payload. Use dpcode.

    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 mqtt
    

    Create 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.mjs
    

    On macOS or Linux:

    DEVICE_ID="<your-device-id>" \
    MQTT_USERNAME="<client-id>" \
    MQTT_PASSWORD="<device-password>" \
    node publish.mjs
    

    A successful run prints:

    connected to mqtt://dev.grapesiot.com:1883
    published to 1v0/<device-id>/uplink
    

    4. 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, or pump should update.

    Live device monitor after an uplink message

    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

    1. Authenticates the MQTT client with the device credentials.
    2. Parses the JSON envelope and requires type, stype, data, and dir.
    3. Matches each data key to a data point code in the device's product.
    4. Updates the device's live state.
    5. Writes history if the data point has Storage enabled.
    6. Pushes the update to connected monitors over WebSocket.

    That is why a wrong dpcode can look like a successful publish: the broker accepted it, but the platform had nothing to update.

    Troubleshooting

    Symptom Likely cause Fix
    Connection refused or Not authorized Wrong 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 dpcode Check the Logic tab binding and the payload key
    Values look like strings Type mismatch Send numbers for INT, booleans for BOOL
    payload too large Payload over 4,100 bytes Send fewer fields or split the message

    Security notes

    • Never commit the device password. Use environment variables or a local .env file 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
    1 Reply Last reply
    0

    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
    Reply
    • Reply as topic
    Log in to reply
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes


    • Login

    • Don't have an account? Register

    • Login or register to search.
    Powered by NodeBB Contributors
    • First post
      Last post
    0
    • Categories
    • Recent
    • Tags
    • Popular
    • World
    • Users
    • Groups