graphql-ws.md

GraphQL over WebSocket

The live measurement data, generated by e.g. Tibber Pulse or Watty, is served as a GraphQL subscription. The protocol used is described here: GraphQL over WebSocket Protocol

Usage

Since GraphQL subscriptions are handled as streams over a persistent connection (WebSocket), the process for accessing this data is a bit different compared to REST APIs:

1. Connect to the GraphQL subscription endpoint and initialize connection
2. Subscribe to data streamed from the GraphQL subscription endpoint
3. Read data from stream
4. Unsubscribe from data stream and close connection

Connect to endpont and initialize

Step 1 is handled by the function Connect-TibberWebSocket:

$connection = Connect-TibberWebSocket -HomeId '96a14971-525a-4420-aae9-e5aedaa129ff'
Write-Host "New connection created: $($connection.WebSocket.State)"

Subscribe to data stream

To subscribe to the live measurement data stream (step 2) call the function Register-TibberLiveMeasurementSubscription, passing the connection object returned from the previous call:

$subscription = Register-TibberLiveMeasurementSubscription -Connection $connection
Write-Host "New GraphQL subscription created: $($subscription.Id)"

Read data stream

Packages are then read from the stream (step 3) by calling the function Read-TibberWebSocket, providing a callback script block/function.

With inline script block:

Read-TibberWebSocket -Connection $connection -Callback { param($package)
    Write-Host "New package on WebSocket connection: $package"
}

With pre-defined function:

function Write-PackageToHost {
    param (
        [string] $package
    )
    Write-Host "New package on WebSocket connection: $package"
}

Read-TibberWebSocket -Connection $connection -Callback ${function:Write-PackageToHost}

Use -CallbackArgumentList to pass additional arguments to the callback script block/function, positioned after the response:

function Write-PackageToHost {
    param (
        [Object] $Json,
        [string] $With,
        [string] $Additional,
        [int] $Arguments
    )
    Write-Host "New Json document received: $($Json.payload.data | Out-String)"
    Write-Host "$With $Additional $Arguments"
}

Read-TibberWebSocket -Connection $connection -Callback ${function:Write-PackageToHost} -CallbackArgumentList @("Hello", "world!", 2022)

Duration, deadline, or max package count

To limit the time we read from the WebSocket, provide the -DurationInSeconds, -ReadUntil and/or the -PackageCount parameters:

$result = Read-TibberWebSocket -Connection $connection -Callback ${function:Write-PackageToHost} -DurationInSeconds 30
Write-Host "Read $($result.NumberOfPackages) package(s) in $($result.ElapsedTimeInSeconds) seconds"

$result = Read-TibberWebSocket -Connection $connection -Callback ${function:Write-PackageToHost} -ReadUntil ([DateTime]::Now).AddSeconds(20)
Write-Host "Read $($result.NumberOfPackages) package(s) in $($result.ElapsedTimeInSeconds) seconds"

$result = Read-TibberWebSocket -Connection $connection -Callback ${function:Write-PackageToHost} -PackageCount 3
Write-Host "Read $($result.NumberOfPackages) package(s) in $($result.ElapsedTimeInSeconds) seconds"

Note

If more than one of -DurationInSeconds, -ReadUntil, or -PackageCount are provided the function will return as soon as the first of these limits are hit.

Unsubscribe and close connection

Step 4 is done by unsubscribing from the data stream using Unregister-TibberLiveMeasurementSubscription and closing the WebSocket connection using Disconnect-TibberWebSocket:

Unregister-TibberLiveMeasurementSubscription -Connection $connection -Subscription $subscription
Write-Host "New GraphQL subscription with Id $($subscription.Id) stopped"

Disconnect-TibberWebSocket -Connection $connection

Example

Complete example of reading live measurement data for 30 seconds and gracefully closing the connection when done:

function Write-PackageToHost {
    param (
        [Object] $Json
    )
    Write-Host "New Json document received: $($Json.payload.data | Out-String)"
}

# Get the home Id
$response = Get-TibberHome -Fields 'id', 'appNickname'
$homeId = ($response | Where-Object { $_.appNickname -eq 'Vitahuset' }).id

# Connect WebSocket and register a subscription
$connection = Connect-TibberWebSocket -HomeId $homeId
$subscription = Register-TibberLiveMeasurementSubscription -Connection $connection

# Read data stream
$result = Read-TibberWebSocket -Connection $connection -Callback ${function:Write-PackageToHost} -DurationInSeconds 30
Write-Host "Read $($result.NumberOfPackages) package(s) in $($result.ElapsedTimeInSeconds) seconds"

# Unregister subscription and close down the WebSocket connection
Unregister-TibberLiveMeasurementSubscription -Connection $connection -Subscription $subscription
Disconnect-TibberWebSocket -Connection $connection

Timeouts for WebSocket operations

All above functions have a parameter named -TimeoutInSeconds, representing the time to wait for WebSocket operations, or -1 to wait indefinitely. Use this parameter to adjust the timeouts depending on your network environment.