Sending Data via MQTT

This guide explains how to send production data to OEE Tools using MQTT (Message Queuing Telemetry Transport), a lightweight messaging protocol ideal for real-time data streaming from production equipment.

Overview

MQTT allows you to send production data from your machines, PLCs, or other systems to OEE Tools in real-time. The system automatically processes incoming messages to track production, calculate OEE metrics, and manage production periods.

Getting Started

Prerequisites

Before sending data via MQTT, you need:

1. MQTT Broker Configuration - Your MQTT broker connection details (host, port, username, password)
2. Location Setup - Each production line or station must have an MQTT channel configured
3. MQTT Client - Software or library capable of publishing MQTT messages (available for most programming languages and platforms)

MQTT Topics

Data is sent to specific MQTT topics based on your location's configuration. The topic structure is:

{mqtt_channel}/production

Example: If your location's MQTT channel is oee/factory/line1, you would publish messages to:

oee/factory/line1/production

Note: Contact your administrator to get your location's MQTT channel and broker connection details.

Message Format

Messages must be sent as JSON payloads. Here's the most basic example:

{
  "value": 5
}

This records 5 parts at the current time using default values (good quality, fallback product).

Here's a comprehensive example for a good part:

{
  "product": "PROD001",
  "value": 5,
  "quality": "good",
  "cycle_time": 12.5,
  "recorded_at": 1702900800
}

Here's a comprehensive example for a scrapped part:

{
  "product": "PROD002",
  "value": 1,
  "quality": "scrap",
  "cycle_time": 12.5,
  "recorded_at": 1702900800,
  "reason": "badcut"
}

Message Fields

Field	Type	Description	Required	Default
value	Integer	Number of parts produced	Yes	1
quality	String	Quality status: good, scrap, or rework	No	good
product	String	Product code that identifies what is being produced	No*	-
cycle_time	Float	Cycle time in seconds	No	-
recorded_at	Integer/String	When the part was produced (Unix timestamp or ISO 8601)	No	Current time
reason	String	Scrap reason code (only used when quality is scrap)	No	-

* If product is not provided, the system will attempt to use cycle_time to identify the product. If the product cannot be found, a fallback product will be used.

Quality Values

Value	Description	When to Use
good	Good quality part	Part meets quality standards (default)
scrap	Scrapped part	Part failed quality inspection and cannot be used
rework	Part requiring rework	Part needs additional work to meet standards

Timestamp (recorded_at) Formats

You can specify when a part was produced using either:

Unix timestamp (seconds since epoch):

{
  "recorded_at": 1702900800
}

ISO 8601 datetime string:

{
  "recorded_at": "2024-01-01T10:00:00Z"
}

If you don't provide a timestamp, the system uses the current server time when the message is received.

More Message Examples

Example 1: Recording Good Parts

Send this message when parts are successfully produced:

{
  "product": "WIDGET-A",
  "value": 10,
  "quality": "good",
  "recorded_at": 1702900800
}

This records 10 good parts of product "WIDGET-A" produced at the specified time.

Example 2: Recording Scrap Parts

Send this message when parts fail quality inspection:

{
  "product": "WIDGET-A",
  "value": 2,
  "quality": "scrap",
  "reason": "QUALITY_DEFECT",
  "recorded_at": 1702900800
}

This records 2 scrapped parts with a quality defect reason.

Example 3: Recording Parts with Cycle Time

Include cycle time to help the system calculate production periods:

{
  "product": "WIDGET-B",
  "value": 1,
  "quality": "good",
  "cycle_time": 45.5,
  "recorded_at": 1702900800
}

The system uses the cycle time (45.5 seconds) to determine when production started.

Example 4: Minimal Message

The simplest message you can send:

{
  "product": "WIDGET-A"
}

This records 1 good part of product "WIDGET-A" at the current time.

How It Works

When you send a message via MQTT:

1. Message Received - The system receives your JSON message on the configured topic
2. Location Identified - Your location is identified based on the MQTT topic
3. Product Lookup - The product code is matched to your product catalog
4. Part Recorded - A new part record is created with the quantity and quality information
5. Production Period Updated - The system automatically manages production periods, ending downtime if necessary
6. OEE Calculated - Your OEE metrics are updated in real-time

