Protocol Integrations

• Overview
• Supported Protocols
  • MQTT Integration
  • HTTP Integration
  • CoAP Integration
  • OPC-UA Integration
  • TCP/UDP Integrations
• Data Converters
  • Uplink Converter
  • Downlink Converter
• Protocol Comparison
• Security Considerations
  • Transport Layer Security
  • Authentication Methods
  • Best Practices
• Deployment Options
  • Embedded Integrations
  • Remote Integrations
• Troubleshooting
  • Connection Issues
  • Data Processing Issues
• Next Steps

Overview

IndustryOS supports a wide range of communication protocols to connect devices, sensors, and industrial equipment. Protocol integrations provide standardised interfaces for data exchange between your devices and the platform.

Supported Protocols

MQTT Integration

MQTT (Message Queuing Telemetry Transport) is a lightweight pub/sub messaging protocol ideal for IoT devices.

Features:

• QoS levels (0, 1, 2) for message delivery guarantees
• Retained messages for last known state
• Last Will and Testament (LWT) for device offline detection
• Topic-based routing with wildcards
• SSL/TLS encryption support

Use Cases:

• Real-time sensor data streaming
• Command and control of remote devices
• Mobile and battery-powered devices
• Unreliable network connections

Configuration Example:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "broker": "tcp://mqtt.example.com:1883",
  "clientId": "industryos-integration",
  "username": "integration-user",
  "password": "***",
  "topics": [
    {
      "topic": "sensors/+/data",
      "qos": 1
    }
  ]
}

HTTP Integration

HTTP integrations support both RESTful APIs and webhook endpoints for device communication.

Features:

• GET/POST/PUT/DELETE method support
• Custom headers for authentication
• JSON and form-encoded payloads
• Synchronous and asynchronous processing
• Batch data upload capabilities

Use Cases:

• Webhook receivers for third-party services
• Polling external APIs for device data
• REST API endpoints for device provisioning
• Integration with web-based services

Webhook Endpoint Example:

1
2
3
4
5
6
7
8
9
POST https://your-instance.industryos.io/api/v1/integrations/http/{integrationKey}
Content-Type: application/json

{
  "deviceId": "sensor-001",
  "temperature": 23.5,
  "humidity": 65.2,
  "timestamp": 1684478801936
}

CoAP Integration

CoAP (Constrained Application Protocol) is designed for resource-constrained devices and networks.

Features:

• UDP-based for minimal overhead
• Observe pattern for subscriptions
• Block-wise transfers for large payloads
• DTLS encryption for security
• Resource discovery mechanisms

Use Cases:

• Battery-powered sensors
• Mesh networks
• Constrained devices with limited resources
• Low-power wide-area networks

OPC-UA Integration

OPC-UA (Open Platform Communications Unified Architecture) is an industrial communication protocol for factory automation.

Features:

• Browse server nodes and discover devices
• Subscribe to data changes with configurable intervals
• Type-safe data model with structured data
• Secure communication with certificates
• Historical data access capabilities

Use Cases:

• Manufacturing equipment integration
• SCADA system connectivity
• Industrial automation networks
• PLCs and industrial controllers

Server Configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "serverUrl": "opc.tcp://plc.factory.local:4840",
  "securityMode": "SignAndEncrypt",
  "identity": {
    "type": "username",
    "username": "opcua-client",
    "password": "***"
  },
  "subscriptions": [
    {
      "nodeId": "ns=2;s=Temperature",
      "samplingInterval": 1000
    }
  ]
}

TCP/UDP Integrations

Raw socket integrations for custom protocols and legacy devices.

TCP Features:

• Connection-oriented reliable delivery
• Binary and text payload support
• Custom framing protocols
• Keep-alive mechanisms

UDP Features:

• Connectionless lightweight messaging
• Broadcast and multicast support
• Minimal latency for time-sensitive data
• Custom packet formats

Use Cases:

• Legacy industrial devices
• Custom proprietary protocols
• GPS trackers and telemetry devices
• Modbus TCP gateways

Data Converters

All protocol integrations use data converters to transform between protocol-specific formats and IndustryOS data model.

Uplink Converter

Transforms incoming protocol data to IndustryOS format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// MQTT Uplink Converter Example
function decodeUplink(input) {
    // input.data contains the MQTT payload
    // input.metadata contains topic, qos, etc.
    
    var data = JSON.parse(input.data);
    var topic = input.metadata.topic;
    
    // Extract device ID from topic: sensors/{deviceId}/data
    var deviceId = topic.split('/')[1];
    
    return {
        deviceName: deviceId,
        deviceType: "MQTTSensor",
        telemetry: {
            temperature: data.temp,
            humidity: data.hum
        },
        attributes: {
            lastUpdateTime: Date.now()
        }
    };
}

Downlink Converter

Transforms IndustryOS commands to protocol-specific format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// MQTT Downlink Converter Example
function encodeDownlink(msg, metadata, msgType) {
    var command = {
        cmd: msg.method,
        params: msg.params,
        timestamp: Date.now()
    };
    
    return {
        contentType: "JSON",
        data: JSON.stringify(command),
        metadata: {
            topic: "commands/" + metadata.deviceName + "/rpc",
            qos: 1,
            retain: false
        }
    };
}

Protocol Comparison

Security Considerations

Transport Layer Security

• TLS/SSL: Encrypt data in transit (MQTT, HTTP, OPC-UA)
• DTLS: Secure CoAP communications
• Certificates: Use X.509 certificates for authentication
• VPN: Secure tunnel for legacy protocols

Authentication Methods

1. Username/Password: Basic authentication
2. API Keys: Token-based access control
3. Certificates: Mutual TLS authentication
4. OAuth2: Delegated authorisation

Best Practices

• Use encrypted protocols in production
• Implement strong authentication
• Rotate credentials regularly
• Monitor for unusual activity
• Apply principle of least privilege
• Keep protocol libraries updated

Deployment Options

Embedded Integrations

Run within the main IndustryOS process:

Pros:

• Simple deployment and configuration
• Minimal latency for message delivery
• Direct access to platform resources

Cons:

• Shares resources with main process
• Lower isolation between components
• Cannot access local networks from cloud deployment

Remote Integrations

Deploy in local networks, stream data to cloud:

Pros:

• Access to local MQTT brokers and OPC-UA servers
• Isolated process with dedicated resources
• Offline buffering capabilities
• Network segregation for security

Cons:

• Requires separate installation
• Additional infrastructure to manage
• More complex deployment process

Troubleshooting

Connection Issues

MQTT:

• Verify broker address and port
• Check authentication credentials
• Confirm topic permissions
• Review firewall rules

HTTP:

• Test endpoint URL accessibility
• Validate API keys and headers
• Check SSL certificate validity
• Review rate limiting settings

OPC-UA:

• Verify server URL and endpoint
• Check security mode compatibility
• Validate certificates
• Confirm node IDs exist

Data Processing Issues

• Enable debug mode for detailed logs
• Test converters with sample data
• Verify JSON syntax in converters
• Check device name and type fields
• Validate telemetry key names

Next Steps

• MQTT Integration Guide
• HTTP Integration Guide
• OPC-UA Integration Guide
• Custom Integrations
• Cloud Platform Integrations