Phase grouping

This information relates to v3.2+ of the API.

This document assumes the reader is familiar and comfortable with the device status (GET /devices/{device-id}, PATCH /devices/{device-id}) and energy data (e.g. /GET short-energy/{device-id} and GET /long-energy/{device-id}) endpoints outlined in API endpoints.

Wattwatchers devices are highly flexible and can be installed in a number of different configurations.

A common use case is installation in a 3 phase environment, which in Australia is a popular form of polyphase system.

In past iterations, the Wattwatchers API provided a circuit-level view of energy data where a phase was represented across multiple individual channels. Phase-related metadata was not tracked for a device, nor returned via the API.

This meant that calling systems needed to track this information separately and perform the required calculations on data returned via the API to present a single energy data-point for each phase group.

As of API version 3.2 (released July 2019) the API provides a mechanism for storing and retrieving this metadata, as well as retrieving energy data organised by phase.

This support note examines how these features work.

Background/Concepts

Clean phase grouping

The most common scenario for Wattwatchers being deployed in a polyphase system is for each phase to be monitored via an individual CT.

So, for example, in a 3 phase environment, a 6 channel Auditor may be employed to monitor both the mains (grid) connection and a single 3 phase piece of equipment—a load (e.g. pool pump) or generation source (such as solar). Using the pool pump example, a typical configuration might be:

Channel	Connected To	Channel Group	Phase	Label
CH1	Grid	1	1	Grid connect (Phase 1)
CH2	Grid	1	2	Grid connect (Phase 2)
CH3	Grid	1	3	Grid connect (Phase 3)
CH4	Circuit 1	2	1	Pool pump (Phase 1)
CH5	Circuit 2	2	2	Pool pump (Phase 2)
CH6	Circuit 3	2	3	Pool pump (Phase 3)

Mixed phase grouping

A less common scenario is a device installed in a "mixed" system. For example, some installations (particularly in a residential context) may be configured to use 3 phase for some aspects (such as the grid connection and/or solar), but also to monitor single-phase loads. In this case, 3 CTs would be applied to monitoring a 3 phase component, and the remaining 3 CTs would monitor individual single phase appliances.

By way of example, a 6 channel device may be installed as such:

Channel	Connected To	Channel Group	Phase	Label
CH1	Grid	1	1	Grid Connect (Phase 1)
CH2	Grid	1	2	Grid Connect (Phase 2)
CH3	Grid	1	3	Grid Connect (Phase 3)
CH4	Circuit 1	2	1	Pool pump
CH5	Circuit 2	2	2	Hot water
CH6	Circuit 3	2	3	Oven

Irregular CT order

While installation best practice suggests channel CTs be installed in phase order (e.g. Channel 1 configured to phase 1, Channel 2 to phase 2 etc.), there are some circumstances where CT ordering is irregular, for example:

Channel	Connected To	Channel Group	Phase	Label
CH1	Grid	1	1	Grid connect (Phase 1)
CH5	Grid	1	2	Grid connect (Phase 2)
CH3	Grid	1	3	Grid connect (Phase 3)
CH4	Circuit 1	2	1	Pool pump (Phase 1)
CH2	Circuit 2	2	2	Pool pump (Phase 2)
CH6	Circuit 3	2	3	Pool pump (Phase 3)

Note the channels do not follow a sequential order (see the bolded entries.)

While this type of configuration is not advised (and is often an indication of misconfiguration of the device), the Wattwatchers API also supports these types of irregular configurations so that re-work (which would require a site visit) is not required to correct such an issue.

Calculating phase group values

To determine the value for energy data across all phases, you sum the value of each phase.

For example, if a 3 channel device in 3 phase mode returns eReal values of 24838, 250316, 311787, the combined value for the phase group is 586941.

Of course, this can be done by a calling system via the existing API provided it knows what the phase configuration looks like.

The additions to the API highlighted in this support note just make it easier to do, and enable a calling system to use the Wattwatchers API to track phase-related metadata without necessarily having to store/track this elsewhere.

Getting phase configuration

Two new properties have been added to the GET /devices/{device-id} endpoint to allow the retrieval of a device's phase configuration.

These are:

Property	Valid values	Description
phases.count	null, 0, 1, 2, 3	The number of phases for the device installation. See further description below.
phases.grouping	List	A list of objects outlining what channels are included in each phase group.

An example GET response may look like:

200 OK