All timestamps are automatically converted to your configured timezone, and all messages are stored for audit purposes.

Implementation Examples

Python Example

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

# Configure connection
broker = "mqtt.example.com"
port = 1883
username = "your_username"
password = "your_password"
topic = "oee/factory/line1/production"

# Create client
client = mqtt.Client()
client.username_pw_set(username, password)
client.connect(broker, port)

# Send production data
message = {
    "product": "WIDGET-A",
    "value": 5,
    "quality": "good",
    "recorded_at": int(time.time())
}

client.publish(topic, json.dumps(message))
client.disconnect()

Node.js Example

const mqtt = require('mqtt');

// Configure connection
const client = mqtt.connect('mqtt://mqtt.example.com:1883', {
  username: 'your_username',
  password: 'your_password'
});

const topic = 'oee/factory/line1/production';

client.on('connect', () => {
  // Send production data
  const message = {
    product: 'WIDGET-A',
    value: 5,
    quality: 'good',
    timestamp: Math.floor(Date.now() / 1000)
  };
  
  client.publish(topic, JSON.stringify(message));
  client.end();
});

Arduino/ESP32 Example

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

const char* mqtt_server = "mqtt.example.com";
const int mqtt_port = 1883;
const char* mqtt_user = "your_username";
const char* mqtt_password = "your_password";
const char* topic = "oee/factory/line1/production";

WiFiClient espClient;
PubSubClient client(espClient);

void sendProduction() {
  StaticJsonDocument<200> doc;
  doc["product"] = "WIDGET-A";
  doc["value"] = 1;
  doc["quality"] = "good";
  doc["recorded_at"] = millis() / 1000;
  
  char buffer[256];
  serializeJson(doc, buffer);
  
  client.publish(topic, buffer);
}

void setup() {
  client.setServer(mqtt_server, mqtt_port);
  // Connect to WiFi and MQTT...
}

Best Practices

1. Use Accurate Timestamps

Always send the actual production time, not the time you're sending the message. This ensures accurate OEE calculations.

2. Send Messages Promptly

Send messages as soon as parts are produced for real-time monitoring. Avoid batching unless necessary.

3. Use Correct Product Codes

Ensure product codes match exactly what's configured in your system. Product codes are case-sensitive.

4. Handle Connection Failures

Implement retry logic in your MQTT client to handle temporary network issues:

# Example: Python with retry logic
def publish_with_retry(client, topic, message, max_retries=3):
    for attempt in range(max_retries):
        try:
            client.publish(topic, json.dumps(message))
            return True
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(5)  # Wait before retry
            else:
                print(f"Failed to publish after {max_retries} attempts")
                return False

5. Validate Messages Before Sending

Ensure your JSON is valid and contains required fields:

def validate_message(message):
    # Check if product code exists
    if 'product' not in message:
        return False
    
    # Validate quality value
    if 'quality' in message:
        valid_qualities = ['good', 'scrap', 'rework']
        if message['quality'] not in valid_qualities:
            return False
    
    return True

Troubleshooting

Messages Not Appearing in OEE Tools

Check these common issues:

1. Incorrect Topic - Verify you're publishing to the correct MQTT topic for your location
2. Invalid JSON - Ensure your message is valid JSON format
3. Connection Issues - Verify your MQTT broker credentials and network connectivity
4. Product Code Mismatch - Check that the product code exists in your system
5. Timestamp Format - Ensure timestamps are in Unix seconds or ISO 8601 format

Testing Your Connection

Use an MQTT client tool like MQTT Explorer or mosquitto_pub to test your connection:

# Test publishing a message
mosquitto_pub -h mqtt.example.com -p 1883 \
  -u your_username -P your_password \
  -t "oee/factory/line1/production" \
  -m '{"product":"WIDGET-A","value":1,"quality":"good"}'

Getting Help

If you continue to experience issues:

1. Contact your system administrator for connection details
2. Check that your location's MQTT channel is properly configured
3. Verify your MQTT broker is accessible from your network
4. Review the system logs for error messages

Security Considerations

• Use Strong Passwords - Ensure MQTT credentials are secure
• Network Security - Consider using TLS/SSL for MQTT connections in production
• Access Control - Only publish to topics assigned to your locations
• Credential Storage - Never hardcode credentials; use environment variables or secure configuration files