Chapter 4 Domain This chapter describes the separate domain in the open smart grid platform.

Web Service Adapters

The web service adapters use Spring Web Service, contract first. JAXB is used to generate Java classes from the XSD's. All SOAP operations are bound to an endpoint. The incoming SOAP requests are authenticated by organization identification (plus certificates). Organization authorizations are checked for the desired operation. If the request is OK, a JMS message is sent to a domain adapter component.

Domain Adapters

Domain adapters contain business logic and persistence. Domain adapters process and forward the JMS message to the Core component.

Domain Components

Domain components contain entities and value objects.

This chapter describes all the web services in the smart metering domain.

Up-to-date information on use-cases can be found on the Grid eXchange Fabric website.

Reference implementation in The Netherlands: Flexible system for operating public lighting (FlexOVL)

FlexOVL, a new and flexible switching system of public lighting delivers more control for municipalities and is the first solution which is powered by the Open Smart Grid Platform.

Technical drivers for Alliander

• Replacing Ripple Control

• Decrease future investments

• Decrease outages

Customer drivers (Municipalities)

• Be more in control, by controlling switching times themselves

• Resolve power failures faster, through up-to-date information

• Reduction in costs, through energy saving and more efficient maintenance and management

• No vendor lock-in, not dependent on one supplier

Implementation/roll-out

• Small scale roll-out started January 2015

• 200 Sub Stations will be fitted with an SSLD to control public lighting and tariff switching

• 15 municipalities in the Liander grid operator area will be participating

• Goal is to allow municipalities to use the application, give feedback and to see if the services offered to municipalities are adequate

• Large scale roll-out will start around 2016

• The entire Liander grid operator area will use SSLD's to control all public lighting and tariff switching

• About 25.000 Sub Stations (middenspanningsruimtes)

• About 800.000 street lights will be switched by the SSLD's mounted in the 25.000 Sub Stations

FlexOVL web application (not open source available)

Municipalities are free to choose their own (web)application (using the web services of the Open Smart Grid Platform), or they could use the default web application developed by Alliander.

Functionality of the default web application as used by grid operator Liander (example)

• Create switching schedules and assign those schedules to one or more SSLD's

• Create groups of SSLD's in order to be able to assign schedules to many SSLD's at once

• On demand switching of public lighting

• Review current status of an SSLD in order to review public lighting and tariff switching states

• Abilities to monitor power consumption of public lighting (available if the SSLD is fitted with an Electricity Meter)

• Monthly report offering insight into switch moments and power consumption

The Open Smart Grid Platform act as an central component to monitor and control microgrids.

Scope

The goal of this domain is to control and monitor microgrids.

Features

Currently, the following features are available within the Open Smart Grid Platform:

Get Data

Get data is used to retrieve measurement and profile data from the device

Set Data

Set data is used to set setpoints and profiles on the device

Notifications

When either report data or the result for a request is available, a notification is sent to a client, after which the client will be able to obtain the data or result by sending an 'async' message.

Reporting

When a device is connected it will periodically push measurement reports (and send trigger-based status reports) to OSGP. OSGP will inform the client via a notification, after which the data can be retrieved in a way similar to GetData (using the GetDataAsync message). In order to determine whether all report data are received, the response of a GetDataAsync message will (in case of a report) contain report metadata consisting of a report id, sequence number and time of entry.(XSD is already updated with report metadata, returning the report metadata from OSGP is not yet implemented)

Messages

• GetData is a request to retrieve measurement and profile data from a device.

• GetDataAsync is a request to retrieve the result of the GetData request or to retrieve report data pushed by the device.

• SetData is a request to set setpoints and profiles on a device.

• SetDataAsync is a request to retrieve the result of the SetData request.

WSDLs

Cucumber test

Functionality like GetData can now be tested, with the Cucumber framework, using the protocol-simulator-iec61850. This simulator can be started from the Cucumber tests, and is configured with its own properties file.

Multiple Server names

By default the RTU device is configured with the servername: WAGO61850Server. This name also appears in the icd file, that is used by the RTU device. The name of this icd file, is configured in a properties file. Multiple server names are now supported, with the introduction of the new column: server_name in the iec61850_device table. If this value is null, the default servername (WAGO61850Server) is used, otherwise the servername from the database is used (eg 'WAGO123'). In that case another corresponding icd file, in which this servername is used, must be configured!

The Open Smart Grid Platform can also be used in the monitoring of a variety of components in substations; RTUs, switches, transformers, etc. Often, an RTU or Remote Terminal Unit is used as a central information hub in a substation. The RTU is connected to one or more sensors or devices that can measure any kind of information. Usually, the focus is on measuring power quality values, temperature and other 'health' variables, but any kind of measurable data can be read through OSGP.

Scope

The goal of this domain is to control and monitor substations; the current focus is on health status information and power quality data, but this may be extended in the future.

Features

Currently, the following features are available within the Open Smart Grid Platform using the IEC 61850 protocol;

Get PQ Values

Get PQ Values retrieves the actual, current PQ values from a device. Examples of PQ values are Current, Voltage, Reactive Power, Active Power, etc. These examples merely serve as an indication of what is possible; OSGP does not impose any restriction on the number or content of variables that can be read. The outline of what should be measured is configured on the device and in the application that reads the data.

Get Health Status

Retrieves the current health status of a device. This is useful in a monitoring application.

Get Device Model

Retrieves the device model or metadata of a device. This includes the variables that can be measured, the information structure of the device, etc.

Notifications

When either report data or the result for a request is available, a notification is sent to a client, after which the client will be able to obtain the data or result by sending an 'async' message. A notification message always contains the correlation ID of the original request; the client can retrieve the result using this correlation ID.

Messages

• GetPQValues is a request to retrieve PQ values from a device.

• GetPQValuesAsync is a request to retrieve the result of the GetPQValues request or to retrieve report data pushed by the device.

• GetHealthStatus is a request to retrieve the health status of a device.

• GetHealthStatusAsync is a request to retrieve the result of a GetHealthStatus request.

• GetDeviceModel is a request to retrieve the device model from a device

• GetDeviceModelAsync is a request to retrieve the result of a GetDeviceModel request.

WSDLs

This domain covers the use of the open smart grid platform for smart lighting.

Scope

The goal of this domain is to control, monitor and manage (street) lights at scale. It allows streetlight owners to control/manage the (street) lights in an more intelligent way compared to ripple control technology.

Features

This domain consist of Switching schedules, groups, light sensors, manual switching and monitoring of a typical public lighting use-case.

PublicLighting webservices

• PublicLighting WSDL's

• PublicLighting XSD schema's

The open smart grid platform core and admin functions for device management.

Scope

This core and admin domain contains all generic web services that can be used in other domains. Most generic services relate to device management including powerful device authorization management

Common webservices

• Core WSDL's

• Core XSD schema's

Admin webservices

• Admin WSDL's

• Admin XSD schema's

This covers the services for tariff switching domain using the open smart grid platform.

Scope

This domain allows tariff switching. It allows a relay to switch when a tariff changes. This domain could be used to replace ripple control tariff signals.

Webservices

• Tariff switching WSDL's

• Tariff switching XSD schema's

TARIFF (normal) vs. TARIFF_REVERSED

When configuring a device via the platform to switch relays according to a tariff schedule, the device can be instructed to switch the tariff relay normally ("TARIFF") or reversed ("TARIFF_REVERSED").

The devices themselves are unaware of the difference between TARIFF and TARIFF_REVERSED. When sending a setScheduleRequest message for a tariff schedule to the platform, the tariff switching domain adapter checks if the device relay(s) are configured with TARIFF_REVERSED. If so, the tariff switching domain adapter will invert the relay value for all tariff schedule entries before the tariff schedule is sent to the device.

