MQTT

Connection

Setting	Value
Server	mqtt.kealink.co.nz
Port	50607, TLS required (TLS 1.2 or later)
Certificate	Let's Encrypt. Standard trust stores accept it; no CA file needed.
WebSockets (optional)	wss://ws.kealink.co.nz, port 443
Username	The machine id
Client id	The machine id
Password	The machine's password
QoS	1
Retain	Off
Clean session	On
Keepalive	60 seconds

Open outgoing TCP port 50607 on the site's firewall. Use one connection per machine id: a second client connecting with the same id knocks the first off.

Topic

kealink/<machine-id>/data

A machine can only publish under its own id. It cannot subscribe to anything. Messages on any other topic are refused or ignored.

Payload

One JSON object per message, usually one every 30 seconds:

{
  "ts": 1790000000000,
  "spindle_temp": 41.2,
  "hydraulic_pressure": 118.5,
  "cycle_count": 10432,
  "running": 1
}

Field	Rule
ts	Optional. Unix time in milliseconds for the whole message. Without it, arrival time is used. A time more than 24 hours old or more than 5 minutes ahead is replaced by arrival time.
Other keys	The keys of the machine's readings. Matched without regard to case, so Temp1, TEMP1 and temp1 all find temp1.
Values	Numbers. true and false are stored as 1 and 0. For a reading of kind Text, a string of up to 200 characters (trimmed), or a number, stored as its digits.

• Keys that match no reading are not stored. They are listed on the machine's setup page with a button to add each one.
• Values of the wrong type (a string for a number reading, null, an object) are not stored.
• If two keys in one message differ only by case, the first is kept.
• TS and Ts are read as ts.

Nested values

Readings may also sit under values, the shape some gateways send:

{ "ts": 1790000000000, "values": { "spindle_temp": 41.2 } }

If a key appears both at the top and inside values, the top one is kept.

Sending buffered readings

After a connection drop, send a JSON array of up to 200 such objects, each with its own ts, on the same topic:

[
  { "ts": 1790000000000, "spindle_temp": 41.2 },
  { "ts": 1790000030000, "spindle_temp": 41.4 }
]

The 24 hour rule applies to each entry. Only the newest value of each reading is checked for alerts, so catching up never raises alerts about the past.

Size and rate

• Up to 16 KB per message.
• Each machine may send a burst of up to 120 messages, then about one a second. Messages beyond that are dropped.

See Limits.

Test from a terminal

With Mosquitto's mosquitto_pub on Linux:

mosquitto_pub -h mqtt.kealink.co.nz -p 50607 --capath /etc/ssl/certs -q 1 \
  -i <machine-id> -u <machine-id> -P '<password>' \
  -t kealink/<machine-id>/data -m '{"spindle_temp": 40.1}'

On Windows or macOS, download Let's Encrypt's ISRG Root X1 and use --cafile isrgrootx1.pem in place of --capath.

MQTT gives no reply, so check the machine's page or setup page in the portal to see what arrived.

Node.js

With the mqtt package:

import mqtt from "mqtt";

const id = process.env.KEALINK_MACHINE_ID;
const client = mqtt.connect("mqtts://mqtt.kealink.co.nz:50607", {
  clientId: id,
  username: id,
  password: process.env.KEALINK_PASSWORD,
  keepalive: 60,
  clean: true,
});

client.on("connect", () => {
  setInterval(() => {
    const payload = { ts: Date.now(), spindle_temp: readTemperature() };
    client.publish(`kealink/${id}/data`, JSON.stringify(payload), { qos: 1, retain: false });
  }, 30_000);
});

client.on("error", (err) => console.error(err.message));

Python

With paho-mqtt 2:

import json, os, time
import paho.mqtt.client as mqtt

machine_id = os.environ["KEALINK_MACHINE_ID"]
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=machine_id)
client.username_pw_set(machine_id, os.environ["KEALINK_PASSWORD"])
client.tls_set()
client.connect("mqtt.kealink.co.nz", 50607, keepalive=60)
client.loop_start()

while True:
    payload = {"ts": int(time.time() * 1000), "spindle_temp": read_temperature()}
    client.publish(f"kealink/{machine_id}/data", json.dumps(payload), qos=1)
    time.sleep(30)

Node-RED without the Kealink node

The Kealink node is easier. With Node-RED's own mqtt out node instead:

• Server mqtt.kealink.co.nz, Port 50607, Use TLS ticked with the default TLS configuration.
• Client ID, and on the Security tab Username: the machine id. Password: the machine's password.
• QoS 1, Retain false.

Build the payload in a function node before it:

msg.topic = "kealink/<machine-id>/data";
msg.payload = { ts: Date.now(), spindle_temp: global.get("spindle_temp") };
return msg;

Microcontrollers

Anything with WiFi or Ethernet and a TLS-capable MQTT client works. Three things trip boards up:

• Trust the root certificate. Store ISRG Root X1 (valid to 2035) on the board. Do not turn certificate checks off.
• Set the clock before connecting. A board that boots thinking it is 1970 refuses the certificate. Get the time over NTP first. Without a reliable clock, leave ts out and let Kealink stamp arrival time.
• Raise the MQTT buffer. Some libraries default to 256 bytes, too small for a few readings and a timestamp, and fail without saying why.

A board that sleeps between readings is often better on HTTP: every wake would otherwise need a fresh MQTT connection.