Digi Device Cloud Smart Energy ConnectPort X2e and ERT Documentation

Table Of Contents

SE Interface

The Smart Energy RPC interface is divided into two classes, RPC_SE_Server_Interface for server commands and RPC_SE_Client_Interface for client commands. Generally, the server interface interacts with local SE server clusters, while the client interface interacts with local SE client clusters. Some methods are shared between both classes. For example, both interfaces can interact with an SE Metering cluster, which will only have a client instantiated locally. Note that it is legal for both interfaces to be instantiated on the local device simultaneously if necessary.

SE clusters are also ZCL clusters, and as such can also be interacted with using the RPC_ZCL_Interface class. For example, attributes can be read from an SE Metering server using the read_attributes command.

SE Server Interface

create_DRLC_event

Creates a new DRLC event based on the given event record. The event will be stored on the local DRLC server and also will be immediately sent to all known DRLC client devices.

This command requires the local device to have a DRLC cluster server instantiated on an endpoint.

Request Parameters

Parameter Type Description
record LoadControlEventRecord Record describing the new DRLC event.
source_endpoint_id* int

8-bit identifier of the endpoint containing the DRLC server cluster which will host the new event.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the DRLC server cluster which hosted the new event.
cluster_id int 16-bit identifier of the DRLC server cluster.
status int The ZCL status code associated with the creation of the event.
record LoadControlEventRecord Record describing the new DRLC event.
device_list* list The list of 64-bit extended addresses of client devices to which the event was sent. List items will be of type MAC. Only included if status is success (0).

Example

<create_DRLC_event>
    <record type="LoadControlEventRecord">
        <issuer_event_id>0x1234</issuer_event_id>
        <device_class>0x0FFF</device_class>
        <utility_enrollment_group>0x00</utility_enrollment_group>
        <start_time>0</start_time>
        <duration_in_minutes>0x100</duration_in_minutes>
        <criticality_level>0x01</criticality_level>
        <cooling_temperature_offset>0xFF</cooling_temperature_offset>
        <heating_temperature_offset>0xFF</heating_temperature_offset>
        <duty_cycle>0xFF</duty_cycle>
        <event_control>0x03</event_control>
    </record>
</create_DRLC_event>

<create_DRLC_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="LoadControlEventRecord">
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <device_class type="int">0xFFF</device_class>
        <utility_enrollment_group type="int">0x0</utility_enrollment_group>
        <start_time type="int">0x0</start_time>
        <duration_in_minutes>0x100</duration_in_minutes>
        <criticality_level type="int">0x01</criticality_level>
        <cooling_temperature_offset type="int">0xFF</cooling_temperature_offset>
        <heating_temperature_offset type="int">0xFF</heating_temperature_offset>
        <duty_cycle type="int">0xFF</duty_cycle>
        <event_control type="int">0x3</event_control>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</create_DRLC_event_response>

cancel_DRLC_event

Cancels a DRLC event based on the given record. The cancellation will be immediately sent to all known DRLC client devices. Also, the event will be removed from the local DRLC server unless the cancel record specifies an effective time in the future, in which case the event will be removed once the effective time is reached.

This command requires the local device to have a DRLC cluster server instantiated on an endpoint.

Note

The device_class bitmap in the record must specify a superset of the device_class bitmap of the original event which is being cancelled. For example, if the original event has a device_class setting of 0x00FF and the cancel has a device_class setting of 0x000F, the cancel will be rejected. Additionally, unless the cancel record has a utility enrollment group of 0 (any group), the enrollment group of the cancel record must match the enrollment group of the original event.

Request Parameters

Parameter Type Description
record CancelLoadControlEventRecord Record describing the cancellation.
source_endpoint_id* int

8-bit identifier of the endpoint containing the DRLC server cluster which will cancel the event.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the DRLC server cluster which cancelled the event.
cluster_id int 16-bit identifier of the DRLC server cluster.
status int The ZCL status code associated with the cancellation of the event.
record CancelLoadControlEventRecord Record describing the cancellation.
device_list* list The list of 64-bit extended addresses of client devices to which the cancel was sent. List items will be of type MAC. Only included if status is success (0).

Example

<cancel_DRLC_event>
    <record type="CancelLoadControlEventRecord">
        <issuer_event_id>0x1234</issuer_event_id>
        <device_class>0x0FFF</device_class>
        <utility_enrollment_group>0x00</utility_enrollment_group>
        <cancel_control>0x01</cancel_control>
    </record>
</cancel_DRLC_event>

<cancel_DRLC_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="CancelLoadControlEventRecord">
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <device_class type="int">0xFFF</device_class>
        <utility_enrollment_group type="int">0x0</utility_enrollment_group>
        <cancel_control type="int">0x1</cancel_control>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</cancel_DRLC_event_response>