When two devices have the same schedule, while one device is using TARIFF and the other TARIFF_REVERSED, the state of their tariff relays will always be the opposite of each other.

Communicated/Stored values

The values as shown in the table below will be returned, when getting the status from a device or from the platform.

Schedules for light switching can be set using from the . For brevity the XML element and type names in the descriptions below will not include the namespace (which will typically be "http://www.opensmartgridplatform.org/schemas/publiclighting/schedulemanagement/2014/10").

A switching schedule is defined by a number of declarations of switching moments (also known as schedule entries). The SetScheduleRequest defines the schedule, where Schedules of type Schedule define the entries. A complete schedule for a device as set with the Set Schedule request can have 1 up to 50 entries. Each schedule entry defines a moment on a day when certain relays on a device are switched on or off. Whether or not a switch action defined in a schedule entry is executed may not only depend on the entry itself. Other switch moments from the schedule that are compared to an entry may cause switching to be skipped.

A more detailed description of the components defining a schedule entry is in the sections below:

• • explicitly configured

  • time of

  • time of

Week Day

The value of WeekDay is used to indicate on which days the schedule entry may trigger switch actions.

Time

Each schedule entry can cause switching at a single time during the day. There are a number of ways in which this time can be specified, starting with ActionTime.

For ActionTime values SUNRISE or SUNSET the value of TriggerType specifies what the actual switching time should be.

Fixed Time

• hh:mm;

• hh:mm:ss;

• hh:mm:ss.SSS

With hh from 00 to 23, mm from 00 to 59, ss from 00 to 59 and SSS from 000 to 999. Some protocols may accept more precise time formats than they support. The IEC61850 implementation for instance, will silently apply only the hours and minutes from any of the formats listed above.

Astronomical Time

For ActionTime SUNRISE or SUNSET with TriggerType ASTRONOMICAL the astronomical sunrise or sunset time (as calculated by the switching device, based on its longitude and latitude) will be used to determine the switching moment.

Astronomical Offsets

If an astronomical offset is configured, it has to be added to the calculated astronomical time to determine the time to be used as the switching moment. For positive offset values, the astronomical time for the switching moment will be the configured amount of minutes after the calculated astronomical sunrise or sunset time, while for negative values the astronomical time used will be the number of minutes before the calculated astronomical sunrise or sunset time.

####Astronomical Sunrise Offset

The astronomical sunrise offset is applied with entries with ActionTime SUNRISE and TriggerType ASTRONOMICAL. The following picture is an example of switching off at 07:30; the calculated astronomical sunrise (say at 07:15 for the day shown) plus 15 minutes (configured as AstronomicalSunriseOffset 15).

####Astronomical Sunset Offset

Astronomical Time With Sensor

Trigger Window

The TriggerWindow with its minutesBefore and minutesAfter defines a window of time around an astronomical sunrise or sunset time with sensor. Switching will occur at the start of the window when light sensor input is received before the window. Switching will occur at the end of the window when light sensor input is not received before the end of the window. Switching will occur at the time light sensor input is received, when this input is received within the window.

Light sensor input in the conditions above means the sensor trigger for light when the schedule entry is switching off, and the sensor trigger for dark when switching on.

Astronomical Time With Sensor Signal Within The Trigger Window

The following picture is an example where the light sensor reports dark within the trigger window for a schedule entry for astronomical time with sensor signal. Switching on occurs at the time the sensor input is received. Note that for this example this could have been at any time between 19:45 and 20:30 (15 minutes before to 30 minutes after the astronomical sunset, calculated to occur at 20:00 on the day shown).

Astronomical Time With Sensor Signal Before The Trigger Window Opens

The following picture is an example where the device has received a light sensor report before the trigger window opens for a schedule entry for astronomical time with sensor signal. Switching off occurs at the start of the trigger window.

Astronomical Time Without Sensor Signal Before The Trigger Window Closes

The following picture is an example where the device has not received a light sensor report before the trigger window closes for a schedule entry for astronomical time with sensor signal. Switching on occurs at the end of the trigger window.

Minimal Burning Time

For certain types of lighting it may be undesirable to switch the lights on only for a short period of time, after which they are switched off again. In such a case the action of switching the lights on will be suppressed if minimumLightsOn is set with a positive number of seconds, and the action switching the lights off again is expected within this time period.

The minimal burning time is always regarded with respect to an actual time for a switching moment that switches a relay on in comparison with the expected time of the next switching moment where the same relay will be switched off again. Switching on will be skipped if switching off is expected to occur within a number of minutes set as minimumLightsOn with the schedule entry that switches the relay on.

Minimal Burning Time With Astronomical Offset

Minimal Burning Time With Light Sensor Trigger Window

Light Value

Each schedule entry may include 1 to 6 LightValue elements. These light values determine the relay to switch, whether the relay should be switched on or off, and whether the lights with a relay should be dimmed (and by how much).

• Index: 0 for all light switching relays in the device, or 1 to 6 for numbered relays (the

  index should indicate an existing relay that is used for light switching).

• On: true if this entry is for switching on the relay(s) identified by Index; false for

  switching off.

• DimValue: optional percentage set as number 1 to 100 indicating a dim value; will be ignored

  when the protocol or switching device does not support dimming.

Common Light Scheduling Patterns

Here are some examples of patterns that are common with light schedules. The patterns are formed by combinations of schedule entries that switch on or off lights controlled by a certain relay on the switching device.

All Night Lights

All night lights is a name for lights that are turned on around sunset and keep burning all night until they are switched off again around sunrise. The all night lights are switched by a pair of schedule entries:

Morning Lights

Morning lights is a name used for lights that are switched on a short period in the morning hours of a day to illuminate a period before or around the morning twilight. The morning lights are switched by a pair of schedule entries:

Fixed Time And Sunrise Interaction

During the summer in the Netherlands for example sunrise can be as early as approximately 05:15, while during the winter the sun may rise even a little later than 08:45. For this example we will assume configuration for the morning lights to switch on at fixed time of say 06:00. This is a time after the earliest sunrise in the year, but well before the latest sunrise in the year. To complete the morning lights configuration, a second switching moment is configured to switch the lights off at sunrise. With this set up the lights will be switched off after having been on for almost three hours at some time in the winter (for instance from 06:00 to 08:45). During summer at some days the lights will not be switched off in the morning at all because they were turned on (at 06:00) after sunrise (switching off at any time before 06:00, for instance at 05:30).

Whether the lights stay on all day in the summer or not is something to be looked into. A switching device may have logic to deal with this situation figuring out the switch off belongs with the later switching moment to turn the lights on, and decide not to switch on. If not, some validation may be needed to enforce such schedules not to be configured.

Evening Lights

The evening lights are switched by a pair of schedule entries:

Fixed Time And Sunset Interaction

Evening/Morning Lights

Validity

The GXF Public Lighting Schedule Management web service does not do much validation, other than checking authorizations for the device identified by the DeviceIdentification from the SetScheduleRequest and whether the request conforms to its XML schema definitions.

If for certain applications more constraints are desirable, it is left up to those applications to make sure the requests made to the platform conform to those additional constraints. Examples of such constraints, that are not enforced by GXF, could be:

• no duplicated schedule entries;

• no schedule entries canceling the switch actions of other entries within some time window;

• schedule entries may be required for all days of the week;

• switching on and off might be required to happen each day in equal number of times and alternately;

• checking expected actions around daylight saving change;

• checking expected switching actions for days with the longest or shortest number of hours of daylight;

• light value indexes map to existing light relays on the device the schedule is set on;

• constraints from applying the provided input with specific devices or protocols.

Protocol Implementations For Light Schedules

This chapter describes the SmartMetering domain including the web services. Currently the web services of the beta version are described, since the web services have not yet officially been released. Information on the DLMS device simulator can be found in the DLMS protocol section

