Subscribe to a Variable's Last Dot

Receive the complete data point — value, timestamp, and context — over MQTT.

Use this topic to subscribe to a variable's last "dot" (data point). Unlike the /lv topic, which returns only the value, this returns the complete data point — value, timestamp, and context.

Topic structure

/v1.6/devices/{DEVICE_LABEL}/{VARIABLE_LABEL}

Parameter	Description
`{DEVICE_LABEL}`	Your device's unique label
`{VARIABLE_LABEL}`	The variable you want to monitor

⚠️
If the device or variable doesn't exist, the subscription will fail.

Connection parameters

Field	Value	Required
Host	`api.surfact.com`	Yes
Port	`1883` (no TLS) / `8883` (TLS)	Yes
Username	Your Surfact token	Yes
Password	Any character or blank	No
Quality of Service	`0` or `1`	No

Response format

The message is a JSON object:

{
  "value": 34.0,
  "timestamp": 1634311791000,
  "context": {
    "status": "cold"
  },
  "created_at": 1634311791000
}

Field	Type	Description
`value`	number	The variable's value
`timestamp`	number	Unix timestamp (ms) when the data was recorded
`context`	object	Additional metadata (optional)
`created_at`	number	Unix timestamp (ms) when the data was created in Surfact

Examples

Command line (mosquitto_sub)

mosquitto_sub \
  -h "api.surfact.com" \
  -t "/v1.6/devices/weather-station/temperature" \
  -u "$SURFACT_TOKEN" \
  -p 8883 \
  -q 1

Python (paho-mqtt)

import paho.mqtt.client as mqtt
import json

token = "your-surfact-token"
device_label = "weather-station"
variable_label = "temperature"

def on_connect(client, userdata, flags, rc):
    topic = f"/v1.6/devices/{device_label}/{variable_label}"
    client.subscribe(topic)

def on_message(client, userdata, msg):
    data = json.loads(msg.payload.decode())
    print(f"Value: {data['value']}")
    print(f"Timestamp: {data['timestamp']}")
    if 'context' in data:
        print(f"Context: {data['context']}")

client = mqtt.Client(client_id="my-device-12345678901234567890")
client.username_pw_set(username=token, password="")
client.on_connect = on_connect
client.on_message = on_message
client.connect("api.surfact.com", 8883)
client.loop_forever()

JavaScript (mqtt.js)

const mqtt = require('mqtt');

const token = 'your-surfact-token';
const deviceLabel = 'weather-station';
const variableLabel = 'temperature';

const client = mqtt.connect('mqtts://api.surfact.com:8883', {
  username: token,
  password: '',
  clientId: 'my-device-12345678901234567890'
});

client.on('connect', () => {
  const topic = `/v1.6/devices/${deviceLabel}/${variableLabel}`;
  client.subscribe(topic);
});

client.on('message', (topic, message) => {
  const data = JSON.parse(message.toString());
  console.log(`Value: ${data.value}`);
  console.log(`Timestamp: ${data.timestamp}`);
  if (data.context) console.log(`Context: ${JSON.stringify(data.context)}`);
});

Use cases

Timestamp information — know exactly when the data was recorded
Context metadata — access extra information sent with the dot
Audit trails — track when data was created and recorded
Logging and analysis — capture complete data points

📘
Only need the number? The /lv topic is lighter.

Updated 3 months ago

Did this page help you?