Payloads

OpenADR 3 request payloads supported by the Switchmakret OpenADR VTN.

Limit Request Event Payload

Example of the request payload for limit request event sent by the VTN.

{
    // Unique ID of the event
    "id": "1",
    // Human readable name that can be used for debugging
    "eventName": "powerLimit",
    "objectType": "EVENT",
    "programID": "1",
    // The duration of the event
    "intervalPeriod": {
        "start": "2023-10-20T12:00:00Z",
        "duration": "PT15M" // 15 minutes specified in ISO 8601
    },
    "reportDescriptors": [
        // If an acknowledgement report is requested here it should be sent
        // as soon as the event is received.
        {
            "payloadType": "POWER_LIMIT_ACKNOWLEDGEMENT",
            "startInterval": 0,
            "historical": false
        }
    ],
    "payloadDescriptors": [
        {
            // For a production resource this will be "PRODUCTION_POWER_LIMIT" instead
            "payloadType": "CONSUMPTION_POWER_LIMIT",
            // Specifies the unit of the power limit (always KW).
            "units": "KW"
        },
        {
            "payloadType": "POWER_LIMIT_VERSION"
        },
        // The three payloads below will not be present until validation has occurred!
        {
            "payloadType": "POWER_LIMIT_VALIDATION_STATUS"
        },
        {
            "payloadType": "POWER_LIMIT_VALIDATION_TIMESTAMP"
        },
        {
            "payloadType": "POWER_LIMIT_VALIDATION_READING",
            // Specifies the unit of the power limit (always KW).
            "units": "KW"
        }
    ],
    "intervals": [{
        // Sequential ID for the interval. Will always be 0 since there will only be one interval.
        "id": 0,
        "payloads": [
            {
                // For a production asset this will be "PRODUCTION_POWER_LIMIT" instead
                "type": "CONSUMPTION_POWER_LIMIT",
                // The actual power limit - 15 000 KW
                "values": [15000]
            },
            {
                "type": "POWER_LIMIT_VERSION",
                // The version of the limit.
                // In case the limit (CONSUMPTION_POWER_LIMIT or PRODUCTION_POWER_LIMIT) is updated
                // after the creation of the event, this value will be incremented. Note that only
                // if the resource is configured to support dynamic limits can the limit change,
                // otherwise both the limit and this value will be static after the event has been created.                
                "values": [1]
            }
            // The three payloads below will not be present until validation has occurred!
            {
                "type": "POWER_LIMIT_VALIDATION_STATUS",
                // Status of the validation. Possible values:
                // - ok: validation succeeded (resource was below limit)
                // - not_ok: validation failed (resource was above limit)
                // - unable_to_validate: validation could not run, e.g due to missing readings or a bad configuration
                "values": ["ok"]
            },
            {
                "type": "POWER_LIMIT_VALIDATION_STATUS_TEXT",
                // Human readable explanation  of the status for debugging purposes.
                "values": ["Validation succeeded."]
            },
            {
                "type": "POWER_LIMIT_VALIDATION_TIMESTAMP",
                // The time & date when the validation was run.
                "values": ["2023-10-20T12:25:00Z"]
            },
            {
                "type": "POWER_LIMIT_VALIDATION_READING",
                // The reading value that was used for validation. Might be an average of several readings.
                "values": [14000]
            }
        ]
    }],
    "targets": [
        {
            "type": "RESOURCE_NAME",
            // Corresponds to the SWITCH resource ID.
            // This is the resource for which the power limit should be applied to.
            "values": ["1"]
        },
        {
            "type": "ORGANIZATION_ID",
            // Corresponds to the SWITCH organization ID.
            // For the FSP this is your own organization ID.
            "values": ["1"]
        }
    ]
}

Acknowledgement Report Payload

Example of the acknowledgement report request payload sent by VEN.

The first time a particular event is received, or if a previously received event is received again but with an incremented POWER_LIMIT_VERSION, the client should immediately respond with the report below to indicate that they have received the event.

You should not send multiple acknowledgements to the same event unless the POWER_LIMIT_VERSION has increased.

Do not send acknowledgements to events which do not contain the POWER_LIMIT_ACKNOWLEDGEMENT report descriptor. Such events target resources which have been configured to not use acknowledgements.

{
    // The ID of the event which was just received
    "eventID": "1",
    // Should be the same as the events program ID
    "programID": "1",
    // SWITCH is not using this field for anything, but it's required by the specification.
    // Can be set to a descriptive name for your integration (for debugging purposes).
    "clientName": "<client name>",
    "payloadDescriptors": [{
        "payloadType": "POWER_LIMIT_ACKNOWLEDGEMENT"
    }],
    "resources": [{
        // The resource for which the power limit has been applied to (see RESOURCE_NAME in the event payload).
        "resourceName": "1",
        // Needs to be the same as the interval period for the event.
        "intervalPeriod": {
            "start": "2023-10-20T12:00:00Z",
            "duration": "PT15M"
        },
        "intervals": [{
            // Sequential ID for the interval. Should always be 0 since there will only be one interval.
            "id": 0,
            "payloads": [{
                "type": "POWER_LIMIT_ACKNOWLEDGEMENT",
                // The version of the power limit which the acknowledgement is intended for.
                // Only the latest version can be acknowledged.
                // See POWER_LIMIT_VERSION in the event payload.
                "values": [1]
            }]
        }]
    }]
}