MQTTnet/Source/MQTTnet.PowerShell

MQTTnet PowerShell Module

A PowerShell module for MQTTnet that provides cmdlets for MQTT communication in PowerShell.

Features

• Full MQTT Protocol Support: Connect, subscribe, publish, and manage MQTT connections
• TCP and WebSocket Transports: Support for both TCP and WebSocket connections
• TLS/SSL Support: Secure connections with TLS encryption
• Async Message Handling: Register PowerShell ScriptBlocks as message handlers
• Advanced MQTT Features:
  • Quality of Service (QoS) levels 0, 1, and 2
  • Retained messages
  • Last Will and Testament (LWT)
  • User properties
  • Message expiry intervals
  • Response topics

Installation

1. Build the MQTTnet.PowerShell project:

   dotnet build Source/MQTTnet.PowerShell/MQTTnet.PowerShell.csproj
   

2. Import the module:

   Import-Module ./Source/MQTTnet.PowerShell/bin/Debug/net8.0/MQTTnet.PowerShell.dll
   

Quick Start

Basic Connection and Publish

# Create a new MQTT session
$session = New-MqttSession

# Connect to a broker
Connect-MqttSession -Session $session -Host "broker.hivemq.com" -Port 1883

# Publish a message
Publish-MqttMessage -Session $session -Topic "test/topic" -Payload "Hello MQTT!"

# Disconnect and cleanup
Disconnect-MqttSession -Session $session
Remove-MqttSession -Session $session

Subscribe and Receive Messages

$session = New-MqttSession
Connect-MqttSession -Session $session -Host "broker.hivemq.com"

# Subscribe to a topic
Subscribe-MqttTopic -Session $session -Topic "test/demo"

# Wait for a message (with timeout)
$message = Receive-MqttMessage -Session $session -TimeoutSeconds 30
Write-Host "Received: $($message.Payload)"

Disconnect-MqttSession -Session $session
Remove-MqttSession -Session $session

Async Message Handler

$session = New-MqttSession
Connect-MqttSession -Session $session -Host "broker.hivemq.com"

Subscribe-MqttTopic -Session $session -Topic "test/#"

# Register a message handler
Register-MqttMessageHandler -Session $session -Action {
    param($topic, $payload, $message)
    Write-Host "Message on $topic : $payload"
    Write-Host "QoS: $($message.QoS), Retain: $($message.Retain)"
}

# Messages will be handled asynchronously
Start-Sleep -Seconds 60

Disconnect-MqttSession -Session $session
Remove-MqttSession -Session $session

Available Cmdlets

Help and Examples

Show-MqttExamples

Displays quick examples for common MQTT tasks.

Show-MqttExamples

Session Management

New-MqttSession

Creates a new MQTT session.

$session = New-MqttSession

Connect-MqttSession

Connects to an MQTT broker with various options.

TCP Connection:

Connect-MqttSession -Session $session -Host "broker.hivemq.com" -Port 1883

TCP with TLS:

Connect-MqttSession -Session $session -Host "broker.hivemq.com" -Port 8883 `
    -UseTls -AllowUntrustedCertificates

WebSocket Connection:

Connect-MqttSession -Session $session -WebSocketUri "broker.hivemq.com:8000/mqtt"

With Authentication:

Connect-MqttSession -Session $session -Host "broker.hivemq.com" `
    -Username "user" -Password "pass"

With Last Will and Testament:

Connect-MqttSession -Session $session -Host "broker.hivemq.com" `
    -WillTopic "status/client" -WillPayload "Offline" -WillQoS 1 -WillRetain

Parameters:

• Session: The MQTT session (mandatory)
• Host: Broker hostname (for TCP)
• Port: Broker port (default: 1883)
• WebSocketUri: WebSocket URI (for WebSocket connections)
• Username: Username for authentication
• Password: Password for authentication
• ClientId: Client identifier (auto-generated if not specified)
• CleanSession: Use clean session (default: true)
• UseTls: Enable TLS encryption
• AllowUntrustedCertificates: Allow untrusted certificates
• KeepAlivePeriod: Keep-alive period in seconds (default: 15)
• Timeout: Connection timeout in seconds (default: 10)
• WillTopic: Last Will topic
• WillPayload: Last Will payload
• WillQoS: Last Will QoS level (0-2)
• WillRetain: Retain Last Will message

Get-MqttSessionStatus

Gets the current status of the MQTT session.

$status = Get-MqttSessionStatus -Session $session
Write-Host "Connected: $($status.IsConnected)"

Disconnect-MqttSession

Disconnects from the MQTT broker.

Disconnect-MqttSession -Session $session

Parameters:

• Session: The MQTT session (mandatory)
• Reason: Disconnect reason code
• ReasonString: Human-readable reason
• SessionExpiryInterval: Session expiry interval

Remove-MqttSession

Disposes the MQTT session and releases resources.

Remove-MqttSession -Session $session

Test-MqttConnection

Tests if the MQTT connection is alive by sending a PING packet.

$isAlive = Test-MqttConnection -Session $session -TimeoutSeconds 5
Write-Host "Connection is alive: $isAlive"

Parameters:

• Session: The MQTT session (mandatory)
• TimeoutSeconds: Timeout for the ping operation (default: 5)

Publishing

Publish-MqttMessage

Publishes a message to a topic.

Basic:

Publish-MqttMessage -Session $session -Topic "test/topic" -Payload "Hello"

With QoS and Retain:

Publish-MqttMessage -Session $session -Topic "test/topic" -Payload "Hello" `
    -QoS 1 -Retain

