Sparkplug B Integration with Proxus

​

Introduction

This guide provides detailed instructions for implementing Sparkplug B integration in Proxus. Sparkplug B is an industrial IoT-focused MQTT specification that provides standardized approach to MQTT implementation including state management, payload formatting, and topic namespace management.

​

Why Sparkplug B?

• Well-defined Topic Namespace: Structured approach to MQTT topic organization
• State Management: Built-in birth/death certificate handling
• Auto-discovery: Dynamic device and metric discovery capabilities
• Data Type Standardization: Consistent payload formatting
• Bidirectional Communication: Native support for command and control

​

Configuration Parameters

​

Core Connection Parameters

​

Authentication Parameters

​

Protocol Settings

​

WebSocket Configuration

*Required only when UseWebSocket is true

​

TLS Security Configuration

*Required when UseTls is true

​

Advanced Configuration Examples

​

Basic MQTT Configuration

{
  "BrokerHost": "mqtt.example.com",
  "BrokerPort": 1883,
  "GroupId": "Factory1",
  "EdgeNodeId": "Assembly_Line_1",
  "Protocol": "V311"
}

​

Secure WebSocket Configuration

{
  "BrokerHost": "mqtt.example.com",
  "BrokerPort": 443,
  "UseWebSocket": true,
  "WebSocketPath": "/mqtt",
  "UseTls": true,
  "TlsVersion": "Tls12"
}

​

Enterprise Authentication Configuration

{
  "BrokerHost": "mqtt.enterprise.com",
  "UseTls": true,
  "TlsVersion": "Tls13",
  "PfxCertificate": "<base64-certificate>",
  "Username": "enterprise_user",
  "Password": "secure_password"
}

​

Data Type Mapping

​

Automatic Type Detection

The integration automatically detects and maps data types based on the value content:

​

Supported Data Types

​

Topic Structure and Namespace

​

Topic Format

spBv1.0/[group_id]/[message_type]/[edge_node_id]/[device_id]

​

Message Types

​

State Management

​

Node States

​

Device States

​

Error Handling and Troubleshooting

​

Common Connection Issues

​

Debug Logging

Enable detailed logging by configuring the logging level:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Proxus.Shared.Actors.OutboundIntegrations": "Debug"
    }
  }
}

​

Performance Optimization

​

Best Practices

1. Message Rate Control

   • Set appropriate publish rates
   • Use QoS levels wisely
   • Monitor broker performance

2. Resource Management

   • Control payload sizes
   • Manage connection pooling
   • Monitor memory usage

3. Network Optimization

   • Use appropriate QoS levels
   • Implement message batching
   • Consider compression for large payloads

​

Recommended Settings

{
  "PublishRate": "1000ms",
  "BatchSize": 100,
  "QoS": 1,
  "RetainMessages": false,
  "CompressPayload": true
}

​

Security Considerations

​

TLS Implementation

1. Certificate Management

   • Use strong certificates
   • Implement certificate rotation
   • Validate certificate chain

2. Authentication

   • Use strong passwords
   • Implement client certificates
   • Enable access control lists (ACLs)

​

Example Secure Configuration

{
  "UseTls": true,
  "TlsVersion": "Tls13",
  "ValidateCertificate": true,
  "CertificateValidation": {
    "ValidateChain": true,
    "AllowedCertificateAuthorities": ["CA1", "CA2"]
  }
}

​

Monitoring and Metrics

​

Key Performance Indicators

1. Connection Metrics

   • Connection state
   • Reconnection attempts
   • Connection latency

2. Message Metrics

   • Messages sent/received
   • Message latency
   • Error rates

3. Device Metrics

   • Active devices
   • Birth/death events
   • Command response times

​

Example Monitoring Implementation

// Monitoring metrics structure
{
  "connection": {
    "status": "connected",
    "lastConnected": "2025-03-06T12:00:00Z",
    "reconnectAttempts": 0
  },
  "messages": {
    "sent": 1000,
    "received": 950,
    "errors": 2
  },
  "devices": {
    "active": 5,
    "total": 6,
    "birthEvents": 10
  }
}

​

Appendix

​

Example Device Configuration

{
  "device": {
    "id": "Device1",
    "metrics": [
      {
        "name": "temperature",
        "dataType": "Float",
        "properties": {
          "engUnit": "Celsius",
          "min": 0,
          "max": 100
        }
      },
      {
        "name": "status",
        "dataType": "String",
        "properties": {
          "enum": ["Running", "Stopped", "Error"]
        }
      }
    ]
  }
}

​

Complete Integration Example

{
  "integration": {
    "type": "SparkplugB",
    "connection": {
      "brokerHost": "mqtt.company.com",
      "brokerPort": 8883,
      "useTls": true,
      "tlsVersion": "Tls12",
      "useWebSocket": false
    },
    "authentication": {
      "username": "proxus_edge",
      "password": "secure_password"
    },
    "sparkplug": {
      "groupId": "Factory1",
      "edgeNodeId": "Assembly_Line_1",
      "scadaHostId": "MainScada"
    },
    "performance": {
      "publishRate": "1000ms",
      "reconnectInterval": 5,
      "batchSize": 100
    }
  }
}

This comprehensive documentation should provide all necessary information for implementing and maintaining a Sparkplug B integration with Proxus. For additional support or specific use cases, please contact Proxus support.