cancel_all_DRLC_events

Cancels all DRLC events. The cancellation will be immediately sent to all known DRLC client devices. Also, the events will be removed from the local DRLC server.

This command requires the local device to have a DRLC cluster server instantiated on an endpoint.

Request Parameters

Parameter Type Description
record CancelAllLoadControlEventsRecord Record describing the cancellation.
source_endpoint_id* int

8-bit identifier of the endpoint containing the DRLC server cluster which will cancel the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the DRLC server cluster which cancelled the events.
cluster_id int 16-bit identifier of the DRLC server cluster.
status int The ZCL status code associated with the cancellation of the event.
record CancelAllLoadControlEventsRecord Record describing the cancellation.
device_list* list The list of 64-bit extended addresses of client devices to which the cancel was sent. List items will be of type MAC. Only included if status is success (0).

Example

<cancel_all_DRLC_events>
    <record type="CancelLoadControlEventRecord">
        <cancel_control>0x01</cancel_control>
    </record>
</cancel_all_DRLC_events>

<cancel_all_DRLC_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="CancelLoadControlEventRecord">
        <cancel_control>0x1</cancel_control>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</cancel_all_DRLC_events_response>

received_report_event_status*

Response only. Generated when a DRLC client device sends a Report Event Status message to the local DRLC server.

This response will only be generated if the local device has a DRLC cluster server instantiated on an endpoint.

Note

The non-repudiation signature contained in the record parameter of this response is not checked for validity by the framework.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
record ReportEventStatusRecord Record describing the event status report.

Example

<received_report_event_status>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <record type="ReportEventStatusRecord">
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <event_status type="int">0x2</event_status>
        <event_status_time type="int">0x12345678</event_status_time>
        <criticality_level_applied type="int">0x1</criticality_level_applied>
        <cooling_temperature_set_point_applied type="int">0x8000</cooling_temperature_set_point_applied>
        <heating_temperature_set_point_applied type="int">0x8000</heating_temperature_set_point_applied>
        <average_load_adjustment_percentage_applied type="int">-0x80</average_load_adjustment_percentage_applied>
        <duty_cycle_applied type="int">0xFF</duty_cycle_applied>
        <event_control type="int">0x3</event_control>
        <signature_type type="int">0x1</signature_type>
        <signature type="base16">000000000000000000000000000000000000000000000000000000000000000000000000000000000000</signature>
    </record>
</received_report_event_status>

create_message_event

Creates a new Message event based on the given event record. The event will be stored on the local Messaging server and also will be immediately sent to all known Messaging client devices.

This command requires the local device to have a Messaging cluster server instantiated on an endpoint.

Request Parameters

Parameter Type Description
record DisplayMessageRecord Record describing the new Messaging event.
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging server cluster which will host the new event.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Messaging server cluster which hosted the new event.
cluster_id int 16-bit identifier of the Messaging server cluster.
status int The ZCL status code associated with the creation of the event.
record DisplayMessageRecord Record describing the new Messaging event.
device_list* list The list of 64-bit extended addresses of client devices to which the event was sent. List items will be of type MAC. Only included if status is success (0).

Example

<create_message_event>
    <record type="DisplayMessageRecord">
        <message_id>0x1234</message_id>
        <message_control>0x80</message_control>
        <start_time>0</start_time>
        <duration_in_minutes>0x100</duration_in_minutes>
        <message type="string">Please confirm this message.</message>
    </record>
</create_message_event>

<create_message_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <record type="DisplayMessageRecord">
        <message_id type="int">0x1234</message_id>
        <message_control type="int">0x80</message_control>
        <start_time type="int">0</start_time>
        <duration_in_minutes type="int">0x100</duration_in_minutes>
        <message type="string">Please confirm this message.</message>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</create_message_event_response>

cancel_message_event

Cancels a Message event based on the given record. The cancellation will be immediately sent to all known Messaging client devices. Also, the event will be removed from the local Messaging server.

This command requires the local device to have a Messaging cluster server instantiated on an endpoint.

Request Parameters

Parameter Type Description
record CancelMessageRecord Record describing the cancellation.
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging server cluster which will cancel the event.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Messaging server cluster which cancelled the event.
cluster_id int 16-bit identifier of the Messaging server cluster.
status int The ZCL status code associated with the cancellation of the event.
record CancelMessageRecord Record describing the cancellation.
device_list* list The list of 64-bit extended addresses of client devices to which the cancel was sent. List items will be of type MAC. Only included if status is success (0).

Example

<cancel_message_event>
    <record type="CancelMessageRecord">
        <message_id>0x1234</message_id>
    </record>
</cancel_message_event>

<cancel_message_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <record type="CancelMessageRecord">
        <message_id type="int">0x1234</message_id>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</cancel_message_event_response>

cancel_all_message_events

