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

Describes the actions as defined in SmartMeteringAdhoc.wsdl

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

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

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.

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

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 http://www.opensmartgridplatform.org/schemas/smartmetering/sm-bundle/2014/10. 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.

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 ResponseMessages.

Actions

Currently, the following actions are supported:

• FindEventsRequest see FindEvents

• SetSpecialDaysRequest see SetSpecialDays

• ReadAlarmRegisterRequest see ReadAlarmRegister

• GetActualMeterReadsRequest see ReadAlarmRegister

• GetActualMeterReadsGasRequest see GetActualMeterReadsGas

• GetAdministrativeStatusRequest see GetAdministrativeStatus

• GetPeriodicMeterReadsRequest see GetPeriodicMeterReads

• GetPeriodicMeterReadsGasRequest see GetPeriodicMeterReadsGas

• SetAdministrativeStatusRequest see SetAdministrativeStatus

• SetActivityCalendarRequest see SetActivityCalendar

• SetKeyOnGMeterRequest see SetKeyOnGMeter

• SetAlarmNotificationsRequest see SetAlarmNotifications

• SetConfigurationObjectRequest see SetConfigurationObject

• SetPushSetupAlarmRequest see SetPushSetupAlarm

• SetPushSetupSmsRequest see SetPushSetupSms

• SynchronizeTimeRequest see SynchronizeTime

• GetConfigurationRequest

• GetFirmwareVersionRequest

• UpdateFirmwareRequest see UpdateFirmware

• GetSpecificConfigurationObjectRequest see SpecificConfigurationObject

• SetKeysRequest

• GetAssociationLnObjectsRequest

• SetClockConfigurationRequest SetClockConfiguration

• GetProfileGenericDataRequest see GetProfileGenericData

• ConfigureDefinableLoadProfileRequest see ConfigureDefinableLoadProfile

• SetMbusUserKeyByChannelRequest see SetMbusUserKeyByChannel

• GetMBusEncryptionKeyStatusRequest see GetMbusEncryptionKeyStatus

References

XSD: sm-bundle.xsd

WSDL: SmartMeteringBundle.wsdl

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: sm-adhoc.xsd

WSDL: SmartMeteringAdhoc.wsdl

Describes the actions as defined in SmartMeteringConfiguration.wsdl

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:

sm-adhoc.xsd

sm-bundle.xsd

sm-configuration.xsd

sm-management.xsd

sm-monitoring.xsd

WSDL: SmartMeteringBundle.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 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: 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

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.

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.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

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

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

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

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

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

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

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

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

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

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

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: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.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

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

GetSetSpecialDaysResponse returns the result from setting a Special Day. 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

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

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

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 SetKeyOnGMeter request.

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

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

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

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

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

References

XSD: sm-configuration.xsd

WSDL: SmartMeteringConfiguration.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

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

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

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

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 ResponseMessages.

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

References

XSD: sm-management.xsd

WSDL: SmartMeteringAdhoc.wsdl

Description

ScanMbusChannelsResponse returns the result of a ScanMbusChannels 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: sm-adhoc.xsd

WSDL: SmartMeteringAdhoc.wsdl

Describes the actions as defined in SmartMeteringInstallation.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 ResponseMessages

GetAddDeviceResponse 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: sm-installation.xsd

WSDL: SmartMeteringInstallation.wsdl

Example scenario

  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

Example XML Message

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.opensmartgridplatform.org/schemas/common/2014/10" xmlns:ns1="http://www.opensmartgridplatform.org/schemas/smartmetering/sm-installation/2014/10">
   <soapenv:Header>
      <ns:ApplicationName>AutomaticTest</ns:ApplicationName>
      <ns:UserName>SoapUI</ns:UserName>
      <ns:OrganisationIdentification>test-org</ns:OrganisationIdentification>
   </soapenv:Header>
   <soapenv:Body>
      <ns1:AddDeviceRequest>
         <ns1:Device>
            <!--Optional:-->
            <ns1:Device_Identification>TEST1024000000001</ns1:Device_Identification>
            <!--Optional:-->
            <ns1:Device_type>SMART_METER_E</ns1:Device_type>
            <!--Optional:-->
            <ns1:Communication_method>GPRS</ns1:Communication_method>
            <!--Optional:-->
            <ns1:Communication_provider>KPN</ns1:Communication_provider>
            <!--Optional:-->
            <ns1:ICC_id>icc_id</ns1:ICC_id>
            <!--Optional:-->
            <ns1:DSMR_version>4.2.2</ns1:DSMR_version>
            <!--Optional:-->
            <ns1:Supplier>Kaifa</ns1:Supplier>
            <!--Optional:-->
            <ns1:HLS3_active>false</ns1:HLS3_active>
            <!--Optional:-->
            <ns1:HLS4_active>false</ns1:HLS4_active>
            <!--Optional:-->
            <ns1:HLS5_active>true</ns1:HLS5_active>
            <!--Optional:-->
            <ns1:Master_key>m_key</ns1:Master_key>
            <!--Optional:-->
            <ns1:Global_encryption_unicast_key>e_key</ns1:Global_encryption_unicast_key>
            <!--Optional:-->
            <ns1:Authentication_key>a_key</ns1:Authentication_key>
            <ns1:Delivery_date>2017-05-17 06:16:57.07</ns1:Delivery_date>
         </ns1:Device>
      </ns1:AddDeviceRequest>
   </soapenv:Body>
</soapenv:Envelope>

Description

GetAddDeviceResponse returns if the result is successful from the AddDevice 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

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

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

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:

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 CoupleMbusDevice request.

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

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 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.

References

XSD: sm-installation.xsd

WSDL: SmartMeteringInstallation.wsdl

Description

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: sm-installation.xsd

WSDL: SmartMeteringInstallation.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

Describes the actions as defined in 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

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

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

Describes the funtions as defined in SmartMeteringMonitoring.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

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 .

References

XSD:

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

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

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

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

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

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 request.

All requests have similar response behaviour which is described in .

References

XSD:

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

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

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

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 .

References

XSD:

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 .

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 .

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 .

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

References

XSD:

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

Description

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: 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

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

Describes the actions as defined in the SmartMeteringNotification.wsdl