Scope

The goal of this domain is to read and manage millions of smart meters. This includes smart meter installation, firmware updates, smart meter removal, read smart meter values, time synchronisation, etc. Everything that is needed to professionally manage millions of smart meters is or can be included in this domain.

Features

Currently, the following Smart Metering features are available within the open smart grid platform:

• Add smart meter to the platform, so the device is known and additional actions can be performed for the device

• Process shipment file, which adds several smart meters to the platform along with all needed information

• Synchronize time between smart meters and head-end system, in case the smart meter adjusts its time, some events will be logged

• Retrieve events from the smart meter, several event logs are available

• Retrieve periodic meter reads from the smart meter

Generic functionality

• bypass retry operations can be given the flag 'bypass retry'. Which means that an operation will not be retried in case of an error.

• priority operations can be given a priority from 0 to 9, default is 4. Higher values causes messages to be processed faster.

• scheduling operations can be scheduled for a certain time.

• bundling operations can be combined in a Bundle.

Messages

SmartMeteringAdHoc

• SynchronizeTime is an operation to synchronize the date and time on a device. The date and time are retrieved from the server and sent to the device.

• GetSynchronizeTimeResponse is an operation which returns the response from the SynchronizeTime operation.

• RetrieveAllAttributeValues is an operation to obtain all the attributes of the whole tree of objects from an E-meter.

• GetRetrieveAllAttributeValuesResponse is an operation which returns the response from the RetrieveAllAttributeValues operation.

• GetSpecificAttributeValue is an operation to obtain a specific attribute value from an ObisCode from an E-meter.

• GetSpecificAttributeValueResponse is an operation which returns the response from the GetSpecificAttributeValue operation.

• GetAssociationLnObjects is an operation to get the associated ln objects.

• GetGetAssociationLnObjectsResponse is an operation which gets the response from the GetAssociationLnObjects operation.

• ScanMbusChannels is an operation to get the M-Bus Short ID attribute values for all four channels from an E-meter.

• ScanMbusChannelsResponse is an operation which returns the response from the ScanMbusChannels operation.

SmartMeteringConfiguration

• SetSpecialDays is an operation to set a dayId profile and its tariffs for a specific date on a device.

• GetSetSpecialDaysResponse is an operation which returns the response from the SetSpecialDays operation.

• SetConfigurationObject is an operation to set ConfigurationObject settings on a device to specify behaviour and connection options.

• GetSetConfigurationObjectResponse is an operation which returns the response from the SetConfigurationObject operation.

• GetConfigurationObject is an operation to retrieve a ConfigurationObject from a device.

• GetConfigurationObjectResponse is an operation which returns the response, a ConfigurationObject, from the GetConfigurationObject operation.

• SetPushSetupAlarm is an operation that pushes received alarm messages to OSGP.

• GetSetPushSetupAlarmResponse is an operation which returns the response from the SetPushSetupAlarm operation.

• SetPushSetupSms is an operation to set an endpoint in a device which tells the device where to connect to when it is waked up.

• GetSetPushSetupSmsResponse is an operation which returns the response from the SetPushSetupSms operation.

• SetAlarmNotifications is an operation to set the types of alarm notifications that must be notified from the device when they occur.

• GetSetAlarmNotificationsResponse is an operation which returns the response from the SetAlarmNotifications operation.

• SetKeyOnGMeter is an operation to transfer and set a G-meter key on a device.

• GetSetKeyOnGMeterResponse is an operation which returns the response from the SetKeyOnGMeterRequest operation.

• SetMbusUserKeyByChannel is an operation to set the M-Bus encryption key on an M-Bus device by using the E-meter device identification and channel from the G-meter.

• SetMbusUserKeyByChannelResponse is an operation which returns the response from the SetMbusUserKeyByChannel operation.

• GetMbusEncryptionKeyStatus is an operation to retrieve the encryption key status for a M-Bus device.

• GetGetMbusEncryptionKeyStatusResponse is an operation which returns the response from the GetMbusEncryptionKeyStatus operation.

• GetMbusEncryptionKeyStatusByChannel is an operation to get the M-Bus encryption key status from an M-Bus device by using the E-meter device identification and channel from the G-meter.

• GetMbusEncryptionKeyStatusByChannelResponse is an operation which returns the response from the GetMbusEncryptionKeyStatusByChannel operation.

• SetActivityCalendar is an operation to set several parameters on an E-meter such as tariffs per day in a week profile.

• GetSetActivityCalendarResponse is an operation which returns the response from the SetActivityCalendar operation.

• GetAdministrativeStatus is an operation to retrieve the current AdministrativeStatus setting.

• GetGetAdministrativeStatusResponse is an operation which returns the response from the GetAdministrativeStatus operation.

• SetAdministrativeStatus is an operation to set the AdministrativeStatus.

• GetSetAdministrativeStatusResponse is an operation which returns the response from the SetAdministrativeStatus operation.

• GetFirmwareVersion is an operation to retrieve the firmware version(s).

• GetGetFirmwareVersionResponse is an operation which returns the response from the GetFirmwareVersionoperation.

• ReplaceKeys is an operation to change the keys on a E-meter.

• GetReplaceKeysResponse is an operation which returns the response from the ReplaceKeys operation.

• UpdateFirmware is an operation to update the firmware module(s) on a device.

• GetUpdateFirmwareResponse is an operation which returns the response from the UpdateFirmware operation.

• GenerateAndReplaceKeys is an operation to generate and set the encryption and authentication key on a device.

• GenerateAndReplaceKeysResponse is an operation which returns the response from the GenerateAndReplaceKeys operation.

• SetClockConfiguration is an operation to set the clock configuration on a device.

• GetSetClockConfigurationResponse is an operation which returns the response from the SetClockConfiguration operation.

• ConfigureDefinableLoadProfile is an operation to configure the load profile on a device.

• GetConfigureDefinableLoadProfileResponse is an operation which returns the response from the ConfigureDefinableLoadProfile operation.

SmartMeteringInstallation

• AddDevice is an operation to add a device to the OSGP database.

• GetAddDeviceResponse is an operation which returns the response from the AddDevice operation.

• CoupleMbusDevice is an operation to couple a M-Bus device to a gateway.

• GetCoupleMbusDeviceResponse is an operation which returns the response from the CoupleMbusDevice operation.

• CoupleMbusDeviceByChannel is an operation to couple a M-Bus device to a gateway.

• GetCoupleMbusDeviceByChannelResponse is an operation which returns the response from the CoupleMbusDeviceByChannel operation.

• DeCoupleMbusDevice is an operation to decouple an M-Bus device from a gateway.

• GetDeCoupleMbusDeviceResponse is an operation which returns the response from the DeCoupleMbusDevice operation.

SmartMeteringManagement

• ClearMBusStatusOnAllChannels is an operation to clear the M-Bus status on all channels, so G-meters are ready to raise new alarms.

• FindEvents is an operation to retrieve events logging from a device.

• GetFindEventsResponse is an operation which returns the response from the FindEvents operation.

• GetDevices is an operation to retrieve the last known relay statuses for a group of devices.

• EnableDebugging is an operation to enable debug logging for a device.

• GetEnableDebuggingResponse is an operation which returns the response from the EnableDebugging operation.

• DisableDebugging is an operation to disable debug logging for a device.

• GetDisableDebuggingResponse is an operation which returns the response from the DisableDebugging operation.

• FindMessageLogs is an operation to read the debug logging from a device.

• GetFindMessageLogsResponse is an operation which returns the response from the FindMessageLogs operation.

• SetDeviceCommunicationSettings is an operation to set the OSGP device communication settings for a specific device.

• SetDeviceCommunicationSettingsResponse is an operation which returns the response from the SetDeviceCommunicationSettings operation.

• SetDeviceLifecycleStatus is an operation to set the lifecycle status from a device.