Cancels all Message events known by the Messaging server. These events will also be removed from the server.

This command requires the local device to have a Messaging cluster server instantiated on an endpoint.

Note

There is no mechanism in the SE specification to cancel all message events with a single command. Message cancellations are sent by the server individually.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging server cluster which will cancel the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Messaging server cluster which cancelled the events.
cluster_id int 16-bit identifier of the Messaging server cluster.
status int The ZCL status code associated with the cancellation of the events.
device_list* list The list of 64-bit extended addresses of client devices to which the cancel was sent. List items will be of type MAC. Only included if status is success (0).

Example

<cancel_all_message_events/>

<cancel_all_message_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</cancel_all_message_events_response>

received_message_confirmation*

Response only. Generated when a Messaging client device sends a message confirmation to the local Messaging server.

This response will only be generated if the local device has a Messaging cluster server instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
record MessageConfirmationRecord Record describing the Message confirmation.

Example

<received_message_confirmation>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <record type="MessageConfirmationRecord">
        <message_id type="int">0x1234</message_id>
        <confirmation_time type="int">0x12345678</confirmation_time>
    </record>
</received_message_confirmation>

create_price_event

Creates a new Price event based on the given event record. The event will be stored on the local Price server and also will be immediately sent to all known Price client devices.

This command requires the local device to have a Price cluster server instantiated on an endpoint.

Request Parameters

Parameter Type Description
record PublishPriceRecord Record describing the new Price event.
source_endpoint_id* int

8-bit identifier of the endpoint containing the Price server cluster which will host the new event.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Price server cluster which hosted the new event.
cluster_id int 16-bit identifier of the Price server cluster.
status int The ZCL status code associated with the creation of the event.
record PublishPriceRecord Record describing the new Price event.
device_list* list The list of 64-bit extended addresses of client devices to which the event was sent. List items will be of type MAC. Only included if status is success (0).

Example

<create_price_event>
    <record type="PublishPriceRecord">
        <provider_id>0x12345678</provider_id>
        <rate_label type="string">SamplePrice</rate_label>
        <issuer_event_id>0x1234</issuer_event_id>
        <start_time>0</start_time>
        <price>0x78</price>
        <price_trailing_digit_and_price_tier>0x33</price_trailing_digit_and_price_tier>
        <number_of_price_tiers_and_register_tier>0x43</number_of_price_tiers_and_register_tier>
        <duration_in_minutes>0x100</duration_in_minutes>
    </record>
</create_price_event>

<create_price_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <status type="int">0x0</status>
    <record type="PublishPriceRecord">
        <provider_id type="int">0x12345678</provider_id>
        <rate_label type="string">SamplePrice</rate_label>
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <start_time type="int">0x0</start_time>
        <price type="int">0x78</price>
        <price_trailing_digit_and_price_tier type="int">0x33</price_trailing_digit_and_price_tier>
        <number_of_price_tiers_and_register_tier type="int">0x43</number_of_price_tiers_and_register_tier>
        <duration_in_minutes type="int">0x100</duration_in_minutes>
        <unit_of_measure type="int">0x0</unit_of_measure>
        <currency type="int">0x348</currency>
        <price_ratio type="int">0xFF</price_ratio>
        <generation_price type="int">0xFFFFFFFF</generation_price>
        <generation_price_ratio type="int">0xFF</generation_price_ratio>
        <alternate_cost_delivered type="int">0xFFFFFFFF</alternate_cost_delivered>
        <alternate_cost_unit type="int">0x1</alternate_cost_unit>
        <alternate_cost_trailing_digit type="int">0xFF</alternate_cost_trailing_digit>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
        <item type="MAC">11:22:33:44:55:66:77:89</item>
        <item type="MAC">11:22:33:44:55:66:77:8A</item>
    </device_list>
</create_price_event_response>

cancel_all_price_events

Removes all Price events from the local Price server.

This command requires the local device to have a Price cluster server instantiated on an endpoint.

Note

There is no mechanism in the SE specification for cancelling Price events on client devices. This command exists as a convenience function for clearing state information from the local Price server.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Price server cluster which will cancel the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Price server cluster which cancelled the events.
cluster_id int 16-bit identifier of the Price server cluster.
status int The ZCL status code associated with the cancellation of the events.

Example

<cancel_all_price_events/>

<cancel_all_price_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <status type="int">0x0</status>
</cancel_all_price_events_response>

SE Client Interface

get_scheduled_DRLC_events

Requests scheduled DRLC events from known DRLC server devices. Events will be sent individually by the servers as though they were new events being published (see received_DRLC_event*).

This command requires the local device to have a DRLC cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
record* GetScheduledEventsRecord Record describing which events will be requested. If not included, a record will be generated for requesting all events.
source_endpoint_id* int