{
    "id": "ED12345678901",
    "model": "6W",
    "firmwareVersion": "41.3.2",
    "latestStatus": 1550684123,
    "shortEnergyReportingInterval": 30,
    "pending": {
        "shortEnergyReportingInterval": 5
    },
    "comms": {
        "type": "wifi",
        "lastHeardAt": 123456789.2341,
        "signalQualityDbm": -57,
        "networkId": "my-wifi-net"
    },
    "channels": [
        {
            ...channel-attributes
        }
    ],
    "phases": {
        "count": 3,
        "grouping": [
            {
                "included": [
                    "D123456789012_C1",
                    "D123456789012_C2",
                    "D123456789012_C3"
                ]
            },
            {
                "included": [
                    "D123456789012_C4",
                    "D123456789012_C5",
                    "D123456789012_C6"
                ]
            }
        ]
    },
    "switches": [
        {
            "id": "{switch-id}",
            ...switch-attributes
        }
    ]
}

• The phases collection will always be returned, even when no phase information has been set.
• Valid values for phases.count are:
• null: Not set (no phase configuration has been provided for the device)
• 0: Mixed
• 1: Single phase
• 2: Two phase
• 3: Three phase
• When phases.count is null, no phases.grouping property is returned (as it is not applicable/relevant).
• When phases.count is a non-null value, the phases.grouping array outlines how channels are allocated. Note that a phases.count value of 1 also returns a phases.grouping value, but each phase configuration object will contain a single channel in the included collection (that is 6 objects for a 6 channel device).

Setting phase configuration

In the design of the API implementation, our aim has been to simplify configuration to require the minimum amount of input from calling systems to configure for common use cases (such as the Clean 3 phase example outlined above).

However, we also provide support for "mixed" configurations, as noted in the Mixed phase grouping and Irregular CT order examples above.

Phase configuration of a device is handled by the PATCH /devices/{device-id} endpoint.

The phases.count and phases.grouping properties enable setting the phase configuration parameters.

Setting clean phase grouping

To set a clean phase grouping (e.g. where a 6 channel device is monitoring two 3 phase sources), you only need to specify phases.count to the integer value 3—i.e. the request body would be:

{
    "id": "D123456789012",
    "phases": {
        "count": 3
    }
}

The same applies for a single or two phase device configuration, except phases.count would be set to 1 or 2 respectively.

The default grouping values are as follows:

# of device channels	Phase Count	Grouping
6	1	N/A
6	2	[1, 2], [3, 4], [5, 6]
6	3	[1, 2, 3], [4, 5, 6]
3	1	N/A
3	2	[1, 2], [3]
3	3	[1, 2, 3]

You can also specify this (or an alternate) order explicitly if you so choose (see Setting irregular CT order for the syntax).

Setting irregular CT order

If your device configuration differs from the default grouping values outlined above, you can provide the (optional) phases.grouping value to specify the order you need.

For example, using the illustrative example from earlier in this document, you would specify:

{
    "id": "D123456789012",
    "phases": {
        "count": 3,
        "grouping": [
            {
                "included": [
                    "D123456789012_C1",
                    "D123456789012_C5",
                    "D123456789012_C3"
                ]
            },
            {
                "included": [
                    "D123456789012_C4",
                    "D123456789012_C2",
                    "D123456789012_C6"
                ]
            }
        ]
    }
}

The order of channels in the phases.grouping value is not critical. e.g. specifying:

"included": [
    "D123456789012_C1",
    "D123456789012_C2",
    "D123456789012_C3"
]

is treated the same as:

"included": [
    "D123456789012_C3",
    "D123456789012_C2",
    "D123456789012_C1"
]

However, the order of the phases.grouping objects themselves is important, as the output data reflects the group order.

e.g.

"phases": {
    "count": 3,
    "grouping": [
        {
            "included": [
                "D123456789012_C1",
                "D123456789012_C2",
                "D123456789012_C3"
            ]
        },
        {
            "included": [
                "D123456789012_C4",
                "D123456789012_C5",
                "D123456789012_C6"
            ]
        }
    ]
}

is different to:

"phases": {
    "count": 3,
    "grouping": [
        {
            "included": [
                "D123456789012_C4",
                "D123456789012_C5",
                "D123456789012_C6"
            ]
        },
        {
            "included": [
                "D123456789012_C1",
                "D123456789012_C2",
                "D123456789012_C3"
            ]
        }
    ]
}

as this will change the order of energy data entries returned via the API.

Setting an alternative 2 phase order

For a 3 channel device in 2 phase configuration, the order of the CTs may be installed as [[1], [2,3]]. If you wish to use this configuration, specify the phases.grouping value accordingly:

{
    "id": "D123456789012",
    "phases": {
        "count": 2,
        "grouping": [
            {
                "included": [
                    "D123456789012_C1"
                ]
            },
            {
                "included": [
                    "D123456789012_C2",
                    "D123456789012_C3"
                ]
            }
        ]
    }
}