• SetDeviceLifecycleStatusResponse is an operation which returns the response from the SetDeviceLifecycleStatus operation.

• SetDeviceLifecycleStatusByChannel is an operation to set the lifecycle status from a device.

• SetDeviceLifecycleStatusByChannelResponse is an operation which returns the response from the SetDeviceLifecycleStatusByChannel operation.

SmartMeteringMonitoring

• GetActualMeterReads is an operation to retrieve the actual meter reads from an E-meter.

• GetActualMeterReadsResponse is an operation which returns the response from the ActualMeterReads operation.

• GetActualMeterReadsGas is an operation to retrieve the actual meter reads from a G-meter.

• GetActualMeterReadsGasResponse is an operation which returns the response from the ActualMeterReadsGas operation.

• GetPeriodicMeterReads is an operation to retrieve the periodic meter reads from an E-meter.

• GetPeriodicMeterReadsResponse is an operation which returns the response from the PeriodicMeterReads operation.

• GetPeriodicMeterReadsGas is an operation to retrieve the periodic meter reads from a G-meter.

• GetPeriodicMeterReadsGasResponse is an operation which returns the response from the PeriodicMeterReadsGas operation.

• GetProfileGenericData is an operation to retrieve any Profile Generic data from an E-meter.

• GetProfileGenericDataResponse is an operation which returns the response from the ProfileGenericData operation.

• ReadAlarmRegister is an operation to read the alarm register from a device.

• GetReadAlarmRegisterResponse is an operation which returns the response from the ReadAlarmRegister operation.

• RetrievePushNotificationAlarm is an operation to push retrieved alarm notifications to OSGP.

• ClearAlarmRegister is an operation to clear the Alarm register flags for pushed event notifications.

• ClearAlarmRegisterResponse is an operation which returns the response from the ClearAlarmRegister operation.

DeviceManagement

• SetDeviceLifecycleStatus is an operation to set the device lifecycle status of a device.

• SetDeviceLifecycleStatusResponse is an operation which returns the response from the SetDeviceLifecycleStatus operation.

SmartMeteringNotification

• SendNotification is an operation to let Webapps know there is a result ready to retrieve from the platform.

SmartMeteringBundle

• Bundle is a special operation in which one or more single operation(s) to a specific device can be bundled.

• GetBundleResponse is an operation which gets the response from the Bundle operation.

All operations sent to this device make use of one communication channel, which may improve performance considerably.

WSDL's

• SmartMetering WSDL's

• SmartMetering XSD schema's

By adding an element BypassRetry in namespace http://www.opensmartgridplatform.org/schemas/common/2014/10 with a value true or false, you can bypass retry when request to the device fail.

By adding an element MessagePriority in namespace http://www.opensmartgridplatform.org/schemas/common/2014/10 with a value from 0 - 9 you can give a message a lower or higher priority.

Describes the actions as defined in SmartMeteringAdhoc.wsdl

Description

GetAssociationLnObjects is a request to get the Association LN object tree from an E-meter. The request is sent with the DeviceIdentification number from the desired device.

All requests have similar response behaviour which is described in ResponseMessages.

GetGetAssociationLnObjectsResponse returns the result values from getting the Association LN object. The response contains the DeviceIdentification and CorrelationUid which is received from the GetAssociationLnObjects request.

References

XSD: sm-adhoc.xsd

WSDL: SmartMeteringAdhoc.wsdl

Description

SpecificConfigurationObject is a request to retrieve the data for a specific configuration object indicated with:

• ClassId

• Attribute

• ObisCode

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringBundle.wsdl

By adding an element ScheduleTime in namespace http://www.opensmartgridplatform.org/schemas/common/2014/10 with a xsd:dateTime value can schedule a message.

Description

GetGetAssociationLnObjectsResponse returns the result values from getting the Association LN object. The response contains the DeviceIdentification and CorrelationUid which is received from the GetAssociationLnObjects request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-adhoc.xsd

WSDL: SmartMeteringAdhoc.wsdl

Description

SynchronizeTime request synchronizes the date and time on a device. The date and time are retrieved from the server and sent to the device with CLASS_ID 8, OBIS_CODE 0.0.1.0.0.255 and ATTRIBUTE_ID 2. The request is sent with the DeviceIdentification number from the desired device. The request should contain a Deviation of local time to UTC in minutes (from the range of -720 to 720 inclusive) and a value Dst indicating whether daylight savings is active. For example in Central European Summer Time, DST is active and times are UTC/GMT +2 hours. For devices in a region where CEST applies, during the summer time the value for deviation should be "-120" (120 minutes deducted from local time gives GMT/UTC time) and dst should be "true".

All requests have similar response behaviour which is described in ResponseMessages.

GetSynchronizeTimeResponse returns the result from synchronizing date and time. The response contains the DeviceIdentification and CorrelationUid which is received from the SynchronizeTime request.

References

XSD: sm-adhoc.xsd

WSDL: SmartMeteringAdhoc.wsdl

You can combine multiple requests to a meter in a bundle by creating a BundleRequest with one or more Actions in the namespace . Each Action contains one of the existing requests to a meter.

A bundle is executed using one connection to the meter. A bundle response contains all individual responses of executed commands both successful and unsuccessful. When an individual request fails it is retried when this is useful, more precisely the bundle is retried, executing only requests that are fit for re-submission.

Describes the actions as defined in

Description

GetBundleResponse returns the result of the bundle requested with the Bundle method. The response contains the DeviceIdentification and CorrelationUid which is received from the request.

All requests have similar response behaviour which is described in .

References

XSD:

WSDL:

Description

GetAdministrativeStatus is a request to retrieve the current AdministrativeStatus setting from a device. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in .

returns if the setting GetAdministrativeStatus is enabled. The response contains the DeviceIdentification and CorrelationUid which is received from the GetAdministrativeStatus request.

References

XSD:

WSDL:

Description

Bundle is a special request in which one or more single request(s) to a specific device can be bundled. All requests sent to this device make use of one communication channel, which may improve performance considerably.

returns the result of the actions of the bundle. The response contains the DeviceIdentification and CorrelationUid which is received from the Bundle request.

The Bundle request has an Actions tag. This contains a list of one or more single request(s). The response behavior is described in .

Actions

Currently, the following actions are supported:

• FindEventsRequest see

• SetSpecialDaysRequest see

• ReadAlarmRegisterRequest see

• GetActualMeterReadsRequest see

• GetActualMeterReadsGasRequest see

• GetAdministrativeStatusRequest see

• GetPeriodicMeterReadsRequest see

• GetPeriodicMeterReadsGasRequest see

• SetAdministrativeStatusRequest see

• SetActivityCalendarRequest see

• SetKeyOnGMeterRequest see

• SetAlarmNotificationsRequest see

• SetConfigurationObjectRequest see

• SetPushSetupAlarmRequest see

• SetPushSetupSmsRequest see

• SynchronizeTimeRequest see

• GetConfigurationRequest

• GetFirmwareVersionRequest

• UpdateFirmwareRequest see

• GetSpecificConfigurationObjectRequest see

• SetKeysRequest

• GetAssociationLnObjectsRequest

• SetClockConfigurationRequest

• GetProfileGenericDataRequest see

• ConfigureDefinableLoadProfileRequest see

• SetMbusUserKeyByChannelRequest see

• GetMBusEncryptionKeyStatusRequest see

References

Description

GetSynchronizeTimeResponse returns the result from synchronizing date and time. The response contains the DeviceIdentification and CorrelationUid which is received from the SynchronizeTime request.

All requests have similar response behaviour which is described in .

References

XSD:

WSDL:

Description

