TripQube MQTT GPS Device Integration

Integrate GPS tracking hardware devices with TripQube using MQTT protocol. Perfect for IoT applications, custom GPS trackers, and embedded systems.

🔌 MQTT Connection Details

📝 Device Registration

Before pushing location data via MQTT, your device must be registered in the TripQube system. Use the HTTP registration API to register approved devices.

Registration Payload

{
  "device_id": "TRK-ABC-12345",
  "pin": "98765",
  "firmware_version": "2.1.0",
  "manufacturer": "TripQube Hardware"
}

Registration Fields

📍 Publishing Location Data via MQTT

After device registration, publish GPS location updates to the MQTT broker. TripQube will automatically create or update trips based on location data.

MQTT Message Format (JSON)

{
  "device_id": "TRK-ABC-12345",
  "pin": "98765",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "speed": 15.5,
  "heading": 180,
  "accuracy": 10,
  "altitude": 50,
  "battery_level": 85,
  "timestamp": 1705012345000
}

Message Fields

💻 Implementation Examples

Python (paho-mqtt)

Simple Python implementation for testing and prototyping MQTT GPS devices.

import paho.mqtt.client as mqtt
import json
import time
import ssl

# MQTT Configuration
BROKER = "q3edf31f.ala.asia-southeast1.emqxsl.com"
PORT = 8883
USERNAME = "YOUR_USERNAME"  # Request from TripQube
PASSWORD = "YOUR_PASSWORD"  # Request from TripQube

DEVICE_ID = "TRK-ABC-12345"
PIN = "98765"

def on_connect(client, userdata, flags, rc):
    if rc == 0:
        print("Connected to MQTT broker successfully")
    else:
        print(f"Connection failed with code {rc}")

def publish_location(client, lat, lon, battery=None):
    topic = f"gps/{DEVICE_ID}/location"
    
    payload = {
        "device_id": DEVICE_ID,
        "pin": PIN,
        "latitude": lat,
        "longitude": lon,
        "timestamp": int(time.time() * 1000)
    }
    
    if battery is not None:
        payload["battery_level"] = battery
    
    message = json.dumps(payload)
    result = client.publish(topic, message, qos=1)
    
    if result.rc == mqtt.MQTT_ERR_SUCCESS:
        print(f"Location published: {lat}, {lon}")
    else:
        print(f"Failed to publish location: {result.rc}")

# Create MQTT client
client = mqtt.Client(client_id=f"gps_device_{DEVICE_ID}")
client.username_pw_set(USERNAME, PASSWORD)

# Configure TLS/SSL
client.tls_set(cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2)

# Set callbacks
client.on_connect = on_connect

# Connect to broker
client.connect(BROKER, PORT, 60)
client.loop_start()

# Publish location
time.sleep(1)  # Wait for connection
publish_location(client, 37.7749, -122.4194, battery=85)

# Keep alive
time.sleep(2)
client.loop_stop()
client.disconnect()

Arduino / ESP32

Implementation for ESP32/ESP8266 GPS tracker hardware using PubSubClient library.

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>

// WiFi Configuration
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// MQTT Configuration
const char* mqtt_broker = "q3edf31f.ala.asia-southeast1.emqxsl.com";
const int mqtt_port = 8883;
const char* mqtt_username = "YOUR_USERNAME";  // Request from TripQube
const char* mqtt_password = "YOUR_PASSWORD";  // Request from TripQube

// Device Configuration
const char* device_id = "TRK-ABC-12345";
const char* device_pin = "98765";

WiFiClientSecure espClient;
PubSubClient client(espClient);

void setup_wifi() {
  delay(10);
  Serial.println("Connecting to WiFi...");
  WiFi.begin(ssid, password);
  
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  
  Serial.println("\nWiFi connected");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());
}

void reconnect() {
  while (!client.connected()) {
    Serial.print("Connecting to MQTT broker...");
    
    String clientId = "ESP32_" + String(device_id);
    
    if (client.connect(clientId.c_str(), mqtt_username, mqtt_password)) {
      Serial.println("connected");
    } else {
      Serial.print("failed, rc=");
      Serial.print(client.state());
      Serial.println(" retrying in 5 seconds");
      delay(5000);
    }
  }
}

void publish_location(float lat, float lon, int battery) {
  // Build topic
  String topic = "gps/" + String(device_id) + "/location";
  
  // Create JSON payload
  StaticJsonDocument<256> doc;
  doc["device_id"] = device_id;
  doc["pin"] = device_pin;
  doc["latitude"] = lat;
  doc["longitude"] = lon;
  doc["battery_level"] = battery;
  doc["timestamp"] = millis();
  
  // Serialize JSON
  char buffer[256];
  serializeJson(doc, buffer);
  
  // Publish message
  if (client.publish(topic.c_str(), buffer, true)) {
    Serial.println("Location published successfully");
  } else {
    Serial.println("Failed to publish location");
  }
}

