Price Cluster
This chapter outlines the Price cluster, which is used to hold and exchange price information.
The Price cluster has a Cluster ID of 0x0700.
CAUTION:
**Important:**While the Price cluster software supports Block mode, this mode is not certifiable in SE 1.1.1 (07-5356-17) or earlier and is therefore not fully documented in this chapter. Customers who wish to use Block mode should contact NXP for direct support.
Overview
The Price cluster is required in ZigBee devices as indicated in the table below.
Server-side |
Client-side |
|
|---|---|---|
Mandatory in… |
ESP |
Smart Appliance |
Optional in… |
ESP Metering Device, IPD, PCT, Load Control Device |
The ESP normally acts as the Price cluster server, holding price information received from the utility company. Other devices act as clients and receive price information from the ESP. The clients’ price information must be kept up-to-date with the server’s price information.
The Price cluster is enabled by defining CLD_PRICE in the zcl_options.h file. Further compile-time options for the Price cluster are detailed in Section 40.13.
The Price cluster can operate in a mode in which pricing is based on the time at which the consumption occurs - this is called Time-Of-Use (TOU) mode. The cluster allows up to fifteen price ‘tiers’, numbered 1 to 15, which correspond to different time periods. Each price tier is given a label, which is used to identify the tier - typical labels are “Normal”, “Shoulder”, “Peak”, “Real-time Pricing” and “Critical Peak”. The tiers must be numbered consecutively in price order, with Tier 1 being the cheapest.Note that tiers 7 to 15 are not certifiable in SE 1.1.1 or earlier and are reserved for future use.
The information that can potentially be stored in the Price cluster is organised into the following attribute sets: Tier Label, Block Threshold, Block Period, Commodity, Block Price Information, Billing Period Information. The attribute sets Block Threshold, Block Period, Block Price Information and Billing Period Information are reserved for future use (with Block mode). There is also a set of attributes exclusively for use on a Price cluster client.
The cluster includes commands for requesting and publishing (distributing) price information. The price information that is valid for a certain time is sent from the Price cluster server (ESP) to the Price cluster clients using Publish Pricecommands, which may be sent from the ESP under the following circumstances:
Unsolicited from the server - for example, when new pricing information has been received from the utility company or a new price tier becomes active
In response to a Get Current Price command, sent by a client that needs the price for the current time period
In response to a Get Scheduled Prices command, sent by a client that needs both current and future prices
Functions are provided for implementing the cluster commands. These functions are referenced in Section 40.4 and Section 40.5, and detailed in Section 40.9.
Parent topic:Price Cluster
Price cluster structure and attributes
The Price cluster is contained in the following tsCLD_Price structure:
typedef struct CLD_Price_tag
{
/* Tier Price Label Set (D.4.2.2.1) */
#if (CLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT != 0)
tsZCL_OctetString asTierPriceLabel[CLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT];
uint8 au8TierPriceLabel[CLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT][SE_PRICE_SERVER_MAX_STRING_LENGTH];
#endif
/* Block Threshold Set (D.4.2.2) */
#if (CLD_P_ATTR_BLOCK_THRESHOLD_MAX_COUNT != 0)
zuint48 au48BlockThreshold[CLD_P_ATTR_BLOCK_THRESHOLD_MAX_COUNT];
#endif
/* Block Period Set (D.4.2.2.3) */
#ifdef CLD_P_ATTR_START_OF_BLOCK_PERIOD
zutctime utctStartOfBlockPeriod;
#endif
#ifdef CLD_P_ATTR_BLOCK_PERIOD_DURATION
zuint24 u24BlockPeriodDuration;
#endif
#ifdef CLD_P_ATTR_THRESHOLD_MULTIPLIER
zuint24 u24ThresholdMultiplier;
#endif
#ifdef CLD_P_ATTR_THRESHOLD_DIVISOR
zuint24 u24ThresholdDivisor;
#endif
/* Commodity Set Set (D.4.2.2.4) */
#ifdef CLD_P_ATTR_COMMODITY_TYPE
zenum8 e8CommodityType;
#endif
#ifdef CLD_P_ATTR_STANDING_CHARGE
zuint32 u32StandingCharge;
#endif
#ifdef CLD_P_ATTR_CONVERSION_FACTOR
zuint32 u32ConversionFactor;
#endif
#ifdef CLD_P_ATTR_CONVERSION_FACTOR_TRAILING_DIGIT
zbmap8 b8ConversionFactorTrailingDigit;
#endif
#ifdef CLD_P_ATTR_CALORIFIC_VALUE
zuint32 u32CalorificValue;
#endif
#ifdef CLD_P_ATTR_CALORIFIC_VALUE_UNIT
zenum8 e8CalorificValueUnit;
#endif
#ifdef CLD_P_ATTR_CALORIFIC_VALUE_TRAILING_DIGIT
zbmap8 b8CalorificValueTrailingDigit;
#endif
/* Block Price Information Set (D.4.2.2.5) */
#if (CLD_P_ATTR_NO_TIER_BLOCK_PRICES_MAX_COUNT != 0)
zuint32 au32NoTierBlockPrice[CLD_P_ATTR_NO_TIER_BLOCK_PRICES_MAX_COUNT];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 0)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier1BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 1)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier2BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 2)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier3BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 3)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier4BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 4)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier5BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 5)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier6BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 6)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier7BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 7)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier8BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 8)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier9BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 9)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier10BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 10)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier11BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 11)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier12BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 12)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier13BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 13)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier14BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#if ((CLD_P_ATTR_NUM_OF_TIERS_PRICE > 14)&&(CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE != 0))
zuint32 au32Tier15BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE];
#endif
#ifdef CLD_P_ATTR_START_OF_BILLING_PERIOD
zutctime utctStartOfBillingPeriod;
#endif
#ifdef CLD_P_ATTR_BILLING_PERIOD_DURATION
zuint24 u24BillingPeriodDuration;
#endif
#ifdef CLD_P_CLIENT_ATTR_PRICE_INCREASE_RANDOMIZE_MINUTES
uint8 u8ClientIncreaseRandomize;
#endif
#ifdef CLD_P_CLIENT_ATTR_PRICE_DECREASE_RANDOMIZE_MINUTES
uint8 u8ClientDecreaseRandomize;
#endif
#ifdef CLD_P_CLIENT_ATTR_COMMODITY_TYPE
zenum8 e8ClientCommodityType;
#endif
} tsCLD_Price;
where:
‘Tier Label’ Attribute Set
The following are optional attributes that are only relevant to TOU mode**(tiers 7 to 15 are not certifiable in SE 1.1.1 or earlier and are reserved for future use):
asTierPriceLabel[CLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT]is a
tsZCL_OctetStringstructure containing information on tier labels. The maximum size ofasTierPriceLabelis defined by assigning a value toCLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT. This optional element is paired withau8TierPriceLabel(below)au8TierPriceLabel[CLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT]``[SE_PRICE_SERVER_MAX_STRING_LENGTH]is an array containing the tier labels, e.g. “Peak”. This optional element is paired with the elementasTierPriceLabel(above)
Note: Memory space for each (enabled) price tier label is statically allocated and comprises 13 bytes per label (plus one byte for the ‘octet count’). Therefore, memory space remains allocated for unused bytes.
‘Block Threshold’ Attribute Set
The following are optional attributes that relate to Block mode and are fully described in the ZigBee Smart Energy Profile Specification(these attributes are not certifiable in SE 1.1.1 or earlier and are for future use):
au48BlockThreshold[CLD_P_ATTR_BLOCK_THRESHOLD_MAX_COUNT]
‘Block Period’ Attribute Set
The following are optional attributes that relate to Block mode and are fully described in the ZigBee Smart Energy Profile Specification(these attributes are not certifiable in SE 1.1.1 or earlier and are for future use):
utctStartOfBlockPeriodu24BlockPeriodDurationu24ThresholdMultiplieru24ThresholdDivisor
‘Commodity’ Attribute Set
The following are optional attributes:
e8CommodityTypeis an enumeration representing the type of commodity (e.g. gas) to which the prices apply - the enumerations used are those provided in theteCLD_SM_MeteringDeviceTypestructure of the Simple Metering cluster and listed in Section 42.10.6u32StandingChargeis the value of a fixed daily ‘standing charge’ associated with supplying the commodity, expressed in the currency and with the decimal places indicated in the Publish Price command described in Section 40.11.1 (the value 0xFFFFFFFF indicates that the field is not used)u32ConversionFactoris used only for gas and accounts for the variation of gas volume with temperature and pressure (and is dimensionless). The Price server can change this conversion factor at any time and this attribute contains the currently active value. The default value is 1. The position of the decimal point is indicated byb8``ConversionFactorTrailingDigitdescribed below.b8``ConversionFactorTrailingDigitis an 8-bit bitmap which indicates the location of the decimal point in theu32ConversionFactorattribute. The most significant 4 bits indicate the number of digits after the decimal point. The remaining bits are reserved.u32CalorificValueis used only for gas and indicates the quantity of energy in MJ that is generated per unit volume or unit mass of gas burned (seee8``CalorificValueUnit) - the value can be used to calculate energy consumption in kWh. The position of the decimal point is indicated byb8``CalorificValueTrailingDigitdescribed below.e8``CalorificValueUnitis an enumerated value indicating whetheru32CalorificValueis quantified per unit volume or per unit mass. The possible values are 0x01 for MJ/m3 and 0x02 for MJ/kg (all other values are reserved).b8``CalorificValueTrailingDigitis an 8-bit bitmap which indicates the location of the decimal point in theu32CalorificValueattribute. The most significant 4 bits indicate the number of digits after the decimal point. The remaining bits are reserved.
‘Block Price Information’ Attribute Set
The following are optional attributes that relate to Block mode and are fully described in the ZigBee Smart Energy Profile Specification(these attributes are not certifiable in SE 1.1.1 or earlier and are for future use):
au32NoTierBlockPrice[CLD_P_ATTR_NO_TIER_BLOCK_PRICES_MAX_COUNT] au32Tier1BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier2BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier3BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier4BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier5BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier6BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier7BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier8BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier9BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier10BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier11BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier12BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier13BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier14BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE] au32Tier15BlockPrice[CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE]
‘Billing Period Information’ Attribute Set
The following are optional attributes that relate to Block mode (both attributes are not certifiable in SE 1.1.1 or earlier and are for future use):
utctStartOfBillingPeriod
u24BillingPeriodDuration
Client Attribute Set
The following set of attributes are only for use on a Price cluster client:
u8ClientIncreaseRandomizerepresents the maximum length of time, in minutes, between a client node applying a price increase and taking a resulting action (such as reducing its power consumption). The action may be performed before or after the price increase is implemented, and the delay (either way) must be chosen at random by the application on the node. The maximum is set in minutes, in the range 0 to 60 minutes, but it is recommended that the random delay is selected in seconds.u8ClientDecreaseRandomize represents the maximum length of time, in minutes, between a client node applying a price decrease and taking a resulting action (such as switching itself on). The action may be performed before or after the price decrease is implemented, and the delay (either way) must be chosen at random by the application on the node. The maximum is set in minutes, in the range 0 to 60 minutes, but it is recommended that the random delay is selected in seconds.
e8ClientCommodityType is an enumeration representing the commodity that is priced on the client device. This enumeration is one from the ‘Metering Device Type’ enumerations listed in Table74.
Note: Price information for Time-Of-Use (TOU) mode is held in the tsSE_PricePublishPriceCmdPayload structure described in Section 40.11.1. Prices are matched to tiers using the strings defined in the Tier Label attributes.
Parent topic:Price Cluster
Attribute settings
The Price cluster structure (see Section 40.2) contains no mandatory elements. All elements are optional, each being enabled/disabled through a corresponding macro defined in the zcl_options.h file - for example, the commodity type attribute is enabled/disabled through the macro CLD_P_ATTR_COMMODITY_TYPE. The attributes that are used depend on the number of tiers implemented (and Block mode attributes must be disabled).
Note:
The Tier Label attributes are connected to the tier-related attributes in the Simple Metering cluster, e.g.
u48CurrentTier6SummationDeliveredfor Tier 6. For a complete list of these Simple Metering attributes, refer to Section 42.2.The price information for Time-Of-Use (TOU) mode is stored in the structure
tsSE_PricePublishPriceCmdPayloaddescribed in Section 40.11.1.
Parent topic:Price Cluster
Initializing and maintaining price lists
A list of prices is held on both the Price cluster server (ESP) and client(s). The price list on a client must be maintained to mirror the price list on the server. On device startup, the Price cluster software initializes the device’s price list as empty. The price lists are then built and maintained as described below.
The ESP receives price information from the utility company and populates its price list with this information. The application on the ESP does this by calling the function eSE_PriceAddPriceEntry() for each new price received from the utility company. This function also sends out a Publish Price command containing the new price information to all Price cluster clients in the network. On receiving this command, a Price cluster client automatically adds this price information to its own price list (see Section 40.5.1). However, at ESP startup, there may be no other active nodes in the network to receive the Publish Price commands (since the ESP is normally also the ZigBee Co-ordinator and is, therefore, the first node to be started). For this reason, the Price cluster clients should normally request the scheduled prices from the ESP when they start up, as described in Section 40.5.3.
Note: When initializing the price list at ESP startup, the ESP application should call eSE_PriceAddPriceEntry() with the address mode parameter set to E_ZCL_AM_NO_TRANSMIT, so that the price additions are not subsequently transmitted.
Note: A Price cluster server should take precautions to prevent clients from attempting to read the server price list during ESP initialization, before the prices have been received from the utility company. This can be achieved by adding the obtained prices to the server price list after the call to the relevant endpoint registration function (for example, eSE_RegisterEspEndPoint()) but before the call to ZPS_eAplZdoStartStack().
A price list is maintained in time order and if there is an active price, it is positioned at the head of the list (with index 0). Price lists on clients are updated to reflect the price list on the server, as described in Section 40.5.
Note: The Price cluster of ZigBee Smart Energy automatically deletes a price entry from a client or server price list immediately after the price event has expired. This is because the start-time of a price event is a universal time (UTC) and therefore corresponds to a one-off event. In practice, the price list may need a new price schedule daily, which may be provided by the utility company. Alternatively, if a similar schedule is required every day, the ESP application can keep a local copy of the schedule, which it can modify (e.g. start-times) and add to the price list on a daily basis.
The active price is always at the head of the price list (entry zero). The application should check that the entry at the head of the list is active before displaying it as the current price. If it is not active, a message may be displayed indicating that the current price is not known. The item at the head of the list is active if both of the following hold:
Its start time is less than or equal to the current time, obtained by u32ZCL_GetUTCTime()
The time on the client has been synchronized, i.e. a call to bZCL_GetTimeHasBeenSynchronised() returns TRUE
In addition to the function eSE_PriceAddPriceEntry(), the following functions allow an ESP application to access and manipulate its price list:
eSE_PriceGetPriceEntry() obtains the price entry with the specified index.
eSE_PriceDoesPriceEntryExist() checks whether there is a price entry with the specified start-time.
eSE_PriceRemovePriceEntry() deletes the price entry with the specified
start-time.
eSE_PriceClearAllPriceEntries() deletes all price entries in the list.
These functions are fully detailed in Section 40.9.
Parent topic:Price Cluster
Publishing price information
This section and its sub-sections describe the ways in which price information can be published (distributed) in a ZigBee network. As introduced in Section 40.1, there are three ways in which price information may be published to the network from the Price cluster server (ESP):
Unsolicited unicasts - refer to Section 40.5.1
Response to a Get Current Price command - refer to Section 40.5.2
Response to a Get Scheduled Prices command - refer to Section 40.5.3
All of the above methods require the ESP to send a Publish Price command to the relevant device(s), where the payload of this command includes information such as resource (for example, gas), unit of measure, currency, price, current time, start-time, and duration. On receipt of this command, if valid, the received price information is automatically added to the price list on the device. If it is successfully added, an E_SE_PRICE_TABLE_ADD event is generated on the receiving device and this event is handled by the callback function registered for the relevant endpoint.
Unsolicited Price Updates
When the ESP receives updated price information from the utility company (via the backhaul network) or a new price tier becomes active, the ESP must inform all network devices that are using the Price cluster. The ESP therefore individually unicasts a Publish Price command to all these devices. This command is sent out automatically - there is no need for the application on the ESP to explicitly send the command. In the case of new prices received from the utility company, the ESP application must call the function eSE_PriceAddPriceEntry() to add the new price to the price list held by the server, and the Publish Price command is then automatically sent out (possibly with a ‘start-time of now’). Note that if the stack has not been started when eSE_PriceAddPriceEntry() is called, the function’s address mode parameter should be set to E_ZCL_AM_NO_TRANSMIT, so that no transmission is attempted.
It is recommended that price updates on the ESP are relayed to Price cluster clients with which the ESP has been (previously) bound.
Note: Each of these bindings is initiated on the client node (e.g. IPD) using the ZigBee PRO stack function ZPS_eAplZdpBindUnbindRequest() to add the client’s address and endpoint to the Binding table on the ESP. Binding is described in the ZigBee 3.0 Stack User Guide (JNUG3130).
Therefore, when updating its price list, the ESP application should call eSE_PriceAddPriceEntry() with the address mode parameter set to E_ZCL_AM_BOUND, so that the price updates are transmitted only to bound endpoints/nodes.
As an alternative to using binding, the ESP can maintain a list of network nodes that are able to receive unsolicited Publish Price commands at all times - that is, nodes with radio receivers that remain active during idle periods (e.g. when sleeping). Unsolicited updates are then only sent to clients in this group. The ESP gathers information for this group from the Get Current Price commands received from clients (see Section40.5.2). This option requires the address node parameter to be set to ZPS_E_APL_AF_BROADCAST_RX_ON in eSE_PriceAddPriceEntry().
The ESP can send unsolicited Publish Price commands with ‘start-time of now’ when an E_SE_PRICE_TABLE_ACTIVE event indicates that a new price has become active (see Section 40.8). This command can be used by devices that do not implement a real-time clock.
Parent topic:Publishing price information
Get Current Price
Any device which supports the Price cluster can request the currently active price information from the ESP by sending a Get Current Price command. The function eSE_PriceGetCurrentPriceSend() allows a Price cluster client to send this command to the Price cluster server and deal with the response.
On receiving the command, the server automatically responds with a Publish Price command containing the requested price information.
On receiving the response, the client checks whether the received price information is currently in the client’s price list. If it is not, the client adds the new price information to the list and generates an E_SE_PRICE_TABLE_ADD event - this event is handled by the callback function registered for the relevant endpoint.
The Get Current Price command contains information on whether the radio receiver of the sending device remains active when the node is otherwise idle (e.g. sleeping). If this is true, the ESP application can use the address of the node to update a list of such devices, which it may use when sending out unsolicited Publish Price commands (see Section 40.5.1). The ESP application can extract this information from the event E_SE_PRICE_GET_CURRENT_PRICE_RECEIVED which is generated when a Get Current Price command is received by the server - this event is handled by the callback function registered for the relevant endpoint.
Parent topic:Publishing price information
Get Scheduled Prices
Any device which supports the Price cluster can request the current price schedule from the ESP by sending a Get Scheduled Prices command - the schedule includes a set of prices with their start-times and durations. The function eSE_PriceGetScheduledPricesSend() allows a Price cluster client to send this command to the Price cluster server and deal with the responses.
On receiving the command, the server automatically responds with a sequence of Publish Price commands, where each of these responses contains the information for one scheduled price.
On receiving a response, the client checks whether the received price information is currently in the client’s price list. If it is not, the client adds the new price information to the list and generates an E_SE_PRICE_TABLE_ADD event - this event is handled by the callback function registered for the relevant endpoint.
Parent topic:Publishing price information
Parent topic:Price Cluster
Time-synchronization via Publish Price commands
As an alternative to using the Time cluster to time-synchronize a ZigBee device with the ESP (as described in Section 18.5.3), the local application can use the time embedded in a Publish Price command from the ESP (see Section 40.5), as described below.
Note: A device that implements the Price cluster must also implement the Time cluster.
It is the responsibility of the application on a ZigBee device to perform time-synchronization with the ESP. This involves updating the ZCL time on the local device.
The initialization of the ZCL time on a device should be performed using the Time cluster by requesting the current time from the ESP, as described in Section 18.5.2 (this method also gets the time-zone and daylight saving information).
Subsequent re-synchronizations of a device with the time-master can use the time contained in Publish Price commands from the ESP (but note that no time-zone or daylight saving information is included). Therefore, a device can update its ZCL time whenever it receives a Publish Price command. On receiving this command, a ‘data indication’ stack event is generated, which causes a ZCL user task to be activated. The event is initially handled by this task as described in Chapter 3, resulting in an E_ZCL_ZIGBEE_EVENT event being passed to the ZCL via vZCL_EventHandler(). The ZCL invokes the relevant user-defined callback function (see Chapter 3) which, provided that the event is of the type E_SE_PRICE_TIME_UPDATE, must update the ZCL time using vZCL_SetUTCTime().
Note that the utctTime field of the local copy of the Time cluster is not updated, since this should only be done following a read of the Time cluster attributes from the server.
CAUTION:
If a device is handling Publish Price commands from more than one server, the time must only be updated with time events from one server, to prevent the time from jittering forwards and backwards if the servers’ times are not in sync.
The time-synchronization of a device (with the time-master) should be performed regularly. As a rule, if no Publish Price commands have been received from the ESP in the last 48 hours, the device should request the current time from the ESP and update its own times as described in Section 18.5.3.
It is worth noting that an undefined ZCL time causes the following issues in the Price cluster:
A Price cluster server without a ZCL time cannot issue any Publish Price commands, since the current time is a mandatory field of this command.
A Price cluster client without a ZCL time cannot process a Publish Price command with a ‘start-time of now’, unless the ZCL time is first set with the time extracted from the received command.
If the price at the head of the price list has a specified start-time, it is not possible to know whether this price is active or not.
Regarding the last point, a device should be time-synchronized with the ESP (as described in Section 18.5.2) before an attempt is made to add scheduled prices to the device’s price list. Then, if the device receives a scheduled price with a ‘start-time of now’, it is permissible to add this price to the list.
Parent topic:Price Cluster
Conversion factor and calorific value (gas only)
The Price cluster provides attributes related to conversion factor and calorific value for use with gas (only):
Conversion factor: Accounts for the variation of gas volume with temperature and pressure
Calorific value: Indicates the quantity of energy in MJ that is generated per unit volume or unit mass of gas burned
The attributes associated with the above properties are part of the ‘Commodity’ set - refer to Section 40.2.
If required, conversion factor and/or calorific value must be enabled in the compile-time options, as described in Section 40.13.
Conversion factors and calorific values can be independently scheduled with associated start-times. The Price cluster server (ESP) and clients each maintain a list of the scheduled conversion factors and a list of the scheduled calorific values (along with their start-times). The maximum number of entries in each list is by default 2 (allowing the present one and the next one to be stored), but this maximum can be re-defined in the compile-time options.
The ESP (Price cluster server) receives a scheduled conversion factor or calorific value from the utility company. A received value and its associated start-time are added as an entry to the relevant list on the server by the ESP application as follows:
A new entry is added to the conversion factor list by calling the function eSE_PriceAddConversionFactorEntry()
A new entry is added to the calorific value list by calling the function eSE_PriceAddCalorificValueEntry()
The entries are maintained in the list in increasing order of start-times. If an existing entry in the list has the same start-time as the new entry, the entry with the greater value of the Issuer Event ID is included in the list (and the other entry is discarded).
Once a new entry is added to a list on the server, a Publish Conversion Factor or Publish Calorific Value command is automatically sent to the cluster clients to inform them that a new value is available, allowing them to update their lists with the new information.
Initializing Conversion Factors and Calorific Values at Network Startup
Note the following issues at network startup:
When the ESP node first starts, there may be no other active nodes in the network to receive a new conversion factor and/or calorific value. Thus, the Price cluster clients should request this information from the ESP when they start. They can do this using eSE_PriceGetConversionFactorSend() or eSE_PriceGetCalorificValueSend(), as appropriate.
When initializing the conversion factor or calorific value at ESP startup, the ESP application should call eSE_PriceAddConversionFactorEntry() or eSE_PriceAddCalorificValueEntry() with the address mode parameter set to E_ZCL_AM_NO_TRANSMIT. This prevents the new value from being transmitted to a network with no other active nodes.
Any clients that are active during ESP initialization should not request a conversion factor or calorific value from the ESP before the values are received from the utility company. To avoid this problem, the ESP application should obtain the values from the utility company before calling the ZigBee PRO function ZPS_eAplZdoStartStack() and after calling the relevant endpoint register function (example, eSE_RegisterEspMeterEndPoint()).
Parent topic:Price Cluster
Price events
The Price cluster has its own events that are handled through the callback mechanism described in Chapter 3. If a device uses the Price cluster then Price event handling must be included in the callback function for the associated endpoint, where this callback function is registered through the relevant endpoint registration function (for example, through eSE_RegisterEspEndPoint() for a standalone ESP). The relevant callback function will then be invoked when a Price event occurs.
For a Price event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to a tsSE_PriceCallBackMessage structure which contains the Price parameters:
typedef struct
{
teSE_PriceCallBackEventType eEventType;
uint32 u32CurrentTime;
union {
tsSE_PriceTableCommand sPriceTableCommand;
tsSE_PriceTableTimeEvent sPriceTableTimeEvent;
teSE_PriceCommandOptions ePriceCommandOptions;
tsSE_PriceAckCmdPayload *psAckCmdPayload;
tsSE_PriceAttrReadInput sReadAttrInfo;
tsSE_BlockPeriodTableTimeEvent sBlockPeriodTableTimeEvent;
tsSE_ConversionFactorTableTimeEvent sConversionFactorTableTimeEvent;
tsSE_CalorificValueTableTimeEvent sCalorificValueTableTimeEvent;
} uMessage;
} tsSE_PriceCallBackMessage;
The eEventType field of the above structure specifies the type of Price event that has been generated - these event types are listed and described below (also refer to Section 40.12.2 for a summary of the Price events).
Note: The field sReadAttrInfo is reserved for future use (for Block mode).
E_SE_PRICE_TABLE_ADD
The E_SE_PRICE_TABLE_ADD event is generated on a Price cluster client when an attempt has been made to add a scheduled price (received in a Publish Price command) to the local price list. In the tsSE_PriceCallBackMessage structure, the u32CurrentTime field is set to the current time from the Publish Price command and the sPriceTableCommand field is used as follows:
typedef struct {
teSE_PriceStatus ePriceStatus;
} tsSE_PriceTableCommand;
ePriceStatus contains E_SE_PRICE_SUCCESS if a new price has been successfully added to the price list. Otherwise, the addition was rejected for the reason specified by ePriceStatus. If the addition was successful but the new price information overlapped (in time) any existing price information in the list, this previous price information may have been deleted from the list according to the rules in the ZigBee SE Profile specification.
E_SE_PRICE_TABLE_ACTIVE
The E_SE_PRICE_TABLE_ACTIVE event is generated when there is a new active price or the active price expires. This event can occur due to a time update or the reception of a Publish Price command from the server. In the tsSE_PriceCallBackMessage structure, the u32CurrentTime field is set to the current ZCL time and the sPriceTableTimeEvent field is used as follows:
typedef struct {
teSE_PriceStatus ePriceStatus;
uint8 u8NumberOfEntriesFree;
} tsSE_PriceTableTimeEvent;
ePriceStatus contains E_SE_PRICE_SUCCESS if there is a new active price or E_SE_PRICE_TABLE_NOT_YET_ACTIVE if the price at the head of the list is scheduled for a time in the future.
u8NumberOfEntriesFree contains the number of free entries in the client’s price list. This number can be used to determine whether the client should issue a new Get Scheduled Prices command, in order to obtain more price entries to fill the free space in the list.
E_SE_PRICE_GET_CURRENT_PRICE_RECEIVED
The E_SE_PRICE_GET_CURRENT_PRICE_RECEIVED event is generated on a Price cluster server when a Get Current Price command is received from a client. In the tsSE_PriceCallBackMessage structure, the ePriceCommandOptions field is used as follows:
typedef enum PACK
{
E_SE_PRICE_REQUESTOR_RX_ON_IDLE = 0x01 // LSB set
} teSE_PriceCommandOptions;
This field indicates whether the client that sent the request has its radio receiver enabled when idle (e.g. sleeping), and is used as described in Section 40.5.1 and Section 40.5.2.
E_SE_PRICE_TIME_UPDATE
The E_SE_PRICE_TIME_UPDATE event is generated on a Price cluster client when a Publish Price command is received from the server. In the tsSE_PriceCallBackMessage structure, the u32CurrentTime field is set to the current time from the Publish Price command. The application may then use this information to time-synchronise the device, as described in Section 40.6.
E_SE_PRICE_ACK_RECEIVED
The E_SE_PRICE_ACK_RECEIVED event is generated on a Price cluster server when a Price Acknowledgment command is received from a client. In the tsSE_PriceCallBackMessage structure, the psAckCmdPayload field is a pointer to the structure tsSE_PriceAckCmdPayload defined as follows:
typedef struct {
uint32 u32ProviderId;
uint32 u32IssuerEventId;
uint32 u32PriceAckTime;
uint8 u8Control;
} tsSE_PriceAckCmdPayload;
This structure contains the Price Acknowledgement command payload.
E_SE_PRICE_NO_PRICE_TABLES
The E_SE_PRICE_NO_PRICE_TABLES event is generated when an active price expires, is deleted from the price list and the price list becomes empty. In the tsSE_PriceCallBackMessage structure the sPriceTableTimeEvent field is used as follows:
typedef struct {
teSE_PriceStatus ePriceStatus;
uint8 u8NumberOfEntriesFree;
} tsSE_PriceTableTimeEvent;
ePriceStatus contains E_SE_PRICE_NO_TABLES.
u8NumberOfEntriesFree contains the number of free entries in the client’s price list. This number can be used to determine whether the client should issue a new Get Scheduled Prices command, in order to obtain more price entries to fill the free space in the list.
E_SE_PRICE_CONVERSION_FACTOR_TABLE_ACTIVE
The E_SE_PRICE_CONVERSION_FACTOR_TABLE_ACTIVE event is generated when a new conversion factor value becomes active - that is, when the start-time of the conversion factor entry becomes less than or equal to the present time. This event can occur due to a time update or the reception of a Publish Conversion Factor command from the server.
In the tsSE_PriceCallBackMessage structure, the u32CurrentTime field is set to the current ZCL time and the field tsSE_PriceConversionFactorTableTimeEvent is used as follows:
typedef struct {
teSE_PriceStatus eConversionFactorStatus;
uint8 u8NumberOfEntriesFree;
} tsSE_ConversionFactorTableTimeEvent;
eConversionFactorStatus takes the value E_ZCL_SUCCESS when a new conversion factor becomes active.
u8NumberOfEntriesFree contains the present number of free entries in the conversion factor list. This value should be checked by the client before issuing a Get Conversion Factor command to obtain a new conversion factor value - the command should be issued only if there is free space in the list for a new entry to be added.
E_SE_PRICE_CONVERSION_FACTOR_ADD
The E_SE_PRICE_CONVERSION_FACTOR_ADD event is generated when a new conversion factor entry is advertised by the ESP to the client application using the Publish Conversion Factor command. Note that the event is generated even when the new entry is not successfully added to the internal conversion factor list maintained by the cluster.
The status of the command is passed back to the user application in the ePriceStatus field of the tsSE_PriceTableCommand structure (see above) within the tsSE_PriceCallBackMessage structure.
E_SE_PRICE_CALORIFIC_VALUE_TABLE_ACTIVE
The E_SE_PRICE_CALORIFIC_VALUE_TABLE_ACTIVE event is generated when a new calorific value becomes active - that is, when the start-time of the calorific value entry becomes less than or equal to the present time. This event can occur due to a time update or the reception of a Publish Calorific Value command from the server.
In the tsSE_PriceCallBackMessage structure, the u32CurrentTime field is set to the current ZCL time and the field tsSE_PriceCalorificValueTableTimeEvent is used as follows:
typedef struct {
teSE_PriceStatus eCalorificValueStatus;
uint8 u8NumberOfEntriesFree;
} tsSE_CalorificValueTableTimeEvent;
eCalorificValueStatus takes the value E_ZCL_SUCCESS when a new calorific value becomes active.
u8NumberOfEntriesFree contains the present number of free entries in the calorific value list. This value should be checked by the client before issuing a Get Calorific Value command to obtain a new calorific value - the command should be issued only if there is free space in the list for a new entry to be added.
E_SE_PRICE_CALORIFIC_VALUE_ADD
The E_SE_PRICE_CALORIFIC_VALUE_ADD event is generated when a new calorific value entry is advertised by the ESP to the client application using the Publish Calorific Value command. Note that this event is generated even when the new entry is not successfully added to the internal calorific value list maintained by the cluster.
The status of the command is passed back to the user application in the ePriceStatus field of the tsSE_PriceTableCommand structure (see above) within the tsSE_PriceCallBackMessage structure.
Parent topic:Price Cluster
Functions
The following Price cluster functions are provided:
eSE_PriceCreate
teSE_PriceStatus eSE_PriceCreate(
bool_t bIsServer,
uint8 u8NumberOfRecordEntries,
uint8 *pu8AttributeControlBits,
uint8 *pau8RateLabel,
tsZCL_ClusterInstance *psClusterInstance,
tsZCL_ClusterDefinition *psClusterDefinition,
tsSE_PriceCustomDataStructure
*psCustomDataStructure,
tsSE_PricePublishPriceRecord
*psPublishPriceRecord,
void *pvEndPointSharedStructPtr);
Description
This function creates an instance of the Price cluster on an endpoint. The cluster instance is created on the endpoint which is associated with the supplied tsZCL_ClusterInstance structure and can act as a server or a client, as specified.
The function should only be called when setting up a custom endpoint containing one or more selected clusters (rather than the whole set of clusters supported by a standard ZigBee device). This function will create a Price cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions. For more details of creating cluster instances on custom endpoints, refer to Appendix D.
Note: This function must not be called for an endpoint on which a standard ZigBee device (e.g. IPD) will be used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function from those described in the ZigBee Devices User Guide (JNUG3131)
When used, this function must be the first Price cluster function called in the application, and must be called after the stack has been started and after the ZCL has been initialized.
The function requires an array to be declared for internal use, which contains one element (of type uint8) for each attribute of the cluster. The array length should therefore equate be the total number of attributes supported by the Price cluster, which can be obtained by using the macro PRICE_NUM_OF_ATTRIBUTES.
The array declaration should be as follows:
uint8 au8AppPriceClusterAttributeControlBits[PRICE_NUM_OF_ATTRIBUTES];
The function initializes the array elements to zero.
The function also requires an array of price labels to be declared, in which each array element is a label (string) for each price in the price list. The required declarations are different for a cluster server and client, as follows:
uint8 au8RateLabel[SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES][SE_PRICE_CLIENT_MAX_STRING_LENGTH];
uint8 au8RateLabel[SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES][SE_PRICE_CLIENT_MAX_STRING_LENGTH];
Parameters
bIsServer Type of cluster instance (server or client) to be created:
TRUE - server
FALSE - client
u8NumberOfRecordEntries Number of prices that can be stored in the price list, one of:
SE_PRICE_NUMBER_OF_SERVER_PRICE_RECORD_ENTRIES
SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES
pu8AttributeControlBits Pointer to an array of uint8 values, with one element for each attribute in the cluster (see above).
pau8RateLabel Pointer to an array of price labels (strings), with one element for each price in the price list (see above).
psClusterInstance Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16). This structure is updated by the function by initialising individual structure fields.
psClusterDefinition Pointer to structure indicating the type of cluster to be created (see Section 6.1.2). In this case, this structure must contain the details of the Price cluster. This parameter can refer to a pre-filled structure called
sCLD_Pricewhich is provided in the Price.h file.psCustomDataStructure Pointer to structure which contains custom data for the Price cluster. This structure is used for internal data storage. No knowledge of the fields of this structure is required
pvEndPointSharedStructPtr Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type
tsCLD_Pricewhich defines the attributes of Price cluster. The function initializes the attributes with default values.
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE
Parent topic:Functions
eSE_PriceGetCurrentPriceSend
teZCL_Status eSE_PriceGetCurrentPriceSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
teSE_PriceCommandOptions ePriceCommandOptions);
Description
This function can be used on a Price cluster client to send a Get Current Price command to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain the currently active price from the ESP.
The ESP should respond with a Publish Price command containing the active price. This response is processed by the Price cluster. The obtained price is checked against the prices currently in the price list on the client. If the price is not currently in the list, it is added to the list and an E_SE_PRICE_TABLE_ADD event is generated to indicate that a price has been added.
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId Number of the local endpoint through which the request is sent
u8DestinationEndPointId Number of the remote endpoint to which the request is sent
psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent
pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request
ePriceCommandOptions Indicates whether the radio receiver on client remains on when the device is idle (for example, asleep):
0x01 - receiver on when idle
0x00 - receiver off when idle
An enumeration is provided for the ‘on’ case:
E_SE_PRICE_REQUESTOR_RX_ON_IDLE
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
Parent topic:Functions
eSE_PriceGetScheduledPricesSend
teZCL_Status eSE_PriceGetScheduledPricesSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
uint32 u32StartTime,
int8 u8NumberOfEvents);
Description
This function can be used on a Price cluster client to send a Get Scheduled Prices command to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain the current price schedule from the ESP, either to check that its own price schedule is up-to-date or to recover the price schedule following a device reset.
You must specify the earliest start-time for the scheduled prices to be included in the results. This is normally set to zero or the current time (UTC). Note that you are not advised to specify the last time in the client price list, since the server may contain updates for prices covering an earlier time-period that are already in the client price list. You must also specify the maximum number of scheduled prices to be returned in the results.
The ESP should respond with multiple Publish Price commands containing the scheduled prices. Each response is processed by the Price cluster. The obtained price is checked against the prices currently in the price list on the client. If the price is not currently in the list, it is added to the list and an E_SE_PRICE_TABLE_ADD event is generated to indicate that a price has been added.
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId Number of the local endpoint through which the request is sent
u8DestinationEndPointId Number of the remote endpoint to which the request is sent
psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent
pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request
u32StartTime The earliest start-time of any prices to be returned - this is normally set to zero or the current time (UTC)
u8NumberOfEvents The maximum number of scheduled prices to be returned in the results - this should normally be set to: SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_ZBUFFER_FAIL
Parent topic:Functions
eSE_PriceAddPriceEntry
teSE_PriceStatus eSE_PriceAddPriceEntry(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
bool_t bOverwritePrevious,
tsSE_PricePublishPriceCmdPayload *psPricePayload,
uint8 *pu8TransactionSequenceNumber);
Description
This function can be used on the Price cluster server to add a price to the local price list. The function also sends an unsolicited Publish Price command containing the new price information to one or more remote endpoints. The function should be called on the ESP when a new price is received from the utility company.
On receiving the Publish Price command, a remote client will automatically add the new price to the local price list. However, you must specify the action to be taken if the time-period of the new price overlaps with the time-period of a price that is already in the client’s price list. You can choose to delete the existing price and add the new price, or leave the existing price in place and not add the new price. The rules on overlapping prices are defined in the ZigBee Smart Energy Profile specification.
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId Number of the local endpoint through which the request is sent
u8DestinationEndPointId Number of the remote endpoint to which the request is sent
psDestinationAddress Pointer to a structure containing the address of the remote node to which the Publish Price command is sent. It is recommended that the command is sent to all bound clients using a ZCL address mode of E_ZCL_AM_BOUND. If the stack has not been started, the E_ZCL_AM_NO_TRANSMIT address mode should be used
bOverwritePrevious Action to be taken if the new price overlaps (in time) a price which is already in the price list:
TRUE - existing price deleted, new price added
FALSE - new price not added and error returned
psPricePayload Pointer to a structure containing the price information to be added (see Section 40.11.1). This parameter only needs to remain in scope for the duration of this function call
pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the command
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE
E_ZCL_ERR_TIME_NOT_SYNCHRONISED
E_ZCL_ERR_INSUFFICIENT_SPACE
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_SE_PRICE_OVERFLOW
E_SE_PRICE_DUPLICATE
E_SE_PRICE_DATA_OLD
Parent topic:Functions
eSE_PriceAddPriceEntryToClient
teSE_PriceStatus eSE_PriceAddPriceEntryToClient(
uint8 u8SourceEndPointId,
bool_t bOverwritePrevious,
tsSE_PricePublishPriceCmdPayload *psPricePayload);
Description
This function can be used on a Price cluster client to add a price to the local price list directly.
Normally, price entries are automatically added to the price list on a client when a Publish Price command is received from the server (e.g. the ESP). However, this function can be used by the local application to directly add a price entry to the price list on the client. The function should therefore only be used on a device which does not receive price information from the server (but by some other means, such as via the Internet).
Parameters
u8SourceEndPointId Number of the local endpoint through which the request is sent
bOverwritePrevious Action to be taken if the new price overlaps (in time) a price which is already in the price list:
TRUE - existing price deleted, new price added
FALSE - new price not added and error returned
psPricePayload Pointer to a structure containing the price information to be added (see Section 40.11.1). This parameter only needs to remain in scope for the duration of this function call
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE
E_ZCL_ERR_TIME_NOT_SYNCHRONISED
E_ZCL_ERR_INSUFFICIENT_SPACE
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_SE_PRICE_OVERFLOW
E_SE_PRICE_DUPLICATE
E_SE_PRICE_DATA_OLD
Parent topic:Functions
eSE_PriceGetPriceEntry
teSE_PriceStatus eSE_PriceGetPriceEntry(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint8 u8TableIndex,
tsSE_PricePublishPriceCmdPayload **psPricePayload);
Description
This function can be used to obtain the entry with specified index from a price list on the local device. For example, the function can be used on an IPD to obtain a price to display.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
Parameters
u8SourceEndPointId Number of the local endpoint for the price list to be accessed
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server (for example, on ESP)
FALSE - client (for example, on IPD)
u8TableIndex The index of the price entry to obtain from the price list (index 0 is the entry with the oldest start-time and may contain the currently active price)
psPricePayload Pointer to a pointer to a structure which will be used to store the obtained price information (see Section 40.11.1), if found. The pointer value that is returned in this parameter points to the structure in the internal storage associated with the list. The data in the structure will be valid as long as the item remains in the list
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_TABLE_NOT_FOUND
Parent topic:Functions
eSE_PriceDoesPriceEntryExist
teSE_PriceStatus eSE_PriceDoesPriceEntryExist(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint32 u32StartTime);
Description
This function can be used to check whether a price entry with the specified start-time is present in a price list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
For a price entry to be successfully found, the specified start-time must exactly match the start-time of an entry in the price list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.
Parameters
u8SourceEndPointId Number of the local endpoint for the price list to be accessed
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
u32StartTime Start-time of the price entry to search for
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_NOT_FOUND
Parent topic:Functions
eSE_PriceRemovePriceEntry
teSE_PriceStatus eSE_PriceRemovePriceEntry(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint32 u32StartTime);
Description
This function can be used to delete a price entry with specified start-time from a price list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
For the successful deletion of a price entry, the specified start-time must exactly match the start-time of an entry in the price list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.
Parameters
u8SourceEndPointId Number of the local endpoint on which Price cluster resides
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
u32StartTime The start-time of the price entry to delete
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_NOT_FOUND
E_SE_PRICE_TABLE_NOT_FOUND
Parent topic:Functions
eSE_PriceClearAllPriceEntries
teSE_PriceStatus eSE_PriceClearAllPriceEntries(
uint8 u8SourceEndPointId,
bool_t bIsServer);
Description
This function can be used to delete all entries in a price list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
Parameters
u8SourceEndPointId Number of the local endpoint for the price list to be cleared
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
Parent topic:Functions
eSE_PriceAddConversionFactorEntry
teZCL_Status eSE_PriceAddConversionFactorEntry(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
bool_t bOverwritePrevious,
tsSE_PricePublishConversionCmdPayload
*psPublishConversionCmdPayload,
uint8 *pu8TransactionSequenceNumber);
Description
The function can be used on a Price cluster server to add a new conversion factor entry to the internal list of scheduled conversion factors maintained by the cluster. The function also sends an unsolicited Publish Conversion Factor command to the Price cluster client nodes in the network, to advertise the new conversion factor. Therefore, the function should be called on the ESP when a new conversion factor is received from the utility company.
On receiving the Publish Conversion Factor command, a remote client automatically adds the new conversion factor to the local conversion factor list. However, if the new entry has the same start-time as an existing entry in the list, the outcome depends on the setting of the boolean parameter bOverwritePrevious in this function:
If this parameter is set to TRUE then the existing entry is removed and the new entry is added
If this parameter is set to FALSE then the Issuer Event IDs of the two conversion factor entries are compared:
If the Event ID of the new entry is the greater, the existing entry is removed and the new entry is added
If the Event ID of the existing entry is the greater, E_ZCL_FAIL is returned and the list is not modified
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId Number of the local endpoint through which the request is sent
u8DestinationEndPointId Number of the remote endpoint to which the request is sent
psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent
bOverwritePrevious Determines whether an existing conversion factor with the same start-time on the clients will be over-written without comparing Event IDs (see above):
TRUE - over-write existing entry
FALSE - compare Event IDs first
psPublishConversionCmdPayload Pointer to conversion factor entry to be added to list on server and advertised to clients
pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_TIME_NOT_SYNCHRONISED
Parent topic:Functions
eSE_PriceGetConversionFactorSend
teZCL_Status eSE_PriceGetConversionFactorSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
uint32 u32StartTime,
uint8 u8NumberOfEvents);
Description
The function can be used on a Price cluster client to send a Get Conversion Factor request to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain scheduled conversion factor values from the ESP. The function allows scheduled conversion factors to be obtained with start-times greater than or equal to a specified time, u32StartTime.
The ESP should respond with a Publish Conversion Factor command containing up to u8NumberOfEvent scheduled conversion factor values. The Price cluster on the receiving client processes the response by updating the local conversion factor list, as follows. For each conversion factor received in the response, the event E_SE_PRICE_CONVERSION_FACTOR_ADD is generated.
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId Number of the local endpoint through which the request is sent
u8DestinationEndPointId Number of the remote endpoint to which the request is sent
psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent
pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request
u32StartTime Earliest start-time of scheduled conversion factors to be returned - a setting of 0 returns the factor that is currently active and factors with start-times in the future
u8NumberOfEvents Maximum number of conversion factors to be returned as a result of this request
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZTRANSMIT_FAIL
Parent topic:Functions
eSE_PriceGetConversionFactorEntry
teSE_PriceStatus eSE_PriceGetConversionFactorEntry(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint8 u8TableIndex,
sSE_PricePublishConversionCmdPayload
**ppsPublishConversionCmdPayload);
Description
This function can be used to obtain the entry with the specified index from the conversion factor list on the local device. For example, the function can be used on an IPD to obtain a conversion factor to display.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
Parameters
u8SourceEndPointId: Number of the local endpoint for the conversion factor list to be accessed
bIsServer: Nature of the Price cluster instance containing the list:
TRUE - server (example on ESP)
FALSE - client (example on IPD)
u8TableIndex: The index of the entry to obtain from the conversion factor list (index 0 is the entry with the oldest start-time and may contain the currently active conversion factor)
ppsPublishConversionCmdPayload: Pointer to a pointer to a structure which will be used to store the obtained conversion factor information (see Section40.11.2), if found. The pointer value that is returned in this parameter points to the structure in the internal storage associated with the list. The data in the structure will be valid as long as the item remains in the list
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_TABLE_NOT_FOUND
Parent topic:Functions
eSE_PriceDoesConversionFactorEntryExist
teSE_PriceStatus eSE_PriceDoesConversionFactorEntryExist(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint32 u32StartTime);
Description
This function can be used to check whether a conversion factor entry with the specified start-time is present in a conversion factor list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
For a conversion factor entry to be successfully found, the specified start-time must exactly match the start-time of an entry in the conversion factor list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.
Parameters
u8SourceEndPointId Number of the local endpoint for the conversion factor list to be accessed
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
u32StartTime Start-time of the conversion factor entry to search for
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_NOT_FOUND
Parent topic:Functions
eSE_PriceRemoveConversionFactorEntry
teSE_PriceStatus eSE_PriceRemoveConversionFactorEntry(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint32 u32StartTime);
Description
This function can be used to delete a conversion factor entry with specified start-time from conversion factor list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
For the successful deletion of a conversion factor entry, the specified start-time must exactly match the start-time of an entry in the conversion factor list, otherwise the status code E_SE_PRICE_NOT_FOUND is returned.
Parameters
u8SourceEndPointId Number of the local endpoint for the conversion factor list to be accessed
bIsServer Nature of the Price cluster instance containing the list:
TRUE - server
FALSE - client
u32StartTime The start-time of the conversion factor entry to delete
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_NOT_FOUND
E_SE_PRICE_TABLE_NOT_FOUND
Parent topic:Functions
eSE_PriceClearAllConversionFactorEntries
teSE_PriceStatus eSE_PriceClearAllConversionFactorEntries(
uint8 u8SourceEndPointId,
bool_t bIsServer);
Description
This function can be used to delete all entries in a conversion factor list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
Parameters
u8SourceEndPointId Number of the local endpoint for the conversion factor list to be cleared
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
Parent topic:Functions
eSE_PriceAddCalorificValueEntry
teZCL_Status eSE_PriceAddCalorificValueEntry(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
bool_t bOverwritePrevious,
tsSE_PricePublishCalorificValueCmdPayload
*psPublishCalorificValueCmdPayload,
uint8 *pu8TransactionSequenceNumber);
Description
The function can be used on a Price cluster server to add a calorific value entry to the internal list of scheduled calorific values maintained by the cluster. The function also sends an unsolicited Publish Calorific Value command to the Price cluster client nodes in the network, to advertise the new calorific value. Therefore, the function should be called on the ESP when a new calorific value is received from the utility company.
On receiving the Publish Calorific Value command, a remote client automatically adds the new calorific value to the local calorific value list. However, if the new entry has the same start-time as an existing entry in the list, the outcome depends on the setting of the boolean parameter bOverwritePrevious in this function:
If this parameter is set to TRUE then the existing entry is removed and the new entry is added
If this parameter is set to FALSE then the Issuer Event IDs of the two calorific value entries are compared:
If the Event ID of the new entry is the greater, the existing entry is removed and the new entry is added
If the Event ID of the existing entry is the greater, E_ZCL_FAIL is returned and the list is not modified
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId: Number of the local endpoint through which the request is sent
u8DestinationEndPointId: Number of the remote endpoint to which the request is sent
psDestinationAddress: Pointer to a structure containing the address of the remote node to which the request is sent
bOverwritePrevious: Determines whether an existing calorific value with the same start-time on the clients will be over-written without comparing Event IDs (see above):
TRUE - over-write existing entry
FALSE - compare Event IDs first
psPublishCalorificValueCmdPayload Pointer to calorific value entry to be added to list on server and advertised to clients
pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_TIME_NOT_SYNCHRONISED
Parent topic:Functions
eSE_PriceGetCalorificValueSend
teZCL_Status eSE_PriceGetCalorificValueSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
uint32 u32StartTime,
uint8 u8NumberOfEvents);
Description
The function can be used on a Price cluster client to send a Get Calorific Value request to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain scheduled calorific values from the ESP. The function allows scheduled calorific values to be obtained with start-times greater than or equal to a specified time, u32StartTime.
The ESP should respond with a Publish Calorific Value command containing up to u8NumberOfEvent scheduled calorific values. The Price cluster on the receiving client processes the response by updating the local calorific value list, as follows. For each calorific value received in the response, the event E_SE_PRICE_CALORIFIC_VALUE_ADD is generated.
A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.
Parameters
u8SourceEndPointId: Number of the local endpoint through which the request is sent
u8DestinationEndPointId: Number of the remote endpoint to which the request is sent
psDestinationAddress: Pointer to a structure containing the address of the remote node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request
u32StartTime: Earliest start-time of scheduled calorific values to be returned - a setting of 0 returns the value that is currently active and values with start-times in the future
u8NumberOfEvents: Maximum number of calorific values to be returned as a result of this request
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZTRANSMIT_FAIL
Parent topic:Functions
eSE_PriceGetCalorificValueEntry
teSE_PriceStatus eSE_PriceGetCalorificValueEntry(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint8 u8TableIndex,
sSE_PricePublishCalorificValueCmdPayload
**ppsPublishCalorificValueCmdPayload);
Description
This function can be used to obtain the entry with the specified index from the calorific value list on the local device. For example, the function can be used on an IPD to obtain a calorific value to display.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
Parameters
u8SourceEndPointId Number of the local endpoint for the calorific value list to be accessed
bIsServer Nature of the Price cluster instance containing the list:
TRUE - server (example on ESP)
FALSE - client (example on IPD)
u8TableIndex The index of the entry to obtain from the calorific value list (index 0 is the entry with the oldest start-time and may contain the currently active calorific value)
**ppsPublishCalorificValueCmdPayload: Pointer to a pointer to a structure which will be used to store the obtained calorific value information (see Section 40.11.3), if found. The pointer value that is returned in this parameter points to the structure in the internal storage associated with the list. The data in the structure will be valid as long as the item remains in the list
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_TABLE_NOT_FOUND
Parent topic:Functions
eSE_PriceDoesCalorificValueEntryExist
teSE_PriceStatus eSE_PriceDoesCalorificValueEntryExist(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint32 u32StartTime);
Description
This function can be used to check whether a calorific value entry with the specified start-time is present in a calorific value list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
For a calorific value entry to be successfully found, the specified start-time must exactly match the start-time of an entry in the calorific value list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.
Parameters
u8SourceEndPointId Number of the local endpoint for the calorific value list to be accessed
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
u32StartTime Start-time of the calorific value entry to search for
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_NOT_FOUND
Parent topic:Functions
eSE_PriceRemoveCalorificValueEntry
teSE_PriceStatus eSE_PriceRemoveCalorificValueEntry(
uint8 u8SourceEndPointId,
bool_t bIsServer,
uint32 u32StartTime);
Description
This function can be used to delete a calorific value entry with specified start-time from calorific value list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
For the successful deletion of a calorific value entry, the specified start-time must exactly match the start-time of an entry in the calorific value list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.
Parameters
u8SourceEndPointId Number of the local endpoint for the calorific value list to be accessed
bIsServer Nature of the Price cluster instance containing the list:
TRUE - server
FALSE - client
u32StartTime Start-time of the calorific value entry to delete
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_SE_PRICE_NOT_FOUND
E_SE_PRICE_TABLE_NOT_FOUND
Parent topic:Functions
eSE_PriceClearAllCalorificValueEntries
teSE_PriceStatus eSE_PriceClearAllCalorificValueEntries(
uint8 u8SourceEndPointId,
bool_t bIsServer);
Description
This function can be used to delete all entries in a calorific value list on the local device.
You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.
Parameters
u8SourceEndPointId Number of the local endpoint for the calorific value list to be cleared
bIsServer Nature of the Price cluster instance containing the price list:
TRUE - server
FALSE - client
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
Parent topic:Functions
Parent topic:Price Cluster
Return codes
In addition to some of the ZCL status enumerations, the following enumerations are returned by Price cluster functions (see Section 40.9) to indicate the outcome of the function call.
typedef enum PACK
{
E_SE_PRICE_OVERLAP =0x80,
E_SE_PRICE_TABLE_NOT_YET_ACTIVE,
E_SE_PRICE_DATA_OLD,
E_SE_PRICE_NOT_FOUND,
E_SE_PRICE_TABLE_NOT_FOUND,
E_SE_PRICE_OVERFLOW,
E_SE_PRICE_DUPLICATE,
E_SE_PRICE_NO_TABLES,
E_SE_PRICE_BLOCK_PERIOD_TABLE_NOT_YET_ACTIVE,
E_SE_PRICE_NO_BLOCKS,
E_SE_PRICE_NUMBER_OF_BLOCK_THRESHOLD_MISMATCH,
E_SE_BLOCK_PERIOD_OVERFLOW,
E_SE_BLOCK_PERIOD_DUPLICATE,
E_SE_BLOCK_PERIOD_DATA_OLD,
E_SE_BLOCK_PERIOD_OVERLAP,
E_SE_PRICE_STATUS_ENUM_END
} teSE_PriceStatus;
The above enumerations are described in the table below.
Enumeration |
Description |
|---|---|
E_SE_PRICE_OVERLAP |
New price overlaps (in time) with existing price in price list |
E_SE_PRICE_TABLE_NOT_YET_ACTIVE |
No active price at head of price list |
E_SE_PRICE_DATA_OLD |
Attempt made to add price which overlaps (in time) with existing price in price list and which is older than existing price * |
E_SE_PRICE_NOT_FOUND |
Specified price was not found in price list |
E_SE_PRICE_TABLE_NOT_FOUND |
Specified price list was not found |
E_SE_PRICE_OVERFLOW |
Attempt to add price to price list failed because end-time for new price (start-time + duration x 60) exceeds maximum permissible time value of 0xFFFFFFFFF (UTC) |
E_SE_PRICE_DUPLICATE |
Specified price information already exists in price list |
E_SE_PRICE_NO_TABLES |
Reserved for future use (for Block mode) |
E_SE_PRICE_BLOCK_PERIOD_TA-BLE_NOT_YET_ACTIVE |
Reserved for future use (for Block mode) |
E_SE_PRICE_NO_BLOCKS |
Reserved for future use (for Block mode) |
E_SE_PRICE_NUMBER_OF_BLOCK_THRESHOLD_MISMATCH |
Reserved for future use (for Block mode) |
E_SE_BLOCK_PERIOD_OVERFLOW |
Reserved for future use (for Block mode) |
E_SE_BLOCK_PERIOD_DUPLICATE |
Reserved for future use (for Block mode) |
E_SE_BLOCK_PERIOD_DATA_OLD |
Reserved for future use (for Block mode) |
E_SE_BLOCK_PERIOD_OVERLAP |
Reserved for future use (for Block mode) |
* Value of u32IssuerEventId in tsSE_PricePublishPriceCmdPayload structure (see Section 40.11.1) is less for the price to be added than for the existing (overlapping) price.
Parent topic:Price Cluster
Structures
tsSE_PricePublishPriceCmdPayload
This structure is used to hold price information to be added to a price list of a Price cluster:
typedef struct {
uint8 u8UnitOfMeasure;
uint8 u8PriceTrailingDigitAndPriceTier;
uint8 u8NumberOfPriceTiersAndRegisterTiers;
uint8 u8PriceRatio;
uint8 u8GenerationPriceRatio;
uint8 u8AlternateCostUnit;
uint8 u8AlternateCostTrailingDigit;
uint8 u8NumberOfBlockThresholds;
uint8 u8PriceControl;
uint16 u16Currency;
uint16 u16DurationInMinutes;
uint32 u32ProviderId;
uint32 u32IssuerEventId;
uint32 u32StartTime;
uint32 u32Price;
uint32 u32GenerationPrice;
uint32 u32AlternateCostDelivered;
tsZCL_OctetString sRateLabel;
} tsSE_PricePublishPriceCmdPayload;
where:
u8UnitOfMeasureindicates the resource (e.g. electricity) and unit of measure (e.g. kWh) for the pricing (see Section 42.10.3)u8PriceTrailingDigitAndPriceTieris an 8-bit bitmap indicating the price tier and the number of digits after the decimal point in the price:The 4 most significant bits give the number of digits to the right of the decimal point in the price
The 4 least significant bits give the price tier in the range 1 to 6
u8NumberOfPriceTiersAndRegisterTiersis an 8-bit bitmap indicating the number of price tiers available and the particular tier that the price information in the structure relates to:The 4 most significant bits give the number of available price tiers in the range 0 to 6
The 4 least significant bits give the price tier used in the range 1 to 6
(this value must be less than or equal to the value in the 4 leading bits)
u8PriceRatio(optional) is the ratio of the price quoted inu32Priceto the ‘normal’ price offered by the utility company. The actual price ratio should be multiplied by 10 for encoding this field, so that a field value of 0x01 represents 0.1 and 0xFE represents 25.4, while 0xFF indicates that the field is not usedu8GenerationPriceRatio(optional) is the ratio of the price quoted inu32GenerationPriceto the ‘normal’ price offered by the utility company. The actual price ratio should be multiplied by 10 for encoding this field, so that a field value of 0x01 represents 0.1 and 0xFE represents 25.4, while 0xFF is reserved to indicate that the field is not usedu8AlternateCostUnit(optional) is an 8-bit bitmap indicating the unit for the alternative cost inu32AlternateCostDelivered. Currently, the only supported unit is kilograms of CO2, indicated by the value 0x01u8AlternateCostTrailingDigit(optional) is an 8-bit bitmap in which the 4 most significant bits indicate the number of digits after the decimal point inu32AlternateCostDelivered(the 4 least significant bits are reserved)u8NumberOfBlockThresholdsis reserved for future use (for Block mode)u8PriceControlis reserved for future use (for Block mode)u16Currencyindicates the currency (e.g. Euro) used for the price - this field should be set to the appropriate value defined by ISO 4217u16DurationInMinutesindicates the duration, in minutes, for which the price will be valid (0xFFFF indicates that price will remain valid until changed)u32ProviderIdis an identifier for the utility companyu``32IssuerEventIdis a unique identifier for the price information - the higher its value, the more recently the price information was issued (a UTC time-stamp could be used in this field)u``32StartTimeindicates the start-time (UTC) for the price, in seconds. The special value 0x00000000 denotes a start-time of ‘now’u``32Priceis the resource price per unit indicated inu8UnitOfMeasure, expressed in the currency indicated inu16Currency, with the position of the decimal point as indicated inu8PriceTrailingDigitAndPriceTie``ru``32GenerationPrice(optional) is the resource price per unit indicated inu8UnitOfMeasure, expressed in the currency indicated inu16Currencyand with the position of the decimal point as indicated inu8PriceTrailingDigitAndPriceTier, for a resource that is generated on the customer premises and supplied to the utility company (e.g. solar-sourced electric power supplied to the national grid). A value of 0xFFFFFFFF indicates that this field is not usedu32AlternateCostDelivered(optional) indicates an alternative cost (per resource consumption unit) which is measured by a means other than monetary - for example, the amount of CO2 emitted per unit of gas consumed This alternative cost is interpreted as specified byu8AlternateCostUnitandu8AlternateCostTrailingDigitsRateLabelis a string of up to 12 characters containing a label for the price information in the structure
Parent topic:Structures
tsSE_PricePublishConversionCmdPayload
This structure is used to hold information to be added to a conversion factor list of a Price cluster:
typedef struct {
uint32 u32IssuerEventId;
uint32 u32StartTime;
uint32 u32ConversionFactor;
zbmap8 u8ConversionFactorTrailingDigit;
}tsSE_PricePublishConversionCmdPayload;
where:
u32IssuerEventIdis a unique identifier for the conversion factor information - the higher the value, the more recently the information was issuedu32StartTimeis the start-time of the conversion factor value. This is the time at which the conversion factor value is scheduled to become activeu32ConversionFactoris used only for gas and accounts for the variation in the volume of gas with temperature and pressure (the value is dimensionless)u8ConversionFactorTrailingDigitis an 8-bit bitmap which indicates the location of the decimal point in theu32ConversionFactorfield. The most significant 4 bits indicate the number of digits after the decimal point. The remaining bits are reserved
Parent topic:Structures
tsSE_PricePublishCalorificValueCmdPayload
This structure is used to hold information to be added to a calorific value list of the Price cluster:
typedef struct {
zenum8 u8CalorificValueUnit;
zbmap8 u8CalorificValueTrailingDigit;
uint32 u32IssuerEventId;
uint32 u32StartTime;
uint32 u32CalorificValue;
}tsSE_PricePublishCalorificValueCmdPayload;
where:
u8CalorificValueUnitis an 8-bit enumerated value which defines the unit for theu32CalorificValuefield (below). It indicates whether the calorific value is quantified per unit volume or per unit mass - see Section 40.12.3.u8CalorificValueTrailingDigitis an 8-bit bitmap which indicates the location of the decimal point in theu32CalorificValuefield (below). The most significant 4 bits indicate the number of digits after the decimal point. The remaining bits are reservedu32IssuerEventIdis a unique identifier for the calorific value information - the higher the value, the more recently the information was issuedu32StartTimeis the start-time of the calorific value. This is the time at which the conversion factor value is scheduled to become activeu32CalorificValueis used only for gas and indicates the quantity of energy in MJ that is generated per unit volume or unit mass of gas burned (seeu8CalorificValueUnit). The position of the decimal point is indicated byu8CalorificValueTrailingDigitdescribed above
Parent topic:Structures
Parent topic:Price Cluster
Enumerations
‘Attribute ID’ Enumerations
The following structure contains the enumerations used to identify the attributes of the Price cluster.
Note: Only the Tier Label attributes are currently used. The remaining attributes are reserved for future use (for Block mode).
typedef enum PACK
{
/*Price Cluster Attribute Tier Price Label Set Attr Ids (D.4.2.2.1)*/
E_CLD_P_ATTR_TIER_1_PRICE_LABEL = 0x0000,
E_CLD_P_ATTR_TIER_2_PRICE_LABEL,
...
...
E_CLD_P_ATTR_TIER_15_PRICE_LABEL,
/*Price Cluster Attribute Block Threshold Set Attr IDs (D.4.2.2.2)*/
E_CLD_P_ATTR_BLOCK1_THRESHOLD = 0x0100,
E_CLD_P_ATTR_BLOCK2_THRESHOLD,
...
...
E_CLD_P_ATTR_BLOCK15_THRESHOLD,
/*Price Cluster Attribute Block Period Set Attr IDs (D.4.2.2.3)*/
E_CLD_P_ATTR_START_OF_BLOCK_PERIOD = 0x0200,
E_CLD_P_ATTR_BLOCK_PERIOD_DURATION,
E_CLD_P_ATTR_THRESHOLD_MULTIPLIER,
E_CLD_P_ATTR_THRESHOLD_DIVISOR,
/*Price Cluster Attribute Commodity Set Attr IDs (D.4.2.2.4)*/
E_CLD_P_ATTR_COMMODITY_TYPE = 0x0300,
E_CLD_P_ATTR_STANDING_CHARGE,
E_CLD_P_ATTR_CONVERSION_FACTOR,
E_CLD_P_ATTR_CONVERSION_FACTOR_TRAILING_DIGIT,
E_CLD_P_ATTR_CALORIFIC_VALUE,
E_CLD_P_ATTR_CALORIFIC_VALUE_UNIT,
E_CLD_P_ATTR_CALORIFIC_VALUE_TRAILING_DIGIT,
/* Price Cluster Attribute Block Price Information Set Attr IDs (D.4.2.2.5)*/
E_CLD_P_ATTR_NOTIER_BLOCK1_PRICE = 0x0400,
E_CLD_P_ATTR_NOTIER_BLOCK2_PRICE,
...
...
E_CLD_P_ATTR_NOTIER_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER1_BLOCK1_PRICE = 0x0410,
...
E_CLD_P_ATTR_TIER1_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER2_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER2_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER3_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER3_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER4_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER4_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER5_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER5_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER6_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER6_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER7_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER7_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER8_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER8_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER9_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER9_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER10_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER10_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER11_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER11_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER12_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER12_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER13_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER13_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER14_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER14_BLOCK16_PRICE,
E_CLD_P_ATTR_TIER15_BLOCK1_PRICE,
...
E_CLD_P_ATTR_TIER15_BLOCK16_PRICE
/* Price Cluster Billing Period Information Set Attr IDs */
E_CLD_P_ATTR_START_OF_BILLING_PERIOD = 0x700,
E_CLD_P_ATTR_BILLING_PERIOD_DURATION
} teCLD_SM_PriceAttributeID;
Parent topic:Enumerations
‘Price Event’ Enumerations
The event types generated by the Price cluster are enumerated in the teSE_PriceCallBackEventType structure below:
typedef enum PACK
{
E_SE_PRICE_TABLE_ADD =0x00,
E_SE_PRICE_TABLE_ACTIVE,
E_SE_PRICE_GET_CURRENT_PRICE_RECEIVED,
E_SE_PRICE_TIME_UPDATE,
E_SE_PRICE_ACK_RECEIVED,
E_SE_PRICE_NO_PRICE_TABLES,
E_SE_PRICE_READ_BLOCK_PRICING,
E_SE_PRICE_BLOCK_PERIOD_TABLE_ACTIVE,
E_SE_PRICE_NO_BLOCK_PERIOD_TABLES,
E_SE_PRICE_BLOCK_PERIOD_ADD,
E_SE_PRICE_READ_BLOCK_THRESHOLDS,
E_SE_PRICE_CONVERSION_FACTOR_TABLE_ACTIVE,
E_SE_PRICE_CONVERSION_FACTOR_ADD,
E_SE_PRICE_CALORIFIC_VALUE_TABLE_ACTIVE,
E_SE_PRICE_CALORIFIC_VALUE_ADD,
E_SE_PRICE_CBET_ENUM_END
} teSE_PriceCallBackEventType;
The above event types are described in Table 56 below.
Note: For further details on Price events, refer to Section 40.8.
Event Type Enumeration |
Description |
|---|---|
E_SE_PRICE_TABLE_ADD |
Generated when a new scheduled price is added to the local price list |
E_SE_PRICE_TABLE_ACTIVE |
Generated when a new price becomes active or the active price expires |
E_SE_PRICE_GET_CURRENT_PRICE_RECEIVED |
Generated on the server when a Get Current Price command is received from a client |
E_SE_PRICE_TIME_UPDATE |
Generated on a client when a Publish Price command is received from the server |
E_SE_PRICE_ACK_RECEIVED |
Generated on a server when a Price Acknowledgment command is received from a client |
E_SE_PRICE_NO_PRICE_TABLES |
Generated when an active price expires, is deleted from the price list and the list becomes empty |
E_SE_PRICE_READ_BLOCK_PRICING |
Reserved for future use (for Block mode) |
E_SE_PRICE_BLOCK_PERIOD_TABLE_ACTIVE |
Reserved for future use (for Block mode) |
E_SE_PRICE_NO_BLOCK_PERIOD_TABLES |
Reserved for future use (for Block mode) |
E_SE_PRICE_BLOCK_PERIOD_ADD |
Reserved for future use (for Block mode) |
E_SE_PRICE_READ_BLOCK_THRESHOLDS |
Reserved for future use (for Block mode) |
E_SE_PRICE_CONVERSION_FACTOR_TABLE_ACTIVE |
Generated when a new conversion factor value becomes active |
E_SE_PRICE_CONVERSION_FACTOR_ADD |
Generated when a new conversion factor entry is advertised by the ESP via a Publish Conversion Factor command |
E_SE_PRICE_CALORIFIC_VALUE_TABLE_ACTIVE |
Generated when a new calorific value becomes active |
E_SE_PRICE_CALORIFIC_VALUE_ADD |
Generated when a new calorific value entry is advertised via a Publish Calorific Value command |
Parent topic:Enumerations
‘Calorific Value Unit’ Enumerations
The possible units for the calorific value attribute of the Price cluster are enumerated in the tsSE_PriceCalorificValueUnits structure below:
typedef enum PACK
{
E_SE_MEGA_JOULES_METER_CUBE = 0x01,
E_SE_MEGA_JOULES_KILOGRAM = 0x02
} tsSE_PriceCalorificValueUnits;
The above enumerations are described in Table 57 below.
Enumeration |
Description |
|---|---|
E_SE_MEGA_JOULES_METER_CUBE |
Calorific value measured in MJ/m3 |
E_SE_MEGA_JOULES_KILOGRAM |
Calorific value measured in MJ/kg |
Parent topic:Enumerations
Parent topic:Price Cluster
Compile-time options
This section describes the compile-time options that may be enabled in the zcl_options.h file of an application that uses the Price cluster.
The Price cluster is enabled by defining CLD_PRICE.
Client and server versions of the cluster are defined by PRICE_CLIENT and PRICE_SERVER, respectively.
Price List Size
The maximum number of prices that can be stored in the price list on a server and client defaults to five and two respectively. These default values can be over-ridden by assigning values to the corresponding macro below:
SE_PRICE_NUMBER_OF_SERVER_PRICE_RECORD_ENTRIES
SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES
Price Tier Label Attribute Set
The maximum number of supported Price Tier Label Attribute Sets can be defined by assigning a value between 1 and 15 (inclusive) to CLD_P_ATTR_TIER_PRICE_LABEL_MAX_COUNT.
Block Threshold Attribute Set
The maximum number of supported Block Threshold Attribute Sets can be defined by assigning a value between 1 to 15 (inclusive) to CLD_P_ATTR_BLOCK_THRESHOLD_MAX_COUNT.
Block Price Information Attribute Set
The maximum number of supported Block Price Information Attribute Sets can be defined by assigning a value (the maximum of which is shown below in brackets) to each of the following:
CLD_P_ATTR_NO_TIER_BLOCK_PRICES_MAX_COUNT (16)
CLD_P_ATTR_NUM_OF_TIERS_PRICE (15)
CLD_P_ATTR_NUM_OF_BLOCKS_IN_EACH_TIER_PRICE (16)
Conversion Factor (Gas Only)
Conversion factor in the Price cluster is enabled by defining the macro PRICE_CONVERSION_FACTOR.
The attributes for conversion factor are enabled by defining the following macros:
CLD_P_ATTR_CONVERSION_FACTOR
CLD_P_ATTR_CONVERSION_FACTOR_TRAILING_DIGIT
The default value of the maximum number of entries that can be stored in the conversion factor list which is maintained on the Price cluster server and client is 2. This value can be over-ridden by assigning another value to the macro:
SE_PRICE_NUMBER_OF_CONVERSION_FACTOR_ENTRIES
Calorific Value (Gas Only)
Calorific value in the Price cluster is enabled by defining the macro PRICE_CALORIFIC_VALUE.
The attributes for calorific value are enabled by defining the following macros:
CLD_P_ATTR_CALORIFIC_VALUE
CLD_P_ATTR_CALORIFIC_VALUE_UNIT
CLD_P_ATTR_CALORIFIC_VALUE_TRAILING_DIGIT
The default value of the maximum number of entries that can be stored in the calorific value list which is maintained on the server and client is 2. This value can be over-ridden by assigning another value to the macro:
SE_PRICE_NUMBER_OF_CALORIFIC_VALUE_ENTRIES
Parent topic:Price Cluster