GetUpdateFirmwareResponse returns the device firmware versions that are on the device after calling the UpdateFirmware method. The response contains the DeviceIdentification and CorrelationUid which is received from the UpdateFirmware request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetGetAdministrativeStatusResponse returns if the setting GetAdministrativeStatus is enabled. The response contains the DeviceIdentification and CorrelationUid which is received from the GetAdministrativeStatus request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

UpdateFirmware is a request to install another firmware version(s) on a device. The request needs the DeviceIdentification and the firmware versions, that together with the device model (as stored with the identified device) uniquely determine the firmware file to be used.

All requests have similar response behaviour which is described in ResponseMessages.

GetUpdateFirmwareResponse returns the version(s). The response contains the DeviceIdentification and CorrelationUid which is received from the UpdateFirmware request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

ReplaceKeys is a request to change the keys on an E-meter. The request needs the DeviceIdentification, an AuthenticationKey and an EncryptionKey.

All requests have similar response behaviour which is described in ResponseMessages.

GetReplaceKeysResponse returns if the result is successful from the ReplaceKeys request. The response contains the DeviceIdentification and CorrelationUid which is received from the ReplaceKeys request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetFirmwareVersion is a request to retrieve the firmware version(s) of a device. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in .

returns the version(s). The response contains the DeviceIdentification and CorrelationUid which is received from the GetFirmwareVersion request.

References

XSD:

WSDL:

Description

GetGetFirmwareVersionResponse returns the device firmware versions requested with the GetFirmwareVersion method. The response contains the DeviceIdentification and CorrelationUid which is received from the GetFirmwareVersion request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetActivityCalendarResponse returns the result from setting a SetActivityCalendar. The response contains the DeviceIdentification and CorrelationUid which is received from the SetActivityCalendar request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetReplaceKeysResponse returns if the result is successful from the ReplaceKeys request. The response contains the DeviceIdentification and CorrelationUid which is received from the ReplaceKeys request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetActivityCalendar is a request to set tariffs on an E-meter according a SeasonProfile and WeekProfile. In a WeekProfile, seven dayprofiles can be filled in with a start time and dayId which contains the tariff.

The request needs the DeviceIdentification, CalendarName, ActivatePassiveCalendarTime, SeasonProfileName, SeasonStart, WeekProfileName, DayId and StartTime.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetActivityCalendarResponse returns the result from setting a SetActivityCalendar. The response contains the DeviceIdentification and CorrelationUid which is received from the SetActivityCalendar request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetKeys is a request to retrieve keys of a device. Multiple keys can be requested in one request. The keys in the response will be encrypted with the configured public key of the calling application.

The following key types are allowed:

• E_METER_MASTER_KEY,

• E_METER_AUTHENTICATION_KEY,

• E_METER_ENCRYPTION_KEY_UNICAST,

• E_METER_ENCRYPTION_KEY_BROADCAST,

• G_METER_MASTER_KEY,

• G_METER_ENCRYPTION_KEY,

• G_METER_FIRMWARE_UPDATE_AUTHENTICATION_KEY,

• G_METER_OPTICAL_PORT_KEY

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetAdministrativeStatusis a request to set the AdministrativeStatus on a device. The request needs the DeviceIdentification and Enabled parameter.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetAdministrativeStatusResponse returns if the setting SetAdministrativeStatus is enabled. The response contains the DeviceIdentification and CorrelationUid which is received from the SetAdministrativeStatus request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetAdministrativeStatusResponse returns if the setting SetAdministrativeStatus is enabled. The response contains the DeviceIdentification and CorrelationUid which is received from the SetAdministrativeStatus request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetAlarmNotifications is a request to set the types of alarm notifications that must be notified from the device when they occur. The following notifications can be enabled or disabled:

CLOCK_INVALID, REPLACE_BATTERY, POWER_UP, PROGRAM_MEMORY_ERROR, RAM_ERROR, NV_MEMORY_ERROR, MEASUREMENT_SYSTEM_ERROR, WATCHDOG_ERROR, FRAUD_ATTEMPT, COMMUNICATION_ERROR_M_BUS_CHANNEL_1, COMMUNICATION_ERROR_M_BUS_CHANNEL_2, COMMUNICATION_ERROR_M_BUS_CHANNEL_3, COMMUNICATION_ERROR_M_BUS_CHANNEL_4, FRAUD_ATTEMPT_M_BUS_CHANNEL_1, FRAUD_ATTEMPT_M_BUS_CHANNEL_2, FRAUD_ATTEMPT_M_BUS_CHANNEL_3, FRAUD_ATTEMPT_M_BUS_CHANNEL_4, NEW_M_BUS_DEVICE_DISCOVERED_CHANNEL_1, NEW_M_BUS_DEVICE_DISCOVERED_CHANNEL_2, NEW_M_BUS_DEVICE_DISCOVERED_CHANNEL_3, NEW_M_BUS_DEVICE_DISCOVERED_CHANNEL_4

The request needs the DeviceIdentification, AlarmType and Enabled parameters.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetAlarmNotificationsResponse returns the result from setting a SetAlarmNotifications. The response contains the DeviceIdentification and CorrelationUid which is received from the SetAlarmNotifications request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetConfigurationObjectResponse returns the result from setting a ConfigurationObject. The response contains the DeviceIdentification and CorrelationUid which is received from the SetConfigurationObject request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetKeyOnGMeter is a request to transfer and set an encryption key, firmware update authentication key or an optical port key on a G-meter via the E-meter. The request needs the DeviceIdentification from the G-meter and the key type (secrettype). If the device identification of the G-meter is not known, but the gateway device identification and M-Bus channel are known, use the SetMbusUserKeyByChannel request instead. If the key type is the optical port key, the parameter to close the optical port can be set as well.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetKeyOnGMeterResponse returns the result from setting a SetKeyOnGMeter. The response contains the DeviceIdentification and CorrelationUid which is received from the SetKeyOnGMeter request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetKeyOnGMeterResponse returns the result from setting a SetKeyOnGMeter. The response contains the DeviceIdentification and CorrelationUid which is received from the SetKeyOnGMeter request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetConfigurationObject is a request to set ConfigurationObject settings on a device. The attributes with OBIS code 0-1:94.31.3.255 give access to set GPRS_operation_mode setting and following flags:

• discover_on_open_cover

• discover_on_power_on

• dynamic_mbus_address

• P0_enable

• HLS_3_on_P3_enable

• HLS_4_on_P3_enable

• HLS_5_on_P3_enable

• HLS_3_on_P0_enable

• HLS_4_on_P0_enable

• HLS_5_on_P0_enable

See DSMR document chapter 8.3 for detailed description. The request needs the DeviceIdentification, GprsOperationMode, ConfigurationFlagType and Enabled parameters.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetConfigurationObjectResponse returns the result from setting a SetConfigurationObject. The response contains the DeviceIdentification and CorrelationUid which is received from the SetConfigurationObject request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetAlarmNotificationsResponse returns the result from setting a SetAlarmNotifications. The response contains the DeviceIdentification and CorrelationUid which is received from the SetAlarmNotifications request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetPushSetupAlarm is a request to define the TCP message that is optionally sent by the device. The request consists of the DeviceIdentification and at least one of the following optional items:

• The destination: Host URL and port.

• The push object list, defining which information should be sent in the alarm.

If an item is not included in the message, the value in the meter will remain unchanged.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetPushSetupAlarmResponse returns the result from setting a SetPushSetupAlarm. The response contains the DeviceIdentification and CorrelationUid which is received from the SetPushSetupAlarm request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetPushSetupAlarmResponse returns the result from setting a SetPushSetupAlarm. The response contains the DeviceIdentification and CorrelationUid which is received from the SetPushSetupAlarm request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetConfigurationObject is a request to retrieve a ConfigurationObject from a device. The configuration object in the electricity meter with the OBIS code 0-1:94.31.3.255 is used to access the GPRS_operation_mode setting and following flags:

