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
Admin webservices
Use cases
Up-to-date information on use-cases can be found on the .
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
Smart lighting
This domain covers the use of the open smart grid platform for smart lighting.
Scope
Light Schedules
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.
SmartMetering
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
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.
This chapter describes all the web services in the smart metering domain.
GetRetrieveConfigurationObjectsResponse
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.
FlexOVL Web Application
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 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.
The value of WeekDay is used to indicate on which days the schedule entry may trigger switch actions.
WeekDay
May trigger a switch action on
MONDAY
Mondays
TUESDAY
Tuesdays
WEDNESDAY
Wednesdays
THURSDAY
Thursdays
FRIDAY
Fridays
SATURDAY
Saturdays
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.
ActionTime
Description
ABSOLUTETIME
a is set for the switching moment in Time
SUNRISE
switching at sunrise at the location of the device
SUNSET
switching at sunset at the location of the device
For ActionTime values SUNRISE or SUNSET the value of TriggerType specifies what the actual switching time should be.
TriggerType
Description
LIGHT_TRIGGER
determines the actual switching time
ASTRONOMICAL
the for sunrise or sunset is the switching time
Fixed Time
For ActionTimeABSOLUTETIME a fixed time can be set for the switching moment as Time.
The Time value needs to be formatted in a way the protocol implementations can handle. For the currently listed implementations, you should be fine when you use a format from:
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 ActionTimeSUNRISE or SUNSET with TriggerTypeASTRONOMICAL 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 ActionTimeSUNRISE and TriggerTypeASTRONOMICAL.
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 AstronomicalSunriseOffset15).
Switching off at astronomical sunrise with 15 minutes offset
####Astronomical Sunset Offset
The astronomical sunset offset is similar to the astronomical sunrise offset, except that it is applied with entries with ActionTimeSUNSET and TriggerTypeASTRONOMICAL.
Astronomical Time With Sensor
For ActionTimeSUNRISE or SUNSET with TriggerTypeLIGHT_TRIGGER the calculated astronomical sunrise or sunset time will be used as a reference time with a trigger window to determine the switching moment.
The astronomical time itself is calculated in the same way as with astronomical time (without light sensor input).
Switching happens within a configured trigger window around the astronomical time, at a moment that is influenced by a signal from a light 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).
Switching on when sensor reports dark within the trigger window
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.
Switching off when sensor input is received before the trigger window opens
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.
Switching on when no sensor input is received before the trigger window closes
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
This example shows the minimal burning time preventing the morning lights to be switched on at a fixed time because switching off at the calculated time of astronomical sunrise (with offset) would happen before passing of the minimum number of minutes the lights should be kept on.
Astronomical switching off within minimum lights on of fixed time switching on
Minimal Burning Time With Light Sensor Trigger Window
This example shows the minimal burning time preventing the morning lights to be switched on at a fixed time because switching off at the start of the trigger window around the calculated time of astronomical sunrise would happen before passing of the minimum number of minutes the lights should be kept on.
Trigger window switching off within minimum lights on of fixed time switching on
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 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:
Depending on the location of the device the time of sunrise may vary quite a bit throughout the year. Because of this it is possible that what for some period would be a very reasonable schedule, is a questionable schedule (possibly to be considered invalid) in another season.
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).
Morning Lights throughout the year
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
Evening lights is a name used for lights that are switched on a short period in the evening hours of a day to illuminate a period after or around dusk.
This is similar to the morning lights, but in the evening instead of the morning, and the fixed time moment comes (normally) after the switch action around sunset.
The evening lights are switched by a pair of schedule entries:
another entry switching off again based on fixed time;
Fixed Time And Sunset Interaction
Depending on the location of the device the time of sunset may vary quite a bit throughout the year. Because of this it is possible that what for some period would be a very reasonable schedule, is a questionable schedule (possibly to be considered invalid) in another season.
See the explanation around sunrise for a graphical example.
Evening/Morning Lights
A combination of morning lights and evening lights can be configured for a relay if the lights may be turned off for a period in the late night and early morning, as opposed to the all night lights that keep on burning all through the night.
Evening/Morning Lights based on light triggers
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.
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.
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!
GetAssociationLnObjects
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:
WSDL:
GetGetAssociationLnObjectsResponse
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:
WSDL:
SpecificConfigurationObject
Description
SpecificConfigurationObject is a request to retrieve the data for a specific configuration object indicated with:
ClassId
Attribute
ObisCode
References
XSD:
WSDL:
SynchronizeTime
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.
returns the result from synchronizing date and time. The response contains the DeviceIdentification and CorrelationUid which is received from the SynchronizeTime request.
References
XSD:
WSDL:
GetSynchronizeTimeResponse
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 ResponseMessages.
References
XSD:
WSDL:
SetDataAsync is a request to retrieve the result of the SetData request.
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.
GetAdministrativeStatus
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 ResponseMessages.
GetGetAdministrativeStatusResponse returns if the setting GetAdministrativeStatus is enabled. The response contains the DeviceIdentification and CorrelationUid which is received from the GetAdministrativeStatus request.
References
XSD:
WSDL:
Bundle
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.
GetBundleResponse 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
References
XSD:
WSDL:
GetBundleResponse
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 Bundle request.
All requests have similar response behaviour which is described in ResponseMessages.
References
XSD:
WSDL:
GetGetFirmwareVersionResponse
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:
WSDL:
GetGetAdministrativeStatusResponse
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:
WSDL:
GetFirmwareVersion
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 ResponseMessages.
GetGetFirmwareVersionResponse returns the version(s). The response contains the DeviceIdentification and CorrelationUid which is received from the GetFirmwareVersion request.
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:
WSDL:
GetConfigurationObjectResponse
Description
GetConfigurationObjectResponse returns the result, a ConfigurationObject, which is received from the request.
All requests have similar response behavior which is described in .
GetMbusEncryptionKeyStatus
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 .
The returned response for the GetMbusEncryptionKeyStatus request is as specified in .
GetUpdateFirmwareResponse
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 request.
All requests have similar response behaviour which is described in .
UpdateFirmware
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 .
returns the version(s). The response contains the DeviceIdentification and CorrelationUid which is received from the UpdateFirmware request.
GetSetActivityCalendarResponse
Description
GetSetActivityCalendarResponse returns the result from setting a SetActivityCalendar. The response contains the DeviceIdentification and CorrelationUid which is received from the request.
All requests have similar response behaviour which is described in .
SetAdministrativeStatus
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 .
returns if the setting SetAdministrativeStatus is enabled. The response contains the DeviceIdentification and CorrelationUid which is received from the SetAdministrativeStatus request.
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:
WSDL:
SetActivityCalendar
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.
returns the result from setting a SetActivityCalendar. The response contains the DeviceIdentification and CorrelationUid which is received from the SetActivityCalendar request.
References
XSD:
WSDL:
GetKeys
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 .
References
XSD:
WSDL:
SetPushSetupAlarm
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 .
returns the result from setting a SetPushSetupAlarm. The response contains the DeviceIdentification and CorrelationUid which is received from the SetPushSetupAlarm request.
References
XSD:
WSDL:
GetSetConfigurationObjectResponse
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:
WSDL:
GetSetPushSetupSmsResponse
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:
WSDL:
SetPushSetupSms
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 ResponseMessages.
GetSetPushSetupSmsResponse returns the result from setting a SetPushSetupSms. The response contains the DeviceIdentification and CorrelationUid which is received from the SetPushSetupSms request.
References
XSD:
WSDL:
SetSpecialDays
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:
WSDL:
GetConfigurationObject
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 .
References
XSD:
WSDL:
GetSetAlarmNotificationsResponse
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:
WSDL:
GetSetAdministrativeStatusResponse
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:
WSDL:
SetKeyOnGMeter
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.
returns the result from setting a SetKeyOnGMeter. The response contains the DeviceIdentification and CorrelationUid which is received from the SetKeyOnGMeter request.
References
XSD:
WSDL:
SetAlarmNotifications
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:
The request needs the DeviceIdentification, AlarmType and Enabled parameters.
All requests have similar response behaviour which is described in .
returns the result from setting a SetAlarmNotifications. The response contains the DeviceIdentification and CorrelationUid which is received from the SetAlarmNotifications request.
References
XSD:
WSDL:
SetConfigurationObject
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 .
returns the result from setting a SetConfigurationObject. The response contains the DeviceIdentification and CorrelationUid which is received from the SetConfigurationObject request.
References
XSD:
WSDL:
ConfigureDefinableLoadProfile
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 common.xsd. 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 GetProfileGenericData 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:
GetSetPushSetupAlarmResponse
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:
WSDL:
GetSetKeyOnGMeterResponse
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:
WSDL:
GetSetSpecialDaysResponse
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:
WSDL:
GetGetMbusEncryptionKeyStatusResponse
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:
WSDL:
GetMbusEncryptionKeyStatusByChannel
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 .
The returned response for the GetMbusEncryptionKeyStatusByChannel request is as specified in .
GetSetMbusUserKeyByChannelResponse
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 .
SetMbusUserKeyByChannel
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 .
ScanMbusChannels
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
AddDevice
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.
The response contains the DeviceIdentification and CorrelationUid which is received from the SetMbusUserKeyByChannel request. GetSetMbusUserKeyByChannelResponse returns the result from issuing a SetMbusUserKeyByChannel request.
Scenario: Add a new device
When receiving a smartmetering add device request
| DeviceIdentification | TEST1024000000001 |
| DeviceType | SMART_METER_E |
| CommunicationMethod | GPRS |
| CommunicationProvider | KPN |
| ICC_id | 1234 |
| DSMR_version | 4.2.2 |
| Supplier | Kaifa |
| HLS3_active | false |
| HLS4_active | false |
| HLS5_active | true |
| Master_key | m_key |
| Authentication_key | a_key |
| Encryption_key | e_key |
Then the get add device response should be returned
| DeviceIdentification | TEST1024000000001 |
| Result | OK |
And the dlms device with identification "TEST1024000000001" exists
And a request to the device can be performed after activation
And the stored keys are not equal to the received keys
GetDeCoupleMbusDeviceResponse returns if the result is successful from the DeCoupleMbusDevice request. The response contains the DeviceIdentification and CorrelationUid which is received from the DeCoupleMbusDevice request.
All requests have similar response behaviour which is described in ResponseMessages.
References
XSD:
WSDL:
GetAddDeviceResponse
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:
WSDL:
GetProfileGenericData
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 .
Selective access will be applied as described in the DLMS standard for access selector range_descriptor. The clock definition is used as
FindEvents
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
GetDevices
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 .
SetDeviceLifecycleStatusByChannel
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 .
The returned response for the SetDeviceLifecycleStatusByChannel request is as specified in .
DeCoupleMbusDevice
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
GetFindEventsResponse
Description
GetFindEventsResponse returns if the result is successful from the FindEvents request. The response contains the DeviceIdentification and CorrelationUid which is received from the request.
All requests have similar response behaviour which is described in .
ScanMbusChannelsResponse
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.
CoupleMbusDevice
Description
CoupleMbusDevice is a request to couple a gateway and a m-bus device. The request needs the following parameters:
DeviceIdentification
GetCoupleMbusDeviceResponse
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 .
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.
All requests have similar response behaviour which is described in ResponseMessages
GetDeCoupleMbusDeviceResponse returns if the result is successful from the request. The response contains the DeviceIdentification and CorrelationUid which is received from the DeCoupleMbusDevice request.
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.
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.
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:
WSDL:
DisableDebugging
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:
WSDL:
EnableDebugging
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:
WSDL:
FindMessageLogs
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.
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:
WSDL:
GetGsmDiagnostic
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:
WSDL:
GetPeriodicMeterReads
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:
WSDL:
GetActualMeterReadsGasResponse
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:
WSDL:
GetPeriodicMeterReadsGas
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.
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.
GetReadAlarmRegisterResponse returns the alarm notifications from the ReadAlarmRegister request. The response contains the DeviceIdentification and CorrelationUid which is received from the ReadAlarmRegister request.
All requests have similar response behaviour which is described in ResponseMessages.
References
XSD:
WSDL:
SendNotification
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 .
GetPeriodicMeterReadsGasResponse
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 request.
All requests have similar response behaviour which is described in .
SetDeviceLifecycleStatusByChannelResponse returns the result of a SetDeviceLifecycleStatusByChannel request. The response contains the GatewayDeviceIdentification, MbusDeviceIdentification, DeviceLifecycleStatus and channel.SetDeviceLifecycleStatusByChannel request.
References
XSD:
WSDL:
ReadAlarmRegister
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 .
returns the alarm notifications from the ReadAlarmRegister request. The response contains the DeviceIdentification and CorrelationUid which is received from the ReadAlarmRegister request.
GetProfileGenericDataResponse
Description
GetProfileGenericDataResponse is a request to return the Generic profile buffer data as requested by a request. It contains the DeviceIdentification and CorrelationUid which is received from the 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 .
The definitions of the capture objects from the buffer that are included in the response are listed as CaptureObject according to the CaptureObject in
GetActualMeterReadsResponse
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 request.
All requests have similar response behaviour which is described in .
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.
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 common.xsd.
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
RetrieveConfigurationObjects
Domains
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.
Distribution automation
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.
WSDLs
Tariff switching
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 (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.
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.
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.
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 (). 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 ().
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.
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 (, generated from wsdl with JAXB) 2. DeviceFunction () 3. MessageType ()
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 . 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 . 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
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.