8-bit identifier of the endpoint containing the DRLC client cluster which will request the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the DRLC client cluster which requested the events.
cluster_id int 16-bit identifier of the DRLC client cluster.
status int The ZCL status code associated with the request.
record GetScheduledEventsRecord Record describing which events were requested.
device_list* list The list of 64-bit extended addresses of server devices to which the request was sent. List items will be of type MAC. Only included if status is success (0).

Example

<get_scheduled_DRLC_events/>

<get_scheduled_DRLC_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="GetScheduledEventsRecord">
        <start_time type="int">0x0</start_time>
        <number_of_events type="int">0x0</number_of_events>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
    </device_list>
</get_scheduled_DRLC_events_response>

clear_DRLC_events

Removes all known DRLC events from the local DRLC client. If events are removed, this may also result in the current active events being updated (see updated_active_DRLC_events*).

This command requires the local device to have a DRLC cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the DRLC client cluster which will remove the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the DRLC client cluster which removed the events.
cluster_id int 16-bit identifier of the DRLC client cluster.

Example

<clear_DRLC_events/>

<clear_DRLC_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
</clear_DRLC_events_response>

received_DRLC_event*

Response only. Generated when a DRLC server device sends an event to the local DRLC client. This message will be generated even if the local client does not store the event, such as when the event is invalid.

This response will only be generated if the local device has a DRLC cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
status int The ZCL status code associated with receiving the event.
record LoadControlEventRecord Record describing the new event.

Example

<received_DRLC_event>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="LoadControlEventRecord">
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <device_class type="int">0xFFF</device_class>
        <utility_enrollment_group type="int">0x0</utility_enrollment_group>
        <start_time type="int">0x0</start_time>
        <duration_in_minutes>0x100</duration_in_minutes>
        <criticality_level type="int">0x01</criticality_level>
        <cooling_temperature_offset type="int">0xFF</cooling_temperature_offset>
        <heating_temperature_offset type="int">0xFF</heating_temperature_offset>
        <duty_cycle type="int">0xFF</duty_cycle>
        <event_control type="int">0x3</event_control>
    </record>
</received_DRLC_event>

received_cancel_DRLC_event*

Response only. Generated when a DRLC server device sends an event cancellation to the local DRLC client. This message will be generated even if the local client does not act on the cancellation, such as when it does not have the event being cancelled.

This response will only be generated if the local device has a DRLC cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
status int The ZCL status code associated with receiving the cancellation.
record CancelLoadControlEventRecord Record describing the cancellation.

Example

<received_cancel_DRLC_event>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="CancelLoadControlEventRecord">
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <device_class type="int">0xFFF</device_class>
        <utility_enrollment_group type="int">0x0</utility_enrollment_group>
        <cancel_control type="int">0x1</cancel_control>
    </record>
</received_cancel_DRLC_event>

received_cancel_all_DRLC_events*

Response only. Generated when a DRLC server device sends an event cancellation for all events to the local DRLC client. This message will be generated even if the local client does not act on the cancellation, such as when it does not any events to cancel.

This response will only be generated if the local device has a DRLC cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
status int The ZCL status code associated with receiving the cancellation.
record CancelAllLoadControlEventsRecord Record describing the cancellation.

Example

<received_cancel_all_DRLC_events>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <status type="int">0x0</status>
    <record type="CancelLoadControlEventRecord">
        <cancel_control>0x1</cancel_control>
    </record>
</received_cancel_all_DRLC_events>

updated_active_DRLC_events*

Response only. Generated when there is a change in which DRLC events known by the local client are active. An event is considered active when its start time is less than the current time and its end time is greater than the current time. More than one DRLC event may be active at a time.

This response will only be generated if the local device has a DRLC cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
record_list list List of LoadControlEventRecord describing the currently active events. If the list is empty, there are no currently active events.

Example

<updated_active_DRLC_events>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <record_list type="list">
        <item type="LoadControlEventRecord">
            <issuer_event_id type="int">0x1234</issuer_event_id>
            <device_class type="int">0xFFF</device_class>
            <utility_enrollment_group type="int">0x0</utility_enrollment_group>
            <start_time type="int">0x0</start_time>
            <duration_in_minutes>0x100</duration_in_minutes>
            <criticality_level type="int">0x01</criticality_level>
            <cooling_temperature_offset type="int">0xFF</cooling_temperature_offset>
            <heating_temperature_offset type="int">0xFF</heating_temperature_offset>
            <duty_cycle type="int">0xFF</duty_cycle>
            <event_control type="int">0x3</event_control>
        </item>
    </record_list>
</updated_active_DRLC_events>

confirm_message_event

Sends a confirmation of a Message event to all known Messaging servers.