• discover_on_open_cover

• discover_on_power_on

• dynamic_mbus_address

• P0_enable

• HLS_3_on_P3_enable

• HLS_4_on_P3_enable

• HLS_5_on_P3_enable

• HLS_3_on_P0_enable

• HLS_4_on_P0_enable

• HLS_5_on_P0_enable

See DSMR document chapter 8.3 for detailed description. The request needs the DeviceIdentification.

All requests have similar response behavior which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetSpecialDaysResponse returns the result from setting a Special Day. The response contains the DeviceIdentification and CorrelationUid which is received from the SetSpecialDays request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetSpecialDays is a request to set a dayId profile for a specific date on a device, other than the standard applicable dayId's. This can be useful to change tariffs and tariff scheduling for specific days such as public holidays. The request is send with the DeviceIdentification number from the desired device, date and dayId.

All requests have similar response behaviour which is described in ResponseMessages.

GetSetSpecialDaysResponse returns the result from setting a Special Day. The response contains the DeviceIdentification and CorrelationUid which is received from the SetSpecialDays request.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

SetPushSetupSms is a request to set an endpoint in a device which tells the device where to connect to when it is woken. The request needs the DeviceIdentification, host URL and port.

All requests have similar response behaviour which is described in .

returns the result from setting a SetPushSetupSms. The response contains the DeviceIdentification and CorrelationUid which is received from the SetPushSetupSms request.

References

XSD:

WSDL:

Description

GetSetPushSetupSmsResponse returns the result from setting a SetPushSetupSms. The response contains the DeviceIdentification and CorrelationUid which is received from the SetPushSetupSms request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetConfigurationObjectResponse returns the result, a ConfigurationObject, which is received from the GetConfigurationObject request.

All requests have similar response behavior which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetConfigureDefinableLoadProfileResponse returns if the result is successful from the ConfigureDefinableLoadProfile request. The request contains the DeviceIdentification and CorrelationUid which is received from the ConfigureDefinableLoadProfile request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

ConfigureDefinableLoadProfile is a request to change the configuration of the definable load profile (COSEM object of interface class 'Profile generic' with logical name '0-1:94.31.6.255') of the device. The request needs the DeviceIdentification, and at least one of CaptureObjects and CapturePeriod.

The CaptureObjects element may be included in the request to specify one or more objects to be captured in the definable load profile, containing definitions as CaptureObject according to the CaptureObjectDefinition in . The CaptureObjects should not include the clock definition ({8,0-0:1.0.0.255,2,0}) as this will always be included as first capture object. This matches the way works when retrieving the buffer of the definable load profile (where you must not specify the clock definition as selected value).

The CapturePeriod may be included to specify the automatic capturing period in seconds (a value of zero meaning no automatic capturing should be done).

All requests have similar response behaviour which is described in .

The response contains the DeviceIdentification and CorrelationUid which is received from the ConfigureDefinableLoadProfile request. returns if the result is successful from the ConfigureDefinableLoadProfile request.

References

XSD:

WSDL:

Description

SetMbusUserKeyByChannel is a request to generate, transfer and set an M-Bus user key on an M-Bus device (for instance a G-meter behind an E-meter) via the DLMS gateway device. The request needs the DeviceIdentification from the gateway device and the channel for the M-Bus device. A use case for a request with the channel (as only identification of the M-Bus device besides the identification of the gateway) as input is to be able to respond to new M-Bus device discovered on channel x alarms (x in 1..4) from a gateway. If a new M-Bus User key is to be set on an M-Bus device with a known identification, this can be done with the request.

All requests have similar response behaviour which is described in .

The response contains the DeviceIdentification and CorrelationUid which is received from the SetMbusUserKeyByChannel request. returns the result from issuing a SetMbusUserKeyByChannel request.

References

XSD:

WSDL:

Description

GetMbusEncryptionKeyStatus is a request to retrieve the encryption key status of a M-Bus device from an E-meter. The request needs the DeviceIdentification of the M-Bus Device.

All requests have similar response behaviour which is described in ResponseMessages.

The returned response for the GetMbusEncryptionKeyStatus request is as specified in GetGetMbusEncryptionKeyStatusResponse.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetSetMbusUserKeyByChannelResponse returns the result from issuing a SetMbusUserKeyByChannel request. The request contains the DeviceIdentification and CorrelationUid which is received from the request.

All requests have similar response behaviour which is described in .

References

XSD:

WSDL:

Description

GetGetMbusEncryptionKeyStatusResponse is a request to return the M-Bus encryption key status as requested by a GetMbusEncryptionKeyStatus request. The possible return values for the M-Bus encryption key status can be found in the EncryptionKeyStatus enum in the sm-configuration.xsd

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

GetMbusEncryptionKeyStatusByChannel is a request to retrieve the encryption key status of an M-Bus device from an E-meter. The request needs the DeviceIdentification of the gateway device and a channel.

All requests have similar response behaviour which is described in ResponseMessages.

The returned response for the GetMbusEncryptionKeyStatusByChannel request is as specified in GetMbusEncryptionKeyStatusByChannelResponse.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.wsdl

Description

ScanMbusChannelsResponse returns the result of a request. The response contains the M-Bus Short Equipment Identifier (Short ID) attributes (Identification number, Manufacturer identification, Version identification, and Device type identification) from all four channels of a Gateway device.

References

XSD:

WSDL:

Describes the actions as defined in

Description

ScanMbusChannels is a request to read the M-Bus Short Equipment Identifier (Short ID) attributes (Identification number, Manufacturer identification, Version identification, and Device type identification) from all four channels on a Gateway device to determine if an M-Bus device is bound on a channel of the Gateway device.

All requests have similar response behaviour which is described in .

The returned response for the ScanMbusChannels request is as specified in .

References

XSD:

WSDL:

Description

AddDevice is a request to add a device to the OSGP database. For the list of parameters, see the .xsd file (link below).

All requests have similar response behaviour which is described in

returns if the result is successful from the request. The response contains the DeviceIdentification and CorrelationUid which is received from the AddDevice request.

References

XSD:

WSDL:

Example scenario

Example XML Message

Description

GetAddDeviceResponse returns if the result is successful from the AddDevice request. The response contains the DeviceIdentification and CorrelationUid which is received from the AddDevice request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-installation.xsd

WSDL: SmartMeteringInstallation.wsdl

Description

CoupleMbusDevice is a request to couple a gateway and a m-bus device. The request needs the following parameters:

• DeviceIdentification

• MbusDeviceIdentification

• Force

All requests have similar response behaviour which is described in ResponseMessages

If Force has value true, the check if Mbus device is connected to other device will be ignored

GetCoupleMbusDeviceResponse returns if the result is successful from the request. The response request contains the DeviceIdentification and CorrelationUid which is received from the CoupleMbusDevice request.

References

XSD: sm-installation.xsd

WSDL: SmartMeteringInstallation.wsdl

Description

DeCoupleMbusDevice is a request to decouple an Mbus device (such as a gas meter) from a device to the OSGP database. The request needs the following parameters:

• DeviceIdentification

• MbusDeviceIdentification

All requests have similar response behaviour which is described in

returns if the result is successful from the request. The response contains the DeviceIdentification and CorrelationUid which is received from the DeCoupleMbusDevice request.

References

XSD:

WSDL:

Describes the actions as defined in

Description

GetDeCoupleMbusDeviceResponse returns if the result is successful from the DeCoupleMbusDevice request. The response contains the DeviceIdentification and CorrelationUid which is received from the request.

All requests have similar response behaviour which is described in .

References

XSD:

WSDL:

Description

GetCoupleMbusDeviceResponse returns if the result is successful from the CoupleMbusDevice request. The response contains the DeviceIdentification and CorrelationUid which is received from the request.