With User Properties:

$props = @{
    "source" = "PowerShell"
    "version" = "1.0"
}
Publish-MqttMessage -Session $session -Topic "test/topic" -Payload "Hello" `
    -UserProperties $props

Parameters:

• Session: The MQTT session (mandatory)
• Topic: Topic to publish to (mandatory)
• Payload: Message payload (mandatory)
• QoS: Quality of Service level (0-2, default: 0)
• Retain: Retain flag
• ContentType: Content type of the payload
• ResponseTopic: Response topic for request/response pattern
• UserProperties: Hashtable of user properties
• TopicAlias: Topic alias
• MessageExpiryInterval: Message expiry interval in seconds

Subscribing

Subscribe-MqttTopic

Subscribes to a topic.

Subscribe-MqttTopic -Session $session -Topic "test/demo" -QoS 1

Parameters:

• Session: The MQTT session (mandatory)
• Topic: Topic filter to subscribe to (mandatory)
• QoS: Quality of Service level (0-2, default: 0)
• NoLocal: No local flag
• RetainAsPublished: Retain as published flag
• RetainHandling: Retain handling option
• SubscriptionIdentifier: Subscription identifier

Unsubscribe-MqttTopic

Unsubscribes from a topic.

Unsubscribe-MqttTopic -Session $session -Topic "test/demo"

Message Handling

Receive-MqttMessage

Waits for and receives a single message.

# Wait indefinitely
$message = Receive-MqttMessage -Session $session

# Wait with timeout
$message = Receive-MqttMessage -Session $session -TimeoutSeconds 30

Parameters:

• Session: The MQTT session (mandatory)
• TimeoutSeconds: Timeout in seconds (0 = no timeout)

Register-MqttMessageHandler

Registers an asynchronous message handler using a PowerShell ScriptBlock.

Register-MqttMessageHandler -Session $session -Action {
    param($topic, $payload, $message)
    
    Write-Host "Topic: $topic"
    Write-Host "Payload: $payload"
    Write-Host "QoS: $($message.QoS)"
    
    # Access full message properties
    if ($message.UserProperties) {
        foreach ($prop in $message.UserProperties) {
            Write-Host "Property: $($prop.Name) = $($prop.Value)"
        }
    }
}

The ScriptBlock receives three parameters:

1. $topic: The message topic (string)
2. $payload: The message payload as UTF-8 string
3. $message: The full message object with properties:
   • Topic: Message topic
   • Payload: Payload as string
   • RawPayload: Payload as byte array
   • QoS: Quality of Service level
   • Retain: Retain flag
   • ContentType: Content type
   • ResponseTopic: Response topic
   • UserProperties: List of user properties

Parameters:

• Session: The MQTT session (mandatory)
• Action: ScriptBlock to execute for each message (mandatory)

Unregister-MqttMessageHandler

Removes all registered message handlers.

Unregister-MqttMessageHandler -Session $session

Advanced Examples

Request-Response Pattern

$session = New-MqttSession
Connect-MqttSession -Session $session -Host "broker.hivemq.com"

# Responder
Subscribe-MqttTopic -Session $session -Topic "request/topic"
Register-MqttMessageHandler -Session $session -Action {
    param($topic, $payload, $message)
    if ($message.ResponseTopic) {
        $response = "Response to: $payload"
        Publish-MqttMessage -Session $session -Topic $message.ResponseTopic `
            -Payload $response
    }
}

# Requestor (in another session)
$responseSession = New-MqttSession
Connect-MqttSession -Session $responseSession -Host "broker.hivemq.com"
Subscribe-MqttTopic -Session $responseSession -Topic "response/topic"
Publish-MqttMessage -Session $responseSession -Topic "request/topic" `
    -Payload "Request data" -ResponseTopic "response/topic"

# Wait for response
$response = Receive-MqttMessage -Session $responseSession -TimeoutSeconds 10

High QoS Publishing

# Publish with QoS 2 (exactly once delivery)
$result = Publish-MqttMessage -Session $session -Topic "critical/data" `
    -Payload "Important data" -QoS 2

Write-Host "Publish result: $($result.ReasonCode)"

Error Handling in Message Handler

Register-MqttMessageHandler -Session $session -Action {
    param($topic, $payload, $message)
    try {
        # Process message
        $data = ConvertFrom-Json $payload
        # Do something with data
    }
    catch {
        Write-Host "Error processing message: $_" -ForegroundColor Red
    }
}

Tips and Best Practices

1. Always disconnect cleanly: Use Disconnect-MqttSession before Remove-MqttSession
2. Use appropriate QoS levels: QoS 0 for best performance, QoS 1 for reliability, QoS 2 for critical data
3. Handle errors in message handlers: Wrap handler code in try-catch blocks
4. Use meaningful client IDs: Set custom client IDs for debugging
5. Secure connections: Use TLS for production environments
6. Topic design: Use hierarchical topic structures like device/sensor/temperature
7. Clean session: Use -CleanSession:$false to maintain subscriptions across reconnects

Requirements

• .NET 8.0 or later
• PowerShell 7.0 or later
• MQTTnet library

License

This project is licensed under the MIT License - see the LICENSE file in the repository root for details.