This command requires the local device to have a Messaging cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
record* MessageConfirmationRecord Record describing the event to be confirmed. If not included, a record will be generated for confirming the currently active event.
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging client cluster which will send the confirmation.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Messaging client cluster which requested the events.
cluster_id int 16-bit identifier of the Messaging client cluster.
status int The ZCL status code associated with the request.
record MessageConfirmationRecord Record describing the confirmed event.
device_list* list The list of 64-bit extended addresses of server devices to which the confirmation was sent. List items will be of type MAC. Only included if status is success (0).

Example

<confirm_message_event>
    <record type="messageConfirmationRecord">
        <message_id>0x1234</message_id>
    </record>
</confirm_message_event>

<confirm_message_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <record type="messageConfirmationRecord">
        <message_id type="int">0x1234</message_id>
        <confirmation_time type="int">0x12345678</confirmation_time>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
    </device_list>
</confirm_message_event_response>

get_last_message_event

Requests the latest Message event from known Messaging server devices. Events will be sent individually by the servers as though they were new events being published (see received_display_message*).

This command requires the local device to have a Messaging cluster client instantiated on an endpoint.

Note

This command has a similar name to get_message_events, which may be confusing. The get_last_message_event command will send a request to the Messaging server, while the get_message_events command immediately returns with the events currently known by the client.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging client cluster which will request the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Messaging client cluster which requested the events.
cluster_id int 16-bit identifier of the Messaging client cluster.
status int The ZCL status code associated with the request.
device_list* list The list of 64-bit extended addresses of server devices to which the request was sent. List items will be of type MAC. Only included if status is success (0).

Example

<get_last_message_event/>

<get_last_message_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
    </device_list>
</get_last_message_event_response>

clear_message_events

Removes all known Message events from the local Messaging client. If events are removed, this may also result in the current active event being updated (see updated_active_message*).

This command requires the local device to have a Messaging cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging client cluster which will remove the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Messaging client cluster which removed the events.
cluster_id int 16-bit identifier of the Messaging client cluster.

Example

<clear_message_events/>

<clear_message_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
</clear_message_events_response>

received_display_message*

Response only. Generated when a Messaging server device sends an event to the local Messaging client. This message will be generated even if the local client does not store the event, such as when the event is invalid.

This response will only be generated if the local device has a Messaging cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
status int The ZCL status code associated with receiving the event.
record DisplayMessageRecord Record describing the new event.

Example

<received_display_message>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <record type="DisplayMessageRecord">
        <message_id type="int">0x1234</message_id>
        <message_control type="int">0x80</message_control>
        <start_time type="int">0</start_time>
        <duration_in_minutes type="int">0x100</duration_in_minutes>
        <message type="string">Please confirm this message.</message>
    </record>
</received_display_message>

received_cancel_message*

Response only. Generated when a Messaging server device sends an event cancellation to the local Messaging client. This message will be generated even if the local client does not act on the cancellation, such as when it does not have the event being cancelled.

This response will only be generated if the local device has a Messaging cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
status int The ZCL status code associated with receiving the cancellation.
record CancelMessageRecord Record describing the cancellation.

Example

<received_cancel_message>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <status type="int">0x0</status>
    <record type="CancelMessageRecord">
        <message_id type="int">0x1234</message_id>
        <message_control type="int">0x0</message_control>
    </record>
</received_cancel_message>

updated_active_message*

Response only. Generated when there is a change in which Message event known by the local client is active. An event is considered active when its start time is less than the current time and its end time is greater than the current time. Because Message events cannot overlap, only one event may be active at a time.

This response will only be generated if the local device has a Messaging cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
record* DisplayMessageRecord Record describing the currently active event. If not included, there is no currently active event.

Example

<updated_active_message>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <record type="DisplayMessageRecord">
        <message_id type="int">0x1234</message_id>
        <message_control type="int">0x80</message_control>
        <start_time type="int">0</start_time>
        <duration_in_minutes type="int">0x100</duration_in_minutes>
        <message type="string">Please confirm this message.</message>
    </record>
</updated_active_message>

get_current_price_event

Requests the current Price event from known Price server devices. Events will be sent individually by the servers as though they were new events being published (see received_publish_price*).

This command requires the local device to have a Price cluster client instantiated on an endpoint.

Note

This command has a similar name to get_price_events, which may be confusing. The get_current_price_event command will send a request to the Messaging server, while the get_price_events command immediately returns with the events currently known by the client.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Price client cluster which will request the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Price client cluster which requested the events.
cluster_id int 16-bit identifier of the Price client cluster.
status int The ZCL status code associated with the request.
device_list* list The list of 64-bit extended addresses of server devices to which the request was sent. List items will be of type MAC. Only included if status is success (0).

Example

<get_current_price_event/>

<get_current_price_event_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <status type="int">0x0</status>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
    </device_list>
</get_current_price_event_response>

get_scheduled_price_events