All requests have similar response behaviour which is described in .

References

XSD:

WSDL:

Description

FindEvents is a request to retrieve periodic events logging from a device. The request needs the DeviceIdentification, EventLogCategory, From and Until DateTime. The EventlogCategories consist off:

• STANDARD_EVENT_LOG

• FRAUD_DETECTION_LOG

• COMMUNICATION_SESSION

• M_BUS_EVENT_LOG

• POWER_QUALITY_EVENT_LOG

• AUXILIARY_EVENT_LOG

DSMR Chapter 4.2.1 and SMR5.1 chapters 4.2.1 and 4.2.2 describe the several events and their descriptions.

All requests have similar response behaviour which is described in ResponseMessages.

GetFindEventsResponse returns if the result is successful from the request. The response contains the DeviceIdentification and CorrelationUid which is received from the FindEvents request.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

GetFindEventsResponse returns if the result is successful from the FindEvents request. The response contains the DeviceIdentification and CorrelationUid which is received from the FindEvents request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

SetDeviceLifecycleStatusBychannel is a request to set the device lifecycle status of an Mbus device, using the device identification of the Gateway device and a channel.

All requests have similar response behaviour which is described in ResponseMessages.

The returned response for the SetDeviceLifecycleStatusByChannel request is as specified in SetDeviceLifecycleStatusByChannelResponse.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

GetDevices is a request to get the last known relay statuses for a group of devices, so you can get an overview of statuses for a specific set of devices. The request needs the Page parameter.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

Enable debugging for a device. Communication with the device will be logged and made available through FindMessageLogs,

All requests have similar response behaviour which is described in ResponseMessages.

GetEnableDebuggingResponse returns the result status. The response contains the DeviceIdentification and CorrelationUid which is received from the GetEnableDebuggingRequest request.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

SetDeviceLifecycleStatusByChannelResponse returns the result of a SetDeviceLifecycleStatusByChannel request. The response contains the GatewayDeviceIdentification, MbusDeviceIdentification, DeviceLifecycleStatus and channel.SetDeviceLifecycleStatusByChannel request.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

Disable debugging for a device. Communication with the device will be logged and made available through FindMessageLogs,

All requests have similar response behaviour which is described in ResponseMessages.

GetDisableDebuggingResponse returns the result status. The response contains the DeviceIdentification and CorrelationUid which is received from the GetDisableDebuggingRequest request.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

FindMessageLogs is a request to retrieve logged messages for a device. The request needs the DeviceIdentification and a Page number to return.

All requests have similar response behaviour which is described in ResponseMessages.

GetFindMessageLogsResponse returns if the result is successful from the request. The response contains the DeviceIdentification and CorrelationUid which is received from the FindMessageLogs request.

Note: This functionality also exists in the admin device management service. It was duplicated here to be implemented asynchronously, as there is no support for asynchronous requests triggering a notification service in the admin project. As soon as asynchronous requests and notifications are implemented throughout the OSGP platform, this method should be removed in favour of the admin implementation.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

GetActualMeterReadsGas is a request to retrieve the actual import and export meter reads from a G-meter. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

GetActualMeterReadsGasResponse returns the retrieved meter reads values, unit and log time from the GetActualMeterReadsGas request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetActualMeterReadsGas request.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Describes the funtions as defined in SmartMeteringMonitoring.wsdl

Description

GetActualMeterReadsResponse returns the retrieved import and export values, unit and logtime from the ActualMeterReads request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetActualMeterReads request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetActualMeterReads is a request to retrieve the actual import and export meter reads from an E-meter. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

GetActualMeterReadsResponse returns the retrieved meter reads values, unit and log time from the GetActualMeterReads request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetActualMeterReads request.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetGsmDiagnostic is a request to retrieve information about the communication modem of a device, such as operator, status, cellInfo and information about adjacent cells.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-management.xsd

WSDL: SmartMeteringManagement.wsdl

Description

GetActualMeterReadsGasResponse returns the retrieved import and export values, unit and log time from the ActualMeterReadsGas request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetActualMeterReadsGas request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetPeriodicMeterReadsGas is a request to retrieve the periodic import and export meter reads from a G-meter. The period can be DAILY, MONTHLY or INTERVAL. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

GetPeriodicMeterReadsGasResponse returns the retrieved meter reads values, unit and log time from the GetPeriodicMeterReadsGas request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetPeriodicMeterReadsGas request.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetPeriodicMeterReads is a request to retrieve the periodic import and export meter reads from an E-meter. The periode can be DAILY, MONTHLY or INTERVAL. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

GetPeriodicMeterReadsResponse returns the retrieved meter reads values, unit and log time from the GetPeriodicMeterReads request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetPeriodicMeterReads request.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetPeriodicMeterReadsGasResponse returns the retrieved import and export values, unit and log time from the PeriodicMeterReadsGas request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetPeriodicMeterReadsGas request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetPeriodicMeterReadsResponse returns the retrieved import and export values, unit and log time from the PeriodicMeterReads request. The response contains the DeviceIdentification and CorrelationUid which is received from the GetPeriodicMeterReads request.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetProfileGenericData is a request to retrieve any DLMS "Profile generic" data from an E-meter. The request needs the DeviceIdentification.

The specific Profile generic data to be retrieved is identified by its OBIS code included as ObisCode according to the ObisCodeValues as specified in common.xsd.

Selective access will be applied as described in the DLMS standard for access selector range_descriptor. The clock definition is used as restricting_object. The from_value and to_value for the captured clock values will be set based on the BeginDate and EndData in the request.

It is possible to further reduce the amount of data retrieved from the device to specify selected_values. This is done by including the optional SelectedValues element in the request specifying one or more capture object definitions as CaptureObject according to the CaptureObjectDefinition in common.xsd.

The clock definition must not be specified in the SelectedValues, since it will always be included in the results. The values that are specified must be capture object definitions that appear in the list of capture_objects for the Profile generic data that is retrieved.

All requests have similar response behaviour which is described in ResponseMessages.

The ultimately returned response for the GetProfileGenericData request is as specified in GetProfileGenericDataResponse.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

GetProfileGenericDataResponse is a request to return the Generic profile buffer data as requested by a GetProfileGenericData request. It contains the DeviceIdentification and CorrelationUid which is received from the GetProfileGenericData request.

The response to the GetProfileGenericDataResponse request contains the logical name of the requested Generic profile as LogicalName according to the ObisCodeValues as specified in common.xsd.

The definitions of the capture objects from the buffer that are included in the response are listed as CaptureObject according to the CaptureObject in common.xsd.

The actual data from the buffer is included in the ProfileEntries, where each ProfileEntry has a list of values that match the capture objects from the response.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

RetrievePushNotificationAlarm is a request to push retrieved alarm notifications to OSGP. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Description

ReadAlarmRegister is a request to retrieve the query alarm register. A notification will be sent and the query will be stored in the database. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

GetReadAlarmRegisterResponse returns the alarm notifications from the ReadAlarmRegister request. The response contains the DeviceIdentification and CorrelationUid which is received from the ReadAlarmRegister request.

References

XSD: sm-monitoring.xsd

WSDL: SmartMeteringMonitoring.wsdl

Describes the actions as defined in the

The response of a request should always contain a DeviceIdentification and CorrelationUid which is used in the response request. Assertions validate if there is a 'SOAP Response' received, if the response is 'Schema Compliant' with the WSDL and if there has been a 'not SOAP Fault'. The last one occurs when a fault code is returned. Possible faults are connection timed-out, SmartMeter could not be found, TCP-IP connection error or Correlationuid is unknown. The faults can be among others a FunctionalFault or TechnicalFault. Responses to a bundle request may include faults in the form of FaultResponseData, resembling the other faults. The format of these faults is described in the .

Description