Setting a mixed phase grouping

When the device is a mix of different phase sources, set phases.count to 0 and specify the appropriate phases.grouping value.

When "Mixed" is specified, you MUST specify a phases.grouping value.

For example, to set a device to match the earlier example, you would specify:

{
    "id": "D123456789012",
    "phases": {
        "count": 0,
        "grouping": [
            {
                "included": [
                    "D123456789012_C1",
                    "D123456789012_C2",
                    "D123456789012_C3"
                ]
            },
            {
                "included": [
                    "D123456789012_C4"
                ]
            },
            {
                "included": [
                    "D123456789012_C5"
                ]
            },
            {
                "included": [
                    "D123456789012_C6"
                ]
            }
        ]
    }
}

Retrieving energy data

The following short and long energy endpoints support specifying a filter[group]=phases query string parameter:

• GET /short-energy/{device-id}
• GET /short-energy/{device-id}/first
• GET /short-energy/{device-id}/latest
• GET /long-energy/{device-id}
• GET /long-energy/{device-id}/first
• GET /long-energy/{device-id}/latest

When this parameter is specified, the API will collapse energy data (eReal, eReactive etc.) into data points that reflect the phases.grouping configuration.

For example, using the Clean phase grouping example, a call to the GET/ long-energy/{device-id} endpoint will return:

[
  {
    "timestamp": 1561471200,
    "duration": 300,
    "groupedBy": "phases",
    "eReal": [
      586941, 16354
    ],
    "eReactive": [
      -626425, -31167
    ],
    ...,
  },
  ...
]

Note the additional groupedBy property in each energy data entry. Also note that, even though this example is based on a 6 channel device, only 2 energy data values are returned, reflecting the number of entries in the phases.grouping collection.

When called for a device in a mixed phase configuration, this will return an energy data entry for each phases.grouping entry. Thus, calling for a device configured as per the Mixed phase grouping example would result in a return similar to:

[
  {
    "timestamp": 1561471200,
    "duration": 300,
    "groupedBy": "phases",
    "eReal": [
      586941, 14671, 642, 1041
    ],
    "eReactive": [
      -626425, -12124, -9305, -9738
    ],
    ...
  },
  ...
]

In this example, the first eReal value (586941) and first eReactive value (-626425) reflect the 3 phase channel group, and the three values following (14671, 642, 1041 and -12124, -9305, -9738 respectively) map to the single channel phase groupings.

Troubleshooting and tips

What order is grouped energy data returned in?

The order of grouped energy data will match the settings of the device in the phases.grouping value.

For example, if the device is configured with a phases.grouping value of [[1,2,3], [4,5,6]] (the default for the phases.count value of 3), than an eReal value of [586941, 16354] represents:

First value 586941 represents the value for channels 1, 2 & 3, and the second value 16354 representing the value for channels 4, 5 & 6.

Note that if you manually specify an irregular configuration, this will translate into the output. For example, if you were to manually set the phases.grouping to [[4,5,6], [1,2,3]] the order would be reversed, with:

First value 16354 represents the value for channels 4, 5 & 6, and the second value 586941 representing the value for channels 1, 2 & 3.

How are multi-phase values calculated?

Polyphase values are summed.

For example, a 3 channel device configured as a 3 phase configuration, might report the following eReal values when the filter[group]=phases parameter is not provided:

[
    {
        "eReal": [
            24838, 250316, 311787
        ],
        ...
    }
]

The corresponding values reported when the filter[group]=phases parameter is specified would return:

[
    {
        "eReal": [
            586941
        ],
        ...
    }
]

Can I calculate phase values myself?

Absolutely. If you don't provide the filter[group]=phases parameter you will continue to receive all channel data for the device, upon which you can perform your own calculations.

Can I label (and categorise) phase groups

Not presently. We expect to implement the ability to specify phase-specific labels and categories in future.

We recommend labeling and categorising each individual channel. When implemented in the future, phase group labeling and categorisation will use the details of the first channel in a group as its default value when migrating data from previously configured devices.

Thus, if you have a 6 channel device in 3 phase configuration, label and categorise channels 1 and 4 according to how you would like the phase group to be represented in future. But be sure to set the label and category information for all channels in the phase group. For example:

Channel	Category	Channel Group	Phase	Label
CH1	Grid connect	1	1	Mains
CH2	Grid connect	1	2	Mains (Phase 2)
CH3	Grid connect	1	3	Mains (Phase 3)
CH4	Pool pump	2	1	Pool
CH5	Pool pump	2	2	Pool (Phase 2)
CH6	Pool pump	2	3	Pool (Phase 3)