Requests scheduled Price events from known Price server devices. Events will be sent individually by the servers as though they were new events being published (see received_publish_price*).

This command requires the local device to have a Price cluster client instantiated on an endpoint.

Note

This command has a similar name to get_price_events, which may be confusing. The get_scheduled_price_events command will send a request to the Messaging server, while the get_price_events command immediately returns with the events currently known by the client.

Request Parameters

Parameter Type Description
record* GetScheduledPricesRecord Record describing which events will be requested. If not included, a record will be generated for requesting all events.
source_endpoint_id* int

8-bit identifier of the endpoint containing the Price client cluster which will request the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Price client cluster which requested the events.
cluster_id int 16-bit identifier of the Price client cluster.
status int The ZCL status code associated with the request.
record GetScheduledPricesRecord Record describing which events were requested.
device_list* list The list of 64-bit extended addresses of server devices to which the request was sent. List items will be of type MAC. Only included if status is success (0).

Example

<get_scheduled_price_events/>

<get_scheduled_price_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <status type="int">0x0</status>
    <record type="GetScheduledPricesRecord">
        <start_time type="int">0x0</start_time>
        <number_of_events type="int">0x0</number_of_events>
    </record>
    <device_list type="list">
        <item type="MAC">11:22:33:44:55:66:77:88</item>
    </device_list>
</get_scheduled_price_events_response>

clear_price_events

Removes all known Price events from the local Price client. If events are removed, this may also result in the current active events being updated (see updated_active_price*).

This command requires the local device to have a Price cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Price client cluster which will remove the events.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_endpoint_id int 8-bit identifier of the endpoint containing the Price client cluster which removed the events.
cluster_id int 16-bit identifier of the Price client cluster.

Example

<clear_price_events/>

<clear_price_events_response>
    <source_endpoint_id type="int">0x5E</source_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
</clear_price_events_response>

received_publish_price*

Response only. Generated when a Price server device sends an event to the local Price client. This message will be generated even if the local client does not store the event, such as when the event is invalid.

This response will only be generated if the local device has a Price cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
status int The ZCL status code associated with receiving the event.
record PublishPriceRecord Record describing the new event.

Example

<received_publish_price>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <status type="int">0x0</status>
    <record type="PublishPriceRecord">
        <provider_id type="int">0x12345678</provider_id>
        <rate_label type="string">SamplePrice</rate_label>
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <start_time type="int">0x0</start_time>
        <price type="int">0x78</price>
        <price_trailing_digit_and_price_tier type="int">0x33</price_trailing_digit_and_price_tier>
        <number_of_price_tiers_and_register_tier type="int">0x43</number_of_price_tiers_and_register_tier>
        <duration_in_minutes type="int">0x100</duration_in_minutes>
        <unit_of_measure type="int">0x0</unit_of_measure>
        <currency type="int">0x348</currency>
        <price_ratio type="int">0xFF</price_ratio>
        <generation_price type="int">0xFFFFFFFF</generation_price>
        <generation_price_ratio type="int">0xFF</generation_price_ratio>
        <alternate_cost_delivered type="int">0xFFFFFFFF</alternate_cost_delivered>
        <alternate_cost_unit type="int">0x1</alternate_cost_unit>
        <alternate_cost_trailing_digit type="int">0xFF</alternate_cost_trailing_digit>
    </record>
</received_publish_price>

updated_active_price*

Response only. Generated when there is a change in which Price event known by the local client is active. An event is considered active when its start time is less than the current time and its end time is greater than the current time. Because Price events cannot overlap, only one event may be active at a time.

This response will only be generated if the local device has a Price cluster client instantiated on an endpoint.

Response Parameters

Parameter Type Description
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
cluster_id int 16-bit identifier of the cluster on the local device which received the response.
record* PublishPriceRecord Record describing the currently active event. If not included, there is no currently active event.

Example

<updated_active_price>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <record type="PublishPriceRecord">
        <provider_id type="int">0x12345678</provider_id>
        <rate_label type="string">SamplePrice</rate_label>
        <issuer_event_id type="int">0x1234</issuer_event_id>
        <start_time type="int">0x0</start_time>
        <price type="int">0x78</price>
        <price_trailing_digit_and_price_tier type="int">0x33</price_trailing_digit_and_price_tier>
        <number_of_price_tiers_and_register_tier type="int">0x43</number_of_price_tiers_and_register_tier>
        <duration_in_minutes type="int">0x100</duration_in_minutes>
        <unit_of_measure type="int">0x0</unit_of_measure>
        <currency type="int">0x348</currency>
        <price_ratio type="int">0xFF</price_ratio>
        <generation_price type="int">0xFFFFFFFF</generation_price>
        <generation_price_ratio type="int">0xFF</generation_price_ratio>
        <alternate_cost_delivered type="int">0xFFFFFFFF</alternate_cost_delivered>
        <alternate_cost_unit type="int">0x1</alternate_cost_unit>
        <alternate_cost_trailing_digit type="int">0xFF</alternate_cost_trailing_digit>
    </record>