GetReadAlarmRegisterResponse returns the alarm notifications from the ReadAlarmRegister request. The response contains the DeviceIdentification and CorrelationUid which is received from the request.

All requests have similar response behaviour which is described in .

References

XSD:

WSDL:

Description

SendNotification is a request from the platform to let Webapps know there is a result ready to retrieve. In this way, there is no need for constant polling between Webapps and the platform. The request needs the DeviceIdentification.

All requests have similar response behaviour which is described in ResponseMessages.

References

XSD: sm-notification.xsd

WSDL: SmartMeteringNotification.wsdl

In order to add a new domain to OSGP, you can benefit from the guidelines given in this document. The general idea for adding a new domain is to copy an existing domain, for instance the microgrids domain, and perform a global search and replace, to replace the old domain name with the new domain name. You can use refactor methods from IntelliJ or Eclipse to help renaming the old domain names.

To add a new domain, changes must be made to 2 GitHub repositories: 1. Config repository. 2. Open smart grid platform repository.

Changes to OSGP/Config

Search for “Microgrids” and “microgrids” in all files and you will find all files to change for a new domain. These files include:

• Apache configuration

• Create domain database script

• Backup, restore, symlinks scripts

• Tomcat context script

Changes to OSGP/open-smart-grid-platform

Directory OSGP/open-smart-grid-platform/osgp/shared/

A new Maven module must be added for the new domain (osgp-ws-newdomain). This module will contain the wsdl files for the new domain services. Copy for instance osgp-ws-microgrids, search and replace microgrids with your domain and replace the wsdl files with your wsdl files. JAXB will generate java classes for your webservices. Change NewDomainWebServiceConfig.java accordingly. Make sure your base Request and Response classes are generated with an @XmlRootElement annotation. Otherwise your endpoints which are based on these types will fail (See @PayloadRoot in AdHocManagementEndpoint in ospg-adapter-ws-microgrids). The structure of your wsdl file determines whether the @XmlRootElement annotation is generated or not.

Image showing the generated @XmlRootElement annotation

Do not forget to add two constants for your new domain in the enum ComponentType.java (https://github.com/OSGP/open-smart-grid-platform/blob/development/osgp/shared/shared/src/main/java/org/opensmartgridplatform/shared/exceptionhandling/ComponentType.java). These constants are used in handling exceptions. Add one constant to denote your new Domain layer (DOMAIN) and one for your new Web Services layer (WS). See for instance MicrogridsService.java (https://github.com/OSGP/open-smart-grid-platform/blob/development/osgp/platform/osgp-adapter-ws-microgrids/src/main/java/org/opensmartgridplatform/adapter/ws/microgrids/application/services/MicrogridsService.java).

Add DTO’s to osgp-dto for your services. The DTO’s are used in the protocol-adapter. Mapping from/to DTO’s is performed in adapter-domain.

Directory OSGP/open-smart-grid-platform/osgp/platform/

Reference the new osgp-ws-newdomain in pom.xml. Also create three new Maven modules and add them to the pom:

• osgp-domain-newdomain

• osgp-adapter-ws-newdomain

• osgp-adapter-domain-newdomain

Constants for the new domain webservices

OSGP uses a couple of Java enums to identify all available services the platform offers.

• The DeviceFunction enum contains all services for all domains.

• The NotificationType enum and the NewDomainRequestMessageType enum are identical and contain the services for 1 domain. The NotificationType enum is generated from the wsdl service definition for the notification service. The NewDomainType enum is defined in the Web Service Layer for the new domain and is used to pass the message type to the other layers of OSGP.

• DeviceRequestMessageType will contain the services for 1 protocol Strictly speaking this enum is not necessary to add a new domain because the enum is located in the protocol layer of OSGP.

Each new service that is offered by the domain, for instance GET_DATA or SET_DATA, must be added to 3 java enums: 1. NotificationType (https://github.com/OSGP/open-smart-grid-platform/blob/development/osgp/shared/osgp-ws-microgrids/src/main/resources/schemas/notification.xsd, generated from wsdl with JAXB) 2. DeviceFunction (https://github.com/OSGP/open-smart-grid-platform/blob/development/osgp/platform/osgp-domain-core/src/main/java/org/opensmartgridplatform/domain/core/valueobjects/DeviceFunction.java) 3. MessageType (https://github.com/OSGP/open-smart-grid-platform/blob/development/osgp/shared/shared/src/main/java/org/opensmartgridplatform/shared/infra/jms/MessageType.java)

SQL for the new domain

A Flyway script should be added for system data. For a new domain a new record must be inserted in the table domain_info in the core database. Check for instance the Flyway script for Distribution Automation https://github.com/OSGP/open-smart-grid-platform/blob/development/osgp/platform/osgp-core/src/main/resources/db/migration/V20170508125704045__Added_Distribution_Automation_domain_info.sql. Test data for a new domain will include:

• Table device_function_mapping in the core database. Add a row for each new service to authorize ‘OWNER’ for this service.

• Table device in the core database. Add a new row for a test device, use the proper protocol_info_id. (Protocol_info_id is a foreign_key to the protocol_info table in core).

• Table device_authorization. Add a new row to authorize owner for this device. (Function_group is a reference to the java enum DeviceFunctionGroup in platform/osgp-domain-core).

Changes to osgp-domain-newdomain

• Review entities. Be careful, the entities in this project are generated in the core database. The name of this project suggests that the entities would be generated in a domain specific database.

• Create valueobjects for your domain. The valueobjects in this project are used only in the adapter-ws and adapter-domain layer.

Changes to osgp-adapter-ws-newdomain

• Add Endpoints for each service request in presentation.ws.

• Add MessageProcessors in infra.jms.messageprocessors for each service response.

• Modify mapping/NewDomainMapper to map the JAXB generated classes to the classes in platform/osgp-domain-new-domain

Changes to osgp-adapter-domain-newdomain

• Add MessageProcessors in infra.jms.ws.messageprocessors for each service request.

• Add MessageProcessors in infra.jms.core.messageprocessors for each service response.

• Modify mapping/DomainNewDomainMapper to map the classes in platform/osgp-domain-new-domain to the classes in shared/osgp-dto. The osgp-dto classes are used in the core layer and the protocol layer.

Testing the new domain services

In order to test the new domain services take a look at the Installation Guide. While following this guide keep the following items in mind:

• A test device for the new domain must be available. This can either be a physical device or a simulated device.

• The test device must be connected or a device simulator must be running.

• The OSGP protocol adapter for the new device must be extended.

• ProgreSQL must be installed with all OSGP databases and system data as listed in the installation guide. The new domain might have a new database in which case the create script for the database and database owner must be run.

• Test data must be inserted into the following tables: organisation, device, device_authorization, device_function_mapping. Depending on the type of protocol adapter used for the new domain other tables might have to be populated as well. For instance a table like rtu_device for the IEC61850 Protocol Adapter.

• Apache Http Server must be installed and the new domain must be added to the configuration

• Apache ActiveMQ must be installed

• Tomcat application server must be installed and at least 4 web applications must be deployed:

  • An OSGP protocol adapter

  • OSGP Core

  • The OSGP Adapter Domain for your new domain

  • The OSGP Adapter WS for your new domain

• SoapUI can be used to test the new webservices for your domain

Up-to-date information on use-cases can be found on the Grid eXchange Fabric website.

Smart Meter Head-end System

Technical drivers

• Replacement or addition to the current head-end system

• During the coming years, many smart meters will be placed in houses, companies and other properties, therefore grid operators need a scalable solution

• E(lectricity) Meters can host up to 4 other smart devices, Gas Meters for example

• DLMS/COSEM is used by many(if not all) Smart Meters

Customer drivers

• People will have more insight in their power consumption

• Meter values can be gathered by the grid operator, instead of relying on people reporting the meter values