Upload
melinda-ball
View
221
Download
0
Tags:
Embed Size (px)
Citation preview
HAN Coordination Update to HAN Coordination Update to Advanced Metering Advanced Metering
Implementation TeamImplementation Team
Prepared and Presented by Prepared and Presented by Jay FolianoJay Foliano
April 24April 24thth 2012 2012
Update OverviewUpdate Overview
• HAN Task Force• Market Awareness & Outreach• National Standards• Call Center Scripts• HAN Documentation Effort• Questions & Comments
2
HAN Support DesignHAN Support Design
HANInitiatives
DocumentationJoselito
HAN Task Force
Jay
Market Awareness
Jay
National Standards
EnerNex - TBD
ScriptsDon
Smallwood
-RMS/AMIT – 04/19/12
TDSP’s ROR/REP/3rd Party/Mfg
HAN Task Force:HAN Task Force:
• HAN Support Model, Milestones:– Workshop, 4/12, TDSP’s and Market Participants
Defined the detailed operational requirements:• Support center responsibilities and scenarios• Level one troubleshooting• Support center triage and hand off processes• Issue Handling Standards, i.e. triage punch list • Customer information captured • Escalation Process and Procedures• Short and Long Term Objectives phased and scalable • Expectations of SLO’s
4
HAN Task ForceHAN Task Force– HAN Support Model, Next Steps:
• Validate and finalize the session requirements, documents and buy-in
• Present findings to OWG for input and buy-in• Present to AMIT to outline the Implementation steps and
recommended oversight/ownership • Commence phased implementation Q2
• HAN Score Card Report to Define:• Report Title, Access Method and Market Awareness• Owner/Gate-Keeper CRITICAL • Frequency• Process and Procedure for Device Testing and updating
5
Awareness & Standards EffortsAwareness & Standards Efforts
• Market Awareness:– On-going outreach to the PUCT, REP’s, Third
Parties, TDSP’s and Vendors– Continued information dissemination to the
market
• National Standards:– Securing a Consultant to Assume the Ownership
6
HAN Call Center ScriptsHAN Call Center Scripts
• Donald Smallwood Project Lead• Weekly Status Meetings• Project execution Plan• Defined the Script Template• Developed Draft Scripts for each scenario • Collaborating with the SMT Help Desk on the
Script development and implementation• Initial Completion Q2
7
HAN DocumentationHAN Documentation– Objectives, Milestones, Review and Editing Process, Access
and Detailed overview of the documentPresenter: Joselito Samoy
– Process and Procedure for on-going support:• Ownership• Maintenance • Communication effort to the market• Who should have access to the HAN documentation
Presenter: Robert Smith
8
HAN Guide HAN Guide PresentationPresentation
April 24, 2012April 24, 2012
HAN GuideHAN GuideHAN Guide is available to registered REPs and TDSPs in private SMT website
10
HAN GuideHAN Guide
• The Smart Meter Texas (SMT) Home Area Network (HAN) Guide is the primary HAN document for the Texas market participants with existing HAN programs and for other participants that are considering implementation of HAN products and services in the Texas territories covered by American Electric Power (AEP), CenterPoint Energy (CNP), Texas New Mexico Power (TNMP) and Oncor Electric.
11
HAN GuideHAN Guide
• The HAN Guide is a consolidation of all relevant HAN documents and artifacts developed for the Texas market participants, with the objective of being the main source of information regarding the processes involved with SMT HAN implementation. The HAN Guide is a “living” document, continually evolving based on national standards as they are developed, developments in HAN and Advanced Metering System (AMS) technology, and market input.
12
HAN Guide SectionsHAN Guide Sections
HAN Topics Interested Party Sections
HAN functionalities that are supported via the SMT User Interface Business Analysts Sections 2,
3 and 4
HAN Messaging Report Technical Analysts, Business Analysts
Section 4
HAN functionalities that are supported via the HAN API (Application Programming Interface
Technical Analysts, Business Analysts
Sections 5 and 6
HAN Messaging Technical Analysts, Business Analysts
Section 5
HAN Addressing of Messages Technical Analysts, Business Analysts
Section 5
Examples of HAN Messaging Technical Analysts, Business Analysts
Section 5
How to Integrate with SMT (HAN Integration with SMT) DataPower / API Technical Integration Team
Section 6
Technical Requirements to Interface with SMT DataPower / API Technical Integration Team
Section 7
Technical Requirements and Details on Authentication and Authorization
DataPower / API Technical Integration Team
Section 8
HAN Device Testing with TDSPs REPs of Records / HAN Vendors
Section 9
HAN Interoperability Report All Market Participants Section 9
HAN Device Reprovisioning during Meter Exchange All Market Participants Section 10
HAN Project Assumptions Business Analysts Section 11
Glossary of Terms All Market Participants Section 11
13
List of All HAN FunctionsList of All HAN FunctionsUI / API HAN FunctionalitiesUI HAN UI (User Interface)
UI Account Management
UI Grant HAN Access
UI Revoke HAN Access
UI Provisioning/Deprovisioning
UI View Provisioning Status
UI Provisioning
UI Deprovisioning
UI Messaging
UI View Messaging History
API HAN API (Application Programming Interface)
API Provisioning/Deprovisioning/UEG
API Provisioning
API Deprovisioning
API Update Utility Enrollment Group
API Messaging
API Send Price Signal
API Send Simple Text/Display
API Cancel Simple Text/Display
API Send Load Control Event
API Cancel Load Control Event
API Cancel All Load Control Events14
HAN Account Management Functional HAN Account Management Functional SpecificationsSpecifications
The HAN Account Management processes describe how HAN Permissions are granted/revoked to users in the Portal. The HAN Account Management business rules describe how HAN Permissions are granted/revoked at the entity level.
15
HAN Account Management HAN Account Management User ExperienceUser Experience
User Account Details (View) - REP
16
HAN Account Management HAN Account Management User ExperienceUser Experience
User Account Details (View) - TDSP
17
HAN Account ManagementHAN Account ManagementGrant HAN Access
Au
tom
ate
dA
uto
ma
ted
RE
P A
dm
in,
TD
SP
Ad
min
RE
P A
dm
in,
TD
SP
Ad
min
020.Navigate to My Account
060.Select a particular user
110.Check the HAN Control box
070.Conduct Search
100.Display User Account Details
Screen
090.Select a particular user
Save
010.Enter Portal through Private
URL
030.User Action?
2.0
Account Management
Processes
Authorized Meter
My Profile
Company Profile
040.Display Search Screen
050.Display list of users pending for
approval
Manage Users Pending Approval
080.Display Search Results
Edit Permissions
120.User Type=REP?
130.Enable View, Provisioning,
Deprovisioning, Messaging Rights
140.Enable View, Provisioning,Depro
visioning Rights
Yes
No
UI-2.11.3.b
UI-2.11.3.c
UI-2.11.3.c UI-2.11.3.b
18
HAN Account ManagementHAN Account ManagementRevoke HAN Access
Au
tom
ate
dA
uto
ma
ted
RE
P A
dm
in,
TD
SP
Ad
min
RE
P A
dm
in,
TD
SP
Ad
min
Save
Authorized Meter
My Profile
Company Profile
Manage Users
Pending Approval
020.Navigate to My Account
080.Display User Account Details
Screen
060.Display Search Results
090.Uncheck the HAN Control box
2.0
Account Management
Processes
050.Conduct Search
030.User Action? 070.Select a
particular user
100.Disable User’s HAN Rights
010.Enter Portal through Private
URL
040.Display Search Screen
UI-2.11.3.b
UI-2.11.3.c
UI-2.11.3.c UI-2.11.3.b
19
HAN Device Provisioning and HAN Device Provisioning and Deprovisioning Functional SpecificationsDeprovisioning Functional Specifications
The HAN Provisioning processes describe how authorized users provision and deprovision HAN Devices through the Portal and how the Portal handles the different statuses of a provisioned Device. The processes also describe how authorized users are able to view provisioning information through the portal.
20
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
Meter Search and Search Results
21
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
View HAN Devices
22
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
View HAN Devices
23
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
Add HAN Devices
24
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
View HAN Device Details
25
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
Remove HAN Device
26
HAN Device ProvisioningHAN Device ProvisioningUser ExperienceUser Experience
HAN Device History
27
HAN Device ProvisioningHAN Device ProvisioningSMT ProceduresSMT Procedures
SMT Procedure – Adding HAN Devices
s Action
NOTE: You must have a Meter List displayed before you can complete the remaining steps.
1 Select checkbox (required)
Select the checkbox next to one of the Smart Meters. Viewing HAN Devices is only available for one Smart Meter at a time.
2 Click ‘View HAN Devices’ button
The resulting screen will display a list of the HAN Devices that have been added to this Smart Meter.
3 Click ‘Add a HAN Device’ button
NOTE: A Smart Meter can have up to 5 HAN Devices. If the Smart Meter already has 5 HAN Devices, the Add a HAN Device button will be disabled.
4 Device Description
Enter an optional name for this HAN Device that will help you remember what the device is or where the device is located, e.g., “Den Thermostat”.
5 Type of HAN Device (required)
Select the type of HAN Device that you are adding from the dropdown menu.
6 MAC Address (required)
Enter a valid MAC Address. You may find the MAC Address in the Device Manufacturer’s box. The MAC Address contains hexadecimal characters only, this means that the MAC Address contains the following letters only: ABCDEF, and the following numbers: 0123456789. An example of a MAC Address is: 001BC5007000052B. If you cannot find the MAC Address contact the Device Manufacturer.
7 Installation Code (required)
Enter a valid Installation Code. You may find the Installation Code in the Device Manufacturer’s box. The Installation Code contains hexadecimal characters only, this means that the Installation Code contains the following letters only: ABCDEF, and the following numbers: 0123456789. An example of an Installation Code is: 83FED3407A939723A5C639B26916D505C3B5. The installation code can have a maximum of 36 characters. If you cannot find the Installation Code contact the Device Manufacturer.
28
HAN Device Status DescriptionsHAN Device Status Descriptions
HAN Device Status Descriptions – Add a HAN Device
Status Status Description
Add Acknowledged A request to Add this HAN Device was sent by the Customer or by the Retail Electric Provider and has been received by SMT.
Add Pending The Add request has been sent by SMT and has been received by the TDSP.
Note: This status is applicable to CNP only.
Meter Ready The Smart Meter is ready to communicate with the HAN Device. The HAN Device is ready for action. You should advise the Customer to press the button on the HAN Device to establish communication between the HAN Device and the Smart Meter. You may also review the manufacturer’s instructions for the HAN Device to complete the Add Process.
Device Added The HAN Device has been successfully Added and is ready to display usage or receive messages.
NOTE: Functionality varies by HAN Device. Please consult the manufacturer’s guide for the specific HAN Device to learn more about the specific functions.
Add Failed The request to Add a HAN Device has failed. You may try to Add the Device again.
29
Removing HAN DeviceRemoving HAN DeviceSMT ProceduresSMT Procedures
SMT Procedure – Removing HAN Devices
p Action
NOTE: You must have a Meter List displayed before you can complete the remaining steps.
1 Select checkbox (required)
Select the checkbox next to one of the Smart Meters. Viewing HAN Devices is only available for one Smart Meter at a time.
2 Click ‘View HAN Devices’ button
The resulting screen will display a list of the HAN Devices that have been added to this Smart Meter.
3 Select checkbox (required)
Select the checkbox next to the HAN Device that is to be removed.
4 Click ‘Remove HAN Device’ button
A new screen will display; this screen shows the Device selected to be removed.
5 Reason for Removing (required)
Select the removal reason from the dropdown box.
6 Comments
You may provide optional comments.
7 Click ‘Remove HAN Device’ button
The process to Remove a HAN Device from your Smart Meter may take some time.
You may check the status of your HAN Device by going to the List of HAN Devices added to an ESI ID. When you click OK on this page you will be directed to that page. The Status of the request is displayed in the last column of the table.
The Remove a HAN Device process is complete when the status of your HAN Device in SMT is Device Removed. This will be displayed in the lower portion of the List of HAN Devices page.
30
HAN Device Status DescriptionsHAN Device Status Descriptions
HAN Device Status Descriptions – Remove a HAN Device
Status Status Description
Remove Acknowledged A request to Remove this HAN Device was received by SMT.
Remove Pending The Remove request has been sent by SMT and received by the TDSP.
Note: This status is applicable to CNP only.
Device Removed The HAN Device has been successfully Removed and can no longer receive messages.
NOTE: Removing the HAN Device from SMT does not physically remove the device from the property. It simply causes the communication link between the HAN Device and the Smart Meter to be removed.
Remove Failed The request to Remove a HAN Device has failed. You may try to Remove the Device again.
31
HAN Device ProvisioningHAN Device ProvisioningProvisioning (UI)
Aut
omat
edA
utom
ated
TD
SP
TD
SP
Aut
horiz
ed R
EP
s,
Aut
horiz
ed T
DS
Ps
Aut
horiz
ed R
EP
s,
Aut
horiz
ed T
DS
Ps
140.Send Provisioning
Request
120.Allocate Slot/Update HAN Main List – Set Device
Status to Add Acknowledged
150.Receive Provisioning
Request
160.Send Acknowledgement
of Provisioning Request
180.TDSP HAN
Provisioning Process
220.Update HAN Main List – Set
Device Status to Add Pending
190.Send Provisioning
Status
Add HAN Device
200. Provisioning
Status?
Provision Failed
230.Update HAN Main List – Set
Device Status to Meter Ready
Meter Ready
240.Update HAN Main List – Set
Device Status to Device Added
Provision Complete
View Provisioning Status
030.Display Provisioning
Screen
040.Enter Device Information and
Networking Details
Add a HAN Device
080.Validate MAC Address and
Installation Code
090.MAC and IC Valid?
YesNo
095.Display Error Message
270.List rejected/failed provisioning request in the HAN
List Sub-Screen
280.Wait <10> Calendar Days
290.Clear rejected/ failed provisioning
requests from Sub-Screen
View Provisioning Status
Cancel
No
130.Update information on the HAN Provisioning
History Log
A
A
Log provisioning activity at the
user level
100. Device already provisioned to that ESI ID?
110. Display Error Message
Yes
050. Selection?
UI-HAN-1.6
UI-HAN-1.6
UI-HAN-1.5
UI-HAN-1.9
UI-HAN-1.6 UI-HAN-1.6
UI-HAN-1.5UI-HAN-1.5
UI-HAN-1.5
UI-HAN-1.5
Pending
210.Clear Slot from HAN Main
List
Request Rejected
B
B
260.Clear Slot from HAN Main
List
UI-HAN-1.5
250.Before Meter
Ready is received?
Yes
255.Ignore Failure Message, maintain
Meter Ready Status
No
Statuses:Add Rejected
Add Failed
See note in Process Details for this step
32
HAN Device DeprovisioningHAN Device DeprovisioningDeprovisioning (UI)
TD
SP
TD
SP
Aut
omat
edA
utom
ated
Aut
horiz
ed R
EP
s,
Aut
horiz
ed T
DS
Ps
Aut
horiz
ed R
EP
s,
Aut
horiz
ed T
DS
Ps
Deprovision Complete
DeprovisioningFailed
Remove HAN Device
110.Provisioning Status?
060.Send Deprovisioning
Request
070.Receive Deprovisioning
Request
100.Send Provisioning
Status
140.Clear Slot from HAN Main
List
Provisioning/Deprovisioning
95.TDSP HAN Deprovisioning
Process
150.List deprovisioned
device in the HAN List Sub-Screen
120.Update HAN List Screen – Set Device Status to Remove Pending
160.Wait <10> Calendar Days
170.Clear deprovision/failed
deprovisioning devices from Sub-
Screen
135.List rejected/ failed deprovisioning request in the HAN List Sub-
Screen / Update Correct Status on Main Screen
View Provisioning Status
Cancel
040.Update HAN List Screen – Set Device Status to
Remove Acknowledged
080.Send Acknowledgement
of Provisioning Request
Status: Device Deprovisioned
050.Update information on the HAN Provisioning
History Log
Log provisioning activity at the
user level
130.Request Current
Status Device to TDSP
Includes any deprovisioning activity initiated by the
TDSP, which should also include the reason code
010. Select Reason Code + Enter Optional
Comments
Remove HAN Device
Reason Code will be stored in the Database, to be used for reporting purposes
UI-HAN-1.8
UI-HAN-1.9 UI-HAN-1.5UI-HAN-1.5
UI-HAN-1.5
UI-HAN-1.5
UI-HAN-1.5
See Process Details for this step to see possible values. Dropdown Values are different based on User Type
See note in Process Details for this step
Deprovisioning Pending
Request Rejected
Status do not take a slot:-Remove Rejected
-Remove Failed
33
HAN Device Messaging HistoryHAN Device Messaging History
This HAN Device Messaging History describes what the authorized user will be able to do through the UI, which is simply the ability to retrieve message acknowledgments (message log) for a particular message type, DUNS and message creation date.
34
HAN Device MessagingHAN Device MessagingUser ExperienceUser Experience
Message Log – Request Report
35
HAN Device MessagingHAN Device MessagingUser ExperienceUser Experience
Request Message – Log Confirmation
36
HAN Device MessagingHAN Device MessagingUser ExperienceUser Experience
Report Request Status
37
Request Messaging ReportRequest Messaging ReportSMT ProceduresSMT Procedures
SMT Procedure – Requesting the HAN Message Log
p Action
1 Navigate to the ‘My Account’ tab
2 Select ‘HAN Device Messages’ from the left menu
3 Message Type (required)
Select one or more message types to include on the report.
4 DUNS (required)
HAN Messages are associated with the specific DUNS that is the ROR for the Smart Meter. If you have access to multiple DUNS numbers, then all of your DUNS will show in the selection list.
5 Date of Message (required)
Select a date using the calendar tool. This is the date that the message was sent to SMT using your API.
6 Click ‘Submit Request ‘ button
A new screen will display showing an Order Number for your report request. Your request will be run offline. When the request completes, an email will be sent to the Email Address in your Account Profile
38
Messaging Report File FormatMessaging Report File Format
Element Required Description
TDSPDUNSNumber Yes DUNS Number
RequestID No Request ID generated by the Portal
MessageID No Message ID assigned by the REP
ESIID Yes
MeterSerialNumber No
DeviceMACAddr No Identifies the HAN Device if device-level status is available.
EventCategoryID Yes Allowed values are:
STM - SimpleMessage CSM - CancelSimpleMessage LCE - LCEvent CLE - CancelLCEvent CAL - CancelAllLCEvents PRM - PriceMessage,
StatusCode Yes Allowed values are:
RQA: Request Accepted and sent to TDSP ACK: Acknowledgment from TDSP that the message request has been received PEN – Pending CON – Confirmed STR – Request/Event Started OPT – Opt Out FLR – Failure
SNT – Message Sent COM – Completed CAN – Canceled
StatusDesc No Additional status description text provided by the TDSP
StatusTimestamp Yes The timestamp for the status information. Ideally, this is the timestamp derived from the meter/ESI.
39
HAN Device Messaging ReportHAN Device Messaging ReportView Messaging Status
Aut
omat
edA
utom
ated
RE
P (
Aut
horiz
ed U
ser)
RE
P (
Aut
horiz
ed U
ser)
Submit Request
150.Wait 10 days110.Add Report
Request to Report Request Status
Link on Usage Tab
160.Purge the Files/Status Messages
120.Process Data Request
140.Send e-mail to user that made
request
130.Publish Result File
170.Wait for confirmation e-mail
240.Go to FTP Site to Access
Result File
180.Access Report Request Status
Link on Usage Tab
ROR has access to all messaging history: up to last
<35> days (configurable)
040.Display Search Screen
050.Select Message Type(s)
070.Select Date of Message
060. Select DUNS
100.Display Order ID number with instructions to retrieve Log
020.Navigate to My Account Tab/
Land on Customer Meters
010.Enter Portal through Private
URL
030.Select HAN Devices Messages
190.Display List of Requests with
Status
200.Status of Request?
220.Display Data Unavailable
Message according to
processing error
210.Display processing message
230.Display Link to FTP Site to access File
Processing
Unsuccesful
Complete
Display List of DUNS numbers that specific REP
(as Admin/User) has access to
UI-HAN-2.0
UI-HAN-2.0
UI-HAN-2.0
UI-HAN-2.0
UI-HAN-2.1
40
HAN Application Programming Interface HAN Application Programming Interface (API)(API)
• Assumptions on Central Time– REPs have the ability to specify the current time and/or start times for
display of messages, load control events and price signals. SMT assumes that all time values input through the API are in Central Standard or Central Daylight Time and converts it to UTC (Coordinated Universal Time).
• An example for how Central time values should be formatted appears below: <StartTime>2009-12-01T16:00:00</StartTime> • UTC values should be formatted as follows: <StartTime>2009-12-01T16:00:00Z</StartTime>
41
HAN Application Programming Interface HAN Application Programming Interface (API)(API)
• Meter Numbers
• An example of a manufacturer’s serial number appears below: <MeterSerialNumber>6039657245</MeterSerialNumber>
• Some TDSPs add a manufacturer code to the manufacturer’s serial number to guarantee uniqueness.
• CenterPoint places the manufacturer code before the serial number. <MeterSerialNumber>I6039657245</MeterSerialNumber>
• Oncor appends the manufacturer code to the end of the serial number. <MeterSerialNumber>6039657245LG</MeterSerialNumber>
42
HAN Application Programming Interface HAN Application Programming Interface (API)(API)
• Schema Definitions
• All provisioning and deprovisioning requests use the following schema definition:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:smt="http://schemas.esb.ams.com/smtxpprovisiondevice">
• All messaging requests use the following schema definition:<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:smt="http://schemas.esb.ams.com/smtxpmessaging">
43
HAN Application Programming Interface HAN Application Programming Interface (API)(API)
• Header Information
Element Mandatory Type Description RequestID N string(32) Unique request identifier.
Every request sent to SMT will be assigned a RequestID. A REP may assign their own unique value for a Request ID as part of the request sent to SMT, however it is discouraged because the value is not guaranteed to be unique across all REPs. SMT always generates its own unique value and use it for communications with TDSP systems. The SMT-generated value will be returned to the REP in a request acknowledgement.
RequesterType Y Int Requester Type indicator. Accepted values are: 0 REP; 1 TDSP; 2 Customer; 3 Third-party; 4 Host; 5 Supplemental
RequesterAuthenticationID Y string(9,16) REPs and TDSPs should input their primary DUNS number
RequesterID Y string System Account ID of the Requestor RequestPriority Y string(1) Priority of request. Accepted values are:
H – High M – Medium L – Low
CallbackUri N string(256) (For future use as a REP callback mechanism.)
44
HAN Provisioning and Deprovisioning APIHAN Provisioning and Deprovisioning API
• Slot Management• A meter may have up to 5 devices provisioned to it. Each device takes a slot.
Meter slot management rules are as follows:o A slot is allocated when a valid provisioning request is accepted by SMT. o A slot is de-allocated if the TDSP returns a failure status associated with a provisioning
request.o A slot is de-allocated when the TDSP returns a completion status for a deprovisioning
request.o If a deprovisioning request fails, slot allocation is unchanged.
45
HAN Provisioning and Deprovisioning APIHAN Provisioning and Deprovisioning API
• HAN Device Provisioning Request Information
Element Mandatory Type Description ESIID Y string(17,64) Energy Service Interface identifier MeterSerialNumber Y string(30) TDSP Meter manufacturer serial number DeviceMACAddr Y string(16) Device MAC Address DeviceInstallCode Y string(36) Device Installation Code DeviceClusterSupport N Int Sum of 1 - Messaging, 2 - Load Control, 4 Pricing, 0 - unspecified (max
integer value = 7), default=0 DeviceClass N string(5) Bitmap values. Bit position(right to left) as
1=InHomeDisplay, 2=LoadControlDevice, 3=ProgrammableThermostat, 4=IntelligentGateway.
The SMT API will accept a string(5) value. Characters must be a "0" or a "1". ACK=FLR is returned if this value deviates from these rules.
DeviceText N string(256) User-friendly label for device identification
46
HAN Provisioning and Deprovisioning APIHAN Provisioning and Deprovisioning API
• HAN Device Deprovisioning Request Information
Element Mandatory Type Description ESIID Y string(17,64) Energy Service Interface identifier
MeterSerialNumber Y string(30) TDSP Meter manufacturer serial number
DeviceMACAddr Y string(16) Device MAC Address
ReasonCode Y string(1) Deprovisioning reason code are : 1 = RepRequested 2 = CustomerRequested, 3 = MalfunctioningDevice, 4 = UnsupportedDevice, 5 = RequestProvByMistake, 6 = NetworkInterference 7 = Other
ReasonComment N string(64) Reason description for deprovisioning
47
HAN Provisioning and Deprovisioning APIHAN Provisioning and Deprovisioning API
• HAN Device Provisioning and Deprovisioning Acknowledgment
Element Mandatory Type Description RequestID Y string(32) Unique Request ID which is generated by SMT RequestStatus Y string(3) Values returned are:
ACK - Acknowledgement indicating the request was accepted for further processing.
FLR - Failure, indicating the request was not accepted for processing RequestStatusDesc N string(64) Request Status Description
48
HAN Update Utility Enrollment Group APIHAN Update Utility Enrollment Group API
• HAN Device Update Utility Enrollment Group Request Information
49
Element Mandatory Type DescriptionESIID Y string(17,64) Energy Service Interface identifier
MeterSerialNumber Y string(30) TDSP Meter manufacturer serial number
DeviceMACAddr Y string(16) Device MAC Address
UtilityEnrollmentGroup Y int Utility Enrollment Group
HAN Messaging APIHAN Messaging API• Addressing of Smart Energy Messages
Element Mandatory Type Description GroupID N string(16) CNP requires that the GroupID field be populated
with the REP DUNS number for Multicast Messaging. The value in the GroupID field should be the same as the RequesterAuthenticationID field. For Point-to-Point Messaging, the GroupID field should be populated with BLANK value and the Address List (ESIID and Meter Serial) should be populated with the target ESIID(s). Whenever the GroupID is populated, CNP will treat the HAN Message as Multicast, regardless of whether the ESIID/Meter Serial Number is populated or not. Oncor and AEP requires that the GroupID field be populated with BLANK value.
Address List
N Collection of address elements Address ESIID Y string(64) Energy Service Interface identifier
CNP requires that the ESIID field be populated with the target ESIID(s) for Point-to-Point Messaging Oncor and AEP require that the ESIID field be populated with the target ESIID(s)
Meter Serial Number
Y string(30) TDSP Meter manufacturer serial number CNP requires that the Meter Serial Number field be populated with the target Meter Serial Number for Point-to-Point Messaging Oncor/AEP require that the Meter Serial Number field be populated with the target Meter Serial Number(s)
Device MAC Addr
N string(16) All TDSPs require that the Device MAC Addr field be populated with BLANK value.
50
HAN Messaging APIHAN Messaging API• Addressing of Messages with Group ID• When a Smart Energy message is addressed by the requester with a Group ID,
SMT creates copies of the message for each TDSP. Then, the appropriate copy of the message is forwarded to each TDSP. The reason for this is that a group id cannot be identified with a particular TDSP: there is no way to distinguish which TDSP it needs to be sent to.
• Oncor and AEP will reject the message with no return error message if there is only the Group id and no list of ESIID and meter serial numbers.
• CNP will perform internal validation, and processes the message accordingly. For Multicast Messaging, CNP requires that the GroupID field be populated with the REP DUNS number, whether the ESIID/Meter Serial Number is populated or not. Whenever the GroupID field is populated, CNP will treat the HAN Message as Multicast Messaging. The value in the GroupID field should be the same as the RequesterAuthenticationID field. CNP will broadcast the message to the REP group.
51
HAN Messaging APIHAN Messaging API
• Addressing of Messages with ESIID
52
Simple Text / Display Message APISimple Text / Display Message API
• Request Information
Element Mandatory Type Description MessageID Y Int Message Identifier, REPS issued StartTime Y dateTime The time at which the message becomes valid.
REP provided value. For “now”, use 2000-01-01T00:00:00Z
DurationTime Y Int SEP defines a range from 0 to 0xFFFF. In Release 1, the maximum number of minutes allowed is 255.
Message Y string(80) As per SEP MCTransmission Y Int Values are per SEP:
0 Secured/normal 1 InterPAN 2 Secured & InterPAN
In Release 1, SMT will only allow a value of 0. MCPriority Y Int Values are per SEP:
0 Low 1 Medium 2 High 3 Critical
MCConfirmation Y Int Values are per SEP: 0 confirmation not required 1 confirmation required
53
Cancel Simple Text / Display Message APICancel Simple Text / Display Message API
• Request Information
Element Mandatory Type Description MessageRequestID Y string(32) This is the SMT-generated value sent in the header of the original text
display request. MessageID Y Int This message id assigned by the requester in the original display text
request. MCTransmission Y Int Values are per SEP:
0 Secured/normal 1 InterPAN 2 Secured & InterPAN
SMT will only allow a value of 0. MCPriority Y Int Values are per SEP:
0 Low 1 Medium 2 High 3 Critical
MCConfirmation Y Int Values are per SEP: 0 confirmation not required 1 confirmation required
54
Load Control Message APILoad Control Message API• Request Information
Element Mandatory Type Description EventID Y Int Event identifier, unique within messages. REPS
assigned EventID StartTime Y dateTime The time at which the message becomes valid.
REP provided value. For “now”, use 2000-01-01T00:00:00Z
DurationTime Y Int As per SEP: allowed values are 1 to 1440 DeviceClass Y string(16) This is a bitmap value as related to Table D.2 in
Section D.2.2.3.1.1.1 in revision 15 of the Smart Energy Profile Spec (page 143). That table defines a bit map for Load Control the device class. Bit 0 (right-most bit) controls HVAC compressors or furnaces. Bit 1 controls Strip and baseboard heaters...... Bit 11 controls Generation systems. Bits 12-15 are reserved. The SMT API will accept a string(16) value. Counting characters from the right, characters 1-12 must be a "0" or a "1". ACK=FLR is returned if this value deviates from these rules.
UtilityEnrollmentGroup Y Int Per SEP: Range 0 - 255 CriticalityLevel Y Int Per SEP: Range of 1-9 CoolingTemperationOffset N Int Per SEP HeatingTemperatureOffset N Int Per SEP CoolingTemperationSetPoint N Int Per SEP, Range -27315 to 32766 & 32768 HeatingTemperatureSetPoint N Int Per SEP, Range -27315 to 32766 & 32768 AverageLoadAdjustPercent N Int As per SEP: Range of -100 to 100 or 128(0x80) which
indicates the field is not used. DutyCycle N Int As per SEP: Range of 0 to 100 & 255 for NULL EventControl Y Int Values are per Zigbee:
0 – do not randomize start time, do not randomize end time
1 – randomize start time, do not randomize end time
2 – do not randomize start time, randomize end time
3 – randomize start and end times
55
Cancel Load Control Message APICancel Load Control Message API
• Request Information
Element Mandatory Type Description LCRequestID Y string Original RequestID of the LC Message EventID Y string(32) EventID of issued event that needs to be cancelled EffectiveTime Y dateTime The time at which the message becomes valid.
REP provided value. For “now”, use 2000-01-01T00:00:00Z
DeviceClass Y string(16) This is a bitmap value as related to Table D.3 in Section D.2.2.3.2.1. in revision 15 of the Smart Energy Profile Spec (page 148). That table defines a bit map for Load Control the device class. Bit 0 (right-most bit) controls HVAC compressors or furnaces. Bit 1 controls Strip and baseboard heaters...... Bit 11 controls Generation systems. Bits 12-15 are reserved. The SMT API will accept a string(16) value. Counting characters from the right, characters 1-12 must be a "0" or a "1". ACK=FLR is returned if this value deviates from these rules.
UtilityEnrollmentGroup Y Int Per SEP: Range 0 - 255 CancelControl Y Int As per SEP:
0 do not randomize 1 randomizes
56
Cancel ALL Load Control Message APICancel ALL Load Control Message API
• Request Information
57
Element Mandatory Type DescriptionCancelControl Y int Identifies additional control options for the event
Price Signal Message APIPrice Signal Message API• Request Information
Element Mandatory Type Description ProviderID
Y Int Provider ID (limited to 9 digits) – REP will provide a unique number for Provider. Discussion of using the first 9 digits of the REP DUNS possibly, or a different identifier chosen by REP.
RateLabel Y String(12) Rate Label
IssuerEventID Y Int Issuer Event ID – Mandatory in SEP, unique identifier controlled by REP for message.
CurrentTime Y dateTime Current Time – API will include current time field as mandatory for REP and TDSP.
UOM Y Int Unit Of Measure – Per SEP. Currency Y String(3) Currency (USD= US Dollars) - Use ISO 4217, US Dollar=USD=840, use
character value. Price Tier Y Int Price Tier – REP will provide. As per SEP - 0 means no Tiers, values 1
thru 6 indicate a Price Tier. Tier 1 is the least expensive. Tier 6 is the most expensive.
Price Trailing Digit Y Int Price Trailing Digit – REP will provide. As per SEP - number of digits to right of the decimal point in the price field.
Register Tier Y Int Register Tier (4 bits Unsigned – Range 0 to 15) -As per SEP - Table D.31 in spec. 0 means no tier related. Register Tier values of 1 thru 6 allowed.
Start Time Y dateTime The time at which the message becomes valid. REP provided value. For “now”, use 2000-01-01T00:00:00Z
Duration Y Int Duration (in minutes) - REP will provide. As per SEP, 16 bits, a max value of 0xffff (=65535) would mean stay in place until changed, by a subsequent Price message.
Price Y Int Price – REP will provide. As per SEP. Price Ratio N Int Price Ratio per SEP. GenerationPrice N Int Generation Price per SEP.
GenerationRatio N Int Generation Price Ratio per SEP.
AlternateCostDelivered N Int Alternate Cost Delivered per SEP.
AlternateCostUnit N Int Alternate Cost Unit per SEP.
AlternateCostTrailingDigit N Int Alternate Cost Trailing Digit per SEP.
58
HAN Messaging ExamplesHAN Messaging Examples
• Simple Text / DisplayThe following example illustrates how to send a simple message that starts immediately for a duration of 30 minutes. No confirmation (0) is required for this simple message.
<SimpleMessageBlock> <MessageID>58158</MessageID> <StartTime>2000-01-01T00:00:00Z</StartTime> <DurationTime>30</DurationTime> <Message>Simple Message Test</Message> <MCTransmission>0</MCTransmission> <MCPriority>0</MCPriority> <MCConfirmation>0</MCConfirmation></SimpleMessageBlock>
59
HAN Messaging ExamplesHAN Messaging Examples
• Load Control Messaging Temperature Set PointThe following example illustrates how to send a load control message to set the cooling temperature setpoint to 30 deg C (3000 in the example below) and the heating temperature setpoint to 15 deg C (1500 in the example below). Since the start time has been set to 2000-01-01T00:00:00Z, this load control event will be started immediately for a duration of 30 minutes. All HAN Devices, regardless of the utility enrollment group they are assigned to, will receive the event as the Utility Enrollment Group in the load control event has been set to 0.
Duty Cycle is 255 or NULL which means that the load control switches will not react to this load control event.
<LCMessageBlock> <EventID>12348911</EventID> <StartTime>2000-01-01T00:00:00Z</StartTime> <DurationTime>30</DurationTime> <DeviceClass>0000111111111111</DeviceClass> <UtilityEnrollmentGroup>0</UtilityEnrollmentGroup> <CriticalityLevel>1</CriticalityLevel> <CoolingTemperationSetPoint>3000</CoolingTemperationSetPoint> <HeatingTemperatureSetPoint>1500</HeatingTemperatureSetPoint> <DutyCycle>255</DutyCycle> <EventControl>0</EventControl> </LCMessageBlock> 60
HAN Messaging ExamplesHAN Messaging Examples
• Load Control Messaging Temperature OffsetThe following example illustrates how to send a load control message to set the cooling temperature offset 2 deg C (20 in the example below) and the heating temperature offset 3 deg C (30 in the example below). Since the start time has been set to 2012-02-23T14:15:00Z, this load control event will be started Feb 23, 2012 at 8:15 AM CST. The 2 zeros on the end represent seconds and rarely other than 00 used. The 14:15 is UTC or Greenwich Mean Time – CST +6hr). The duration of the load control event is 45 minutes. All HAN Devices, regardless of the utility enrollment group they are assigned to, will receive the event as the Utility Enrollment Group in the load control event has been set to 0.
Duty Cycle is 255 or NULL which means that the load control switches will not react to this load control event.
<LCMessageBlock> <EventID>12348911</EventID> <StartTime>2012-02-23T14:15:00Z</StartTime> <DurationTime>45</DurationTime> <DeviceClass>0000111111111111</DeviceClass> <UtilityEnrollmentGroup>0</UtilityEnrollmentGroup> <CriticalityLevel>1</CriticalityLevel> <CoolingTemperationOffset>20</CoolingTemperationOffset> <HeatingTemperatureOffset>30</HeatingTemperatureOffset> <DutyCycle>255</DutyCycle> <EventControl>0</EventControl> </LCMessageBlock>
61
HAN Messaging ExamplesHAN Messaging Examples
• Load Control Messaging Temperature Offset with Duty Cycle
The Duty Cycle is 50 which means that the load control switches will react to this load control event. The switches will be on 50% of the time, and off 50% of the time.
<LCMessageBlock> <EventID>12348911</EventID> <StartTime>2012-02-23T14:15:00Z</StartTime> <DurationTime>45</DurationTime> <DeviceClass>0000111111111111</DeviceClass> <UtilityEnrollmentGroup>0</UtilityEnrollmentGroup> <CriticalityLevel>1</CriticalityLevel> <CoolingTemperationOffset>20</CoolingTemperationOffset> <HeatingTemperatureOffset>30</HeatingTemperatureOffset> <DutyCycle>50</DutyCycle> <EventControl>0</EventControl> </LCMessageBlock>
62
HAN Messaging ExamplesHAN Messaging Examples
• Price Signal
The following example illustrates how to send a price message (11 cents) that starts immediately for a duration of 30 minutes.
<PriceMessageBlock> <ProviderID>123456789</ProviderID> <RateLabel>Rate Label1</RateLabel> <IssuerEventID>865888</IssuerEventID> <CurrentTime>2000-01-01T00:00:00Z</CurrentTime> <UOM>0</UOM> <Currency>USD</Currency> <PriceTier>1</PriceTier> <PriceTrailingDigit>2</PriceTrailingDigit> <RegisterTier>1</RegisterTier> <StartTime>2000-01-01T00:00:00Z</StartTime> <Duration>30</Duration> <Price>11</Price> <PriceRatio>255</PriceRatio> <GenerationPrice>11000</GenerationPrice> <GenerationRatio>95</GenerationRatio> <AlternateCostDelivered>2222</AlternateCostDelivered> <AlternateCostUnit>1</AlternateCostUnit> <AlternateCostTrailingDigit>4</AlternateCostTrailingDigit> </PriceMessageBlock> 63
HAN Messaging ExamplesHAN Messaging Examples
• Update Utility Enrollment Group
The following example illustrates how to send an update utility enrollment group message to set the UEG of the HAN Device 001B0000B0000000 to UEG = 10. The ESIID and Meter Serial Number should also be populated accordingly.
<DeviceUpdateUEGRequestList> <DeviceUpdateUEGRequest> <ESIID>1000000000000000000000</ESIID> <MeterSerialNumber>60000000</MeterSerialNumber> <DeviceMACAddr>001B0000B0000000</DeviceMACAddr> <UtilityEnrollmentGroup>10</UtilityEnrollmentGroup> </DeviceUpdateUEGRequest> </DeviceUpdateUEGRequestList>
64
HAN Device Provisioning APIHAN Device Provisioning API
No
Provisioning (API)
TD
SP
TD
SP
SM
TxP
MQ
/ D
BS
MT
xP M
Q/
DB
SM
TxP
ES
BS
MT
xP E
SB
Aut
horiz
ed
RE
P (
AP
I)A
utho
rized
R
EP
(A
PI)
010.Send Provisioning
Request
020.Receive Provisioning
Request
DB030.Assign Request ID
040.> 1Device in Request?
070.All Slots filled for that
ESI ID?
050.Fail Request, Log Failure and
Send Ack
060.Receive Ack
Yes
090.ESI ID/Meter ID Valid?
REP has access?
No
Yes100.MAC and
IC Valid?
110. Device already provisioned to that ESI ID?
Yes Yes
No Yes
065.Meter ID with Request?
No
No Yes
140.Create Provisioning
Request for TDSP that owns the ESI
ID
120.Accept Provisioning
Request and Send Ack
No130.Make Status Update Available
through the UI
MQ150.Queue the
Message
160.Enrich and Log the Message
180.Receive Provisioning
Request
170.Send Provisioning
Request
190.Send Acknowledgement
210.Make Status Update Available
through the UI200.Status?
Ack Succesful
Ack Failure
220.Request sent
3 times in the last 3 hours?
No
Yes
Status: Add Acknowledged
Status could be: Add Rejected, Add
Pending, Meter Ready, Device Added, Add
Failed
215.Receive and Make Available further Status
Updates
230.Clear Slot / Communicate to
UI
240.Log failed provisioning
request/Communicate to
UI
65
HAN Device Deprovisioning APIHAN Device Deprovisioning APIDe-provisioning (API)
TD
SP
TD
SP
SM
TxP
M
Q/
DB
SM
TxP
M
Q/
DB
SM
TxP
ES
BS
MT
xP E
SB
Au
tho
rize
d
RE
P (
AP
I)A
uth
ori
zed
R
EP
(A
PI)
NoYes
No
YesNo
Ack Succesful
Ack Failure
No
070.ESI ID/Meter ID Valid?
110.Create De-Provisioning
Request for TDSP that owns the ESI
ID
040.> 1Device in Request?
080.REP Has Access to this
ESI ID?
010.Send De- Provisioning
Request
170.Status?140.Send De-Provisioning
Request
090.Accept Provisioning
Request and Send Ack
050.Fail Request, Log Failure and
Send Ack
180.Make Status Update Available
through the UI
020.Receive De-Provisioning
Request
100.Make Status Update Available
through the UI
DB030.Assign Request ID
130.Enrich and Log the Message
150.Receive De-Provisioning
Request
MQ120.Queue the
Message
060.Receive Ack
190.Request sent
3 times in the last 3 hours?
160.Send Acknowledgement
185.Receive and Make Available further Status
Updates
Yes
Status: Remove Acknowledged
Status could be: Remove Rejected, Remove Pending, Device Removed,
Remove Failed
210.Log failed de-provisioning
request/Communicate to
UI
Yes
200.Request Current
Status Device to TDSP
065.Meter ID with Request?
Yes
No
66
HAN Device Messaging APIHAN Device Messaging API
GroupID + ESI IDs
Message Request (API) (1 / 2)
SM
TxP
ES
BS
MT
xP E
SB
Au
tho
rize
d
RE
P (
AP
I)A
uth
ori
zed
R
EP
(A
PI)
NoYes
No
Yes Yes No
090.Receive Ack010.Send
Messaging Request
020.Receive Messaging
Request/Assign Request ID (DB)
140.Mix of Valid/Invalid
ESI IDs
080.Fail Request, Log Failure and
Send Ack
120.ESI ID/Meter ID Valid?
160.Accept Messaging
Request and Send Ack
130.REP Has Access to
these ESI IDs?
030.Contents of Address
Block?
Em
pty
On
ly G
rou
pID
070.> 10,000 ESI
IDs?
Only ESI IDs
150.Accept Messaging
Request and Send Partial Success
Ack
Yes
All Original ESI IDs are valid
B
200.Create Messaging
Request(s) for TDSPs
170.Validate Message Format/Block according to
Message Type
180.Message Format Valid?
Yes
No
190.Log failed messages, make available to be retrieved through the
Message Log Request
1
We will not filter for ESI IDs that have HAN Devices
No
A
A
B
065. Meter IDs with Request?
Yes
No
Note: When the address block has both GroupID and ESI ID populated, SMT will
validate the ESI ID list, but not the Group ID. Group ID is managed by the TDSP. After
validation, SMT will send the message request to the TDSP, and the TDSP will process the
message accordingly. Refer to HAN Messaging Section in the HAN Document.
67
HAN Device Messaging APIHAN Device Messaging APIMessage Request (API) (2 / 2)
TD
SP
TD
SP
SM
TxP
DB
SM
TxP
DB
SM
TxP
MQ
SM
TxP
MQ
SM
TxP
ES
BS
MT
xP
ES
B
240.Receive Messaging
Request
210.Queue the Message
250.Send Acknowledgement
1280..Request
sent 3 times in the last 3 hours?
260.Receive and Log
Acknowledgement
230.Send Messaging Request
220.Enrich and Log the Message
270.Ack was a failure?
No
290.Log failed messages, make
available to be retrieved through the Message
Log Request
68
HAN API Starter KitHAN API Starter Kit
The HAN API Starter Kit is a soap UI-based tool that SMT has developed that Retail Electric Providers (REPs) can use for invoking the Smart Meter Texas (SMT) Home Area Networking (HAN) Web Service interface.
69
HAN API Starter KitHAN API Starter Kit
• Users of this Starter Kit are assumed to have basic technical expertise in these areas: o Downloading applications from the Interneto Installation and setup of applicationso Creation and editing of XML documentso Internet security including user ids, passwords, and the use of X.500 certificateso Network communications including URLs, IP addresses and common network
troubleshooting commands such as ping, telnet, FTP, etc.
70
HAN API Starter KitHAN API Starter Kit
Environmental Setup• Staging• REPs can submit this environmental information for access to the SMT Staging environment:• SSL certification –SMT will accept a Certificate Authority (CA) or self-signed certificate. A REP
needs to provide to SMT with their SSL certificate for Staging environment setup.• Signing certificate–SMT will accept a CA or self-signed signer certificate. A REP will need to
provide SMT with their signer certificate for Staging environment setup.• DUNS – An SMT system account will be created that REPs must use when accessing the SMT
Staging environment. One or more DUNS number must be associated with the SMT system account.
• Entity Name – This is the preferred REP name.
71
HAN API Starter KitHAN API Starter Kit
Environmental Setup• Production• REPs can submit this environmental information for access to the SMT Production
environment.• SSL certification –SMT will only accept a CA certificate. A REP needs to provide to SMT with
their CA SSL certificate for Production environment setup.• Signing certificate–SMT will accept a CA signer certificate. A REP will need to provide SMT
with their CA signer certificate for Production environment setup.• DUNS – An SMT system account will be created that REPs must use when accessing the SMT
Staging environment. One or more DUNS number must be associated with the SMT system account.
• IP Address(es) – Access is restricted to the SMT Production Environment. The REP IP Address is needed to enable access.
• Entity Name – This is the preferred REP name.
72
HAN API Starter KitHAN API Starter Kit
Overview of Steps for using the Starter Kit
• Set up the Starter Kit• Configure SSL • Configure WS-Security• Invoke Web Services
73
HAN API Starter KitHAN API Starter KitTroubleshooting• In the event that Start Kit users are not able invoke a web service via
SOAPUI client, these troubleshooting steps should be:• Review the soapUI error log.• Records in the soapUI error log should indicate a range of communication
problems and can be used to determine the root-cause of a failure.• Soap Fault Codes
2100 Invalid Message Signature failure 2200 SMT System Error 2300 Authentication Failure Invalid Credentials 2400 SMT Internal System Error 2500 SMT internal Fault 2600 SOAP Fault Message Rejected by SMT
74
HAN API Starter KitHAN API Starter KitTroubleshooting• Check if you can ping the SMT Server, from the machine where the SOAPUI client is
running? – If ping succeeds, it means you are able to communicate to the server. Proceed to test telnet as described below.– If you cannot ping the SMT server, soapUI requests are not reaching the SMT server. Determine and fix the cause of the problem that is
impeding end-to-end communications.
• Check if you can telnet the SMT Server, from the machine where the SOAPUI client is running?
– If telnet succeeds, it means you are able to communicate to the server using port 5205. – If you cannot ping the SMT server, soapUI requests are not reaching the SMT server. Determine and fix the cause of the problem that is
impeding end-to-end communications.
• Check your public SSL key "Common Name" is same as the "hostname" of the server where SOAPUI client is running.
– The REP will need to generate and send a new certificate and submit it to SMT.
• For communications to the Production environment, validate that your public IP address matches with the value originally submitted to the SMT team during REP configuration.
– Starter Kit requests will only pass through the SMT firewall when they are submitted from defined IP addresses.
• If the submitted web service request failed with a SOAP Fault Exception, analyze the error code, description in the SOAP response and validate the input message.
– The actual SOAP Fault description in the response will contain a detailed message related to the specific input attributes. Check the input elements and retry the service with valid inputs
• Check to make sure the correct URL/endpoint has been selected
75
HAN API Starter KitHAN API Starter KitHAN Provisioning and Messaging WSDL FilesAfter the REPs have integrated with SMT HAN API’s using the API Starter Kit, the WSDL (Webservice description language)
files for HAN related services will be provided by SMT upon request. These files can be utilized to build client applications to consume the SMT services for HAN. SMT will provide the WSDL files for the HAN services listed below.
• HAN Device Provisioning / Deprovisioning• HAN Device Utility Enrollment Group• HAN Device Messaging which includes:
• Sending simple text message• Cancel simple text message• Sending price signal• Sending Load control event• Cancel a Load control event• Cancel all Load control events
• The REPs are expected to raise a request with the SMT help desk (Call 1-888-616-5859) to request these WSDL files. SMT technical team would provide the WSDL files in a compressed (.zip) file. The WSDL files can also be imported to SOAP UI tool to create and setup the project to access the service.
76
HAN Interface SecurityHAN Interface Security
Prerequisites for Interfaces
• All communication to SMT from REPs and TDSPs will be over 2-Way Secure Sockets Layer (SSL). For each TDSP, a VPN channel has to be established between SMT and TDSP systems. In the case of TDSPs, SSL will be employed over a virtual private network (VPN).
• For API requests from TDSPs, SMT requires that a user credential be passed in a SAML token that is part of SOAP header. The specific of SAML token is described in a later section.
• For API requests from REPs, SMT requires that a user credential be passed in a UserName Token that is part of SOAP header. SMT does not require password to be passed as part of
• UsernameToken.
77
HAN Interface SecurityHAN Interface SecurityPrerequisites for Interfaces
· SMT will only accept CA issued certificates (SSL and Signer Cert) in its production environment. Selfsigned certificates (SSL or Code Signed) will not be accepted.
· SMT will accept self-signed certificates for testing purposes only. Although the self-signedcertificates will be accepted for testing, CA certificates are preferred. · It is assumed that partners will use Class 3 certificates. · The system account for TDSPs and REPs should exist in the SMT user repository and be known toTDSP and REP in advance. The system account is case sensitive. · SMT will only accept signed requests as per WS-Sec 1.1 specification for all the incoming requests.The SMT signature processing module does explicit checks for the signature of UserNameToken,Simple Object Access Protocol (SOAP) Body and Time stamp. Although the SOAP request may besigned, the request will be reject if these elements are not signed. · Signature Confirmation is not implemented.
78
HAN Interface SecurityHAN Interface SecurityValidation ParametersFollowing table describes validation parameters, source and purpose:
Parameter Source Purpose
Subject Name SSL Client Certificate To know the originator of request
UserName Child element of UserNameToken element of SOAP Header
To validate against System Account
RequesterType Child element of SOAP Body To get a LDAP branch where System Account will be validated.
RequesterAuthenticationID Child element of SOAP Body To validate the DUNS number that is presented in this element.
Signer Certificate Out-of-Band To validate the signature
Intermediate SSL Certificate Out-of-Band SSL handshake
Self Signed SSL Certificate Out-of-Band SSL Handshake(Staging Only)
79
HAN Interface SecurityHAN Interface SecurityValidation StepsFollowing are the authentication and validation sequence that happens on the SMT perimeter: • SMT does 2-way SSL hand-shake with the REP endpoint.
• SMT gets the REP name or string identifying REP by reading the HTTP Header variable.
• SMT performs Schema Validation.
80
HAN Interface SecurityHAN Interface SecurityValidation StepsFollowing are the authentication and validation sequence that happens on the SMT perimeter: • SMT validates the signature of the incoming request.
• SMT validates the system account of the REP using the HTTP header variable ENTITY_NAME, UserName from UserNameToken, and RequesterType elements.
• SMT validates the DUNS number of REP using the HTTP header variable ENTITY_NAME, RequesterType and RequsterAuthenticationID elements • If all the steps are successful, the request is sent to SMT internal systems. In the event of
failure at any step, the fault message is sent with an appropriate fault code.
81
HAN Interface SecurityHAN Interface Security
Certificate Authorities List– American Express– ANX– Belacom-E-Trust– C-and-W-HKT-SecureNet-CA– Certipose– Certisign– Certplus– Deutshe– Entrust– Equifax– EUnet– FESTE– First-Data
– Global Sign– GTE-CyberTrust– Microsoft– NetLock– RSA– Saunalahaden– SecureNet– SecureSign– SwissKey– TC-TrustCenter– Thawte– UTN-DATACORP– Valicert– Verisign– ViaCode
82
HAN API Authentication and HAN API Authentication and AuthorizationAuthorization
Authentication and Authorization
• This section discusses how the API authentication and authorization will be handled when direct web service request is made by the REPs to Smart Meter Texas Portal (SMTxP) Enterprise Service Bus.
• Clients who communicate with SMT using the HAN web service interface must support mutual authentication over SSL. DataPower and Tivoli components will authenticate users. Authorization is enforced by the SMT integration environment.
• Two kinds of tokens will be used for authentication: Username or SAML tokens. The majority of the HAN web service consumers are expected to use a Username token. In either case, token data is used to map the sender to a system account. When a Username token is sent, the User Name element identifies the system account. If a SAML token is passed, the NameId element identifies the system account. DataPower validates the originator by verifying the WS-Security signature using the signer certificate from the SMT certificate store. If the digital signature is valid and the user can be authenticated, the web service request is passed to the ESB. Otherwise, a SOAP fault is issued.
83
HAN API Authentication and HAN API Authentication and AuthorizationAuthorization
REP-API SMTxP-DataPower SMTxP-LDAPTDSPSMTxP-ESB
1: SMTxP Provisioning/Messaging Requests
2: Check UserToken
5: Validate REPs DUN with RequesterAuthenticationID in message element
6: Validate RequesterType of REP in message, matches with DUNS Number as REP
10: TDSP Provisioning/Messaging Status Responses
11: Check SAML Token
12: Validate System Account ID
7 : Validate XML Schema
13: Validate XML Schema
9: Send SOAP Faults
15: Send SOAP Faults
3: Validate System Account ID
4: Get REPs DUNS for System Account ID
8: Forward Request to ESB
14: Forward Request to ESB
84
HAN Device Testing CriteriaHAN Device Testing Criteria
• Note: Verify that TDSPs have processes in place to support HAN Device Testing with REPs and HAN Device vendors.
• The TDSPs provide a standardized method of testing and verifying HAN Device functionality to ensure that HAN Devices function as designed within the specifications detailed in the Smart Energy Profile 1.0 when operated on TDSPs advanced metering system (AMS) network. The REPs and HAN Device vendors should contact the TDSPs to initiate request to perform HAN Device testing.
• • The HAN Device test cases that are executed during the ZigFest Interoperability events are
the basis of the test cases executed by the TDSPs in their HAN Device validation program. Some TDSPs have more test cases, and some have less, but all are based on the ZigFest test cases. These include provisioning, deprovisioning, and messaging (simple text, load control and pricing). The TDSPs record the testing results and provide feedbacks to the REPs and HAN Device vendors that requested the tests.
85
HAN Device Testing CriteriaHAN Device Testing Criteria
The following are the technical requirements necessary for HAN Device testing:
• 64-bit IEEE MAC address and installation code
• SEP 1.0 certificationNote: If your device is not SEP 1.0 certified, contact ZigBee athttp://www.zigbee.org or 1-925-275-6607.
• Production certificateNote: If your device does not have production certificates, contactCerticom at http://www.certicom.com/index.php/regzigbee to registerfor production certificates.
86
HAN Device Test CasesHAN Device Test Cases
ZIGBEE HAN TEST CASE
DEVICE TYPE DESCRIPTION DESIRED OUTCOME
PROVISIONING ALL Add a device to the Device successfully
AMS ESI joined to target ESI
DEPROVISIONING ALL Remove device from Device disassociated
the AMS ESI from ESI
TEXT MESSAGE IHD PCT Send a text message Device displays the
correct message CANCEL TEXT MESSAGE IHD PCT Message cancelled Message removed
from the device
CANCEL FUTURE IHD PCT Message cancelled Message removed
TEXT MESSAGE from the device
PRICE MESSAGE IHD PCT Send a price signal Price signal displayed
on the device TIME SYNCRONIZATION ALL HAN Device receives Time is synchronized
current time Time is displayed
and supports DST SEND LOAD CONTROL PCT Temperature Device adjusts MESSAGE - COOLING setpoint change for setpoint at the
TEMPERATURE COOLING for a requested time for SETPOINT prescribed period requested duration SEND LOAD CONTROL PCT Temperature Device adjusts MESSAGE - HEATING setpoint change for setpoint at the
TEMPERATURE HEATING for a requested time for SETPOINT prescribed period requested duration SEND LOAD CONTROL PCT Temperature Device adjusts MESSAGE - COOLING offset change for setpoint at the
TEMPERATURE SOME LCS COOLING for a requested time for
OFFSET prescribed period requested duration SEND LOAD CONTROL PCT Temperature Device adjusts MESSAGE - HEATING offset change for setpoint at the
87
HAN Interoperability ReportHAN Interoperability Report
• The HAN Device Interoperability Report contains information regarding HAN Devices that have passed testing at a particular TDSP. The reports are updated monthly and filed with each TDSP's Commission report. Each report contains the device name, version, meter firmware version, device configuration and date tested. Devices that are in testing or have failed testing are not on this list.
HAN Manufacturer Product
Device Type
HAN Device Firmware
Meter Configuration TDSP
For time period ending
HAN Device A Product name IHD HAN Device FW version
TDSP meter version AEP 29-Feb-12
HAN Device B Product name Thermostat HAN Device FW version
TDSP meter version TNMP 29-Feb-12
HAN Device C Product name GW HAN Device FW version
TDSP meter version CNP 29-Feb-12
HAN Device D Product name LC Switch HAN Device FW version
TDSP meter version ONCOR 29-Feb-12
88
HAN Device Reprovisioning HAN Device Reprovisioning During Meter ExchangeDuring Meter Exchange
Step Description
1
TDSP sends meter exchange transactions with old meter id, new meter id and ESIID
2
SMT removes the HAN Devices from the old meter
3
SMT removes the old meter from the ESIID
4
SMT adds the new meter to the ESIID
5
SMT adds the HAN Devices to the new meter. (This is accomplished via the TDSP MeterHANSynch service and other TDSP-SMT processes)
6
SMT displays the HAN Devices in the UI
89
HAN Device ReprovisioningHAN Device ReprovisioningHAN Meter Exchange (HAN Device Reprovisioning)
Aut
omat
edT
DS
Ps
TD
SP
s
090.TDSP Re provisioning
process
005.TDSP Meter
Exchange Scheduling
010.Send Meter Exchange
Information
030.Request Information on
Devices associated with
ESI ID
TDSP Provisions the HAN Devices to the New Meter
020.Receive Meter Exchange
Information
040.Receive Information
Request
070.Update Provisioning
Status in the Main HAN List/Sublist
050.Send Information
Update
060.Receive Information
Update
080.Update information on the HAN Provisioning
History Log
90
Next StepsNext Steps• Working with Handbook and Education taskforces to review and fine-
tune the HAN Guide – Method to incorporate the HAN documentation into the HandBook – Going forward Process & Procedures to interface HAN documentation, future versions,
with both Task Forces group efforts– Education Process to advise the market of the HAN documentation availability, location
and access method– AMIT steering committee to determine who in the market can have access to the HAN
documentation– Will we provide a soft copy, hard copy or both available to the market
• Gather feedbacks and comments from the Market Participants, and include these in the next version of the HAN Guide
• Please send your feedbacks and comments to:
[email protected] (Joselito Samoy)
91
Thank youThank you