</updated_active_price>

Shared Commands

get_DRLC_events

Retrieves all DRLC events currently stored on the local DRLC server.

This command requires the local device to have a DRLC cluster server or DRLC cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the DRLC server cluster to query.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
endpoint_id int 8-bit identifier of the endpoint containing the cluster whose events were queried.
cluster_id int 16-bit identifier of the cluster whose events were queried.
server_or_client int Whether the cluster whose events were queried is a server (0) or client (1) cluster.
events_record_list list List of LoadControlEventRecord representing the queried events.

Example

<get_DRLC_events/>

<get_DRLC_events_response>
    <endpoint_id type="int">0x5E</endpoint_id>
    <cluster_id type="int">0x701</cluster_id>
    <server_or_client type="int">0x0</server_or_client>
    <events_record_list type="list">
        <item type="LoadControlEventRecord">
            <issuer_event_id type="int">0x1234</issuer_event_id>
            <device_class type="int">0xFFF</device_class>
            <utility_enrollment_group type="int">0x0</utility_enrollment_group>
            <start_time type="int">0x0</start_time>
            <duration_in_minutes>0x100</duration_in_minutes>
            <criticality_level type="int">0x01</criticality_level>
            <cooling_temperature_offset type="int">0xFF</cooling_temperature_offset>
            <heating_temperature_offset type="int">0xFF</heating_temperature_offset>
            <duty_cycle type="int">0xFF</duty_cycle>
            <event_control type="int">0x3</event_control>
        </item>
    </events_record_list>
</get_DRLC_events_response>

get_message_events

Retrieves all Message events currently stored on the local Messaging server.

This command requires the local device to have a Messaging cluster server or Messaging cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Messaging server cluster to query.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
endpoint_id int 8-bit identifier of the endpoint containing the cluster whose events were queried.
cluster_id int 16-bit identifier of the cluster whose events were queried.
server_or_client int Whether the cluster whose events were queried is a server (0) or client (1) cluster.
events_record_list list List of DisplayMessageRecord representing the queried events.

Example

<get_message_events/>

<get_message_events_response>
    <endpoint_id type="int">0x5E</endpoint_id>
    <cluster_id type="int">0x703</cluster_id>
    <server_or_client type="int">0</server_or_client>
    <events_record_list type="list">
        <item type="DisplayMessageRecord">
            <message_id type="int">0x1234</message_id>
            <message_control type="int">0x80</message_control>
            <start_time type="int">0x0</start_time>
            <duration_in_minutes type="int">0x100</duration_in_minutes>
            <message type="string">Please confirm this message.</message>
        </item>
    </events_record_list>
</get_message_events_response>

get_price_events

Retrieves all Price events currently stored on the local Price server.

This command requires the local device to have a Price cluster server or Price cluster client instantiated on an endpoint.

Request Parameters

Parameter Type Description
source_endpoint_id* int

8-bit identifier of the endpoint containing the Price server cluster to query.

Before 1.4.0: If not provided, defaults to 0x5E.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
endpoint_id int 8-bit identifier of the endpoint containing the cluster whose events were queried.
cluster_id int 16-bit identifier of the cluster whose events were queried.
server_or_client int Whether the cluster whose events were queried is a server (0) or client (1) cluster.
events_record_list list List of PublishPriceRecord representing the queried events.

Example

<get_price_events/>

<get_price_events_response>
    <endpoint_id type="int">0x5E</endpoint_id>
    <cluster_id type="int">0x700</cluster_id>
    <server_or_client type="int">0x0</server_or_client>
    <events_record_list type="list">
        <item type="PublishPriceRecord">
            <provider_id type="int">0x12345678</provider_id>
            <rate_label type="string">SamplePrice</rate_label>
            <issuer_event_id type="int">0x1234</issuer_event_id>
            <start_time type="int">0x0</start_time>
            <price type="int">0x78</price>
            <price_trailing_digit_and_price_tier type="int">0x33</price_trailing_digit_and_price_tier>
            <number_of_price_tiers_and_register_tier type="int">0x43</number_of_price_tiers_and_register_tier>
            <duration_in_minutes type="int">0x100</duration_in_minutes>
            <unit_of_measure type="int">0x0</unit_of_measure>
            <currency type="int">0x348</currency>
            <price_ratio type="int">0xFF</price_ratio>
            <generation_price type="int">0xFFFFFFFF</generation_price>
            <generation_price_ratio type="int">0xFF</generation_price_ratio>
            <alternate_cost_delivered type="int">0xFFFFFFFF</alternate_cost_delivered>
            <alternate_cost_unit type="int">0x1</alternate_cost_unit>
            <alternate_cost_trailing_digit type="int">0xFF</alternate_cost_trailing_digit>
        </item>
    </events_record_list>
