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
Parameter Description Default Required Example BrokerHost MQTT broker hostname or IP address localhost Yes ”mqtt.company.com” BrokerPort MQTT broker port number 1883 No 1883 GroupId Logical grouping of Edge nodes ProxusGroup No ”Plant1” EdgeNodeId Unique identifier for the Edge node Edge_ No ”Edge_Production” ScadaHostIdentifier Primary application identifier scada1 No ”mainScada”
Authentication Parameters
Parameter Description Default Required Example Username MQTT broker username - No ”proxus_user” Password MQTT broker password - No ”secure_password”
Protocol Settings
Parameter Description Default Options Example Protocol MQTT protocol version V311 V310, V311, V500 ”V311” ReconnectInterval Time between reconnection attempts (seconds) 5 1-3600 ”30”
WebSocket Configuration
Parameter Description Default Required Example UseWebSocket Enable WebSocket transport false No true WebSocketPath WebSocket endpoint path /mqtt No* “/ws”
*Required only when UseWebSocket is true
TLS Security Configuration
Parameter Description Default Required Example UseTls Enable TLS encryption false No true TlsVersion TLS protocol version Tls12 No ”Tls13” PfxCertificate Base64 encoded PFX certificate - No* “MIIKYwIBA…” ValidateCertificate Enable certificate validation true No false
*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:
Value Pattern Sparkplug B Type Example true/false Boolean true Integer numbers Int32 42 Decimal numbers Float/Double 23.5 Date strings DateTime ”2025-03-06T12:00:00Z” Other strings String ”Running”
Supported Data Types
Int16: 16-bit signed integer (-32,768 to 32,767)
UInt16: 16-bit unsigned integer (0 to 65,535)
Int32: 32-bit signed integer (-2^31 to 2^31-1)
UInt32: 32-bit unsigned integer (0 to 2^32-1)
Int64: 64-bit signed integer (-2^63 to 2^63-1)
UInt64: 64-bit unsigned integer (0 to 2^64-1)
Float: 32-bit floating point
Double: 64-bit floating point
Boolean: true/false values
String: Text data
DateTime: Timestamp values
Bytes: Binary data
Topic Structure and Namespace
spBv1.0/[group_id]/[message_type]/[edge_node_id]/[device_id]
Message Types
Type Description Direction Example NBIRTH Node birth certificate Node → Server spBv1.0/Factory1/NBIRTH/Edge_01 NDEATH Node death certificate Node → Server spBv1.0/Factory1/NDEATH/Edge_01 DBIRTH Device birth certificate Node → Server spBv1.0/Factory1/DBIRTH/Edge_01/Device1 DDEATH Device death certificate Node → Server spBv1.0/Factory1/DDEATH/Edge_01/Device1 NDATA Node data Node → Server spBv1.0/Factory1/NDATA/Edge_01 DDATA Device data Node → Server spBv1.0/Factory1/DDATA/Edge_01/Device1 NCMD Node command Server → Node spBv1.0/Factory1/NCMD/Edge_01 DCMD Device command Server → Node spBv1.0/Factory1/DCMD/Edge_01/Device1
State Management
Node States
Device States
Error Handling and Troubleshooting
Common Connection Issues
Error Possible Causes Solutions Connection Refused - Invalid credentials - Wrong port - Broker offline - Verify credentials - Check broker status - Confirm port number TLS Handshake Failed - Invalid certificate - Wrong TLS version - Validate certificate - Check TLS version compatibility Topic Permission Error - Insufficient permissions - Wrong topic structure - Verify ACL settings - Check topic format
Debug Logging
Enable detailed logging by configuring the logging level:
{
"Logging" : {
"LogLevel" : {
"Default" : "Information" ,
"Proxus.Shared.Actors.OutboundIntegrations" : "Debug"
}
}
}
Best Practices
Message Rate Control
Set appropriate publish rates
Use QoS levels wisely
Monitor broker performance
Resource Management
Control payload sizes
Manage connection pooling
Monitor memory usage
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
Certificate Management
Use strong certificates
Implement certificate rotation
Validate certificate chain
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
Connection Metrics
Connection state
Reconnection attempts
Connection latency
Message Metrics
Messages sent/received
Message latency
Error rates
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.