void setup() {
  Serial.begin(115200);
  
  setup_wifi();
  
  // Configure TLS/SSL (skip cert verification for simplicity)
  espClient.setInsecure();
  
  client.setServer(mqtt_broker, mqtt_port);
  
  reconnect();
  
  // Publish test location
  publish_location(37.7749, -122.4194, 85);
}

void loop() {
  if (!client.connected()) {
    reconnect();
  }
  client.loop();
  
  // Publish location every 30 seconds
  static unsigned long lastPublish = 0;
  if (millis() - lastPublish > 30000) {
    // Replace with actual GPS coordinates
    publish_location(37.7749, -122.4194, 85);
    lastPublish = millis();
  }
}

JavaScript/Node.js

Implementation for server-side MQTT clients and Node.js applications.

const mqtt = require('mqtt');
const fs = require('fs');

// MQTT Configuration
const BROKER = 'mqtts://q3edf31f.ala.asia-southeast1.emqxsl.com:8883';
const OPTIONS = {
  username: 'YOUR_USERNAME',  // Request from TripQube
  password: 'YOUR_PASSWORD',  // Request from TripQube
  clientId: `mqtt_gps_${Math.random().toString(16).slice(3)}`,
  clean: true,
  reconnectPeriod: 1000,
  connectTimeout: 30000,
  rejectUnauthorized: true  // Verify SSL certificate
};

const DEVICE_ID = 'TRK-ABC-12345';
const PIN = '98765';

// Connect to MQTT broker
const client = mqtt.connect(BROKER, OPTIONS);

client.on('connect', () => {
  console.log('Connected to MQTT broker');
  
  // Publish test location
  publishLocation(37.7749, -122.4194, 85);
});

client.on('error', (error) => {
  console.error('Connection error:', error);
});

function publishLocation(lat, lon, battery = null) {
  const topic = `gps/${DEVICE_ID}/location`;
  
  const payload = {
    device_id: DEVICE_ID,
    pin: PIN,
    latitude: lat,
    longitude: lon,
    timestamp: Date.now()
  };
  
  if (battery !== null) {
    payload.battery_level = battery;
  }
  
  client.publish(topic, JSON.stringify(payload), { qos: 1 }, (error) => {
    if (error) {
      console.error('Publish error:', error);
    } else {
      console.log(`Location published: ${lat}, ${lon}`);
    }
  });
}

// Publish location every 30 seconds
setInterval(() => {
  // Replace with actual GPS coordinates
  publishLocation(37.7749, -122.4194, 85);
}, 30000);

MicroPython (umqtt)

Lightweight implementation for MicroPython-enabled microcontrollers.

import time
import ujson
from umqtt.simple import MQTTClient
import network

# WiFi Configuration
WIFI_SSID = "YOUR_WIFI_SSID"
WIFI_PASSWORD = "YOUR_WIFI_PASSWORD"

# MQTT Configuration
BROKER = "q3edf31f.ala.asia-southeast1.emqxsl.com"
PORT = 8883
USERNAME = b"YOUR_USERNAME"  # Request from TripQube
PASSWORD = b"YOUR_PASSWORD"  # Request from TripQube

DEVICE_ID = "TRK-ABC-12345"
PIN = "98765"

def connect_wifi():
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    if not wlan.isconnected():
        print('Connecting to WiFi...')
        wlan.connect(WIFI_SSID, WIFI_PASSWORD)
        while not wlan.isconnected():
            time.sleep(1)
    print('WiFi connected:', wlan.ifconfig())

def publish_location(client, lat, lon, battery=None):
    topic = f"gps/{DEVICE_ID}/location".encode()
    
    payload = {
        "device_id": DEVICE_ID,
        "pin": PIN,
        "latitude": lat,
        "longitude": lon,
        "timestamp": int(time.time() * 1000)
    }
    
    if battery is not None:
        payload["battery_level"] = battery
    
    message = ujson.dumps(payload).encode()
    client.publish(topic, message, qos=1)
    print(f"Location published: {lat}, {lon}")

# Connect to WiFi
connect_wifi()

# Create MQTT client
client_id = f"micropython_{DEVICE_ID}".encode()
client = MQTTClient(client_id, BROKER, port=PORT, 
                   user=USERNAME, password=PASSWORD, ssl=True)

# Connect to MQTT broker
print("Connecting to MQTT broker...")
client.connect()
print("Connected to MQTT broker")

# Publish location
publish_location(client, 37.7749, -122.4194, battery=85)

# Cleanup
time.sleep(2)
client.disconnect()

🐛 Troubleshooting

Connection Issues

Device Not Receiving Updates

TLS/SSL Errors

📚 Additional Resources

MQTT Libraries

GPS Modules

Testing Tools

🔒 Security Best Practices

💬 Support & Resources