</get_price_events_response>

get_meter_profile

Queries the Simple Metering cluster on the given device for its profile data. The profile data is the incremental energy usage given in fixed time periods determined by the meter (typically 15 minutes). The client requests a time span that it wants to receive profile data for and the meter responds using its own interval period. This is an optional feature for meters and will not always be supported. If a meter does support this command it is very useful to get historical usage and the usage data used for billing purposes by the meter.

This command requires the local device to have a Metering cluster client instantiated on an endpoint.

Note

As of 1.5.0:
  • Command will now send multiple requests to the meter to get the meter profile data for the entire period that is requested.
  • start_time parameter added to GetProfileRecord to help specify the time span of the responses.

Request Parameters

Parameter Type Description
record GetProfileRecord The record describing the profile data to query.
destination_address* MAC 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device.
destination_endpoint_id* int

8-bit identifier of the endpoint on the target device containing the Metering server cluster.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

source_endpoint_id* int

8-bit identifier of the endpoint on the local device from which the ZCL command will be sent.

Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
profile_id int 16-bit identifier of the profile of the response.
cluster_id int 16-bit identifier of the cluster that received the response.
server_or_client int Whether the cluster that sent the response is a server (0) or client (1) cluster.
record GetProfileResponseRecord The record describing the profile data.

Example

<get_meter_profile>
    <destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
    <destination_endpoint_id>0x10</destination_endpoint_id>
    <source_endpoint_id>0x5E</source_endpoint_id>
    <record type="GetProfileRecord">
        <interval_channel>0x00</interval_channel>
        <end_time>0x12345678</end_time>
        <number_of_periods>10</number_of_periods>
        <start_time>0x12345000</start_time>
    </record>
</get_meter_profile>

<get_meter_profile_response>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <profile_id>0x109</profile_id>
    <cluster_id type="int">0x702</cluster_id>
    <server_or_client type="int">0x0</server_or_client>
    <record type="GetProfileResponseRecord">
        <end_time type="int">0x12345678</end_time>
        <status type="int">0x0</status>
        <profile_interval_period type="int">0x0</profile_interval_period>
        <intervals type="list">
            <item type="int">0xAB8000</item>
            <item type="int">0xAB7000</item>
            <item type="int">0xAB6000</item>
            <item type="int">0xAB5000</item>
            <item type="int">0xAB4000</item>
            <item type="int">0xAB3000</item>
            <item type="int">0xAB2000</item>
            <item type="int">0xAB1000</item>
        </intervals>
    </record>
</get_meter_profile_response>

request_fast_poll_mode

Requests the target Metering server to allow fast polling for some duration. This is a Smart Energy 1.1-specific command.

Note

Added in version 1.5.0.

Request Parameters

Parameter Type Description
record RequestFastPollModeRecord The record describing the requested fast polling window.
destination_address* MAC 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device.
destination_endpoint_id* int

8-bit identifier of the endpoint on the target device containing the Metering server cluster.

As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

source_endpoint_id* int

8-bit identifier of the endpoint on the local device from which the ZCL command will be sent.

Before :ref:`1_4_0`: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. *As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information.

Response Parameters

Parameter Type Description
source_address MAC 64-bit extended address of the device which sent the response.
source_endpoint_id int 8-bit identifier of the endpoint on the device which sent the response.
destination_endpoint_id int 8-bit identifier of the endpoint on the local device which received the response.
profile_id int 16-bit identifier of the profile of the response.
cluster_id int 16-bit identifier of the cluster that received the response.
server_or_client int Whether the cluster that sent the response is a server (0) or client (1) cluster.
record FastPollModeResponseRecord The record describing the fast polling window.

Example

<request_fast_poll_mode>
    <destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
    <destination_endpoint_id>0x10</destination_endpoint_id>
    <source_endpoint_id>0x5E</source_endpoint_id>
    <record type="RequestFastPollModeRecord">
        <fast_poll_update_period>10</fast_poll_update_period>
        <duration_in_minutes>5</duration_in_minutes>
    </record>
</request_fast_poll_mode>

<request_fast_poll_mode_response>
    <source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
    <source_endpoint_id type="int">0x10</source_endpoint_id>
    <destination_endpoint_id type="int">0x5E</destination_endpoint_id>
    <profile_id>0x109</profile_id>
    <cluster_id type="int">0x702</cluster_id>
    <server_or_client type="int">0x0</server_or_client>
    <record type="FastPollModeResponseRecord">
        <applied_update_period type="int">10</applied_update_period>
        <end_time type="int">12345678</end_time>
    </record>
</request_fast_poll_mode_response>