Open Smart Grid Platform Documentation

O pen Smart Grid Platform Documentation
Table of Contents
1. Introduction
2. General platform architecture
1. Platform properties
2. Architecture introduction
3. Architecture functional layers
4. Architecture Principles
5. Platform components des cription
6. Mes s age flow examples
7. Logical Authoris ation Model
8. Non-functional overview
1. T imeBehavior
2. Internationalization and localization
3. Security
4. Scalability
5. Redundancy
6. Performance
9. T echnical O verview
1. Web Services Layer
2. Domain Layer
3. Core Layer
4. Protocol Layer
5. T echnology Stack
10. Us e cas es
3. General Us er's Guide
1. Ins tallation Guide
1. Ins tallation
1. Vagrant
2. Manual Setup
2. Platform Setup
3. T es t the Platform
1. Us ing SoapUi
2. Us ing the Demo App
2. Configuration
1. Add a device
2. Us ers
3. Add a new organis ation
3. Web Services
4. Deployment
5. FAQ
4. O pen Source Community
1. Start contributing
2. Developers 101
3. Contributing to the code
4. Contributing to documentation
5. Communication and Contact
6. Governance
7. Code of Conduct
8. Foundation
5. Domains
1. Admin
2. Smart lighting
1. Us e cas es
3. T ariff s witching
4. Microgrids
5. Dis tribution automation
6. SmartMetering
1. Web Services
1. bypas s retry
2. priority
3. s cheduling
4. AdHocManagement
1. GetAs s ociationLnO bjects
2. GetGetAs s ociationLnO bjects Res pons e
3. RetrieveConfigurationO bjects
4. GetRetrieveConfigurationO bjects Res pons e
5. SpecificConfigurationO bject
6. SynchronizeT ime
7. GetSynchronizeT imeRes pons e
5. Bundle
2
1. Bundle
2. GetBundleRes pons e
6. Configuration
1. GetAdminis trativeStatus
2. GetGetAdminis trativeStatus Res pons e
3. GetFirmwareVers ion
4. GetGetFirmwareVers ionRes pons e
5. UpdateFirmware
6. GetUpdateFirmwareRes pons e
7. ReplaceKeys
8. GetReplaceKeys Res pons e
9. SetActivityCalendar
10. GetSetActivityCalendarRes pons e
11. SetAdminis trativeStatus
12. GetSetAdminis trativeStatus Res pons e
13. SetAlarmNotifications
14. GetSetAlarmNotifications Res pons e
15. SetConfigurationO bject
16. GetSetConfigurationO bjectRes pons e
17. SetEncryptionKeyExchangeO nGMeter
18. GetSetEncryptionKeyExchangeO nGMeterRes pons e
19. SetPus hSetupAlarm
20. GetSetPus hSetupAlarmRes pons e
21. SetPus hSetupSms
22. GetSetPus hSetupSms Res pons e
23. SetSpecialDays
24. GetSetSpecialDays Res pons e
25. GetConfigurationO bject
26. GetConfigurationO bjectRes pons e
27. ConfigureDefinableLoadProfile
28. GetConfigureDefinableLoadProfileRes pons e
29. SetMbus Us erKeyByChannel
30. GetSetMbus Us erKeyByChannelRes pons e
31. GetMbus EncryptionKeyStatus
32. GetGetMbus EncryptionKeyStatus Res pons e
33. GetMbus EncryptionKeyStatus ByChannel
34. GetGetMbus EncryptionKeyStatus ByChannelRes pons e
7. Ins tallation
1. AddDevice
2. GetAddDeviceRes pons e
3. CoupleMbus Device
4. GetCoupleMbus DeviceRes pons e
5. DeCoupleMbus Device
6. GetDeCoupleMbus DeviceRes pons e
8. Management
1. FindEvents
2. GetFindEvents Res pons e
3. GetDevices
4. SetDeviceLifecycleStatus ByChannel
5. SetDeviceLifecycleStatus ByChannelRes pons e
6. EnableDebugging
7. Dis ableDebugging
8. FindMes s ageLogs
9. Monitoring
1. GetActualMeterReads
2. GetActualMeterReads Res pons e
3. GetActualMeterReads Gas
4. GetActualMeterReads Gas Res pons e
5. GetPeriodicMeterReads
6. GetPeriodicMeterReads Res pons e
7. GetPeriodicMeterReads Gas
8. GetPeriodicMeterReads Gas Res pons e
9. GetProfileGenericData
10. GetProfileGenericDataRes pons e
11. ReadAlarmRegis ter
12. GetReadAlarmRegis terRes pons e
13. RetrievePus hNotificationAlarm
10. Notification
1. SendNotification
2. Res pons eMes s ages
3. Us e cas es
7. Guidelines to add a new domain to O SGP
3
6. Protocols
1. IEC 61850
2. DLMS / CO SEM
1. DLMS device s imulator
3. O SLP
1. O SLP v0.5.1
1. Protobuf Contract
2. O SLP v0.6.1
1. Regis terDevice
2. ConfirmRegis terDevice
3. GetConfiguration
4. SetConfiguration
5. SetEventNotifications
6. EventNotification
7. SetSchedule
8. Res umeSchedule
9. GetFirmwareVers ion
10. UpdateFirmware
11. SetReboot
12. StartSelfT es t
13. StopSelfT es t
14. SetLight
15. SetT rans ition
16. GetStatus
17. GetPowerUs ageHis tory
18. UpdateDeviceSs lCertification
19. SetDeviceVerificationKey
20. SwitchFirmware
21. SwitchConfiguration
22. Protobuf Contract
7. Support
8. Licens e
9. Glos s ary
4
Introduction
Introduction to the Open Smart Grid Platform

T he O pen Smart Grid Platform (O SGP) is an open, generic, s calable and independent 'Internet of T hings ' platform, which
enables various connected s mart objects in the public s pace to be eas ily controlled and monitored. O ur platform allows the
us e of any (web)application and with any IP communication infras tructure.
O ur goal is to s timulate the development of s mart and s us tainable s olutions . Smart devices and s mart apps play a central role
in the development of s mart grids and s mart s ocieties . T he open s mart grid platform s oftware enables you to connect to
thous ands of devices , control them, and monitor their performance. T his is done in an open and s ecure way, s o you can us e it
for your own applications and devices , thereby reducing the time to market and decreas ing development cos ts .
Us ing the p latform
T he O pen Smart Grid Platform is us ed in the following way:
A us er or operator us es one or more (web) applications to monitor and/or control devices

T he applications connect to the open s mart grid platform via s everal web s ervices which are divided into functional
domains , i.e. Public Lighting, Smart Metering, Power Q uality, etc. T hird party developers can us e the web s ervices
for the development or integration of new applications
T he platform handles all thes e application reques ts in a s ecure way and us es various functions and s ervices to do s o
(e.g. authorization, authentication, device management, logging)
For the 'trans lation' and communication of us er/operator commands to the various s mart devices , the platform us es
multiple (open) protocols
T he platform s upports various IP bas ed data telecommunication technologies and protocols to communicate with the
devices
More technical and us er information about the open s mart grid platform can be found in this document. More generic/product
information about the open s mart grid platform can be found on the open s mart grid platform webs ite.
Example us e cas e for the open s mart g rid platform

Us e cas es of the open s mart grid platform are only limited by your imagination. Here are s ome examples :
Ad-hoc and s cheduled Switching of Public Lighting

Electrical T rans portation
Smart Metering
T raffic Control (LED/matrix s igns , traffic lights )
Flexible load management ( s olar energy and wind energy)
Power Q uality monitoring
Getting s tarted
Vis it the us erguide s ection to try the open s mart grid platform on your local machine
T he Architecture s ection provides information on platform architecture
Check out the domain s ection if you want to know about the the exis ting domains
Check out the protocol s ection to find out more on the exis ting s upported protocols
Read the open s ource s ection how to contribute!
Introduction 5
General platform architecture

CHAPTER 1 Technical overview of the Open Smart Grid
Platform
T his chapter contains the general architecture and properties of the O pen Smart Grid Platform. Domain and protocol
s pecific information can be found in the domain and protocol chapters . T his chapter is written for (potential) us ers ,
architects and developers .
General platform architecture 6

Platform properties
Properties of the Open Smart Grid Platform
T he O pen Smart Grid Platform is des igned for mes s age bas ed communication.
Acts as a conne cting link between (web)applications and s mart devices

T he open Source approach p re ve nts ve nd or lock-in
State of the art s e curity
Fully s calab le , dynamically s caling up and down as more devices and applications are added.
Freedom of choice in the d e s ire d IP communication infras tructure , e.g. CDMA and GPRS.
Stimulates open innovation by us ing op e n s tand ard s and op e n s ource technology
Multip le d e vice s and communication protocols are s upported
Ind e p e nd e nt of (cloud) hos ting infras tructure
By de-linking the chain and the us e of open s tandards and the open s ource licens e, anyone can build his or her
applications on top of the open s mart grid platform.
T he open s mart grid platform is op timiz e d to provide reliable and efficient delivery of command and control
information for e.g. s mart meters , direct load control modules , s olar panels , gateways and other applications .
T he open s mart grid platform s implifies the implementation of s mart devices res ulting in a s horter time-to-market by
having built-in d e vice manag e me nt features
T he platform s upports various IP data communication infras tructures to communicate with the devices (internet, lan,
GPRS, CDMA, UMT S, etc.).
T he open s mart grid platform als o s upports authentication and encryption for all data exchanges to protect the
integrity and privacy of data as required in e.g. the s mart grid.
T he open s mart grid platform s upports multip le p rotocols
Eas y ap p lication inte g ration
Supports active -active s etup over multiple data centers
Adding s ervers can be done in runtime
Pleas e note: the O pen Smart Grid Platform is not built for s treaming data s uch as video, audio or a s tream of high frequency
meas urement data.
Unique features of the Open Smart Grid Platform

T he O pen Smart Grid Platform is unique due to its multi-dimens ional, generic and open des ign. Becaus e of a true s eparation
of layers and the us e of open s tandards , other s uppliers and/or third parties are able to develop and market innovative
s olutions .
1. T he platform is multi-d ime ns ional. T his means that s everal cus tomer us e cas es (with s eparate bus ines s models )
are able to us e the various device functions . O ne s ingle application could us e the s ame function of different devices .
2. T he g e ne ric des ign ens ures that the platform can be us ed in a flexible way for s everal functions and applications
(e.g. public lighting s ervices and s mart meter s ervices ).
3. T he platform is aimed at the 'common p arts ' of the technology chain; s uppliers or vendors (of both applications and
devices ) have no competitive advantage in delivering thes e kind of s ervices .
4. T he platform layers are truly s eparated by open s tandards and the platform is made available as op e n s ource
s oftware.
5. T he platform does not s tore any application data (the platform is thus s tate le s s ). No mes s ages /commands will ever
get los t. T his enables third party vendors and developers to deliver innovative applications which are competitive in
both rich functionalities and the generated data.
Platform properties 7
Architecture introduction
Basic Architecture
T he b as ic archite cture
Architecture introduction 8
Bas ic O verview
Layered architecture
T he O pen Smart Grid Platform environment cons is ts of five layers :
1. Web s ervices layer

2. Domain logic layer
3. O pen Smart Grid Platform Core layer
4. Protocol layer
5. Device layer
Web s ervices layer

In this layer the web s ervices are expos ed to the outs ide world. Applications can connect to the web s ervices to implement
the required functionality of the open s mart grid platform. T he web s ervices are divided into functional domains , i.e. Public
Lighting, Smart Metering, Power Q uality, etc. Additional functional domains can be created.
Domain log ic layer

Every functional domain has a s eparate s et of web s ervices and a corres ponding domain logic block. In the domain logic
block the bus ines s logic of that functional domain can be found. T his is where a functional command will be trans lated into a
generic intermediate format. For example, in the cas e of public lighting the command "T urn light on" will be trans lated into a
command like "s et s witch(1) in clos ed pos ition". In this layer it could als o be decided that one functional command res ults in
multiple commands to a device. T he domain logic is clos ely related to the web s ervices layers and can be added as well.
Open Smart Grid Platform core layer

In the core of the O pen Smart Grid Platform the following generic functions are found:
Device management
T ime s ynchronization
Firmware management
Workflow engine
Device ins tallation s ervices
Scheduler
Device s tatus monitoring
Routing of device commands to appropriate device protocol
Protocol layer
T he different protocol adapters are found in this layer. Here the generic intermediate format of a command for a s pecific
device will be trans lated into the protocol mes s age the device unders tands . T his mes s age will be s ent to the device. A retry
mechanis m has been implemented to prevent communication failure in the cas e that the receiving end is temporarily
unavailable. T he lis teners for mes s ages initiated by a device are implemented here. Examples are the DLMS/CO SEM protocol
adapter for s mart meters .
Devices
Any device in the public s pace with an Internet connection may be connected to the platform. T he platform is independent of
the device us ed, therefore this part of the s et-up is not part of the platform.
Architecture functional layers

Functional view
Image, functional layers overview
S tarting archite cture
T he Functional view s hows an overview of the mos t important functions of the s ys tem. T he two images below s how the
s tarting architecture and functional reference architecture res pectively.
Image, functional starting architecture
Architecture functional layers 11

1. Web applications
2. O pen Smart Grid Platform
3. Web s ervices
4. Bas ic functions
5. Databas e
6. Communication infras tructure (CDMA/GPRS/Ethernet)
7. IP infras tructure
8. O pen Street Light Protocol (O SLP)
9. Public Street Lighting Device (PSLD) or Sub Station Lighting Device (SSLD)
Functional Reference
T his model partitions the s ys tem in s even functional clus ters (vertically) which are s hown on the s ys tem layers (horizontally).
T he circled numbers refer to image 1.
Image, functional reference architecture
Vertical clus ters :

Device ins tallation

Device management
Firmware management
Configuration management
Schedule management
Ad-hoc control and s tatus
Monitoring
Horizontal Sys tem layers :
Web applications
HT T PS/SO AP communication
Platform
O pen protocols
Smart devices

Architecture Principles
Architecture Principles
T his chapter gives an overview of the principles us ed defining and implementing the architecture. T he following principles
were applied:
Layering
Domain driven des ign
Dependency invers ion principle
Behavior driven development
Layering
T he us e of layers improves the s eparation of res pons ibilities . Each application contains the following layers :
Pres entation layer: res pons ible for providing information to us ers (pers ons and/or s ys tems ) and the handling of us er
reques ts
Application layer: res pons ible for executing s ys tem tas ks including authoris ation control
Domain layer: res pons ible for the repres entation of the problem domain.
Infras tructure layer: res pons ible for technical matters s upporting other layers . For ins tance pers is tence, mes s aging,
etc
Image, Layers:
1. Audit logger
2. Web Services
3. Functions
4. Q ueue
5. Workflow engine
6. Protocol framework
7. Protocol implementations
8. Workflow engine
9. Q ueue
10. Communication
Architecture Principles 14
Domain driven des ig n (DDD)

Domain-driven des ign focus es on the problem domain. DDD's s tarting point is creating an optimal model for a s pecific
problem domain by having a common language and cons tructive collaboration between technical and domain experts .
DDD us es the following building blocks :
Entity: An object not identified by its attributes but by its own identity.
Value O bject: an object with attributes but has no own identity.
A collection of objects s urrounding a s pecific root entity (or aggregate root). T o ens ure cons is tency objects in the
aggregate can only be addres s ed through the aggregate root.
Service: Contains ins tructions not related to a s pecific object.
Repos itory: Serves as a collection for fetching and s aving objects . Creates an abs traction for actual pers is tent
implementations .
Factory: Contains methods to create domain objects .
Dependency invers ion principle

T he dependency invers ion principle promotes an independent connection by inverting dependency relations . T his ens ures
that the domain model can be very 'clean' without knowledge of the underlying infras tructure (PO JO clas s es ). T he Spring
framework is us ed to implement the Dependency Invers ion principle.
Behavior driven development (BDD)

Behavior driven development is a way of programming that firs t des cribes behavior in us er s tories and then implements this
in code. T he us er s tories contain s cenarios with acceptation criteria that can be automated. T his creates a complete tes t
s uite for the whole s ys tem.
For the application of BDD the following frameworks are us ed:
Cucumber and Gherkin, automated acceptance tes ting, bas ed on s cenarios from s tories .
Architecture Principles 15
Platform components description

Description of the individual platform components
Application Layering
T he us e of layers improves the s eparation of res pons ibilities . Each application contains the following layers :
Pres entation layer: res pons ible for providing information to us ers (pers ons and/or s ys tems ) and the handling of us er
reques ts
Application layer: res pons ible for executing s ys tem tas ks including authorization control
Domain layer: res pons ible for the repres entation of the problem domain.
Infras tructure layer: res pons ible for technical matters s upporting other layers . For ins tance pers is tence, mes s aging,
etc
Laye rs :
Authentication and authorization

T he web s erver is configured with a SSL certificate to encrypt the incoming and outgoing communication. T he SO AP Web
s ervice (Spring Framework web s ervice) us es a Java Keys tore and a certificate for each organization. O nly organizations
that are known within the platform are authorized to us e the web s ervice.
Application integ ration layer

For the s everal functional domains s eparate SO AP Web s ervices are offered. T his s eparation offers authorization per
functional domain. Each of the web s ervice components s end a queue mes s age to the corres ponding domain component.
WSDL A s eparate WSDL is implemented for each functional clus ter. All SO AP operations have a reques t object parameter
and return a res pons e object. For Synchronized Web Services the res ult is immediately included in the res pons e. For
as ynchronous web s ervices the res pons e contains a correlation ID. T his Correlation ID is to be us ed by the reques ter to
receive the actual res ult from the platform. T he following diagram is an example of s uch an as ynchronous reques t.
Platform components des cription 16

Furthermore each SO AP mes s age has a header which contains the us er's organis ation ID. T his table dis plays an overview of
the WSDL's including operations and fields in the reques t and res pons e objects .
SO AP vs . REST
SO AP is chos en in the open s mart grid platform web s ervices over REST for the following reas ons :
REST is res ources /data oriented (put, get, delete) while the open s mart grid platform is function/method oriented
SO AP has the advantage of having a contract (WSDL)
SO AP has extens ive s ecurity features that are being us ed in the open s mart grid platform to meet the high s ecurity
demands /requirements reques ted by e.g. the energy utilities
Energy companies are generally not progres s ive in terms of technology. SO AP is acceptable for energy companies
and REST is s ometimes s een as new and ins ecure.
T he benefits of REST (e.g. s peed / les s overhead) does not outweigh the benefits of SO AP. More general information on this
topic can be found online.
Domain log ic layer

For each functional domain bus ines s logic is implemented us ing a s eparate domain component. Common functionality like
authorization s hould be abs tracted to a s hared component. Domain components receive queue mes s ages from web s ervice
components and s end queue mes s ages to the open s mart grid platform core component.
More information on the s pecific domains can be found in the domain chapter
Open Smart Grid Platform Core Services

T he open s mart grid platform core component receives queue mes s ages from domain components . T hes e mes s ages from
domain components are forwarded to a protocol adapter project. T he open s mart grid platform core component als o offers
logic for a protocol adapter project to s end the res pons e of a s mart device back to a domain project. T he Core component
routes mes s ages from domain adapter components to protocol adapter components and vice vers a. T he core layer als o
contains a workflow engine.
T he internal databas e model in the core layer:


Image, Overview of platform data model
Data model explanation:
T ab le De s crip tion
devices Devices table
Authoris ation table, function group column concerns the device functions (AD_HO C,
device_authoris ation
INST ALLAT IO N, etc)
organization O rganization table, function group column concerns the platform functions (ADMIN of USER)
event Events table
os lp_log_item T able for logging of O SLP mes s ages .
webs ervice monitor log
Audit record for tracking webs ervice activity.
item
T he platform will s tore as little data as pos s ible. Generic (and domain s pecific) devices attributes are s tored in core DB.
Protocol Layer
T he open s mart grid platform s upports multiple protocols .
O SLP (O pen Street Light Protocol)

DLMS/CO SEM
IEC61850
T he protocols can us e one of the s ecurity layers :
T LS (T rans port Layer Security encryption)

SSL (Secure Sockets Layer encryption)
O ther protocols can be eas ily added to the platform. If pos s ible, we prefer protocols bas ed on open s tandards . A
comprehens ive lis t of protocols that are currently s upported can be found in the protocols chapter.
Protocol s pecific device attributes are s tored in the protocol adapter DB
Queues
O pen s mart grid platform components connect to each other through mes s age queues .

T rans actions on mes s ages to and from the queues

Mes s ages are pers is ted on the queues
Q ueues are clus tered for reliability and s peed
By us ing queues , the open s mart grid platform can be s tateles s
Smart devices
T he open s mart grid platform can connect to any device that s upports one of the s upported protocols . Smart devices can
receive mes s ages from or s end mes s ages to protocol adapter components . In cas e of SSLD's this is done us ing T CP/IP over
mobile internet connections (e.g. GPRS, CDMA, etc.). T he communication is encrypted us ing public key cryptography.

Message flow examples

Messageflow examples
T his are s ome examples how a mes s age flows in the O pen Smart Grid Platform.
Message Flow: Request/Acknowledge/Poll
S te p De s crip tion
1 WS adapter receives client s oap reques t with organization certificate and organization id in s oap header
WS adapter authenticates organization, checks authorizations and s ends reques t mes s age to domain adapter (via
2
queue)
3 WS adapter returns s oap acknowledgement with correlation id
4 Domain adapter s ends reques t mes s age to core (via queue)
5 Core determines protocol for device and s ends reques t mes s age to protocol adapter (via queue)
6 Protocol adapter trans lates domain reques t mes s age, s ends reques t to device and receives res pons e from device
7 Protocol adapter s ends res pons e mes s age to core (via queue)
8 Core forwards res pons e mes s age to domain adapter (via queue)
9 Domain adapter forwards res pons e mes s age to res pons e queue
10 Client app polls for res pons e us ing correlation id (with organization certificate and organization id in s oap header)
11 WS adapter retrieves res pons e mes s age from res pons e queue
12 WS adapter s ends s oap res pons e to client app
Message Flow: Request/Acknowledge/Notify
Mes s age flow examples 21

S te p De s crip tion
1-8 Same as reques t/acknowledge/poll mes s age flow
9 Domain adapter forwards res pons e mes s age to WS adapter
10 WS adapter s tores res pons e in DB
11 WS adapter s ends s oap notification with correlation id to client app
12 Client app s ends s oap reques t with correlation id to retrieve the res pons e
13 WS adapter retrieves (and deletes ) res pons e from DB
14 WS adapter s ends s oap res pons e to client app
Mes s age flow examples 22

Logical Authorisation Model

Logical Authorisation Data Model
Authe ntication of op e n s mart g rid p latform
T he O pen Smart Grid Platform contains an extens ive authorization model, which enables a device owner to give certain
rights on certain devices to other organizations . Every organization will only s ee devices they have rights to.
T his model dis plays the mos t important entities of the open s mart grid platform s ys tem and their mutual relations hips .
Image of Logical Authorisation Data Model
T he logic of the model above:
At the top of the image is the entity "authoris ation". T his repres ents the permis s ions of an organization on a certain device. In
general an organis ation will have a lot of permis s ions , at leas t one for each device it needs to manage.
T he functions an organis ation can execute on a device are determined by the function group the authoris ation refers to.
Function groups are collections of functions and are predefined in the s oftware. T he following function groups have been
predefined.
O wner-group (this contains all functions )

Ad hoc-group (Functions for ad hoc s witching of lighting)
Management-group (Platform functions )
Ins tallation-group (Functions to ins tall devices )
Firmware-group (Functions for updating firmware)
Schedule-group (Functions to create lighting s chedules )
T ariff s cheme-group (Functions to create tariff groups )
Configuration-group (Functions to configure devices )
Monitoring-group (Functions to monitor devices )
T his s tructure provides maximum flexibility when as s igning rights to devices . Devices always belong to an O wner. An owner
is an organis ation, but not every organis ation is an owner. T he entity "Event", at the bottom of the image, is the execution of a
function by an organis ation on a device.
Logical Authoris ation Model 23

Details like device-type, device-s tatus , etc. have been omitted from this model.
O ne s ecurity requirement is that each event mus t be traced back to a 'natural' pers on, als o known as an audit trail. Although
the open s mart grid platform does not regis ter individual us ers we can meet this requirement by regis tering a data-item with
each event. T his enables the us er organis ation to inves tigate which events belongs to which 'natural' pers on. T his data-item
can for example be an us er-ID provided by the us er organis ation which does n't have to be unique in the open s mart grid
platform.
T able des cribing the entities in the logical data-model
Entity De s crip tion

Authorization – Permis s ions of an organis ation to execute a certain function (member of a role) on a certain
authorization
device
Electronics pres ent in a "container" (for example a lamp pos t), connecting to the open s mart grid platform and
device
(in cas e of a lamp pos t) controls the lights . O ne device has one owner.
audit trail T he actions of an organization on a device. A combination of [time, organization, function and device].
function An end-to-end operation. For example "s et s chedule". A function belongs to multiple function groups .
function Us ually this will be larger groups than the "function clus ters " in this document. All functions available to end
group us ers could be in a s ingle group for example.
organization A party playing a role in the management and control of the devices , for example municipalities .
owner An organization role. Each device has an owner.
An event reported by the device (which is not the action of a natural pers on) for example an error or s ecurity
event
problem.
An organization can get rights to one or more function groups , and thus all functions in that function group will be available
to this organization.
T o ens ure that devices can only receive ins tructions from a 'genuine' open s mart grid platform it mus t be pos s ible to
authenticate the open s mart grid platform. T his is implemented through a s tandard technology bas ed on as ymmetric
encryption (if s upported by the Device). T he open s mart grid platform will receive a unique key to enable the devices to tell if
the mes s ages come from a 'genuine' open s mart grid platform. Both O SLP and DLMS device types us e this kind of
encryption. T o prevent replay-attacks each mes s age will get an index number (this is s tandard practice as well).
Authe ntication of d e vice s
T o ens ure that the open s mart grid platform can dis tinguis h between 'genuine' devices and 'illegal' devices , all devices are
s upplied with a manufacturer key. Each device has a unique key. Becaus e of the as ymmetrical encryption the platform
contains the public part of each key. In this way devices can be identified by their unique key and their unique hardware ID.
T he device-ID will be encrypted in each mes s age s ent from the device to the platform.
All communication between the open s mart grid platform and the devices will be s igned with thes e keys to ens ure (1) the
s ource is legitimate and (2) to ens ure the integrity of the mes s age. It is not neces s ary to encrypt the whole mes s age becaus e
confidentiality is not important. T his res ults in a les s computationally intens ive proces s .
When a key is s tolen (by hacking a device) this will not affect the integrity of the other devices . Each device has an unique key
after all and only the hacked device has to be excluded from communication in the platform.
T he s ecurity is independent from the carrier (GPRS, CDMA, Ethernet, etc.). T he open s mart grid platform s upports
s ymmetric and as ymmetric encryption (depends on device and protocol).
For O SLP devices , the firmware will be us ed to dis tribute keys to devices . In this way we can us e the exis ting s ecure
firmware update mechanis m for updating keys and certificates . DLMS devices us e a mechanis m to s witch keys that is not
dependent on firmware updates .
Additional s ecurity may be provided by us ing T LS communication.
Authoris ation of org anis ations
Authoris ation for us e of the platform functionalities is handled by function groups . Function groups are defined for both
platform functionality and device functionality. Each function group has one or more functions . Acces s to device functions
can be s et per device. T he tables below s how an overview of all function-groups and device-functions and platform-groups
and platform-functions res pectively.
Group s
Functions O WNER INST ALLAT IO N AD_HO C MANAGEMENT FIRMWARE SCHEDULING T ARIFF_SCHEDULING
GET _DEVICE_AUT HO RISAT IO N X X X X X X X
SET _DEVICE_AUT HO RISAT IO N X
ST ART _SELF_T EST X X
ST O P_SELF_T EST X X

SET _LIGHT X X
GET _ST AT US X X
RESUME_SCHEDULE X X
SET _REBO O T X X
SET _T RANSIT IO N X X
SET _EVENT _NO T IFICAT IO NS X X
GET _EVENT _NO T IFICAT IO NS X X
REMO VE_DEVICE X X
UPDAT E_FIRMWARE X X
GET _FIRMWARE_VERSIO N X X
SET _SCHEDULE X X
SET _T ARIFF_SCHEDULE X X
SET _CO NFIGURAT IO N X
GET _CO NFIGURAT IO N X
GET _ACT UAL_PO WER_USAGE X
GET _PO WER_USAGE_HIST O RY X
Group s
Functions ADMIN USER
CREAT E_O RGANISAT IO N X
GET _O RGANISAT IO NS X X
GET _DEVICE_NO _O WNER X
GET _MESSAGES X
FIND_DEVICES X
SET _O WNER X

Non-functional overview
Non-functional view
T he non-functional view is an overview of the mos t s ignificant non-functional demands .
T he identified non-functional demands are:
T ime Behavior
Extens ibility
Internationalis ation and localis ation
Security
Scalability
Non-functional overview 26
TimeBehavior
Time Behavior
T ime behavior is mainly important in the Flexovl application when a lot of devices have to be addres s ed in a s hort period of
time over a wireles s network. Both latency and limited bandwidth have to be taken into cons ideration while demanding the
coordinated on and off s witching of the lighting, s ince we want to avoid the Chris tmas tree effect.
T ime s ynchronization: devices periodically regis ter with the platform and receive a time.
Protocol: becaus e of the limited bandwidth an efficient protocol "protobuf" was s elected.
Points of inte re s t:
Light metering mes s ages

When the SSLD's are dis abled the PSLDs cannot be addres s ed
Becaus e of thes e points of interes t we us e mes s age queueing combined with a retry mechanis m of delayed delivery.
T he platform and devices us e UT C time. T he O SLP protocol between platform and devices us es UT C time as well.
T imeBehavior 27
Internationalization and localization

Internationalization and localization
T he platform and devices us e UT C time. T he O SLP protocol between platform and devices us es UT C time as well.
Internationalization and localization 28

Security
Security
T he following s ecurity meas ures can be us ed in a hos ted environment:
Cloud s ecurity
DDO S protection
IPSEC VPN connections
IP whitelis ting
Mos t cloud environments s upport thes e features .
Operating Sys tem

Hardened operating s ys tems (according to Center of Internet Security)
Platform s ecurity
Communication over T LS
Firewalls between all s ervers and layers
Certificates from a recognized Certificate Authority (CA)
Audit trail on all actions throughout the platform
Role bas ed authorizations on s pecific functions of devices
Acces s control
Unique device identification
For every major releas e there will be a mandated s ecurity tes t initiated by Smart Society Services .
In cooperation with the European Network of Cyber Security (ENCS) s tate of the art s ecurity meas ures were implemented.
Security per device

Security per application
Security Certificates per O rganis ation and per device
All communication is encrypted
Security 29
S e curity me as ure s :
1. Firewall in defined zone

2. O perating Sys tem Hardening
3. DDO S protection
4. Replay attack prevention
5. Private encryption key per device
6. Certificates from a Certificate Authority
7. Encryption via Elliptic Curve DSA
8. IPSEC VPN for CDMA and GPRS
9. Unique device identification
10. Unique CDMA modem number
11. Role bas ed authorizations on functions and devices
Encryp tion
An analys is of s afety as pects has led to the decis ion that the s afety of the whole s ys tem will be realized by proven
technology bas ed on as ymmetrical coding (als o known as public-key encryption).
Authe ntication of we b ap p lications
T wo-way SSL will be us ed between web applications and the O pen Smart Grid Platform to verify the identities for both client
and s erver. Us er organis ations are res pons ible for the adminis tration of the identity of and acces s to their web applications .
T he web applications feature a login page. After s ucces s ful login the us er is linked to an organis ation. Pas s words will be
s tored with encryption. T he organis ation ID will be s ent in each mes s age to the O pen Smart Grid Platform and will be
verified by the SSL certificate.
Alg orithms
O nly public encryption Algorithms will be us ed. Due to performance limitations (of the devices ) and recommendations from
Security 30
T he European Network for Cyber Security (ENCS) Elliptic Curve DSA with 256-bit-keys was s elected. T his improves the
s ecurity and efficiency over the 1024 bit RSA algorithm. Mes s ages can be s maller and les s proces s or capacity is needed. T he
key length of Elliptic Curve DSA is s imilar to the 3072 bit key length of RSA.
Note: Even though the open s mart grid platform us es ECDSA to s ecure the O SLP, other encryptions may be us ed as well.
T he RSA Algorithm is s till s upported if preferred. T his is a flexible configuration option.
Private APN
A private APN is us ed for linking to mobile data communication infras tructures .
Log g ing
Every action to and from devices is logged in the audit trail
Mes s ages from unknown devices will be denied (and logged)
Security 31
Scalability
Scalability
T he O pen Smart Grid Platform is des igned and built for s calability and reliability
Mes s ages will never get los t, In the wors t cas e s cenario, a mes s age will be s ent to the dead letter queue.
Any layer of the platform can be independently s caled up- and down
Adding s ervers can be done runtime
It can run in an active-active s etup over multiple s ervers and data centers . In our cloud hos ted s etup even over s ets of
data centers in different countries .
Scalability 32
Scalability 33
Redundancy
Redundancy
T his chapter des cribes the pos s ibilities of a redundant s et up of the O pen Smart Grid Platform. T he Platform is des igned to
run in a High Available (or HA) environment, and to prevent data los s due to unexpected failures . Each component of the
Platform is des igned to be s tateles s . Components communicate with each other us ing mes s age queues , which are proces s ed
in an as ynchronous way.
Active -active
In an active-active s etup, multiple ins tances of each component (eg. Web Services , Core, Protocol Adapter) proces s the data
at the s ame time. T raffic is equally dis tributed acros s the ins tances . In cas e of a defect in one ins tance the traffic is
automatically proces s ed by the remaining ins tance(s ). T he O pen Smart Grid Platform is des igned to run in s uch a s et up, and
thus preventing down time in cas e of a failing s erver. Each component of the Platform can run in an independent, redundant
and s calable way.
Datab as e
T he O pen Smart Grid Platform us es a Pos tgreSQ L databas e. Pos tgreSQ L s upports multiple databas e s ervers . For example,
a s lave and mas ter node, where the s lave node continuous ly replicates the mas ter node. In cas e the mas ter node fails , the
s lave mode is triggered and will s top replicating from the mas ter node, execute a recovery and will become the mas ter node.
Active MQ
T he components of the Platform communicate with each other through a Mes s age Q ueue. T he O pen Smart Grid Platform
us es Apache Active Mes s age Q ueue, which makes as ynchronous communication pos s ible between components . T he
components can regis ter to the queues as cons umers . In cas e a cons umer (e.g. a s erver running a component of the platform)
is down, the mes s age will s till be cons umed by the remaining cons umer(s ). T he Mes s age Brokers can be us ed as a
Mas terSlave. In cas e the Mas ter mes s age broker is down, you get immediate fail-over to the s lave without los s of mes s ages .
Redundancy 34
Redundancy 35
Performance
Performance
T his chapter des cribes the res ults of a performance tes t, to give potential us ers an indication of the s ys tem requirements for
the platform.
T he Platform was tes ted with the following AWS s etup:
Sys tems :
S p e cifications Comp one nt S e rve r: 2 CPU's , 8 GB RAM

S p e cifications Datab as e S e rve r: 1 CPU, 2 GB RAM
Setup:
Front-e nd : 2x Component Server

Mid d le -e nd : 2x Component Server
Back-e nd : 2x Component Server
Active MQ Front-Mid d le : 1x Component Server
Active MQ Mid d le -Back: 1x Component Server
Datab as e s : 1x DB Server
For the tes t to s ucceed, two requirements were to be met:
1. Switch 10.000 s imulated O SLP devices under 5 minutes .

2. Switch 40.000 s imulated O SLP devices under 5 minutes .
T he res ults s howed that both tes ts s ucceeded.
Performance 36
Technical Overview
Technical Architecture
T his chapter gives a more technical overview. It des cribes each layer of the platform by giving an overview of its packages
and the code it contains . Furthermore it des cribes how a mes s age proceeds through the platform. If you are planning on
adding your own Domain Adapter or Protocol Adapter, it will be us eful to read this chapter to get a feeling of how the
Platform has been built.
A Re q ue s t throug h the Platform
T he picture below depicts an example of a reques t (O SLP SetLight reques t) proceeding through the platform to a device.
A web reques t enters the platform at its EndPoint, which in turns calls the Reques tService. T he Reques tService
checks if the organis ation in the reques t is authorized, creates the reques t mes s age and s ends it to the
Mes s ageSender which in turn puts it on the queue of the Domain Adapter.
In the Domain Adapter, the incoming mes s age is proces s ed in the Mes s ageProces s or, which in turn calls the Reques t
Service. Here the mes s age is converted to a DT O object. T he CoreReques tMes s ageSender puts the mes s age on the
Core Q ueue.
T he Mes s ageLis tener in Core receives the mes s age. T he DeviceReques tMes s ageService contains generic
functionality s uch as Authorization, Validation, etc. O nce thes e procedures are completed, the mes s age is routed to
the appropriate protocol adapter.
In the Protocol Adapter the mes s age is received by the Mes s ageLis tener. It is proces s ed through the
Mes s ageProces s or and O s lpDeviceService. T he reques t eventually ends up in the O s lpChannelHandler, where the
actual Protocol Reques t to the device is made.
For a detailed des cription of each layer, pleas e take a look at a more detailed des cription of each layer in this chapter.
Config uration file s
T he Platform us es property files for certain s ettings (s uch as JMS s ettings , Pers is tence s ettings , etc.). T hes e files are s tored
in property files which can be found in the Config repos itory on Github. T hes e files are s ym linked to /etc/os p/, where the
Platform (through reference in context.xml) looks for the property files .
T echnical O verview 37
T echnical O verview 38
Web Services Layer

Web Services
T he Web Services layer contains the web s ervices that are us ed to communicate with the Platform. T he O pen Source Smart
Grid Platform us es the Simple O bject Acces s Protocol or SO AP to expos e its interfaces . T he Web Services Adapter
receives reques ts and s ends thos e to the Domain Adapter. An incoming reques t is converted to a Domain O bject, and put on
the Mes s ageQ ueue of the Domain layer. T he Web Services layer als o has a queue for incoming res pons es from the Domain
adapter.
Each domain of the Platform has its own web s ervices :
Ge ne ric
Core - os gp-adapter-ws -core: Contains the Core (common) web s ervices .

Admin - os gp-adapter-ws -admin: Contains the Admin web s ervices .
Shared - os gp-adapter-ws -s hared: Contains s hared endpoints , s uch as header authorization
Databas e - os gp-adapter-ws -db: Contains repos itories for pers is tence.
Domain
Public Lighting - os gp-adapter-ws -publiclighting: Contains the Public Lighting web s ervices .
Smart Metering - os gp-adapter-ws -s martmetering: Contains the Smart Metering web s ervices .
T ariff Swithcing - os gp-adapter-ws -tariffs witching: Contains the T ariff Switching web s ervices .
Microgrids - os gp-adapter-ws -microgrids : Contains the Micro Grids web s ervices .
Dis tribution Automation - os gp-adapter-ws -dis tributionautomation: Contains the Dis tribution Automation web
s ervices .
For a des cription of the WSDL's s ee the Domain Chapter.
General Packag e s tructure

A des cription of the general package s tructure of a web s ervice component.
ap p lication
config: Contains the configuration files for the Component. Us es the property files in /etc/os p/. -- ApplicationContext -
- AdapterInitializer -- Mes s agingConfig -- Pers is tenceConfig -- WebServiceConfig
exceptionhandling: Exceptions are defined here.
mapping: Cus tom O rika converters .
s ervices : Contains s ervices us ed by the domain, s uch as AdHocManagement. T hes e are called by the end points and
convert the reques t to a Domain O bject and put the reques t on the domain mes s age queue us ing the JMS clas s es .
e nd p oints
EndPoints for the web s ervices : contain a reference to a s ervice that proceeds with handling the reques t.
infra
jms : contains the JMS clas s es s uch as : -- Mes s ageSender(s ) -- Mes s ageT ype -- Res pons eMes s ageFinder
we b ap p
T he WSDL and s chema definitions can be found under main/webapp/WEB_INF/ws dl.
Web Services Layer 39

Domain Layer
Domain Adapters
T he Domain Adapters are res pons ible for receiving reques ts from the Web Services layer, and delivering them to the Core
layer. T he Domain Layer mainly contains Mes s ageProces s ors and Services for reques t handling.
T he Core/Admin components contains the s hared functionality, while the Domain components contain additional domain
s pecific functionality.
At the moment the Platform us es the following Domain Adapters :
Generic
Core - os gp-adapter-domain-core: Contains Core (common) functionality; AdHocManagement,

FirmwareManagement, etc.
Admin - os gp-adapter-domain-admin: Contains Admin functionality, e.g. DeviceManagement.
Domain
Public Lighting - os gp-adapter-domain-publiclighting: Contains functionality for the Public Lighting Domain.
Smart Metering - os gp-adapter-domain-s martmetering: Contains functionality for the Smart Metering Domain.
T ariff Switching - os gp-adapter-domain-tariffs witching: Contains functionality for the T ariff Switching Domain.
Microgrids - os gp-adapter-domain-microgrids : Contains functionality for the Micro Grids domain.
Dis tribution Automation - os gp-adapter-domain-dis tributionautomation: Contains functionality for the Dis tribution
Automation domain.
General Packag e s tructure
ap p lication
- DomainAdapterInitializer -- Mes s agingConfig -- Pers is tenceConfig
mapping: Cus tom O rika converters for mapping to/from DomainO bjects /DT O O bjects .
s ervices : Contains mos t of the domain logic, related to the s pecific s ervices of the adapter. T he s ervice clas s es
converts DT O objects to Domain objects (or vice vers a), and put the reques t on the Core queue through the JMS
clas s es .
infra
jms .core: Inbound/outbound mes s ages from/to the Core layer. T his package contains Mes s ages , Mes s ageLis teners ,
Mes s ageSenders and Mes s ageProces s ors for s ending reques ts to the Core Q ueue, or receiving and proces s ing
res pons es from Core.
jms .ws : Inbound/outbound mes s ages from/to the web s ervices layer. T his package contains Mes s ages ,
Mes s ageLis teners , Mes s ageSenders and Mes s ageProces s ors for s ending reques ts to the Web Services Q ueue, or
receiving and proces s ing res pons es from the web s ervices layer.
Domain Layer 40
Core Layer
Core Layer
T he Core layer of the O pen Source Grid Platform is res pons ible for Validation, T rans lation, Authoris ation and Routing of
reques t mes s ages . It als o contains all the Domain O bjects .
T he core layer cons is ts of two components :
os gp-domain-core: Shared Domain objects , s ervices , repos itories , etc. T hes e clas s es are us ed through the entire
platform.
os gp-core: Logic for routing domain reques ts , s cheduling, retrying, etc.
General Packag e s tructure: os g p-domain-core

entities : Defines the entities us ed for pers is tence.
exceptions : Domain s pecific exceptions res ide here.
repos itories : Repos itories that contain logic for pers is ting entities .
s ervices : Domain s ervices that reference a repos itory.
s pecifications : Interfaces that define s pecifications for Devices and Events .
validations : Validators and cons traints .
valueobjects : Definitions of the Domain O bjects .
General Packag e s tructure: os g p-core
ap p lication
- O s gpCoreInitializer -- DomainMes s agingConfig -- Pers is tenceConfig -- ProtocolMes s agingConfig --
SchedulingConfig
s ervices : Services that proces s device reques ts / res pons es . Checks for authorization, and if the reques t is s upported
by the platform, it will be routed to the appropriate protocol adapter.
tas ks : Contains tas k s cheduler logic.
d omain.mod e l
T hes e packages contain interfaces for the Services .
domain: Interfaces for the Domain s ervices .

protocol: Interfaces for the Protocol s ervices .
infra.jms
domain: Contains Mes s ages , Mes s ageLis teners and Mes s ageProces s ors for Domain related mes s aging.
protocol: Contains Mes s ages , Mes s ageLis teners and Mes s ageProces s ors for Protocol related mes s aging.
Core Layer 41
Protocol Layer
Protocol Adapters
T he Protocol Adapters are res pons ible for the actual communication to and from a device. T hey us ually operate in a certain
domain, and might us e common/ generic functions from the platform.
T he O pen Smart Grid Platform currently has the following protocol adapters :
Protocol-Adapter-DLMS: Smart Metering

Protocol-Adapter-IEC61850: Public Lighting, Micro Grids and Dis tribution Automation
Protocol-Adapter-O SLP: Public Lighting and Micro Grids
General packag e s tructure
ap p lication
- Mes s agingConfig -- O s gpProtocolAdapterO s lpInitializer -- O s lpConfig -- O s lpPers is tenceConfig
mapping: Cus tom O rika converters .
s ervices : Contains the (functional) s ervices that control communication from (and to) the device. Als o pers is ts
reques ts and res pons es , and deals with s ecurity. Actual communication is done through the clas s es in the infra
package.
d e vice
Contains the Protocol Adapter O bjects us ed for the Protocol Adapter.
reques ts : O bjects repres enting the reques ts that are s upported by this adapter.
res pons es : O bjects repres enting the res pons es that are s upported by this adapter.
d omain
entities : Entities us ed for pers is tence.

repos itories : Repos itories us ed for pers is tence.
e xce p tions
Contains the exceptions that might be thrown while communication with a device, e.g. ValidationException,
Mes s ageRejectedException, etc.
infra
T his package contains all the code for communication through JMS (Platform) and Networking (Device).
mes s aging: Contains the JMS Mes s ages , Mes s ageLis teners , Mes s ageSenders and Mes s ageProces s ors .
networking: Contains the clas s es that are res pons ible for connecting to a device us ing a certain protocol.
s e rvice s
Services us ed to check the reques t s tatus .
Protocol Layer 42
Technology Stack
Tools and technology used
Platform
Apache ActiveMQ : O pen s ource mes s aging s erver, us ed to relay mes s ages between components of the open s mart
grid platform. ActiveMQ is an open s ource mes s age broker written in Java and a full Java Mes s age Service (JMS)
client. It provides "Enterpris e Features " which in this cas e means fos tering the communication from more than one
client or s erver.
Apache HT T P s erver: Web s erver, us ed as front for Apache T omcat.
Apache T omcat: Provides a "pure Java" s ervlet container for Java code to run in.
pgAdmin-III: Pos tgreSQ L adminis tration and management tools .
Protobuf (Google Protocol Buffers ): A language-neutral, platform-neutral, extens ible way of s erializing s tructured
data for us e in communications protocols , data s torage, and more.
Flyway: Agile databas e migration framework for Java
HikariCP: JDBC connection pool
Hibernate: O bject/Relational mapping
Netty: Network application framework for protocol s ervers & clients
O penMUC: Library implementing the IEC61850 and DLMS/CO SEM communication s tandard
O rika: Java bean mapping
Spring: Application development framework. Several Spring libraries are us ed, including Spring Data, Spring
Security and Spring WS.
Puppet: Application for Automatically delivering, operating and s ecuring your infras tructure
Development
Bower: Package manager for Javas cript packages . Web applications cons is t of various components ; frameworks ,
libraries , as s ets , utilities , and rainbows . Bower manages all thes e things for you.
Eclips e: IDE for developing s oftware.
FileZilla: FT P application.
Git: Vers ion control s ys tem.
NodeJS: T ooling s uite with various Javas cript tools .
NPM: Package manager for the NodeJS Javas cript applications .
Putty: A free and open-s ource terminal emulator, s erial cons ole and network file trans fer application.
Vim: Source code editor.
Apache Maven: Software project management tool.
GIT & GitHub: Source code management.
Tes ting &QA

Apache JMeter: Application des igned to load tes t functional behaviour and meas ure performance.
Cucumber: automated acceptance tes ting framework.
Gherkin: DSL for acceptence tes ting framework.
Sonarqube: Q uality management platform.
SoapUI: Functional tes ting tool for tes ting web s ervices .
JUnit: Unit tes ting.
Mockito: A Mock framework for Unit tes ting.
T he following table pres ents an overview of the components and the mos t important technical choices per component.
Comp one nt T e chnolog y

O pen Smart Grid Platform Java, Spring Framework, Hibernate, Netty
Demo application Java, Spring Framework, Spring MVC
Web s ervices SO AP, WSDL
O SLP Protocol Google Protocol Buffers
Comp one nt (not op e n s ource ) T e chnolog y
O SGP Management application Java, Spring Framework, Spring MVC
Net-Management application Java, Spring Framework, JAX-RS, AngularJS
Liander Ins tallatie application Java, Spring Framework, JAX-RS, AngularJS
T echnology Stack 43
Use cases
Use cases
T he open s mart grid platform us e-cas es are s trongly related to the open s mart grid platform domains . Up-to-date
information on us e-cas es can be found on the open s mart grid platform webs ite.
Us e cas es 44
General User's Guide

CHAPTER 2. User's Guide
Sys Admins who are tas ked with keeping the O pen Source Grid Platform running on a environment, can find s ome information
in this chapter.
Get Started
T o get s tarted with O pen Source Grid Platform, pleas e read our Introduction. T he Introduction offers an excellent overview
of the Platform and its features .
A next s tep could be to have a look at the WSDL's to unders tand which functions are pres ent per functional domain.
Depending on the functional domain one is interes ted in, one could als o have a look at the Protocol Adapter and device
s imulator for the domain.
Ins tallation
If a full ins tallation is des ired, have a look at our Ins tallation Guide. T his can be us ed to s etup a development environment
which can be us ed to s tart the Platform and run it. Ins tallation on one or s everal s ervers can be derived from the s teps within
the Ins tallation Script.
General Us er's Guide 45

Installation Guide
Installation Script
T o get s tarted quickly, a Vagrant Ins tallation Guide has been created and a guide for Manual Ins tallation.
T he goal of the ins tallation manual is to control a s imulated O SLP device through the Platform. Below, is a s ummary of all
s teps involved. See the next chapters for a detailed guide with s creens hots . Pleas e follow the s teps carefully.
A s ummary of the s teps involved:
Creating a virtual machine us ing Vagrant and Virtual Box

Run the puppet s cript (part of the Vagrant ins tallation), or complete the s teps manually (Manual ins tallation)
Importing Maven Projects into Eclips e
Creating an Apache T omcat7 Server
Setting Up Apache T omcat7 Server Context
Deploying all open s mart grid platform components to an Apache T omcat7 Server
Starting Apache ActiveMQ
Starting Apache T omcat7 Server
Creating the 'tes t-org' organization in the Databas e
Setting up SoapUI
Firs t SO AP Reques ts to add a device to the open s mart grid platform
O pening Device Simulator to add a device
Regis tering a device
Us ing 'SetLight' SO AP Reques t to s witch the light on
Ins tallation Guide 46

Installation
Open Smart Grid Platform Installation
T o ins tall the platform you can us e one of the following procedures .
1. T he Vagrant Ins tallation. T his procedure creates and ins talls a complete image with the O pen Smart Grid Platform
pre-ins talled, including all the tools s uch as Maven, Eclips e, Soap Ui, etc.
2. T he Manual Ins tallation. Follow this guide if you want to ins tall the O pen Smart Grid Platform yours elf.
Ins tallation 47
Vagrant
Installation
T his document des cribes the automatic ins tallation procedure for your O pen Smart Grid Platform development environment.
Manual ins tallation

If you would like to follow the manual ins tallation p roce d ure , pleas e proceed to the Manual Ins tallation Chapter.
Overview
Cre a tin g a Virtu a l Ma c h in e u s in g Virtu a l B o x a n d Va g ra n t
T o improve the us ability of the Ins tallation proces s , a Vagrant file and s ome puppet s cripts are us ed to automatically s et-up
an virtual O pen Smart Grid Platform development environment. T he following s teps will des cribe how to ins tall VirtualBox,
Vagrant and kick off the procedure by running the vagrant up command.
Sys tem Requirements

T he following s ys tem requirements are recommended:
Core i5/i7 ~2.5GHz Dual Core, Q uad Core recommended

At leas t 6 GB RAM, 8 GB RAM recommended
At leas t 20 GB free s pace, 50 GB free s pace recommended
T he ins tallation procedure has been tes ted on Windows 7, Windows 10, MacO S, Ubuntu 14.04 and Ubuntu 16.04.
Ins tall Vag rant and VirtualBox

Start by downloading VirtualBox by going to https ://www.virtualbox.org/wiki/Downloads And follow the ins tallation s teps .
note : If you already have VirtualBox, make s ure it is at leas t ve rs ion 5.1.6
Ins tallation 48
note : Check whether Virtualbox s tores the images on a drive with enough free s pace. (O pen O racle VM VirtualBox
Manager -> Preferences -> General -> Default Machine Folder).
Now download and ins tall Vagrant. Vagrant is available at the following URL: https ://www.vagrantup.com/downloads .html
Ins tallation 49
note : If you already have Vagrant, make s ure it is at leas t ve rs ion 1.8.6 Complete the ins tallation and res tart your PC.
note : If you did a fres h ins tall of Vagrant and already had a command prompt open, make s ure you clos e this command
prompt and open it again.
T ip
Remember to enable Virtualization in your s ys tem BIO S.

Als o dis able Hyper-V in Windows (can be found in Windows Features )
Download and run the Vagrant file

Firs t create a new directory (for example: D:\My Vagrant Images\OSGP Development\)
Brows e to https ://github.com/O SGP/Config/tree/development/vagrant and s ave the png image and Vagrantfile files in your
newly created directory.
Ins tallation 50
Note
Make s ure that the file is named like this : Vagrantfile without an extens ion!
If the file has an extens ion (for example .txt) you can rename the file us ing the following cons ole command.
MacO S/Linux:
mv Vagrantfile.txt Vagrantfile
Windows :
move Vagrantfile.txt Vagrantfile
Now open a Command Prompt and navigate to the newly created directory where you jus t put the files .
note : When you open the Vagrantfile you s ee that default the image is configured to run in virtualbox with 2 cpu cores
and 8192 MB of RAM. If you need to you can change this to more or les s cpu cores and RAM, but it is recommended to
us e the provided s ettings .
Run the following command: vagrant up
note : In cas e of error bad uri Images /O SGP Development/has hicorp/cxtlabs /vagrant-ubuntu-16.04-mate then us e the
following command;
vagrant des troy

vagrant box add cxtlabs /vagrant-ubuntu-16.04-mate
vagrant up
Ins tallation 51
Vagrant will now automatically download an Ubuntu image (+- 2.6 Gb), create a virtualbox image from it and run the
ins tallation puppet s cript when finis hed. T his might take a while, depending on your internet s peed. After s ome time (while
the s cript is s till running) you will notice that a window with an Ubuntu Virtual Machine pops -up. Don't log in yet, wait until the
s cript in the Cons ole is finis hed.
T ip
Ins tallation 52
If the s cript fails for s ome reas on (eg. Errors in the cons ole s uch as time outs during downloading), you can retry the
procedure by running the following command vagrant destroy && vagrant up
Now that the s cript has ran its cours e, go to the Ubuntu virtual machine and log in as 'T he "dev" us er', when as ked for a
pas s word, enter 'dev'.
Optimize your Open Smart Grid Platform Development virtualbox image.

At this point you als o can adjus t the virtualbox s ettings like cpus and memory s ize. If you don't want to adjus t this proceed to
Chapter 2.1.2. Platform Setup.
If you do want to update the virtualbox s ettings for this image, s hut down the image firs t:
Ins tallation 53
O nce the machine has been Shut Down, open VirtualBox and right click on the new virtual machine (called "O SGP
Development") and s elect Settings . Go to Sys tem and increas e the Bas e Memory of the s ys tem to at leas t 6144 MB (6 GB) (or
the maximum recommended (in green) amount for your s ys tem).
Now go to the Proces s or T ab and increas e the amount of Proces s ors to the maximum recommended (in green) amount.
Ins tallation 54
Clos e the Settings window and Start the Virtual Machine again. O nce it is booted, you s hould be automatically logged in as
the 'Dev' us er.
Post actions
In order to us e git correctly you need to execute the following commands in a terminal:
git config --global user.name ""

git config --global user.email
Recap
You jus t created a virtual machine running Ubuntu with pre-ins talled tooling. Proceed with Platform Setup of the guide
des cribing how to s et-up the open s mart grid platform.
Ins tallation 55
Manual Setup
Manual Ins tallation
T his chapter des cribes the s teps for a manual ins tallation (eg. not us ing the vagrant s cript and puppet s cripts ). T his chapter
is for developers who would like to have more control over the ins tallation procedure.
Note
Skip this chapter if you followed the Vagrant ins tallation! You can continue with next chapter: Setup the O pen Smart
grid Platform
Operating Sys tem

T he O pen Smart Grid Platform runs on a Linux environment. It is recommended to s et up a machine running Ubuntu 14.04.
Software and tools

T he O pen Smart Grid platform needs the following s oftware and tools ins talled/downloaded:
Java 8 openjdk-8
Pos tg re S QL and PGAd min 3
Git
Mave n
Active MQ
T omcat 8
Ap ache HT T PD
S oap Ui
Eclip s e EE Luna
Goog le Protocol Buffe rs : p rotob uf-comp ile r, lib p rotoc7 and lib p rotob uf7
Pos tg re S q l JDBC d rive r JRE 7
Setting s
Us e r
It is recommeded to create a 'dev' us er, becaus e s ome s cripts contain hard coded references to this 'dev' us er. It is pos s ible
to s kip this s tep, but then s ome of the s cripts will have to be adjus ted manually.
To m ca t 8
Place the Pos tgreSql JDBC driver jar in the T omcat 8 lib directory.
Change permis s ions of T omcat 8 Config files to 644 in the T omcat 8 conf directory.
Ap a c h e HT T PD
Enable mod_s s l by running the following command:
a2enmod ssl
Enable proxy_ajp by running the following command:
a2enmod proxy_ajp
Java
Make s ure the JAVA_HO ME var is s et, and points to openjdk-8.
Cloning Sources
Clone the following repo's , it is recommeded to create a Sources/OSGP directory in /home/dev/ s ince s ome s cripts
contain hard coded references to thos e folders .
git clone https://github.com/OSGP/Config.git /home/dev/Sources/OSGP/Config

git clone https://github.com/OSGP/Shared.git /home/dev/Sources/OSGP/Shared
git clone https://github.com/OSGP/Platform.git /home/dev/Sources/OSGP/Platform
git clone https://github.com/OSGP/Protocol-Adapter-OSLP.git /home/dev/Sources/OSGP/Protocol-Adapter-OS
git clone https://github.com/OSGP/Protocol-Adapter-DLMS.git /home/dev/Sources/OSGP/Protocol-Adapter-DL
git clone https://github.com/OSGP/Protocol-Adapter-IEC61850.git /home/dev/Sources/OSGP/Protocol-Adapter
git clone https://github.com/OSGP/Integration-Tests.git /home/dev/Sources/OSGP/Integration-Tests
git clone https://github.com/OSGP/Documentation.git /home/dev/Sources/OSGP/Documentation
Ins tallation 56
Make s ure you are on the development branch (default).
Initialize the Git s ubmodules in Platform, Protocol-Adapter-O SLP, Protocol-Adapter-DLMS, Protocol-Adapter-IEC61850

and Integration-T es ts by running the following command in each directory:
git submodule update --init --recursive
Creating directories and s ymlinks

Create the following directories :
/var/log/osp/logs
/etc/osp/
Make the dev us er (or equivelant) the owner of the log directory with rwx permis s ion. Give the other us ers read and execute
permis s ion.
Execute the s cript /home/dev/Sources/OSGP/Config/scripts/create-symlinks.sh
Note T his s cript us es hard coded references to /home/dev/Sources/OSGP/*, if you us ed a different us er, pleas e edit
the s cript before executing it.
T he s cript will make s ymlinks to certificates , and to the Maven s ettings file in ~/.m2
Initiating the Databas e

T o create the databas e run the following command (Change /home/dev/ in cas e of no dev us er)
sudo -u postgres /usr/bin/psql -p 5432 -f /home/dev/Sources/OSGP/Config/sql/create-users-and-databases.s
And create a backup of the pg_hba.conf file
cp -p /etc/postgresql/9.3/main/pg_hba.conf /etc/postgresql/9.3/main/pg_hba.backup
Finally, reload the pos tgres ql s ervice:
service postgresql reload
Set up the Open Smart Grid Platform

Continue with s etting up the O pen Smart Grid Platform by following the Set up the O pen Smart Grid Platform Guide
Ins tallation 57
Platform Setup
Setting Up the Open Smart Grid Platform Development environment
T his chapter des cribes all the s teps needed to finalize the open s mart grid platform development environment.
Importing Maven Projects into Eclips e

O pen Eclips e by clicking the s hortcut on the Des ktop and import the projects .
Go to File -> Import -> Exis ting Maven Projects , brows e to folder /home/dev/Sources/OSGP
Import the following Projects (in the order as mentioned below)
/home/dev/Sources/OSGP/Shared
/home/dev/Sources/OSGP/Platform
/home/dev/Sources/OSGP/Protocol-Adapter-OSLP
/home/dev/Sources/OSGP/Protocol-Adapter-DLMS
/home/dev/Sources/OSGP/Protocol-Adapter-IEC61850
/home/dev/Sources/OSGP/Integration-Tests
Platform Setup 58
Platform Setup 59
Platform Setup 60
Platform Setup 61
Platform Setup 62
Platform Setup 63
Platform Setup 64
Creating an Apache Tomcat7 Server

In Eclips e go to Window -> O pen Pers pective -> Debug
Platform Setup 65
In the 'Debug' pers pective, go to the 'Servers ' view and add a new Apache T omcat7 s erver, T omcat7 is available in the folder
/home/dev/Tools/tomcat
Click on Next
Platform Setup 66
Click on Finis h
Platform Setup 67
Platform Setup 68
After adding the s erver, double click on the T omcat s erver in the 'Servers ' view and s et the following configuration: under
'T imeouts ' s et 'Start' to 600 and 'Stop' to 3.
Platform Setup 69
Click on 'O pen launch configuration', click on the 'Arguments ' tab and add the following at the end of the 'VM arguments ': -
Xms512m -Xmx2048m -Xss512k -XX:MaxMetaspaceSize=1024m -XX:+CMSClassUnloadingEnabled -
XX:+UseConcMarkSweepGC -Dcom.sun.management.jmxremote=true
Platform Setup 70
Setting Up Apache Tomcat7 Server Context

All modules contain their own context.xml. In the module s pecific context.xml are the environment variables defined where the
global and module s pecific configuration files are located. Default they will point to a location in /etc/osp/.
If you want to deviate from this , you might s et up the context.xml in tomcat to be able to redirect in one file to different
locations . T his is optional and not required. In order to us e a cus tom context.xml, copy the entries in
/home/dev/Sources/OSGP/Config/tomcat/context.xml.sample to the T omcat7 context.xml in the eclips e
Servers folder, to map configuration file names to file paths .
Platform Setup 71
Deploying all Open Smart Grid Platform components to Apache Tomcat7 Server
Continue by adding the Maven Projects to the T omcat s erver by right clicking on the T omcat s erver and choos ing 'Add and
Remove', followed by clicking on the 'Add =All' button.
At this point, eclips e's auto-build s hould have built the projects , and the T omcat s erver has been s etup.
Starting Apache ActiveMQ

Continue with s tarting Apache ActiveMQ . O n the des ktop double click the ActiveMQ s hortcut.
Alternatively you can open a terminal and run the executable manually by us ing the following command: (the executable can be
found in the folder /home/dev/Tools/activemq/bin/linux-x86-64)
sudo ./activemq console
T his s tarts ActiveMQ as a terminal proces s (this way, ActiveMQ does n't detach from the terminal and s tarts running as a
daemon).
Platform Setup 72
Starting Apache Tomcat7 Server

With ActiveMQ running, the T omcat7 s erver can be s tarted. Go to Eclips e, go to the Servers tab in the Debug view, and right
click on the T omcat s erver and s elect 'Start'.
Starting pg Admin III and Connect to Pos tg reSQL

O pen pgAdminIII and configure a connection: choos e the 'Add a connection to a s erver.' and fill out the fields us ing
Hos t: localhos t
Port: 5432
Us ername: os p_admin
Pas s word: 1234
Platform Setup 73
Creating the 'tes t-org ' Org anization

Run the s cript in /home/dev/Sources/OSGP/Config/sql/create-test-org.sql to ins ert 'tes t-org' organization
Platform Setup 74
into the organis ation table of the os gp_core databas e.
psql -U osp_admin -d osgp_core -f /home/dev/Sources/OSGP/Config/sql/create-test-org.sql
If as ked for a pas s word, enter 1234
Go back to PgAdmin III, expand s ervers , s elect localhos t -> databas es -> os gp_core -> Schemas -> public -> T ables . Right
click the organis ation table and s elect 's how top 100 data rows '. Confirm that the tes t-org organis ation has been added to the
Databas e.
Now that everything has been s et up, continue to the next chapter to s tart tes ting the Platform by s ending it s ome reques ts .
Platform Setup 75
Test the Platform

Testing the Open Smart Grid Platform
T here are two procedures for tes ting the O pen Smart Grid Platform.
1. SoapUI. Create and s end Soap reques ts to the Platform to manage a (s imulated) light.
2. PublicLighting Demo App. Us e the Demo App to s end reques ts to the Platform to manage a (s imulated) device.
T es t the Platform 76
Using SoapUi
Tes ting the platform
T his chapter will des cribe the s teps needed to tes t the O pen Smart Grid Platform.
Setting Up SoapUI
Start SoapUI by double clicking the s hortcut on the Des ktop or run it manually by typing the following command in a terminal:
/home/dev/Tools/SoapUI/bin/soapui.sh
Go to File -> Preferences -> SSL Settings , and brows e for the KeyStore to
/home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/test-org.pfx and fill out the pas s word (the
pas s word is 1234)
Go to WSDL Settings and check 'Generate Example Values in New Reques ts ' and 'Generate Comments with T ype Information
in New Reques ts '
Add the SoapUI projects to SoapUI

T here are s everal SoapUI project prepared, s ee /home/dev/Sources/OSGP/Config/soapui/. Import all SoapUI
projects pres ent in the folder mentioned above. Below, 2 projects are s hown as examples .
Adding the 'Admin' Soap project

Import the 'admin' project by clicking File -> Import project. Brows e to /home/dev/Sources/OSGP/Config/soapui/,
s elect 'admin-s oapui-project.xml' and click open.
Alternatively you can create the 'admin' project yours elf by following the s teps below:
Create a new SO AP Project and call it 'admin'
O pen the Project View by double-clicking on the 'admin' project. Go to 'WS-Security Configurations ' and s elect the
'Keys tores ' T ab. Click on the '+' to add the test-org.pfx in
/home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/
Fill out the pas s word (1234) and click O k and clos e the Project View window.
Right click the 'admin' project and choos e 'Add WSDL'. Enter the following URL in the WSDL Location field:
/home/dev/Sources/OSGP/Shared/osgp-ws-admin/src/main/resources/DeviceManagement.wsdl
Make s ure the box 'Create s ample reques ts for all operators ' is checked, and click O K.
Adding the 'Public Lig hting ' Soap project.

Import the 'public-lighting' project by clicking File -> Import project. Brows e to
/home/dev/Sourcees/OSGP/Config/soapui/, s elect 'public-lighting-s oapui-project.xml' and click open.
Alternatively you can create the 'public-lighting' project yours elf by following the s teps below:
Create another new SO AP Project and call it 'public-lighting'
O pen the Project View by double-clicking on the 'public-lighting' project. Go to 'WS-Security Configurations ' and
s elect the 'Keys tores ' T ab. Click on the '+' to add the test-org.pfx in
/home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/
Fill out the pas s word (1234) and click O k and clos e the Project View window.
Right click the 'public-lighting' project and choos e 'Add WSDL'. Enter the following URL in the WSDL Location field:
/home/dev/Sources/OSGP/Shared/osgp-ws-publiclighting/src/main/resources/PublicLightingAdHocManagem
Make s ure the box 'Create s ample reques ts for all operators ' is checked, and click O K.
Firs t SOAP reques ts to add a device to the open s mart g rid platform
Before s ending the reques t, the tes t-org.pfx s hould be added as SSL Keys tore: Go to the properties interface for the reques t
(bottom left of the s creen, after s electing 'Reques t 1' under UpdateKey in the 'admin' project'), and choos e test-org.pfx
from the drop-down box.
Note
T his has to be done for each reques t!
A SSLD needs to be added to the platform, as well as a manufacturer and a public key for the SSLD. A couple of s teps need
to be performed to realize this .
1 Add manufacturer 2 Add device model 3 Add SSLD 4 Setup a protocol for the SSLD to us e 5 Set the public key for the
SSLD (in cas e of O SLP)
T he AddManufacturer function adds a new manufacturer to O SGP. All devices are coupled to an manufacturer.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.alliande

<soapenv:Header>
<ns:ApplicationName>APPLICATION_NAME</ns:ApplicationName>
<ns:UserName>USER_NAME</ns:UserName>
<ns:OrganisationIdentification>test-org</ns:OrganisationIdentification>
</soapenv:Header>
<soapenv:Body>
<ns1:AddManufacturerRequest>
<ns1:Manufacturer>
<ns1:Name>Manufacturer01</ns1:Name>
<ns1:ManufacturerId>MAN</ns1:ManufacturerId>
<ns1:UsePrefix>false</ns1:UsePrefix>
</ns1:Manufacturer>
</ns1:AddManufacturerRequest>
</soapenv:Body>
</soapenv:Envelope>
T he AddDeviceModel function adds a new device model to O SGP. All devices are coupled to a device model.

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:AddDeviceModelRequest>
<ns1:DeviceModel>
<ns1:Manufacturer>MAN</ns1:Manufacturer>

<ns1:ModelCode>MOD01</ns1:ModelCode>

<ns1:Description>Device model MOD01.</ns1:Description>
<ns1:Metered>false</ns1:Metered>
</ns1:DeviceModel>
</ns1:AddDeviceModelRequest>
</soapenv:Body>
</soapenv:Envelope>
T he AddDevice function adds a new SSLD to O SGP. T he device is coupled to a device model and a manufacturer.

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:AddDeviceRequest>
<ns1:Device>
<ns1:DeviceIdentification>SSLD_000-00-01</ns1:DeviceIdentification>

<ns1:Owner>test-org</ns1:Owner>

<ns1:Activated>false</ns1:Activated>

<ns1:HasSchedule>false</ns1:HasSchedule>

<ns1:PublicKeyPresent>false</ns1:PublicKeyPresent>
<ns1:DeviceModel>

<ns1:Manufacturer>MAN</ns1:Manufacturer>

<ns1:ModelCode>MOD01</ns1:ModelCode>

<ns1:Description>Test device.</ns1:Description>

<ns1:Metered>false</ns1:Metered>
</ns1:DeviceModel>
</ns1:Device>
</ns1:AddDeviceRequest>
</soapenv:Body>
</soapenv:Envelope>
T he function UpdateDeviceProtocol s ets a protocol for a device.

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:UpdateDeviceProtocolRequest>
<ns1:ProtocolInfo>
<ns1:Id>1</ns1:Id>
<ns1:Protocol>OSLP</ns1:Protocol>
<ns1:ProtocolVersion>1.0</ns1:ProtocolVersion>
</ns1:ProtocolInfo>
</ns1:UpdateDeviceProtocolRequest>
</soapenv:Body>
</soapenv:Envelope>
T he UpdateKey function of the admin webs ervice s ets a public key for a device. Double click 'Reques t 1' under UpdateKey in
the 'admin' project. Add the following reques t:

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:UpdateKeyRequest>


<ns1:PublicKey>MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFhUImXFJdqmputquVAc2CPdnn9Ju00M3m/Ice7wABNN

<ns1:ProtocolInfoId>1</ns1:ProtocolInfoId>
</ns1:UpdateKeyRequest>
</soapenv:Body>
</soapenv:Envelope>
Click the 'play' button to s ubmit the reques t to the endpoint. You s hould receive s imilar res pons e as s hown in the s creens hot
below:
After the SSLD has been added, let's s ee if the function FindAllDevices s hows the SSLD. Continue with the FindAllDevices
reques t from the public-lighting project. Since this is not the s ame project, we have to change the endpoint; in this cas e in
https ://localhos t:443/os gp-adapter-ws -publiclighting/publiclighting/adHocManagementService/. Do not forget to s et the SSL
keys tore in the Reques t Properties . Us e the following parameters in the reques t:

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:FindAllDevicesRequest>

<ns1:Page>0</ns1:Page>
</ns1:FindAllDevicesRequest>
</soapenv:Body>
</soapenv:Envelope>
After the reques t has been s ubmitted, the res pons e s hould include the SSLD device with ID SSLD_000_00_01
Opening Device Simulator to Add a Device

In order to be able to us e the SSLD-000-00-01 Device, the device needs to be s imulated in the Device Simulator. T o do this
we have to create it. In the Firefox Brows er, open the Device Simulator by going to the following URL:
https://localhost/web-device-simulator/devices
If you encounter a Untrus ted Connection page, go to 'I Unders tand the Ris ks ' -> Add Exception.. -> Confirm Security
Exception
Click Add Device
Fill out the fields like this :
Device Identification: SSLD_000-00-01

IP Addres s : 127.0.0.1
Device T ype: SSLD
Protocol: O SLP
Click Create Device
You s hould return to the Devices s creen and s ee the mes s age "Device with identification SSLD_000-00-01 was created."
Reg is tering a Device

Now click on the newly created device and click the 'Regis ter Device' button. After a while the mes s age "Device identification
with identification SSLD_000-00-01 was regis tered at XXXXXXXX" appears .
T hen click the 'Confirm Regis tration' button. T he mes s age s hould read: "Device with identification SSLD_000-00-01 was
confirmed to be regis tered."
Us ing 'SetLig ht' SOAP Reques t to Switch the Lig ht On

Now that the Device is known in the platform, and s imulated in the Device-Simulator, the device can be us ed. Let's s witch on
the Light. Us ing SoapUI, click on Reques t 1 under SetLight at the public-lighting project. Set the following parameters in the
reques t (And do not forget to s et the Keys tore in the reques t properties ):

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SetLightRequest>

<ns1:LightValue>

<ns1:Index>0</ns1:Index>
<ns1:On>true</ns1:On>

<ns1:DimValue>100</ns1:DimValue>
</ns1:LightValue>
</ns1:SetLightRequest>
</soapenv:Body>
</soapenv:Envelope>
Submit the reques t. T ake note of the CorrelationUid in the res pons e. You can us e this Id in another reques t to as k the s erver
for the s tatus of this reques t.
In the home s creen of the O SLP device s imulator, the lightbulb s hould light up for SSLD_000-00-01. T his means that the
reques t s ucceeded.
T he las t reques t concerns the res pons e form the previous SetLight reques t. In SoapUi open Reques t 1 under
'GetSetLightRes pons e' in the 'public-lighting' project. Set the following parameters in the reques t (And the keys tore in the
reques t properties ). Make s ure to replace the CorrelationUid with the value from the res pons from the SetLight reques t.

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SetLightAsyncRequest>
<ns1:AsyncRequest>

<ns:CorrelationUid>test-org|||SSLD_000-00-01|||20160721083641940</ns:CorrelationUid
<ns:DeviceId>SSLD_000-00-01</ns:DeviceId>
</ns1:AsyncRequest>
</ns1:SetLightAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
Note
Do not forget to s et the CorrelationUid to value in the res pons e you received from the s etLight reques t.
T he s erver replied O k, indicicating that the SetLight reques t has been proces s ed s ucces fully.
T his s tep als o condcludes the ins tallation manual.
Using the Demo App

Tes ting the platform us ing the Web Demo
T his chapter will des cribe the s teps needed to tes t the O pen Smart Grid Platform us ing the Web Demo Application.
O pen Eclips e and import the following folder as as Maven project

/home/dev/Sources/OSGP/PublicLightingDemoApp/
Add the PublicLightingDemoApp components to the T omcat Server.
(Re)Start the T omcat Server.
Creating a device
T o acces s the Demo App go to the following URL: https://localhost/web-demo-app/
If you encounter a Untrus ted Connection page, go to 'I Unders tand the Ris ks ' -> Add Exception.. -> Confirm Security
Exception
Click the Add a Device button in the Menu bar, and enter SSLD_000-00-01 at the Device Identification field and pres s
Submit.
T he following s creen will appear, it s hows that the device has been s ucces fully added to the Platform.
Opening Device Simulator to Add a Device

In order to be able to us e the SSLD-000-00-01 Device, the device needs to be s imulated in the Device Simulator. T o do this
we have to create it. In the Firefox Brows er, open the Device Simulator by going to the following URL:
https://localhost/web-device-simulator/devices
Click Add Device
Fill out the fields like this :
Device Identification: SSLD_000-00-01

IP Addres s : 127.0.0.1
Device T ype: SSLD
Protocol: O SLP
Click Create Device
You s hould return to the Devices s creen and s ee the mes s age "Device with identification SSLD_000-00-01 was created."
Reg is tering a Device

Now click on the newly created device and click the 'Regis ter Device' button. After a while the mes s age "Device identification
with identification SSLD_000-00-01 was regis tered at XXXXXXXX" appears .
T hen click the 'Confirm Regis tration' button. T he mes s age s hould read: "Device with identification SSLD_000-00-01 was
confirmed to be regis tered."
Us ing 'SetLig ht' Switch the Lig ht On

Now that the Device is known in the platform, and s imulated in the Device-Simulator, the device can be us ed. Let's s witch on
the Light. Go to the Demo App and pres s the Lis t button in the Menu. A lis t s hould appear, s howing the device that has jus t
been added us ing the Add Device button.
Click on the Manage button to acces s the Device Details .
Switch on the Light by s etting the Light Value to 100 and by checking the 'LightO n' checkbox (as s hown in the s creens hot
below)
Hit s ubmit to s ubmit the reques t to the Platform. T he following s creen s hould appear:
In the home s creen of the O SLP device s imulator, the lightbulb s hould light up for SSLD_000-00-01. T his means that the
reques t s ucceeded.
T his s tep als o condcludes the ins tallation manual.
Configuration
Configuration
We have prepared a full s et of configuration (properties files , certificates , key s tore, ...) which is available in our Config
repos itory. T his configuration can be us ed to s etup a trial environment.
Configuration 98
Add a device
Add a device
Platform us es single device calls.
In order to add a device to the platform, call the add device method in the device ins tallation web s ervice (for a s pecific
domain) for each device.
Implementation may differ for different device types

Each device type may require its own s et of attributes , s ecurity s ettings , etc. Each device type may have its own regis tration
mechanis m.
T o add a DLMS Device to the Platform, take a look at the documentation of the Soap call AddDevice as defined in the
SmartMeteringIns tallation.ws dl.
T o add an O SLP Device to the Platform, the Soap call defined in DeviceIns tallation can be us ed, or the UpdateKey
Reques t.
Pleas e take a look at the chapter T es ting the open s mart grid platform in the ins tallation manual for a detailed guide of how to
add a O SLP device to the platform.
Additional Device actions

In the Domain Chapter of the documentation more information of the Web Service calls can be found for Adding devices ,
s etting configuration, authorizations , s chedules , firmware updates , etc.
Add a device 99
Users
Users
Soap Reques ts in the O pen Source Grid Platform have fields for an Us er name and an Application name in the Header. T hes e
are only us ed for logging and auditing. T here are no res trictions (e.g. Authorizations ) with regard to thes e fields . However, it
is recommended to us e names for Logging and Auditing purpos es .
Us ers 100
Add a new organisation

Adding an Org anis ation to the platform
T his chapter des cribes how to add a new O rganis ation to the platform. T his includes creating a certificate for the new
organis ation.
Creating an Org anis ation

In SoapUi go to DeviceManagement under the Admin project. Click on reques t 1 under CreateO rganis ation. Fill in the
parameters like the example reques t below. Make s ure to s ign the reques t with the tes t-org.pfx and to us e the tes t-org
organis ation in the reques t header.
T his reques t creates a new organis ation called "my-org":

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:CreateOrganisationRequest>
<ns1:Organisation>
<ns1:OrganisationIdentification>my-org</ns1:OrganisationIdentification>

<ns1:Name>my-org</ns1:Name>

<ns1:Prefix>MYO</ns1:Prefix>

<ns1:FunctionGroup>ADMIN</ns1:FunctionGroup>
<ns1:Enabled>true</ns1:Enabled>


<ns1:Domains>COMMON</ns1:Domains>
<ns1:Domains>PUBLIC_LIGHTING</ns1:Domains>
</ns1:Organisation>
</ns1:CreateOrganisationRequest>
</soapenv:Body>
</soapenv:Envelope>
Authoris e the new Org anis ation for the device

T o us e this new organis ation to control the SSLD_000-00-01 device, the authoris ations need to be updated. T o do that the
UpdateDeviceAuthoris ations reques t will be us ed, it can be found under DeviceManagement in the admin project.
Fill in the parameters like s hown below. T he functionGroup will be s et to AdHoc to authoris e the 'my-org' organis ation for
the AdHoc functions .
Make s ure to us e the tes t-org as O rganis ationIdentification in the reques t header, and to s ign the reques t with the tes t-
org.pfx.

<soapenv:Header>
<ns:ApplicationName>AAPLICATION_NAME</ns:ApplicationName>
</soapenv:Header>
<soapenv:Body>
<ns1:UpdateDeviceAuthorisationsRequest>

<ns1:DeviceAuthorisations>
<ns1:deviceIdentification>SSLD_000-00-01</ns1:deviceIdentification>
<ns1:organisationIdentification>my-org</ns1:organisationIdentification>

Add a new organis ation 101

</ns1:DeviceAuthorisations>
</ns1:UpdateDeviceAuthorisationsRequest>
</soapenv:Body>
</soapenv:Envelope>
Cre ating a ce rtificate for the ne w org anis ation
Now that the 'my-org' organis ation is authoris ed to us e the SSLD_000-00-01 device, it is time to create a certificate for the
my-org organis ation. T his certificate will be us ed to s ign the reques ts .
O pen a terminal and navigate to /home/dev/Sources/OSGP/Config/certificates/
A s cript has been created to create the certificates , execute it by running the following command in the terminal:
./create_client_cert.sh my-org 1234 1234
You s hould receive s imilar output as s hown in the s creens hot below.

Now that the certificate has been created, res tart the tomcat s erver.
Sig ning a reques t with the new certificate

When the tomcat s erver is up and running again, go to SoapUi and add the new certificate to the public-lighting project:
double-click on the project, go to the WS-Security Configurations tab and s elect the keys tores tab. Click the '+' button and
brows e to the my-org.pfx certificate which can be found in /home/dev/Sources/OSGP/Config/certificates/osgp-
ca/certs/

Now double-click on 'Reques t 1' in SetLight in PublicLightingAdHocManagement in the public-lighting project. Set the SSL
Keys tore to 'my-org.pfx' in the reques t properties s o the reques t gets s igned with the new certificate. Change the reques t
parameters as s hown in the example below:

<soapenv:Header>
<ns:OrganisationIdentification>my-org</ns:OrganisationIdentification>
</soapenv:Header>
<soapenv:Body>
<ns1:SetLightRequest>
<ns1:LightValue>


<ns1:DimValue>50</ns1:DimValue>
</ns1:LightValue>
</soapenv:Body>
</soapenv:Envelope>
Note the O rganis ationIdentification is now s et to 'my-org'. Send the new reques t, you s hould receive the following res pons e:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetLightAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocman
<ns2:AsyncResponse>
<ns3:CorrelationUid>my-org|||SSLD_000-00-01|||20160805150420802</ns3:CorrelationUid
<ns3:DeviceId>SSLD_000-00-01</ns3:DeviceId>
</ns2:AsyncResponse>
</ns2:SetLightAsyncResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Check the device-s imulator to s ee if the dimValue of the SSLD_000-00-01 changed to 50.
You now have s ucces s fully created a new organis ation, along with a certificate to s ign the reques ts , and changed the device
authoris ations of the device to accept commands from the new organis ation.


Web Services
Using the Open Smart Grid Platform Web Services
All the features of the open s mart grid platform are acces s ible by it's webs ervices , as defined in the WSDL files . T o us e
thes e s ervices to communicate with devices through the platform, pleas e keep in mind the following things .
A Soap reques t will have to be generated from your Application.

In the WSDL and xs d files of the Platform the Reques ts and it's objects are defined.
Fill in the parameters once you have an empty s oap reques t for a certain function. T he res trictions /requirements are
defined in the WSDL files .
T he reques t s hould have a header where an ApplicationName, Us erName and O rganis ationId are defined. At the
moment Us er and App name are not us ed in the Platform (Except for audability and logging). T he O rganis ationId,
however, mus t match a known organis ation within the Platform. T his organis ation mus t have the right authortities to
make a certain reques t.
Furthermore, the Reques t mus t be s igned with a certificate from the O rganization with the O rganis ationId in the
header.
T he reques ts us e the Secure HT T P protocol (https ).
For As ynchronious reques ts , the Platform will res pond with a correlationId after s ucces fully making the reques t. Us e
this correlationId in the matching Res pons e-Reques t to obtain the res pons e from the device.
T o learn more about the open s mart grid platform's webs ervices , pleas e take a look at the Domain Documentation or for
hands -on experience with the Platform's webs ervices follow the Us erGuide.
Res t
It is not pos s ible to communicate with the Platform directly us ing REST webs ervices . As mentioned above, the open s mart
grid platform us es SO AP (For reas ons defined here). If you want to us e REST for your front end, you can write an Integration
Layer that s erves as a Soap Client and expos es the Soap calls through Res t web s ervices that you can acces s from your front
end.
Flows
When us ing the SO AP Web s ervice, there are 2 flows that can occur:
s ome calls are s ynchronous : a res pons e is returned immediately;

other calls are a-s ynchronous : an initial res pons e contains a correlation id, which can be us ed to obtain the actual
res pons e.
Web Services 106

Deployment
Deployment options
Hos ting the open s mart grid platform in the cloud is pos s ible, as well as on premis es .
Active-active s etup over multiple datacenters

If you like to s etup an active-active ins tallation over multiple datacenters . Make s ure that the open s mart grid platform
databas e runs redundant over both datacenters (mas ter-s lave configuration).
Maintenance
T here's not much maintenance that needs to be performed. Archiving s ome old log files , checking up on available dis k s pace
and creating a backup of the databas es . Looking into the queues to s ee if there are no mes s ages in the dead letter queue.
Deployment 107
FAQ
FAQ
How to s tart e ve rything up ? Make s ure that Pos tgreSQ L is running. Make s ure that Apache HT T PD web s erver
and Apache ActiveMQ are running. T hen s tart Apache T omcat application s erver as des cribed in the ins tallation
manual.
Whe re are the log file s ? T he Apache T omcat application s erver logs can be found in /var/log/tomcat7. T he
Apache HT T PD web s erver logs can be found in /var/log/httpd. T he Pos tgreSQ L log files can be found in
/var/lib/pgsql/9.3/data/pg_log. T he platform log files can be found in /var/log/osp/logs/.
He lp : S ELinux is p re ve nting < s ome thing >? Make s ure to s et SELinux to 'permis s ive' mode. T hen try again and it
s hould work as SELinux will no longer enforce the current policy. Later, one can us e the SELinux tools to create a
proper policy that allows everything that was prevented before.
How to ad d or up d ate a comp one nt? Make s ure to place the properties file(s ) for the component in /etc/osp.
Add the locations of the properties file(s ) to Apache T omcat context.xml file. Add the war file to
/usr/share/tomcat7/webapps. Res tart Apache T omcat.
How to config ure a comp one nt? Mos t (if not all) components of the open s mart grid platform are de-coupled us ing
queues . Configure the broker URL in the properties file and take notice of the queues that a component us es /needs .
Make s ure to double check the connections tring for Pos tgreSQ L.
How to config ure URL's for a comp one nt? In this cas e the Apache HT T PD vhos t needs to be updated. T he vhos t
config file can be found in /etc/httpd/conf.d. We us e redirects from HT T P to HT T PS and AJP proxy to s end the
reques ts to Apache T omcat.
How to che ck up on Ap ache Active MQ? Apache ActiveMQ offers a web interface (the default port is 8161). Us ing
the web interface one can check the queues and es pecially the dead letter queue (DLQ ).
How d o I ob tain a p ub lic ke y for a d e vice ? Public Keys are us ually manufacterer s upplied for Smart Metering. For
the O pen Source part you can us e the O SLP device s imulator. In Sources/OSGP/Config/certificates/oslp/
you can find ins tructions for generating a O SLP device public key, and a folder with 5 pre-generated keys for tes t
devices .
My cod e g ive s a lot of e rrors in Eclip s e afte r imp orting T ry the following things : run mvn clean install in
the Shared, Platform and Adapter directories . Right-click on a project in Eclips e and s elect 'Maven -> Update
project..', s elect all projects and update.
T he Vag rant s crip t fails If you are receiving errors while downloading the ubuntu is o, s ources , etc. or if the puppet
s cript does not s tart; try running the Vagrant s cript again by typing vagrant destroy && vagrant up in the
directory with the vagrant file.
I want to up d ate my cod e from Github If you want to update your code, jus t run git pull in the repos itory you
want to update. You can als o create a fres h Virtual Machine us ing the vagrant ins tallation, this procedure makes s ure
you have the mos t recent code.
Is a us e r re q uire d to cons ume p latform s e rvice s ? No, an organization is required.
_If your ques tion is not in this lis t, pleas e create an [is s ue on Github in the documentation repos itory ]documentation
repos itory
FAQ 108
Open Source Community

CHAPTER 3. Open Source and Community
We invite everyone to participate in the development of the open s mart grid platform. T here are multiple ways to s upport the
project.
s ubmit is s ues about bugs or reques ted features

s olve is s ues
develop new features
write or improve the documentation
T his chapter contains all the non-technical and general technical knowledge for developers to s tart contributing.
O pen Source Community 109

Start contributing
T his is a guide to s tart contributing to the open s mart grid platform project:
1. Make yours elf comfortable with the open s mart grid platform by e.g. ins talling it.
2. Read the documentation to get an idea of how the s oftware works (architecture chapter), how the community works
(this chapter).
3. Find an open is s ue to work on or fire an new is s ue.
4. As s ign yours elf to the is s ue and s tart contributing.
5. Start contributing by us ing the procedures mentioned in this chapter.
Start contributing 110

Developers 101
Developer tools, technical guidelines and continuous integration
Tools Used
T he technology and tools us ed can be found in the T echnology s tack s ection.
Code Guidelines and Code Tests

Us e the code formatting rules for Eclips e
Us e the s ave actions for Eclips e
Follow GitFlow approach for branching
Write behaviour driven tes ts us ing Cucumber and Gherkin, s ee the Integration-T es ts repo
In cas e you are not familiar with behaviour driven tes ts , include unit tes ts
Fix SonarQ ube is s ues
Is s ue pull reques t (preferable to development branch)
Continuous Integration
All changes pus hed to GitHub are built by our build s erver. Pull reques ts to mas ter branch or development branch are als o
built. SonarQ ube performs s tatic code analys is to help improve the quality level of the code bas e.
Jenkins builds erver: An open s ource continuous integration tool written in Java.
SonarQ ube: SonarQ ube is an open platform to manage code quality.
Technical Conventions and Rules for New Code

T his project is engineered, built and tes ted us ing Domain Driven Des ign and Behaviour Driven T es ts .
Us e the Frameworks , don't roll your own

Single clas s , s ingle res pons ibility
Value objects are immutable
Map generated objects to value objects or entities
T rans ferring an object means us ing a DT O
Us e bas e clas s es for common logic
Interfaces are good, but 'impl' is bad
Extend clas s es , don't expand clas s es
Migrate databas es us ing Flyway
JMS for mes s aging
Extend the authorization logic if needed, don't bypas s it
Log errors /exceptions
Add meaningful comments to the code
Follow the code guidelines
Development Guide per Component

Web Service Adapters
T he web s ervice adapters us e Spring Web Service, contract firs t. JAXB is us ed to generate Java clas s es from the XSD's . All
SO AP operations are bound to an endpoint. T he incoming SO AP reques ts are authenticated by organization identification
(plus certificates ). O rganization authorizations are checked for the des ired operation. If the reques t is O K, a JMS mes s age is
s ent to a domain adapter component.
Domain Adapters
Domain adapters contain bus ines s logic and pers is tence. Domain adapters proces s and forward the JMS mes s age to the
Core component.
Domain Components
Domain components contain entities and value objects .
Core
T he Core component routes mes s ages from domain adapter components to protocol adapter components and vice vers a.
Furthermore, it offers read-only databas e acces s for protocol adapter components .
Developers 101 111

Protocol Adapters
Protocol Adapter components trans late a mes s age from domain adapter components into a protocol mes s age for a s mart
device. Protocol Adapter components s end the protocol mes s age to a s mart device us ing a network connection. T he
res pons e from the s mart device is trans lated into a domain res pons e mes s age which will be s ent to the Core components
(which will route it to the domain adapter which is s ued the reques t).
OS LP
For the O SLP implementation, two components are us ed. T he firs t component is the protocol adapter for the protocol. It can
trans late mes s age into the protocol mes s age for SSLD's . Second there's the s igning-s erver component. It is res pons ible for
s igning the protocol mes s age us ing the private key of the platform. T he components communicate us ing a key-pair. T he
s igning-s erver can handle multiple protocol adapter ins tances by utilizing a reply-to queue per protocol adapter ins tance.
Since the protocol adapter component needs to be reachable from a network, it is a requirement that the private key may not
be us ed by the protocol adapter directly. T he s igning s erver component can be deployed in s uch a way that no network
acces s is available to this component, as the only coupling needed are the queues / the mes s age broker.
Other Guides
Ins tallation Guide
If a full ins tallation is des ired, have a look at our Ins tallation Guide.
Create New Domain Guide

In order to add a new domain to O SGP, you can benefit from the information in the Create New Domain Guide.
Developers 101 112

Contributing to the code

Contributing to the code
T hank you for contributing to the O pen Smart Grid Platform. Pleas e keep the following in mind before s ubmitting code.
Guidelines
Before code is merged it needs to comply with a number of guidelines :
1. Code s hould be as complete as pos s ible (preferably no placeholders , T O DO 's or FIXME's )

2. Right formatting; code s hould follow the Coding Conventions (s ee 3.1.2)
3. Fixed/added unit tes ts where applicable
4. Javadocs added where applicable
5. Accepting pull-reques ts with SonarQ ube reports "Blocker" and "Critical" are not allowed
6. Comply with International open s tandards where pos s ible (e.g. IEC s tandards )
Contributor Licens e Ag reement

We as k each of our contributors to s ign our contributor licens e agreement (CLA). T his has advantages for both parties , it
gives you the as s urance that your contribution will remain available under the Apache 2.0 licens e. Meanwhile, you give your
code in licens e to us , s o we can add your code to the open s mart grid platform. And we know your contribution is entirely
your work, s o we don't get in trouble with legal is s ues . Pleas e read the CLA text carefully.
Submitting code
T o s ubmit changes to the open s mart grid platform branches :
1. Create a fork of the open s mart grid platform repo you will be working in
2. Make and commit your changes to your fork
3. Create a pull reques t to merge the changes into the right branch (s ee 4.1.4 for the branching s trategy) If the changes
fix a bug, mention the is s ue number in the commit mes s age or pull reques t mes s age (example: fixes 101, s olved 87). If
no ticket exis ts , create one beforehand. Afterwards , pleas e update the relevant documentation in this GitBook.
Open Source Branching Strateg y

T he open s mart grid platform's main branch is mas ter. All major releas es are tagged in this branch. Development is done in
the development and feature branches . We us e the GitFlow branching s trategy. Find more information on this s trategy here:
GitFlow
T he GitFlow workflow is s omeone complicated, but it has the advantage that it gives a clear overview of all previous
releas es and current development and thus helps to collaborate more efficiently. Pleas e follow this s trategy in your commits .
Pull reques ts : review proces s

Anyone can s end in a pull reques t. As s ign a maintainer or other developer with knowledge on this topic to accept/evaluate
your pull reques t. You can view the SonarCube tes t res ults at (http://ci.opens martgridplatform.org/s onarqube/) and the
Jenkins continuous integration res ults at (http://ci.opens martgridplatform.org)
If your code is a us eful contribution and meets our quality s tandards (s ee s ection 3.1), it will be added to the open s mart grid
platform! Developers are in charge of judging this . Don't forget to update the documentation as well.
Contributing to the code 113

Contributing to documentation
Documentation Publication
T his documentation is available in multiple formats .
Web
Development branch publication

Mas ter branch publication
Lates t Pull-reques t publication
PDF
Development branch publication in PDF
Contributing to documentation
T he documentation is build us ing GitBook s oftware from Markdown files in the documentation repos itory.
We encourage you to participate in improving the documentation. From corrected typos to new s ections , every commit is
appreciated. You can acces s the s ource files by clicking the "Fix this page"-button in the GitBook or by s electing the relevant
Markdown-file in the documentation. You can commit your changes by s ending a pull reques t.
1. Fork the repo, do work in a feature branch.
2. Is s ue a pull reques t.
3. Make s ure the automated tes t s uite s ucceeds . T hey will s how-up in the pull reques t.
4. Sign the CLA us ing cla-as s is tant (a comment by CLAAdmin will appear for your pull reques t to help you out).
5. As s ign a maintainer or other developer on this topic to accept/evaluate your pull reques t. T he current maintainer can
be found in the governance paragraph.
Some information on GitBook and us ing Markdown can be found here, more elaborate information on GitHub-flavored
Markdown is found here. If you like to upload illus tration, you can us e git or Github
If you are completely new to this and you need help to get s tarted, file an is s ue in the documentation repos itory.
Chapters in the documentation

It may be obvious to you already from the index, however, here is an overview on what documentation goes in which chapter.
Chapter 1 cons is t of an open s mart grid platform introduction and architecture for potential us ers , architects and
developers . T he open s mart grid platform webs ite is us ed for bas ic product information.
Chapter 2 contains the general us erguide for open s mart grid platform us ers
Chapter 3 contains community related topics
Chapter 4 contains information related to the open s mart grid platform domains
Chapter 5 contains information related to the protocols and s imulators
Chapter 6 s hows the s upport options
Chapter 7 code and documentation licens e
Vers ioning within the documentation

We have chos en to work with GitBook s ince it allows us to make different vers ions of documentation for each releas e. T his is
done by branching the files in the documentation repos itory. T he mas ter branch is us ed for releas es only. T he development
branch is our main and current branch. If you like to improve the documentation, s tart a feature branch with your changes and
s end a pull reques t to the development branch.
Guidelines for new documentation

T he mas ter branch is only us ed by major open s mart grid platform releas es
Don't commit directly to the development branch, pleas e do a pull reques t.
We us e the American s pelling
Pleas e follow the us ed chapter and s ection numbering and apply it in your commits as well
Currently we do not us e image numbering, s ince it is too much of a has s le to keep it up-to-date. If you have a s mart
idea to do this , let us know!
Give your (s ub) document a relevant name or s ection with number
Update SUMMARY.md if needed
Documentation ins piration
Contributing to documentation 114

Ins piration on how to write good documentation can be found here: http://docs .writethedocs .org/.
Contributing to documentation 115

Communication and Contact

Communication and Contact
We choos e Jira for mos t of our development communication. T his keeps the communication central and topic central and
connect to development effort. Pleas e us e Jira for is s ues and bugs .
If you want to get in touch to dis cus s to dis cus s non-technical s ubjects , s end us an email info@opens martgridplatform.org or
open an is s ue on Github. O nce we get the foundation going, we will open an addres s s o you can directly contact one of the
foundation's employees .
Jira
Jira was chos en due to its extens ive features . T he current Jira board is s pons ored by Smart Society Services for s ynergy
reas ons . O nce we have multiple contributors outs ide Smart Society Services we can move to a dedicated Jira ins tance or
s omething els e.
O nce you get actively involved, you can reques t write permis s ions on the Jira board. You can reques t write acces s to the Jira
is s ue board by s ending a reques t to opens ource@s marts ocietys ervices .com (Marcel checks this mailbox for Jira reques ts ).
New Features
1. If there is a need (or wis h!) for a new feature, add it as is s ue to Jira as a us er s tory. Pleas e provide a full des cription
about the background of the problem. Spilt-up big us er s tories in multiple s mall us er s tories .
2. A developer can take on the is s ue and s tart working on it on voluntary bas e. If you need this feature and you have the
money to pay for it, you can hire a developer and have the developer work on it. If open s mart grid platform core
components are involved, pleas e dis cus s your change firs t with one of the developers /maintainers .
3. T he developer makes a des cription on how he wants to fix the problem. O ther developers can dis cus s the s olution as
well. If everybody agrees on the s olution direction, the developer codes the s olution and s ubmits it (by s ending in a
pull reques t). T he developer s hould als o document the feature in the GitBook
4. T he maintainer can check the code (or as s ign this to s omeone els e) and merge it with ups tream releas es .
Bug tracking
1. Find out as much as pos s ible about the bug before reporting it. Pleas e check on GitHub/Jira whether the bug has
already been reported. Als o, look for logs , error mes s ages etc. Pleas e include as much information as pos s ible
background on the bug and s ubmit the bug on Github or Jira.
2. T he maintainer makes s ure that s omebody will look at the bug, check for duplicates and thank the contributor for
s ending in the bug. If the bug turns out to be a duplicate, the is s ue will be clos ed.
3. A developer will try to reproduce the bug and will look for the root caus e. T he developer adds his findings to the
is s ue. If the developer cannot reproduce the bug, the developer will contact the us er for more information or/and
login into the us er's s ys tem (when pos s ible for the us er/developer). If it's impos s ible to re-produce the bug, the is s ue
will be clos ed.
4. O therwis e, the developer will write a patch and tes ts the fix.
5. O nce the patch is accepted (s ee Code review/tes t proces s ), it will be s hipped with the next releas e.
6. T he maintainer than clos es the is s ue.
Ques tions
If you have a ques tion, pleas e create an Github is s ue in the documentation repos itory or reques t acces s to Jira.
Report s ecurity is s ues

Due to the s ens ible nature of s ecurity is s ues e.g. zero days , we prefer a res pons ible dis clos ure. Security is s ues can be
reported on the opens martgridplatform.org webs ite.
Communication and Contact 116

Governance
Governance
With the open s mart grid platform we intend to have the right balance between a benevolent Dictator and a Formal
Meritocracy in order to have a balanced decis ion-making proces s and to prevent unwanted dictators and everlas ting
dis cus s ions . T he bas ic principle is that decis ions are bas ed on cons ens us . If this decis ion making proces s takes too long or
a decis ion is required, the community council has the authority to make a decis ion.
T he governance and rules s hould be res pected.
Community council
T he community council cons is ts of 5 members and has the authority to make decis ions on all community related s ubjects .
T he community council is res pons ible for:
General ambitions , objectives and goals

Principles and unders tandings
Governance and cons ultation bodies
Guidelines and procedures and tool s election
Contribution (proces s ) of individual members
Architectural and (development) infras tructure choices
Rais e s ubjects /is s ues that are important for the direction/development of the community
When the community grows , members of the community council can be elected. If the s ituation demands or requires it, the
community council has the ability to es tablis h s ub councils for a s pecific s ubject, area of domain. O ne member (s eat)
repres ents the O pen Smart Grid Platform Foundation (once s tarted) for alignment between the objectives of the foundation
and the direction of the development of the online community.
T he community council cons is t of the following members :
Sander Jans en - O pen s ource cons ultant - Chairman

Paul Houtman - Lead Architect
Kevin Smeets - Maintainer
Vacancy
Vacancy - O pen Smart Grid Platform foundation s eat
If you would like to join the community council, pleas e contact us ! Mention @O SGP/communitycouncil in an github is s ue. T he
(online) community council meetings will happen when needed.
Maintainers
Maintainers are res pons ible for maintaining parts of the code-bas e. Maintainers have the following res pons ibilities
Coordinate development activity

Make s ure code/documentation reviews are being done
Coordinate pull-reques ts
Coordinate bug follow-ups
Coordinate ques tions
In cas e of long dis cus s ions or arguments , maintainers or other can reques t a community council decis ion.
Current maintainers :
O pen s mart grid platform and s mart lighting domain: Kevin Smeets
Smart metering domain: Bart van der Zwet
Documentation & configuration: Ruud Lemmers
@Sander3003 will track new Github is s ues and as s ign them to maintainers and inform them (via a Jira ticket).
Governance 117
Code of Conduct
Code of Conduct
Like the technical community as a whole, the open s mart grid platform community is made up of a mixture of profes s ionals
and volunteers from all over the world, working on every as pect of the mis s ion - including mentor-s hip, teaching, and
connecting people.
Divers ity is one of our huge s trengths , but it can als o lead to communication is s ues and unhappines s . T o that end, we have a
few ground rules that we as k people to adhere to. T his code applies equally to founders , mentors and thos e s eeking help and
guidance.
T his is n’t an exhaus tive lis t of things that you can’t do. Rather, take it in the s pirit in which it’s intended - a guide to make it
eas ier to enrich all of us and the technical communities in which we participate.
T his code of conduct applies to all s paces managed by the open s mart grid platform project (or O pen Smart Grid Platform
Software Foundation once es tablis hed). T his includes IRC, the mailing lis ts , the is s ue tracker, DSF events , and any other
forums created by the project team which the community us es for communication. In addition, violations of this code outs ide
thes e s paces may affect a pers on's ability to participate within them.
If you believe s omeone is violating the code of conduct, we as k that you report it by emailing
info@opens martgridplatform.org.
Be frie nd ly and p atie nt.
Be we lcoming .
We s trive to be a community that welcomes and s upports people of all backgrounds and identities . T his includes , but is not
limited to members of any race, ethnicity, culture, national origin, color, immigration s tatus , s ocial and economic clas s ,
educational level, s ex, s exual orientation, gender identity and expres s ion, age, s ize, family s tatus , political belief, religion, and
mental and phys ical ability.
Be cons id e rate .
Your work will be us ed by other people, and you in turn will depend on the work of others . Any decis ion you take will affect
us ers and colleagues , and you s hould take thos e cons equences into account when making decis ions . Remember that we're a
world-wide community, s o you might not be communicating in s omeone els e's primary language.
Be re s p e ctful.
Not all of us will agree all the time, but dis agreement is no excus e for poor behavior and poor manners . We might all
experience s ome frus tration now and then, but we cannot allow that frus tration to turn into a pers onal attack. It’s important
to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the open
s mart grid platform community s hould be res pectful when dealing with other members as well as with people outs ide the
open s mart grid platform community.
Be care ful in the word s that you choos e .
We are a community of profes s ionals , and we conduct ours elves profes s ionally. Be kind to others . Do not ins ult or put down
other participants . Haras s ment and other exclus ionary behavior aren't acceptable. T his includes , but is not limited to:
Violent threats or language directed agains t another pers on.

Dis criminatory jokes and language.
Pos ting s exually explicit or violent material.
Pos ting (or threatening to pos t) other people's pers onally identifying information ("doxing").
Pers onal ins ults , es pecially thos e us ing racis t or s exis t terms .
Unwelcome s exual attention.
Advocating for, or encouraging, any of the above behavior.
Repeated haras s ment of others . In general, if s omeone as ks you to s top, then s top.
Whe n we d is ag re e , try to und e rs tand why.
Dis agreements , both s ocial and technical, happen when people get pas s ionate about what they are doing. It is important that
we res olve dis agreements and differing views cons tructively. Remember that we’re different. T he s trength of open s mart
grid platform comes from its varied community, people from a wide range of backgrounds . Different people have different
pers pectives on is s ues . Being unable to unders tand why s omeone holds a viewpoint does n’t mean that they’re wrong. Don’t
forget that it is human to err and blaming each other does n’t get us anywhere. Ins tead, focus on helping to res olve is s ues and
learning from mis takes .
This Code of Conduct is based on the Django Code of Conduct
Code of Conduct 118

Foundation
Foundation
T he Foundation will be an independent organis ation to s upport and promote the open s mart grid platform development (the
foundation is not s tarted yet). T he foundation will be s imilar to the Linux foundation or Apache foundation. T he Foundation
will s tart once we have multiple founding members . If you like to s upport the Foundation, contact us :
info@opens martgridplatform.org. T his foundation will promote and facilitate the us e of and future development of the O pen
Smart Grid Platform. In addition, the Foundation will s upport the community of developers and us ers of the O pen Smart Grid
Platform to accelerate future development and to develop a larger us er bas e of the platform. T his foundation will encourage
the development of the ecos ys tem.
T he foundation will be non-profit. O ur aim is that companies / organizations can make a s pons ors hip contribution to the
foundation, in order to s upport the us e and development of the open s ource platform.
Planned key activities of the foundation are:
Maintaining and developing the O pen Smart Grid Platform via a publicly acces s ible s ource with an open s ource
initiative recognized licens e (Apache 2.0).
Providing information (manuals , publications , releas e notes , white papers , etc.)
T aking care of legal conditions
Community management, events for us ers and developers
Marketing and promotion of the s oftware
Foundation 119
Domains
Chapter 4 Domain T his chapter des cribes the s eparate domain in the open s mart grid platform.
Web Service Adapters

T he web s ervice adapters us e Spring Web Service, contract firs t. JAXB is us ed to generate Java clas s es from the XSD's . All
SO AP operations are bound to an endpoint. T he incoming SO AP reques ts are authenticated by organization identification
(plus certificates ). O rganization authorizations are checked for the des ired operation. If the reques t is O K, a JMS mes s age is
s ent to a domain adapter component.
Domain Adapters
Domain adapters contain bus ines s logic and pers is tence. Domain adapters proces s and forward the JMS mes s age to the
Core component.
Domain Components
Domain components contain entities and value objects .
Domains 120
Admin
The open smart grid platform core and admin functions for device management.
Scope
T his core and admin domain contains all generic web s ervices that can be us ed in other domains . Mos t generic s ervices
relate to device management including powerful device authorization management
Common webs ervices
Op e ration Re q ue s t Re s p ons e
De vice Ins tallation.ws d l
AddDevice DeviceIdentification -
FindDevices WhichHaveNoO wner - Devices
FindRecentDevices - Devices
StartDeviceT es t DeviceIdentification -
StopDeviceT es t DeviceIdentification -
UpdateDevice DeviceIdentification -
GetStatus DeviceIdentification Status
De vice Manag e me nt.ws d l
ChangeO rganis ation O rganis ation -
CreateO rganis ation O rganis ation -
FindAllO rganis ations - O rganis ations
FindDeviceAuthoris ations DeviceIdentification DeviceAuthoris ations
FindDevices PageSize, Page Devices , Page
FindEvents DeviceIdentification, From, Until, PageSize, Page Events , Page
FindMes s ageLogs DeviceIdentification, Page Mes s ageLogPage
RemoveDevice DeviceIdentification -
RemoveO rganis ation O rganis ation
SetEventNotifications DeviceIdentification, EventNotifications -
SetO wner DeviceIdentification, O rganis ationIdentification -
UpdateDeviceAuthoris ations DeviceAuthoris ations -
ActivateO rganis ation O rganis ation -
SetDeviceLifecycleStatus DeviceIdentification, DeviceLifecycleStatus -
Firmware Manag e me nt.ws d l
GetFirmwareVers ion DeviceIdentification FirmwareVers ion
UpdateFirmware DeviceIdentification, FirmwareIdentification -
Config urationManag e me nt.ws d l
GetConfiguration DeviceIdentification Configuration
SetConfiguration DeviceIdentification, Configuration -
S che d ule Manag e me nt.ws d l
SetSchedule DeviceIdentification, Schedules , Page -
SetT ariffSchedule DeviceIdentification, Schedules , Page -
Ad HocManag e me nt.ws d l
SetReboot DeviceIdentification -
Core WSDL's
Core XSD s chema's
Admin webs ervices

Admin WSDL's
Admin XSD s chema's
Admin 121
Smart lighting
This domain covers the use of the open smart grid platform for smart lighting.
Scope
T he goal of this domain is to control, monitor and manage (s treet) lights at s cale. It allows s treetlight owners to
control/manage the (s treet) lights in an more intelligent way compared to ripple control technology.
Features
T his domain cons is t of Switching s chedules , groups , light s ens ors , manual s witching and monitoring of a typical public
lighting us e-cas e.
PublicLighting webservices
De vice Monitoring .ws d l
GetActualPowerUs age DeviceIdentification PowerUs ageData
DeviceIdentification, T imePeriod,
GetPowerUs ageHis tory PowerUs ageData, PageInfo
His toryT ermT ype, Page
Pub licLig hting Ad HocManag e me nt
DeviceIdentification,
SetT rans ition -
T rans itionT ype, T ime
FindAllDevices Page DevicePage
LightValues , PreferredLinkT ype,
GetStatus DeviceIdentification
ActualLinkT ype, LightT ype, EventNotifications
DeviceIdentification, Index,
Res umeSchedule -
Is Immediate
SetLight DeviceIdentification, LightValue -
Pub licLig hting S che d ule Manag e me nt
DeviceIdentification, Schedules ,
SetSchedule -
Page
PublicLighting WSDL's
PublicLighting XSD s chema's
Smart lighting 122

Use cases
Example use-case for this domain
Up-to-date information on us e-cas es can be found on the open s mart grid platform webs ite.
Re fe re nce imp le me ntation in T he Ne the rland s : Fle xib le s ys te m for op e rating p ub lic lig hting (Fle xOVL)
FlexO VL, a new and flexible s witching s ys tem of public lighting delivers more control for municipalities and is the firs t
s olution which is powered by the O pen Smart Grid Platform.
T e chnical d rive rs for Alliand e r
Replacing Ripple Control

Decreas e future inves tments
Decreas e outages
Cus tome r d rive rs (Municip alitie s )
Be more in control, by controlling s witching times thems elves

Res olve power failures fas ter, through up-to-date information
Reduction in cos ts , through energy s aving and more efficient maintenance and management
No vendor lock-in, not dependent on one s upplier
Imp le me ntation/roll-out
Small s cale roll-out s tarted January 2015

200 Sub Stations will be fitted with an SSLD to control public lighting and tariff s witching
15 municipalities in the Liander grid operator area will be participating
Goal is to allow municipalities to us e the application, give feedback and to s ee if the s ervices offered to municipalities
are adequate
Large s cale roll-out will s tart around 2016

T he entire Liander grid operator area will us e SSLD's to control all public lighting and tariff s witching
About 25.000 Sub Stations (middens pannings ruimtes )
About 800.000 s treet lights will be s witched by the SSLD's mounted in the 25.000 Sub Stations
Fle xOVL we b ap p lication (not op e n s ource availab le )
Municipalities are free to choos e their own (web)application (us ing the web s ervices of the O pen Smart Grid Platform), or
they could us e the default web application developed by Smart Society Services .
Us e cas es 123
Functionality of the d e fault we b ap p lication as us e d b y g rid op e rator Liand e r (e xamp le )
Create s witching s chedules and as s ign thos e s chedules to one or more SSLD's
Create groups of SSLD's in order to be able to as s ign s chedules to many SSLD's at once
O n demand s witching of public lighting
Review current s tatus of an SSLD in order to review public lighting and tariff s witching s tates
Abilities to monitor power cons umption of public lighting (available if the SSLD is fitted with an Electricity Meter)
Monthly report offering ins ight into s witch moments and power cons umption
Us e cas es 124
Tariff switching
Tariff switching
T his covers the s ervices for tariff s witching domain us ing the open s mart grid platform.
Scope
T his domain allows tariff s witching. It allows a relay to s witch when a tariff changes . T his domain could be us ed to replace
ripple control tariff s ignals .
Webs ervices
T ariffS witching Ad HocManag e me nt
GetDevices
GetStatus DeviceIdentification Status
T ariffS witching S che d ule Manag e me nt
SetSchedule DeviceIdentification, Schedules , Page -
T ariff s witching WSDL's

T ariff s witching XSD s chema's
T ariff s witching 125

Microgrids
Microgrids documentation
T he O pen Smart Grid Platform act as an central component to monitor and control microgrids .
Scope
T he goal of this domain is to control and monitor microgrids .
Features
Currently, the following features are available within the O pen Smart Grid Platform:
Ge t Data
Get data is us ed to retrieve meas urement and profile data from the device
S e t Data
Set data is us ed to s et s etpoints and profiles on the device
Notifications
When either report data or the res ult for a reques t is available, a notification is s ent to a client, after which the client will be
able to obtain the data or res ult by s ending an 'as ync' mes s age.
Re p orting
When a device is connected it will periodically pus h meas urement reports (and s end trigger-bas ed s tatus reports ) to O SGP.
O SGP will inform the client via a notification, after which the data can be retrieved in a way s imilar to GetData (us ing the
GetDataAs ync mes s age). In order to determine whether all report data are received, the res pons e of a GetDataAs ync
mes s age will (in cas e of a report) contain report metadata cons is ting of a report id, s equence number and time of entry.(XSD
is already updated with report metadata, returning the report metadata from O SGP is not yet implemented)
Mes s ag es
Ge tData is a reques t to retrieve meas urement and profile data from a device.
Ge tDataAs ync is a reques t to retrieve the res ult of the GetData reques t or to retrieve report data pus hed by the
device.
S e tData is a reques t to s et s etpoints and profiles on a device.
S e tDataAs ync is a reques t to retrieve the res ult of the SetData reques t.
WSDLs
WSDL's and s chema's
Cucumber tes t
Functionality like Ge tData can now be tes ted, with the Cucumber framework, us ing the p rotocol-s imulator-ie c61850. T his
s imulator can be s tarted from the Cucumber tes ts , and is configured with its own properties file.
Multiple Server names

By default the RT U device is configured with the s ervername: WAGO61850S e rve r. T his name als o appears in the icd file,
that is us ed by the RT U device. T he name of this icd file, is configured in a properties file. Multiple s erver names are now
s upported, with the introduction of the new column: s e rve r_name in the ie c61850_d e vice table. If this value is null, the
default s ervername (WAGO 61850Server) is us ed, otherwis e the s ervername from the databas e is us ed (eg 'WAGO 123'). In
that cas e another corres ponding icd file, in which this s ervername is us ed, mus t be configured!
Microgrids 126
Distribution automation
Distribution Automation
T he O pen Smart Grid Platform can als o be us ed in the monitoring of a variety of components in s ubs tations ; RT Us , s witches ,
trans formers , etc. O ften, an RT U or Remote T erminal Unit is us ed as a central information hub in a s ubs tation. T he RT U is
connected to one or more s ens ors or devices that can meas ure any kind of information. Us ually, the focus is on meas uring
power quality values , temperature and other 'health' variables , but any kind of meas urable data can be read through O SGP.
Scope
T he goal of this domain is to control and monitor s ubs tations ; the current focus is on health s tatus information and power
quality data, but this may be extended in the future.
Features
Currently, the following features are available within the O pen Smart Grid Platform us ing the IEC 61850 protocol;
Ge t PQ Value s
Get PQ Values retrieves the actual, current PQ values from a device. Examples of PQ values are Current, Voltage, Reactive
Power, Active Power, etc. T hes e examples merely s erve as an indication of what is pos s ible; O SGP does not impos e any
res triction on the number or content of variables that can be read. T he outline of what s hould be meas ured is configured on
the device and in the application that reads the data.
Ge t He alth S tatus
Retrieves the current health s tatus of a device. T his is us eful in a monitoring application.
Ge t De vice Mod e l
Retrieves the device model or metadata of a device. T his includes the variables that can be meas ured, the information
s tructure of the device, etc.
Notifications
When either report data or the res ult for a reques t is available, a notification is s ent to a client, after which the client will be
able to obtain the data or res ult by s ending an 'as ync' mes s age. A notification mes s age always contains the correlation ID of
the original reques t; the client can retrieve the res ult us ing this correlation ID.
Mes s ag es
Ge tPQValue s is a reques t to retrieve PQ values from a device.
Ge tPQValue s As ync is a reques t to retrieve the res ult of the GetPQ Values reques t or to retrieve report data pus hed
by the device.
Ge tHe althS tatus is a reques t to retrieve the health s tatus of a device.
Ge tHe althS tatus As ync is a reques t to retrieve the res ult of a GetHealthStatus reques t.
Ge tDe vice Mod e l is a reques t to retrieve the device model from a device
Ge tDe vice Mod e lAs ync is a reques t to retrieve the res ult of a GetDeviceModel reques t.
WSDLs
WSDL's and s chema's
Dis tribution automation 127

SmartMetering
SmartMetering Documentation (Beta version)
T his chapter des cribes the SmartMetering domain including the web s ervices . Currently the web s ervices of the beta vers ion
are des cribed, s ince the web s ervices have not yet officially been releas ed. Information on the DLMS device s imulator can be
found in the DLMS protocol s ection
Scope
T he goal of this domain is to read and manage millions of s mart meters . T his includes s mart meter ins tallation, firmware
updates , s mart meter removal, read s mart meter values , time s ynchronis ation, etc. Everything that is needed to profes s ionally
manage millions of s mart meters is or can be included in this domain.
Features
Currently, the following Smart Metering features are available within the open s mart grid platform:
Add s mart meter to the platform, s o the device is known and additional actions can be performed for the device
Proces s s hipment file, which adds s everal s mart meters to the platform along with all needed information
Synchronize time between s mart meters and head-end s ys tem, in cas e the s mart meter adjus ts its time, s ome events
will be logged
Retrieve events from the s mart meter, s everal event logs are available
Retrieve periodic meter reads from the s mart meter
Generic functionality
b yp as s re try reques ts can be given the flag 'bypas s retry'. Which means that a reques t will not be retried in cas e of
an error.
p riority reques ts can be given a priority from 0 to 9, default is 4. Higher values caus es mes s ages to be proces s ed
fas ter.
s che d uling reques ts can be s cheduled for a certain time.
b und ling reques ts can be combined in a Bundle.
Mes s ag es
S martMe te ring Ad Hoc
S ynchroniz e T ime is a reques t to s ynchronize the date and time on a device. T he date and time are retrieved from
the s erver and s ent to the device.
Ge tS ynchroniz e T ime Re s p ons e is a reques t which returns the res pons e from the SynchronizeT ime reques t.
Re trie ve AllAttrib ute Value s is a reques t to obtain all the attributes of the whole tree of objects from an E-meter.
Ge tRe trie ve AllAttrib ute Value s Re s p ons e is a reques t which returns the res pons e from the
RetrieveAllAttributeValues reques t.
Ge tS p e cificAttrib ute Value is a reques t to obtain a s pecific attribute value from an O bis Code from an E-meter.
Ge tS p e cificAttrib ute Value Re s p ons e is a reques t which returns the res pons e from the GetSpecificAttributeValue
reques t.
Ge tAs s ociationLnOb je cts is a reques t to get the as s ociated ln objects .
Ge tGe tAs s ociationLnOb je cts Re s p ons e is a reques t which gets the res pons e from the GetAs s ociationLnO bjects
reques t.
S martMe te ring Config uration
S e tS p e cialDays is a reques t to s et a dayId profile and its tariffs for a s pecific date on a device.
Ge tS e tS p e cialDays Re s p ons e is a reques t which returns the res pons e from the SetSpecialDays reques t.
S e tConfig urationOb je ct is a reques t to s et ConfigurationO bject s ettings on a device to s pecify behaviour and
connection options .
Ge tS e tConfig urationOb je ctRe s p ons e is a reques t which returns the res pons e from the SetConfigurationO bject
reques t.
Ge tConfig urationOb je ct is a reques t to retrieve a ConfigurationO bject from a device.
Ge tConfig urationOb je ctRe s p ons e is a reques t which returns the res pons e, a ConfigurationO bject, from the
GetConfigurationO bject reques t.
S e tPus hS e tup Alarm is a reques t that pus hes received alarm mes s ages to O SGP.
Ge tS e tPus hS e tup AlarmRe s p ons e is a reques t which returns the res pons e from the SetPus hSetupAlarm reques t.
S e tPus hS e tup S ms is a reques t to s et an endpoint in a device which tells the device where to connect to when it is
waked up.
Ge tS e tPus hS e tup S ms Re s p ons e is a reques t which returns the res pons e from the SetPus hSetupSms reques t.
S e tAlarmNotifications is a reques t to s et the types of alarm notifications that mus t be notified from the device when
they occur.
Ge tS e tAlarmNotifications Re s p ons e is a reques t which returns the res pons e from the SetAlarmNotifications
SmartMetering 128
reques t.
S e tEncryp tionKe yExchang e OnGMe te r is a reques t to trans fer and s et a G-meter key on a device.
Ge tS e tEncryp tionKe yExchang e OnGMe te rRe s p ons e is a reques t which returns the res pons e from the
SetEncryptionKeyExchangeO nGMeter reques t.
Ge tMb us Encryp tionKe yS tatus is a reques t to retrieve the encryption key s tatus for a M-Bus device.
Ge tGe tMb us Encryp tionKe yS tatus Re s p ons e is a reques t which returns the res pons e from the
GetMbus EncryptionKeyStatus reques t.
S e tActivityCale nd ar is a reques t to s et s everal parameters on an E-meter s uch as tariffs per day in a week profile.
Ge tS e tActivityCale nd arRe s p ons e is a reques t which returns the res pons e from the SetActivityCalendar reques t.
Ge tAd minis trative S tatus is a reques t to retrieve the current Adminis trativeStatus s etting.
Ge tGe tAd minis trative S tatus Re s p ons e is a reques t which returns the res pons e from the GetAdminis trativeStatus
reques t.
S e tAd minis trative S tatus is a reques t to s et the Adminis trativeStatus .
Ge tS e tAd minis trative S tatus Re s p ons e is a reques t which returns the res pons e from the SetAdminis trativeStatus
reques t.
Ge tFirmware Ve rs ion is a reques t to retrieve the firmware vers ion(s ).
Ge tGe tFirmware Ve rs ionRe s p ons e is a reques t which returns the res pons e from the GetFirmwareVers ionReques t.
Re p lace Ke ys is a reques t to change the keys on a E-meter.
Ge tRe p lace Ke ys Re s p ons e is a reques t which returns the res pons e from the ReplaceKeys reques t.
S martMe te ring Ins tallation
Ad d De vice is a reques t to add a device to the O SGP databas e.

Ge tAd d De vice Re s p ons e is a reques t which returns the res pons e from the AddDevice reques t.
Coup le Mb us De vice is a reques t to couple a M-Bus device to a gateway.
Ge tCoup le Mb us De vice Re s p ons e is a reques t which returns the res pons e from the CoupleMbus Device reques t.
De Coup le Mb us De vice is a reques t to decouple an M-Bus device from a gateway.
Ge tDe Coup le Mb us De vice Re s p ons e is a reques t which returns the res pons e from the DeCoupleMbus Device
reques t.
Coup le Mb us De vice ByChanne l is a reques t to couple a M-Bus device to a gateway.
Ge tCoup le Mb us De vice ByChanne lRe s p ons e is a reques t which returns the res pons e from the
CoupleMbus DeviceByChannel reques t.
S martMe te ring Manag e me nt
Find Eve nts is a reques t to retrieve events logging from a device.

Ge tFind Eve nts Re s p ons e is a reques t which returns the res pons e from the FindEvents reques t.
Ge tDe vice s is a reques t to retrieve the las t known relay s tatus es for a group of devices .
S martMe te ring Monitoring
Ge tActualMe te rRe ad s is a reques t to retrieve the actual meter reads from an E-meter.
Ge tActualMe te rRe ad s Re s p ons e is a reques t which returns the res pons e from the ActualMeterReads reques t.
Ge tActualMe te rRe ad s Gas is a reques t to retrieve the actual meter reads from a G-meter.
Ge tActualMe te rRe ad s Gas Re s p ons e is a reques t which returns the res pons e from the ActualMeterReads Gas
reques t.
Ge tPe riod icMe te rRe ad s is a reques t to retrieve the periodic meter reads from an E-meter.
Ge tPe riod icMe te rRe ad s Re s p ons e is a reques t which returns the res pons e from the PeriodicMeterReads reques t.
Ge tPe riod icMe te rRe ad s Gas is a reques t to retrieve the periodic meter reads from a G-meter.
Ge tPe riod icMe te rRe ad s Gas Re s p ons e is a reques t which returns the res pons e from the PeriodicMeterReads Gas
reques t.
Ge tProfile Ge ne ricData is a reques t to retrieve any Profile Generic data from an E-meter.
Ge tProfile Ge ne ricDataRe s p ons e is a reques t which returns the res pons e from the ProfileGenericData reques t.
Re ad AlarmRe g is te r is a reques t to read the alarm regis ter from a device.
Ge tRe ad AlarmRe g is te rRe s p ons e is a reques t which returns the res pons e from the ReadAlarmRegis ter reques t.
Re trie ve Pus hNotificationAlarm is a reques t to pus h retrieved alarm notifications to O SGP.
S martMe te ring Notification
S e nd Notification is a reques t to let Webapps know there is a res ult ready to retrieve from the platform.
S martMe te ring Bund le
Bund le is a s pecial reques t in which one or more s ingle reques t(s ) to a s pecific device can be bundled.
Ge tBund le Re s p ons e is a reques t which gets the res pons e from the Bundle reques t.
All reques t s ent to this device make us e of one communication channel, which may improve performance cons iderably.
WSDL's
SmartMetering WSDL's
SmartMetering 129
SmartMetering XSD s chema's
SmartMetering 130
Web Services
Smart Metering Web Services
T his chapter des cribes all the web s ervices in the s mart metering domain.
Web Services 131

bypass retry
By adding an element Bypas s Retry in names pace http://www.alliander.com/s chemas /os gp/common/2014/10 with a value true
or fals e, you can bypas s retry when reques t to the device fail.
Web Services 132

priority
By adding an element Mes s agePriority in names pace http://www.alliander.com/s chemas /os gp/common/2014/10 with a value
from 0 - 9 you can give a mes s age a lower or higher priority.
Web Services 133

scheduling
By adding an element ScheduleT ime in names pace http://www.alliander.com/s chemas /os gp/common/2014/10 with a
xs d:dateT ime value can s chedule a mes s age.
Web Services 134

AdHocManagement
AdHocManagement
Des cribes the actions as defined in SmartMeteringAdhoc.ws dl
Web Services 135

GetAssociationLnObjects
GetAssociationLnObjects request
Des cription
GetAs s ociationLnO bjects is a reques t to get the As s ociation LN object tree from an E-meter. T he reques t is s ent with the
DeviceIdentification number from the des ired device.
All reques ts have s imilar res pons e behaviour which is des cribed in Res pons eMes s ages .
GetGetAs s ociationLnO bjects Res pons e returns the res ult values from getting the As s ociation LN object. T he res pons e
contains the DeviceIdentification and CorrelationUid which is received from the GetAs s ociationLnO bjects reques t.
References
XSD: s m-adhoc.xs d
WSDL: SmartMeteringAdhoc.ws dl
Web Services 136

GetGetAssociationLnObjectsResponse
GetGetAssociationLnObjectsResponse request
Des cription
GetGetAs s ociationLnO bjects Res pons e returns the res ult values from getting the As s ociation LN object. T he res pons e
contains the DeviceIdentification and CorrelationUid which is received from the GetAs s ociationLnO bjects reques t.
References
XSD: s m-adhoc.xs d
Web Services 137

SpecificConfigurationObject
SpecificConfigurationObject request
Des cription
SpecificConfigurationO bject is a reques t to retrieve the data for a s pecific configuration object indicated with:
Clas s Id
Attribute
O bis Code
References
XSD: s m-configuration.xs d
WSDL: SmartMeteringBundle.ws dl
Web Services 138

SynchronizeTime
SynchronizeTime request
Des cription
SynchronizeT ime reques t s ynchronizes the date and time on a device. T he date and time are retrieved from the s erver and
s ent to the device with CLASS_ID 8, O BIS_CO DE 0.0.1.0.0.255 and AT T RIBUT E_ID 2. T he reques t is s ent with the
DeviceIdentification number from the des ired device. T he reques t s hould contain a Deviation of local time to UT C in minutes
(from the range of -720 to 720 inclus ive) and a value Ds t indicating whether daylight s avings is active. For example in Central
European Summer T ime, DST is active and times are UT C/GMT +2 hours . For devices in a region where CEST applies ,
during the s ummer time the value for deviation s hould be "-120" (120 minutes deducted from local time gives GMT /UT C time)
and ds t s hould be "true".
GetSynchronizeT imeRes pons e returns the res ult from s ynchronizing date and time. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SynchronizeT ime reques t.
References
XSD: s m-adhoc.xs d
Web Services 139

GetSynchronizeTimeResponse
GetSynchronizeTimeResponse request
Des cription
GetSynchronizeT imeRes pons e returns the res ult from s ynchronizing date and time. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SynchronizeT ime reques t.
References
XSD: s m-adhoc.xs d
Web Services 140

Bundle
Bundling
You can combine multiple reques ts to a meter in a bundle by creating a BundleReques t with one or more Actions in the
names pace http://www.alliander.com/s chemas /os gp/s martmetering/s m-bundle/2014/10. Each Action contains one of the
exis ting reques ts to a meter.
A bundle is executed us ing one connection to the meter. A bundle res pons e contains all individual res pons es of executed
commands both s ucces s ful and uns ucces s ful. When an individual reques t fails it is retried when this is us eful, more precis ely
the bundle is retried, executing only reques ts that are fit for re-s ubmis s ion.
Web Services 141

Bundle
Bundle request
Des cription
Bundle is a s pecial reques t in which one or more s ingle reques t(s ) to a s pecific device can be bundled. All reques ts s ent to
this device make us e of one communication channel, which may improve performance cons iderably.
GetBundleRes pons e returns the res ult of the actions of the bundle. T he res pons e contains the DeviceIdentification and
CorrelationUid which is received from the Bundle reques t.
T he Bundle reques t has an Actions tag. T his contains a lis t of one or more s ingle reques t(s ). T he res pons e behavior is
des cribed in Res pons eMes s ages .
Actions
Currently, the following actions are s upported:
FindEvents Reques t s ee FindEvents

SetSpecialDays Reques t s ee SetSpecialDays
ReadAlarmRegis terReques t s ee ReadAlarmRegis ter
GetActualMeterReads Reques t s ee ReadAlarmRegis ter
GetActualMeterReads Gas Reques t s ee GetActualMeterReads Gas
GetAdminis trativeStatus Reques t s ee GetAdminis trativeStatus
GetPeriodicMeterReads Reques t s ee GetPeriodicMeterReads
GetPeriodicMeterReads Gas Reques t s ee GetPeriodicMeterReads Gas
SetAdminis trativeStatus Reques t s ee SetAdminis trativeStatus
SetActivityCalendarReques t s ee SetActivityCalendar
SetEncryptionKeyExchangeO nGMeterReques t s ee SetEncryptionKeyExchangeO nGMeter
SetAlarmNotifications Reques t s ee SetAlarmNotifications
SetConfigurationO bjectReques t s ee SetConfigurationO bject
SetPus hSetupAlarmReques t s ee SetPus hSetupAlarm
SetPus hSetupSms Reques t s ee SetPus hSetupSms
SynchronizeT imeReques t s ee SynchronizeT ime
GetConfigurationReques t
GetFirmwareVers ionReques t
UpdateFirmwareReques t s ee UpdateFirmware
GetSpecificConfigurationO bjectReques t s ee SpecificConfigurationO bject
SetKeys Reques t
GetAs s ociationLnO bjects Reques t
SetClockConfigurationReques t SetClockConfiguration
GetProfileGenericDataReques t s ee GetProfileGenericData
ConfigureDefinableLoadProfileReques t s ee ConfigureDefinableLoadProfile
SetMbus Us erKeyByChannelReques t s ee SetMbus Us erKeyByChannel
GetMBus EncryptionKeyStatus Reques t s ee GetMbus EncryptionKeyStatus
References
XSD: s m-bundle.xs d
Web Services 142

GetBundleResponse
GetBundleResponse request
Des cription
GetBundleRes pons e returns the res ult of the bundle reques ted with the Bundle method. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the Bundle reques t.
References
XSD:
s m-adhoc.xs d
s m-bundle.xs d
s m-configuration.xs d
s m-management.xs d
s m-monitoring.xs d
Web Services 143

Configuration
Configuration
Des cribes the actions as defined in SmartMeteringConfiguration.ws dl
Web Services 144

GetAdministrativeStatus
GetAdministrativeStatus request
Des cription
GetAdminis trativeStatus is a reques t to retrieve the current Adminis trativeStatus s etting from a device. T he reques t needs
the DeviceIdentification.
GetGetAdminis trativeStatus Res pons e returns if the s etting GetAdminis trativeStatus is enabled. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the GetAdminis trativeStatus reques t.
References
WSDL: SmartMeteringConfiguration.ws dl
Web Services 145

GetGetAdministrativeStatusResponse
GetGetAdministrativeStatusResponse request
Des cription
GetGetAdminis trativeStatus Res pons e returns if the s etting GetAdminis trativeStatus is enabled. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the GetAdminis trativeStatus reques t.
References
Web Services 146

GetFirmwareVersion
GetFirmwareVersion request
Des cription
GetFirmwareVers ion is a reques t to retrieve the firmware vers ion(s ) of a device. T he reques t needs the DeviceIdentification.
GetGetFirmwareVers ionRes pons e returns the vers ion(s ). T he res pons e contains the DeviceIdentification and CorrelationUid
which is received from the GetFirmwareVers ion reques t.
References
Web Services 147

GetGetFirmwareVersionResponse
GetGetFirmwareVersionResponse request
Des cription
GetGetFirmwareVers ionRes pons e returns the device firmware vers ions reques ted with the GetFirmwareVers ion method.
T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the GetFirmwareVers ion reques t.
References
Web Services 148

UpdateFirmware
UpdateFirmware request
Des cription
UpdateFirmware is a reques t to ins tall another firmware vers ion(s ) on a device. T he reques t needs the DeviceIdentification
and the firmware vers ions , that together with the device model (as s tored with the identified device) uniquely determine the
firmware file to be us ed.
GetUpdateFirmwareRes pons e returns the vers ion(s ). T he res pons e contains the DeviceIdentification and CorrelationUid
which is received from the UpdateFirmware reques t.
References
Web Services 149

GetUpdateFirmwareResponse
GetUpdateFirmwareResponse request
Des cription
GetUpdateFirmwareRes pons e returns the device firmware vers ions that are on the device after calling the UpdateFirmware
method. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the UpdateFirmware
reques t.
References
Web Services 150

ReplaceKeys
ReplaceKeys request
Des cription
ReplaceKeys is a reques t to change the keys on an E-meter. T he reques t needs the DeviceIdentification, an AuthenticationKey
and an EncryptionKey.
GetReplaceKeys Res pons e returns if the res ult is s ucces s ful from the ReplaceKeys reques t. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the ReplaceKeys reques t.
References
Web Services 151

GetReplaceKeysResponse
GetReplaceKeysResponse request
Des cription
GetReplaceKeys Res pons e returns if the res ult is s ucces s ful from the ReplaceKeys reques t. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the ReplaceKeys reques t.
References
Web Services 152

SetActivityCalendar
SetActivityCalendar request
Des cription
SetActivityCalendar is a reques t to s et tariffs on an E-meter according a Seas onProfile and WeekProfile. In a WeekProfile,
s even dayprofiles can be filled in with a s tart time and dayId which contains the tariff.
T he reques t needs the DeviceIdentification, CalendarName, ActivatePas s iveCalendarT ime, Seas onProfileName, Seas onStart,
WeekProfileName, DayId and StartT ime.
GetSetActivityCalendarRes pons e returns the res ult from s etting a SetActivityCalendar. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetActivityCalendar reques t.
References
Web Services 153

GetSetActivityCalendarResponse
GetSetActivityCalendarResponse request
Des cription
GetSetActivityCalendarRes pons e returns the res ult from s etting a SetActivityCalendar. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetActivityCalendar reques t.
References
Web Services 154

SetAdministrativeStatus
SetAdministrativeStatus request
Des cription
SetAdminis trativeStatus is a reques t to s et the Adminis trativeStatus on a device. T he reques t needs the DeviceIdentification
and Enabled parameter.
GetSetAdminis trativeStatus Res pons e returns if the s etting SetAdminis trativeStatus is enabled. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetAdminis trativeStatus reques t.
References
Web Services 155

GetSetAdministrativeStatusResponse
GetSetAdministrativeStatusResponse request
Des cription
GetSetAdminis trativeStatus Res pons e returns if the s etting SetAdminis trativeStatus is enabled. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetAdminis trativeStatus reques t.
References
Web Services 156

SetAlarmNotifications
SetAlarmNotifications request
Des cription
SetAlarmNotifications is a reques t to s et the types of alarm notifications that mus t be notified from the device when they
occur. T he following notifications can be enabled or dis abled:
CLO CK_INVALID, REPLACE_BAT T ERY, PO WER_UP, PRO GRAM_MEMO RY_ERRO R, RAM_ERRO R,

NV_MEMO RY_ERRO R, MEASUREMENT _SYST EM_ERRO R, WAT CHDO G_ERRO R, FRAUD_AT T EMPT ,
CO MMUNICAT IO N_ERRO R_M_BUS_CHANNEL_1, CO MMUNICAT IO N_ERRO R_M_BUS_CHANNEL_2,
CO MMUNICAT IO N_ERRO R_M_BUS_CHANNEL_3, CO MMUNICAT IO N_ERRO R_M_BUS_CHANNEL_4,
FRAUD_AT T EMPT _M_BUS_CHANNEL_1, FRAUD_AT T EMPT _M_BUS_CHANNEL_2,
FRAUD_AT T EMPT _M_BUS_CHANNEL_3, FRAUD_AT T EMPT _M_BUS_CHANNEL_4,
NEW_M_BUS_DEVICE_DISCO VERED_CHANNEL_1, NEW_M_BUS_DEVICE_DISCO VERED_CHANNEL_2,
NEW_M_BUS_DEVICE_DISCO VERED_CHANNEL_3, NEW_M_BUS_DEVICE_DISCO VERED_CHANNEL_4
T he reques t needs the DeviceIdentification, AlarmT ype and Enabled parameters .
GetSetAlarmNotifications Res pons e returns the res ult from s etting a SetAlarmNotifications . T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetAlarmNotifications reques t.
References
Web Services 157

GetSetAlarmNotificationsResponse
GetSetAlarmNotificationsResponse request
Des cription
GetSetAlarmNotifications Res pons e returns the res ult from s etting a SetAlarmNotifications . T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetAlarmNotifications reques t.
References
Web Services 158

SetConfigurationObject
SetConfigurationObject request
Des cription
SetConfigurationO bject is a reques t to s et ConfigurationO bject s ettings on a device. T he attributes with O BIS code 0-
1:94.31.3.255 give acces s to s et GPRS_operation_mode s etting and following flags :
dis cover_on_open_cover
dis cover_on_power_on
dynamic_mbus _addres s
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 des cription. T he reques t needs the DeviceIdentification, Gprs O perationMode,
ConfigurationFlagT ype and Enabled parameters .
GetSetConfigurationO bjectRes pons e returns the res ult from s etting a SetConfigurationO bject. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetConfigurationO bject reques t.
References
Web Services 159

GetSetConfigurationObjectResponse
GetSetConfigurationObjectResponse request
Des cription
GetSetConfigurationO bjectRes pons e returns the res ult from s etting a ConfigurationO bject. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetConfigurationO bject reques t.
References
Web Services 160

SetEncryptionKeyExchangeOnGMeter
SetEncryptionKeyExchangeOnGMeter request
Des cription
SetEncryptionKeyExchangeO nGMeter is a reques t to trans fer and s et a G-meter key on a G-meter via the E-meter. T he
reques t needs the DeviceIdentification from the G-meter. If the device identification of the G-meter is not known, but the
gateway device identification and M-Bus channel are known, us e the SetMbus Us erKeyByChannel reques t ins tead.
GetSetEncryptionKeyExchangeO nGMeterRes pons e returns the res ult from s etting a SetEncryptionKeyExchangeO nGMeter.
T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the
References
Web Services 161

GetSetEncryptionKeyExchangeOnGMeterResponse
GetSetEncryptionKeyExchangeOnGMeterResponse request
Des cription
GetSetEncryptionKeyExchangeO nGMeterRes pons e returns the res ult from s etting a SetEncryptionKeyExchangeO nGMeter.
References
Web Services 162

SetPushSetupAlarm
SetPushSetupAlarm request
Des cription
SetPus hSetupAlarm is a reques t to define the des tination of the T CP mes s age that is optionally s ent by the device. T he
reques t needs the DeviceIdentification, Hos t URL and port.
GetSetPus hSetupAlarmRes pons e returns the res ult from s etting a SetPus hSetupAlarm. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetPus hSetupAlarm reques t.
References
Web Services 163

GetSetPushSetupAlarmResponse
GetSetPushSetupAlarmResponse
Des cription
GetSetPus hSetupAlarmRes pons e returns the res ult from s etting a SetPus hSetupAlarm. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetPus hSetupAlarm reques t.
References
Web Services 164

SetPushSetupSms
SetPushSetupSms request
Des cription
SetPus hSetupSms is a reques t to s et an endpoint in a device which tells the device where to connect to when it is woken. T he
reques t needs the DeviceIdentification, hos t URL and port.
GetSetPus hSetupSms Res pons e returns the res ult from s etting a SetPus hSetupSms . T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetPus hSetupSms reques t.
References
Web Services 165

GetSetPushSetupSmsResponse
GetSetPushSetupSmsResponse request
Des cription
GetSetPus hSetupSms Res pons e returns the res ult from s etting a SetPus hSetupSms . T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the SetPus hSetupSms reques t.
References
Web Services 166

SetSpecialDays
SetSpecialDays request
Des cription
SetSpecialDays is a reques t to s et a dayId profile for a s pecific date on a device, other than the s tandard applicable dayId's .
T his can be us eful to change tariffs and tariff s cheduling for s pecific days s uch as public holidays . T he reques t is s end with
the DeviceIdentification number from the des ired device, date and dayId.
GetSetSpecialDays Res pons e returns the res ult from s etting a Special Day. T he res pons e contains the DeviceIdentification
and CorrelationUid which is received from the SetSpecialDays reques t.
References
Web Services 167

GetSetSpecialDaysResponse
GetSetSpecialDaysResponse request
Des cription
GetSetSpecialDays Res pons e returns the res ult from s etting a Special Day. T he res pons e contains the DeviceIdentification
and CorrelationUid which is received from the SetSpecialDays reques t.
References
Web Services 168

GetConfigurationObject
GetConfigurationObject request
Des cription
GetConfigurationO bject is a reques t to retrieve a ConfigurationO bject from a device. T he configuration object in the
electricity meter with the O BIS code 0-1:94.31.3.255 is us ed to acces s the GPRS_operation_mode s etting and following flags :
dis cover_on_open_cover
dis cover_on_power_on
dynamic_mbus _addres s
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 des cription. T he reques t needs the DeviceIdentification.
All reques ts have s imilar res pons e behavior which is des cribed in Res pons eMes s ages .
References
Web Services 169

GetConfigurationObjectResponse
GetConfigurationObjectResponse request
Des cription
GetConfigurationO bjectRes pons e returns the res ult, a ConfigurationO bject, which is received from the
GetConfigurationO bject reques t.
All reques ts have s imilar res pons e behavior which is des cribed in Res pons eMes s ages .
References
Web Services 170

ConfigureDefinableLoadProfile
ConfigureDefinableLoadProfile request
Des cription
ConfigureDefinableLoadProfile is a reques t to change the configuration of the definable load profile (CO SEM object of
interface clas s 'Profile generic' with logical name '0-1:94.31.6.255') of the device. T he reques t needs the DeviceIdentification,
and at leas t one of CaptureO bjects and CapturePeriod.
T he CaptureO bjects element may be included in the reques t to s pecify one or more objects to be captured in the definable
load profile, containing definitions as CaptureO bject according to the CaptureO bjectDefinition in common.xs d. T he
CaptureO bjects s hould not include the clock definition ({8,0-0:1.0.0.255,2,0}) as this will always be included as firs t capture
object. T his matches the way GetProfileGenericData works when retrieving the buffer of the definable load profile (where
you mus t not s pecify the clock definition as s elected value).
T he CapturePeriod may be included to s pecify the automatic capturing period in s econds (a value of zero meaning no
automatic capturing s hould be done).
ConfigureDefinableLoadProfile reques t. GetConfigureDefinableLoadProfileRes pons e returns if the res ult is s ucces s ful from
the ConfigureDefinableLoadProfile reques t.
References
Web Services 171

GetConfigureDefinableLoadProfileResponse
GetConfigureDefinableLoadProfileResponse request
Des cription
GetConfigureDefinableLoadProfileRes pons e returns if the res ult is s ucces s ful from the ConfigureDefinableLoadProfile
reques t. T he reques t contains the DeviceIdentification and CorrelationUid which is received from the
ConfigureDefinableLoadProfile reques t.
References
Web Services 172

SetMbusUserKeyByChannel
SetMbusUserKeyByChannel request
Des cription
SetMbus Us erKeyByChannel is a reques t to generate, trans fer and s et an M-Bus us er key on an M-Bus device (for ins tance a
G-meter behind an E-meter) via the DLMS gateway device. T he reques t needs the DeviceIdentification from the gateway
device and the channel for the M-Bus device. A us e cas e for a reques t with the channel (as only identification of the M-Bus
device bes ides the identification of the gateway) as input is to be able to res pond to new M-Bus device dis covered on
channel x alarms (x in 1..4) from a gateway. If a new M-Bus Us er key is to be s et on an M-Bus device with a known
identification, this can be done with the SetEncryptionKeyExchangeO nGMeter reques t.
T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the SetMbus Us erKeyByChannel
reques t. GetSetMbus Us erKeyByChannelRes pons e returns the res ult from is s uing a SetMbus Us erKeyByChannel reques t.
References
Web Services 173

GetSetMbusUserKeyByChannelResponse
GetSetMbusUserKeyByChannelResponse request
Des cription
GetSetMbus Us erKeyByChannelRes pons e returns the res ult from is s uing a SetMbus Us erKeyByChannel reques t. T he reques t
contains the DeviceIdentification and CorrelationUid which is received from the SetMbus Us erKeyByChannel reques t.
References
Web Services 174

GetMbusEncryptionKeyStatus
GetMBusEncryptionKeyStatus request
Des cription
GetMbus EncryptionKeyStatus is a reques t to retrieve the encryption key s tatus of a M-Bus device from an E-meter. T he
reques t needs the DeviceIdentification of the M-Bus Device.
T he returned res pons e for the GetMbus EncryptionKeyStatus reques t is as s pecified in

GetGetMbus EncryptionKeyStatus Res pons e.
References
Web Services 175

GetGetMbusEncryptionKeyStatusResponse
GetGetMBusEncryptionKeyStatusResponse request
Des cription
GetGetMbus EncryptionKeyStatus Res pons e is a reques t to return the M-Bus encryption key s tatus as reques ted by a
GetMbus EncryptionKeyStatus reques t. T he pos s ible return values for the M-Bus encryption key s tatus can be found in the
EncryptionKeyStatus enum in the s m-configuration.xs d
References
Web Services 176

GetMbusEncryptionKeyStatusByChannel
GetMBusEncryptionKeyStatusByChannel request
Des cription
GetMbus EncryptionKeyStatus ByChannel is a reques t to retrieve the encryption key s tatus of an M-Bus device from an E-
meter. T he reques t needs the DeviceIdentification of the gateway device and a channel.
T he returned res pons e for the GetMbus EncryptionKeyStatus ByChannel reques t is as s pecified in
GetMbus EncryptionKeyStatus ByChannelRes pons e.
References
Web Services 177

Installation
Installation
Des cribes the actions as defined in SmartMeteringIns tallation.ws dl
Web Services 178

AddDevice
AddDevice request
Des cription
AddDevice is a reques t to add a device to the O SGP databas e. For the lis t of parameters , s ee the .xs d file (link below).
All reques ts have s imilar res pons e behaviour which is des cribed in Res pons eMes s ages
GetAddDeviceRes pons e returns if the res ult is s ucces s ful from the reques t. T he res pons e contains the DeviceIdentification
and CorrelationUid which is received from the AddDevice reques t.
References
XSD: s m-ins tallation.xs d
WSDL: SmartMeteringIns tallation.ws dl
Web Services 179

GetAddDeviceResponse
GetAddDeviceResponse request
Des cription
GetAddDeviceRes pons e returns if the res ult is s ucces s ful from the AddDevice reques t. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the AddDevice reques t.
References
Web Services 180

CoupleMbusDevice
CoupleMbusDevice request
Des cription
CoupleMbus Device is a reques t to couple a gateway and a m-bus device. T he reques t needs the following parameters :
DeviceIdentification
Mbus DeviceIdentification
GetCoupleMbus DeviceRes pons e returns if the res ult is s ucces s ful from the reques t. T he res pons e reques t contains the
DeviceIdentification and CorrelationUid which is received from the CoupleMbus Device reques t.
References
Web Services 181

GetCoupleMbusDeviceResponse
GetCoupleMbusDeviceResponse request
Des cription
GetCoupleMbus DeviceRes pons e returns if the res ult is s ucces s ful from the CoupleMbus Device reques t. T he res pons e
contains the DeviceIdentification and CorrelationUid which is received from the CoupleMbus Device reques t.
References
Web Services 182

DeCoupleMbusDevice
DeCoupleMbusDevice request
Des cription
DeCoupleMbus Device is a reques t to decouple an Mbus device (s uch as a gas meter) from a device to the O SGP databas e.
T he reques t needs the following parameters :
DeviceIdentification
Mbus DeviceIdentification
GetDeCoupleMbus DeviceRes pons e returns if the res ult is s ucces s ful from the reques t. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the DeCoupleMbus Device reques t.
References
Web Services 183

GetDeCoupleMbusDeviceResponse
GetDeCoupleMbusDeviceResponse request
Des cription
GetDeCoupleMbus DeviceRes pons e returns if the res ult is s ucces s ful from the DeCoupleMbus Device reques t. T he res pons e
contains the DeviceIdentification and CorrelationUid which is received from the DeCoupleMbus Device reques t.
References
Web Services 184

Management
Management
Des cribes the actions as defined in SmartMeteringManagement.ws dl
Web Services 185

FindEvents
FindEvents request
Des cription
FindEvents is a reques t to retrieve periodic events logging from a device. T he reques t needs the DeviceIdentification,
EventLogCategory, From and Until DateT ime. T he EventlogCategories cons is t off:
ST ANDARD_EVENT _LO G
FRAUD_DET ECT IO N_LO G
CO MMUNICAT IO N_SESSIO N
M_BUS_EVENT _LO G
DSMR Chapter 4.2.1 des cribes the s everal events and their des cription.
GetFindEvents Res pons e returns if the res ult is s ucces s ful from the reques t. T he res pons e contains the DeviceIdentification
and CorrelationUid which is received from the FindEvents reques t.
References
XSD: s m-management.xs d
WSDL: SmartMeteringManagement.ws dl
Web Services 186

GetFindEventsResponse
GetFindEventsResponse request
Des cription
GetFindEvents Res pons e returns if the res ult is s ucces s ful from the FindEvents reques t. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the FindEvents reques t.
References
Web Services 187

GetDevices
GetDevices request
Des cription
GetDevices is a reques t to get the las t known relay s tatus es for a group of devices , s o you can get an overview of s tatus es
for a s pecific s et of devices . T he reques t needs the Page parameter.
References
Web Services 188

SetDeviceLifecycleStatusByChannel
SetDeviceLifecycleStatusByChannel request
Des cription
SetDeviceLifecycleStatus Bychannel is a reques t to s et the device lifecycle s tatus of an Mbus device, us ing the device
identification of the Gateway device and a channel.
T he returned res pons e for the SetDeviceLifecycleStatus ByChannel reques t is as s pecified in

SetDeviceLifecycleStatus ByChannelRes pons e.
References
Web Services 189

SetDeviceLifecycleStatusByChannelResponse
SetDeviceLifecycleStatusByChannelResponse request
Des cription
SetDeviceLifecycleStatus ByChannelRes pons e returns the res ult of a SetDeviceLifecycleStatus ByChannel reques t. T he
res pons e contains the GatewayDeviceIdentification, Mbus DeviceIdentification, DeviceLifecycleStatus and
channel.SetDeviceLifecycleStatus ByChannel reques t.
References
Web Services 190

EnableDebugging
EnableDebugging request
Des cription
Enable debugging for a device. Communication with the device will be logged and made available through FindMes s ageLogs ,
GetEnableDebuggingRes pons e returns the res ult s tatus . T he res pons e contains the DeviceIdentification and CorrelationUid
which is received from the GetEnableDebuggingReques t reques t.
References
Web Services 191

DisableDebugging
DisableDebugging request
Des cription
Dis able debugging for a device. Communication with the device will be logged and made available through
FindMes s ageLogs ,
GetDis ableDebuggingRes pons e returns the res ult s tatus . T he res pons e contains the DeviceIdentification and CorrelationUid
which is received from the GetDis ableDebuggingReques t reques t.
References
Web Services 192

FindMessageLogs
FindMessageLogs request
Des cription
FindMes s ageLogs is a reques t to retrieve logged mes s ages for a device. T he reques t needs the DeviceIdentification and a
Page number to return.
GetFindMes s ageLogs Res pons e returns if the res ult is s ucces s ful from the reques t. T he res pons e contains the
DeviceIdentification and CorrelationUid which is received from the FindMes s ageLogs reques t.
Note : T his functionality als o e xis ts in the ad min d e vice manag e me nt s e rvice . It was d up licate d he re to b e
imp le me nte d as ynchronous ly, as the re is no s up p ort for as ynchronous re q ue s ts trig g e ring a notification s e rvice
in the ad min p roje ct. As s oon as as ynchronous re q ue s ts and notifications are imp le me nte d throug hout the OS GP
p latform, this me thod s hould b e re move d in favour of the ad min imp le me ntation.
References
Web Services 193

Monitoring
Monitoring
Des cribes the funtions as defined in SmartMeteringMonitoring.ws dl
Web Services 194

GetActualMeterReads
GetActualMeterReads request
Des cription
GetActualMeterReads is a reques t to retrieve the actual import and export meter reads from an E-meter. T he reques t needs
the DeviceIdentification.
GetActualMeterReads Res pons e returns the retrieved meter reads values , unit and log time from the GetActualMeterReads
reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the GetActualMeterReads
reques t.
References
XSD: s m-monitoring.xs d
WSDL: SmartMeteringMonitoring.ws dl
Web Services 195

GetActualMeterReadsResponse
GetActualMeterReadsResponse request
Des cription
GetActualMeterReads Res pons e returns the retrieved import and export values , unit and logtime from the ActualMeterReads
reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the GetActualMeterReads
reques t.
References
Web Services 196

GetActualMeterReadsGas
GetActualMeterReadsGas request
Des cription
GetActualMeterReads Gas is a reques t to retrieve the actual import and export meter reads from a G-meter. T he reques t
needs the DeviceIdentification.
GetActualMeterReads Gas Res pons e returns the retrieved meter reads values , unit and log time from the
GetActualMeterReads Gas reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received
from the GetActualMeterReads Gas reques t.
References
Web Services 197

GetActualMeterReadsGasResponse
GetActualMeterReadsGasResponse request
Des cription
GetActualMeterReads Gas Res pons e returns the retrieved import and export values , unit and log time from the
ActualMeterReads Gas reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from
the ActualMeterReads Gas reques t.
References
Web Services 198

GetPeriodicMeterReads
GetPeriodicMeterReads request
Des cription
GetPeriodicMeterReads is a reques t to retrieve the periodic import and export meter reads from an E-meter. T he periode
can be DAILY, MO NT HLY or INT ERVAL. T he reques t needs the DeviceIdentification.
GetPeriodicMeterReads Res pons e returns the retrieved meter reads values , unit and log time from the
GetPeriodicMeterReads reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from
the GetPeriodicMeterReads reques t.
References
Web Services 199

GetPeriodicMeterReadsResponse
GetPeriodicMeterReadsResponse request
Des cription
GetPeriodicMeterReads Res pons e returns the retrieved import and export values , unit and log time from the
PeriodicMeterReads reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from the
GetPeriodicMeterReads reques t.
References
Web Services 200

GetPeriodicMeterReadsGas
GetPeriodicMeterReadsGas request
Des cription
GetPeriodicMeterReads Gas is a reques t to retrieve the periodic import and export meter reads from a G-meter. T he period
can be DAILY, MO NT HLY or INT ERVAL. T he reques t needs the DeviceIdentification.
GetPeriodicMeterReads Gas Res pons e returns the retrieved meter reads values , unit and log time from the
GetPeriodicMeterReads Gas reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received
from the GetPeriodicMeterReads Gas reques t.
References
Web Services 201

GetPeriodicMeterReadsGasResponse
GetPeriodicMeterReadsGasResponse request
Des cription
GetPeriodicMeterReads Gas Res pons e returns the retrieved import and export values , unit and log time from the
PeriodicMeterReads Gas reques t. T he res pons e contains the DeviceIdentification and CorrelationUid which is received from
the GetPeriodicMeterReads Gas reques t.
References
Web Services 202

GetProfileGenericData
GetProfileGenericData request
Des cription
GetProfileGenericData is a reques t to retrieve any DLMS "Profile generic" data from an E-meter. T he reques t needs the
DeviceIdentification.
T he s pecific Profile generic data to be retrieved is identified by its O BIS code included as O bis Code according to the
O bis CodeValues as s pecified in common.xs d.
Selective acces s will be applied as des cribed in the DLMS s tandard for acces s s elector range_descriptor. T he clock definition
is us ed as restricting_object. T he from_value and to_value for the captured clock values will be s et bas ed on the BeginDate and
EndData in the reques t.
It is pos s ible to further reduce the amount of data retrieved from the device to s pecify selected_values. T his is done by
including the optional SelectedValues element in the reques t s pecifying one or more capture object definitions as
CaptureO bject according to the CaptureO bjectDefinition in common.xs d.
T he clock definition mus t not be s pecified in the SelectedValues , s ince it will always be included in the res ults . T he values
that are s pecified mus t be capture object definitions that appear in the lis t of capture_objects for the Profile generic data that
is retrieved.
T he ultimately returned res pons e for the GetProfileGenericData reques t is as s pecified in GetProfileGenericDataRes pons e.
References
Web Services 203

GetProfileGenericDataResponse
GetProfileGenericDataResponse request
Des cription
GetProfileGenericDataRes pons e is a reques t to return the Generic profile buffer data as reques ted by a
GetProfileGenericData reques t. It contains the DeviceIdentification and CorrelationUid which is received from the
GetProfileGenericData reques t.
T he res pons e to the GetProfileGenericDataRes pons e reques t contains the logical name of the reques ted Generic profile as
LogicalName according to the O bis CodeValues as s pecified in common.xs d.
T he definitions of the capture objects from the buffer that are included in the res pons e are lis ted as CaptureO bject
according to the CaptureO bject in common.xs d.
T he actual data from the buffer is included in the ProfileEntries , where each ProfileEntry has a lis t of values that match the
capture objects from the res pons e.
References
Web Services 204

ReadAlarmRegister
ReadAlarmRegister request
Des cription
ReadAlarmRegis ter is a reques t to retrieve the query alarm regis ter. A notification will be s ent and the query will be s tored in
the databas e. T he reques t needs the DeviceIdentification.
GetReadAlarmRegis terRes pons e returns the alarm notifications from the ReadAlarmRegis ter reques t. T he res pons e contains
the DeviceIdentification and CorrelationUid which is received from the ReadAlarmRegis ter reques t.
References
Web Services 205

GetReadAlarmRegisterResponse
GetReadAlarmRegisterResponse request
Des cription
GetReadAlarmRegis terRes pons e returns the alarm notifications from the ReadAlarmRegis ter reques t. T he res pons e contains
the DeviceIdentification and CorrelationUid which is received from the ReadAlarmRegis ter reques t.
References
Web Services 206

RetrievePushNotificationAlarm
RetrievePushNotificationAlarm request
Des cription
RetrievePus hNotificationAlarm is a reques t to pus h retrieved alarm notifications to O SGP. T he reques t needs the
DeviceIdentification.
References
Web Services 207

Notification
Notifications
Des cribes the actions as defined in the SmartMeteringNotification.ws dl
Web Services 208

SendNotification
SendNotification request
Des cription
SendNotification is a reques t from the platform to let Webapps know there is a res ult ready to retrieve. In this way, there is
no need for cons tant polling between Webapps and the platform. T he reques t needs the DeviceIdentification.
References
XSD: s m-notification.xs d
WSDL: SmartMeteringNotification.ws dl
Web Services 209

ResponseMessages
ResponseMessages
T he res pons e of a reques t s hould always contain a DeviceIdentification and CorrelationUid which is us ed in the res pons e
reques t. As s ertions validate if there is a 'SO AP Res pons e' received, if the res pons e is 'Schema Compliant' with the WSDL and
if there has been a 'not SO AP Fault'. T he las t one occurs when a fault code is returned. Pos s ible faults are connection timed-
out, SmartMeter could not be found, T CP-IP connection error or Correlationuid is unknown. T he faults can be among others
a FunctionalFault or T echnicalFault. Res pons es to a bundle reques t may include faults in the form of FaultRes pons eData,
res embling the other faults . T he format of thes e faults is des cribed in the common.xs d.
Res pons eMes s ages 210

Use cases
Example use-case for this domain
Up-to-date information on us e-cas es can be found on the open s mart grid platform webs ite.
S mart Me te r He ad -e nd S ys te m
T e chnical d rive rs
Replacement or addition to the current head-end s ys tem

During the coming years , many s mart meters will be placed in hous es , companies and other properties , therefore grid
operators need a s calable s olution
E(lectricity) Meters can hos t up to 4 other s mart devices , Gas Meters for example
DLMS/CO SEM is us ed by many(if not all) Smart Meters
Cus tome r d rive rs
People will have more ins ight in their power cons umption
Meter values can be gathered by the grid operator, ins tead of relying on people reporting the meter values
Us e cas es 211
Guidelines to add a new domain to OSGP

Guidelines to add a new domain to OSGP
In order to add a new domain to O SGP, you can benefit from the guidelines given in this document. T he general idea for
adding a new domain is to copy an exis ting domain, for ins tance the microgrids domain, and perform a global s earch and
replace, to replace the old domain name with the new domain name. You can us e refactor methods from IntelliJ or Eclips e to
help renaming the old domain names .
T o add a new domain, changes mus t be made to 3 GitHub repos itories :
1. Config repos itory.

2. Shared repos itory.
3. Platform repos itory.
Chang es to OSGP/Config
Search for “Microgrids ” and “microgrids ” in all files and you will find all files to change for a new domain. T hes e files
include:
Apache configuration
Create domain databas e s cript
Backup, res tore, s ymlinks s cripts
T omcat context s cript
Chang es to OSGP/Shared
A new Maven module mus t be added for the new domain (os gp-ws -newdomain). T his module will contain the ws dl files for
the new domain s ervices . Copy for ins tance os gp-ws -microgrids , s earch and replace microgrids with your domain and
replace the ws dl files with your ws dl files . JAXB will generate java clas s es for your webs ervices . Change
NewDomainWebServiceConfig.java accordingly. Make s ure your bas e Reques t and Res pons e clas s es are generated with an
@XmlRootElement annotation. O therwis e your endpoints which are bas ed on thes e types will fail (See @PayloadRoot in
AdHocManagementEndpoint in os pg-adapter-ws -microgrids ). T he s tructure of your ws dl file determines whether the
@XmlRootElement annotation is generated or not.
Image showing the generated @XmlRootElement annotation
Do not forget to add two cons tants for your new domain in the enum ComponentT ype.java
(https ://github.com/O SGP/Shared/blob/development/s hared/s rc/main/java/com/alliander/os gp/s hared/exceptionhandling/ComponentT ype.java).
T hes e cons tants are us ed in handling exceptions . Add one cons tant to denote your new Domain layer (DO MAIN) and one for
your new Web Services layer (WS). See for ins tance Microgrids Service.java
(https ://github.com/O SGP/Platform/blob/development/os gp-adapter-ws -
microgrids /s rc/main/java/com/alliander/os gp/adapter/ws /microgrids /application/s ervices /Microgrids Service.java).
Add DT O ’s to os gp-dto for your s ervices . T he DT O ’s are us ed in the protocol-adapter. Mapping from/to DT O ’s is
performed in adapter-domain.
Guidelines to add a new domain to O SGP 212

Chang es to OSGP/Platform
Reference the new os gp-ws -newdomain (from Shared) in the platform pom.xml. Als o create three new Maven modules and
add them to the pom:
os gp-domain-newdomain
os gp-adapter-ws -newdomain
os gp-adapter-domain-newdomain
Cons tants for the ne w d omain we b s e rvice s
O SGP us es a couple of Java enums to identify all available s ervices the platform offers .
T he DeviceFunction enum contains all s ervices for all domains .

T he NotificationT ype enum and the NewDomainReques tMes s ageT ype enum are identical and contain the s ervices for
1 domain. T he NotificationT ype enum is generated from the ws dl s ervice definition for the notification s ervice. T he
NewDomainT ype enum is defined in the Web Service Layer for the new domain and is us ed to pas s the mes s age type
to the other layers of O SGP.
DeviceReques tMes s ageT ype will contain the s ervices for 1 protocol Strictly s peaking this enum is not neces s ary to
add a new domain becaus e the enum is located in the protocol layer of O SGP.
Each new s ervice that is offered by the domain, for ins tance GET _DAT A or SET _DAT A, mus t be added to 4 java enums :
1. NotificationT ype (https ://github.com/O SGP/Shared/blob/development/os gp-ws -

microgrids /s rc/main/res ources /s chemas /notification.xs d, generated from ws dl with JAXB)
2. DeviceFunction (https ://github.com/O SGP/Platform/blob/development/os gp-domain-
core/s rc/main/java/com/alliander/os gp/domain/core/valueobjects /DeviceFunction.java)
3. NewDomainReques tMes s ageT ype (s ee for ins tance, https ://github.com/O SGP/Platform/blob/development/os gp-
adapter-ws -
microgrids /s rc/main/java/com/alliander/os gp/adapter/ws /microgrids /infra/jms /Microgrids Reques tMes s ageT ype.java)
4. DeviceReques tMes s ageT ype (https ://github.com/O SGP/Protocol-Adapter-IEC61850/blob/development/os gp-
protocol-adapter-
iec61850/s rc/main/java/com/alliander/os gp/adapter/protocol/iec61850/infra/mes s aging/DeviceReques tMes s ageT ype.java
or any other protocol adapter)
S QL for the ne w d omain
A Flyway s cript s hould be added for s ys tem data. For a new domain a new record mus t be ins erted in the table domain_info
in the core databas e. Check for ins tance the Flyway s cript for Dis tribution Automation
https ://github.com/O SGP/Platform/blob/development/os gp-
core/s rc/main/res ources /db/migration/V20170508125704045__Added_Dis tribution_Automation_domain_info.s ql. T es t data
for a new domain will include:
T able device_function_mapping in the core databas e. Add a row for each new s ervice to authorize ‘O WNER’ for this
s ervice.
T able device in the core databas e. Add a new row for a tes t device, us e the proper protocol_info_id.
(Protocol_info_id is a foreign_key to the protocol_info table in core).
T able device_authorization. Add a new row to authorize owner for this device. (Function_group is a reference to the
java enum DeviceFunctionGroup in Platform/os gp-domain-core).
Chang e s to os g p -d omain-ne wd omain
Review entities . Be careful, the entities in this project are generated in the core databas e. T he name of this project
s ugges ts that the entities would be generated in a domain s pecific databas e.
Create valueobjects for your domain. T he valueobjects in this project are us ed only in the adapter-ws and adapter-
domain layer.
Chang e s to os g p -ad ap te r-ws -ne wd omain
Add Endpoints for each s ervice reques t in pres entation.ws .

Add Mes s ageProces s ors in infra.jms .mes s ageproces s ors for each s ervice res pons e.
Modify mapping/NewDomainMapper to map the JAXB generated clas s es to the clas s es in Platform/os gp-domain-
new-domain
Chang e s to os g p -ad ap te r-d omain-ne wd omain
Add Mes s ageProces s ors in infra.jms .ws .mes s ageproces s ors for each s ervice reques t.
Add Mes s ageProces s ors in infra.jms .core.mes s ageproces s ors for each s ervice res pons e.
Modify mapping/DomainNewDomainMapper to map the clas s es in Platform/os gp-domain-new-domain to the clas s es
in Shared/os gp-dto. T he os gp-dto clas s es are us ed in the core layer and the protocol layer.
T e s ting the ne w d omain s e rvice s

In order to tes t the new domain s ervices take a look at the Ins tallation Guide. While following this guide keep the following
items in mind:
A tes t device for the new domain mus t be available. T his can either be a phys ical device or a s imulated device.
T he tes t device mus t be connected or a device s imulator mus t be running.
T he O SGP protocol adapter for the new device mus t be extended.
ProgreSQ L mus t be ins talled with all O SGP databas es and s ys tem data as lis ted in the ins tallation guide. T he new
domain might have a new databas e in which cas e the create s cript for the databas e and databas e owner mus t be run.
T es t data mus t be ins erted into the following tables : organis ation, device, device_authorization,
device_function_mapping. Depending on the type of protocol adapter us ed for the new domain other tables might
have to be populated as well. For ins tance a table like rtu_device for the IEC61850 Protocol Adapter.
Apache Http Server mus t be ins talled and the new domain mus t be added to the configuration
Apache ActiveMQ mus t be ins talled
T omcat application s erver mus t be ins talled and at leas t 4 web applications mus t be deployed:
An O SGP protocol adapter
O SGP Core
T he O SGP Adapter Domain for your new domain
T he O SGP Adapter WS for your new domain
SoapUI can be us ed to tes t the new webs ervices for your domain

Protocols
Protocols
T he open s mart grid platform s upported protocols can be found in this s ection. Feel free to add your own protocol or
improve an exis ting protocol adapter.
Protocol Adapters
Protocol Adapter components trans late a mes s age from domain adapter components into a protocol mes s age for a s mart
device. Protocol Adapter components s end the protocol mes s age to a s mart device us ing a network connection. T he
res pons e from the s mart device is trans lated into a domain res pons e mes s age which will be s ent to the Core components
(which will route it to the domain adapter which is s ued the reques t).
OS LP
For the O SLP implementation, 2 components are us ed. T he firs t component is the protocol adapter for the protocol. It can
trans late mes s age into the protocol mes s age for SSLD's . Second there's the s igning-s erver component. It is res pons ible for
s igning the protocol mes s age us ing the private key of the platform. T he components communicate us ing a queue-pair. T he
s inging-s erver can handle multiple protocol adapter ins tances by utilizing a reply-to queue per protocol adapter ins tance.
Since the protocol adapter component needs to be reachable from a network, it is a requirement that the private key may not
be us ed by the protocol adapter directly. T he s inging-s erver component can be deployed in s uch a way that no network
acces s is available to this component, as the only coupling needed are the queues / the mes s age broker.
DLMS
T he DLMS protocol is us ed for (mainly) s mart metering.
IEC61850
T he IEC61850 implementation is us ed for e.g. dis tibution automation, microgrids and public lighting.
Protocols 215
IEC 61850
IEC61850
T he open s mart grid platform s upport IEC61850. IEC61850 is a popular protocol in the field of "s mart grids ". IEC 61850
s tarted as an s tandard for s ubs tation automation but has expanded into other domains s uch as EV and s olar panels .
Currently, the IEC61850 protocol is us ed within the Public Lighting, Microgrids and Dis tribution Automation domains . IEC
61850 on Wikipedia
Protocol security
No s ecurity options exis t in this IEC61850 vers ion 1 and 2
Us e through a s ecured tunnelling protocol like T LS (with client certificates ) or VPN IEC Security guidelines can be
found in IEC 62351.
Specific communication s ervice mapping (SCSM)

T he open s mart grid platform implementation s upports :
IEC 61850-8-1: Mappings to MMS (ISO /IEC9506-1 and ISO /IEC 9506-2)
Us ed library
T he O penMUC IEC61850 library from Fraunhofer is us ed to implement the protocol.
Supported Devices
T his devices are currently s upported by the O pen Smart Grid Platform.
Wago 750-881 RT U
ABB 540CID11 RT U
Kaifa AS101 load control box
IEC 61850 216

DLMS / COSEM
DLMS/COSEM
T he open s mart grid platform s upports DLMS/CO SEM (IEC 62056]. DLMS/CO SEM is a popular protocol to read s mart
meters . DLMS/CO SEM is the de facto s tandard in Europe.
T he open s mart grid platform DLMS/CO SEM implementation was initial bas ed on SMR5 and DSMR v4. O ther types of
meters /profiles can be added to the platform. T he open s mart grid platform implementation s upports HLS3/4/5.
Protocol security
Public/private key pair(s )
Multiple encryption levels ins ide protocol (DSMR requires highes t encryption level)
Full encryption of communication
Us ed library
T he O penMUC jDLMS library from Fraunhofer is us ed to implement the protocol. Pleas e note that jDLMS is licens ed under
the GPLv3.
DLMS device s imulator

Supported devices
T hes e devices can be us ed in combination with the O pen Smart Grid Platform.
E/G S up p lie r T yp e x fas e

E Kaifa MA105
E Kaifa MA105C 1 fas e
E Kaifa MA304
E Kaifa MA304C 3 fas e
E L+G ZCF110CCtFs 2 1 fas e
E L+G ZMF110CCtFs 2 3 fas e
E L+G ZCF110CBtFs 2 1 fas e
E L+G E350
E L+G E650
E Is kra Mx382
G L+G G350 (wireles s /wired)
G Itron G1 RF1
DLMS / CO SEM 217

DLMS device simulator

T he library that is us ed to connect to DLMS devices contains functionality to build a s imulator for a device. T he library
offers the following core functionality.
zero or more s ervers can be s tarted on a hos t (different ports )

zero or more logical devices can be regis tered with a s erver (different device id)
zero or more annotated objects can be regis tered with a logical device
thes e objects define available dlms clas s es , O bis Codes , attributeIds and methods for the device and can contain any
logic
authentication and encryption are s upported
If you want to s imulate a certain device you will prepare annotated clas s es and regis ter ins tances of thes e with a logical
device. Becaus e you create plain Java you can make us e of all functionality Java offers , for example databas es . T o try and
make the s imulation more realis tic you may build in connection timeouts etc.
Us ag e
For each combination of a cos em clas s and obis code you create a java clas s that you annotate with @Cos emClas s (id = ...,
obis = "x.x.x.x.x.255")
In thes e java clas s es you can add fields of type DataO bject that you annotate with @Cos emAttribute(id = ..., type = T ype.x)
Als o you can create getXXX and s etXXX methods to intercept getting and s etting data on a logical device. XXX will be the
name of the corres ponding field s tarting with a capital letter.
For example:
@ CosemClass(id = 3, obis = "1.0.1.8.0.255")

public class ImportValue {
@ CosemAttribute(id = 2, type = Type.DOUBLE_LONG_UNSIGNED)

private DataObject d1 = DataObject.newUInteger32Data(10001);
@ CosemAttribute(id = 3, type = Type.STRUCTURE)

private DataObject d2 = DataObject.newStructureData(DataObject.newInteger8Data((byte) -2),
DataObject.newInteger8Data((byte) 30));
public void setD1(DataObject newData) throws IllegalAttributeAccessException {

// ....
}
public DataObject getD1() throws IllegalAttributeAccessException {
return d1;
}
}
T he value of the field will be the res pons e to get(AttributeAddres s ...) that is fired from os gp CommandExecutors . NO T E that
thes e values can als o be s et! For example us ing the ClientCons ole.
You can als o annotate methods with or without a DataO bject return value and with or without a DataO bject parameter:
@Cos emMethod(id = ..., cons umes = T ype.x)
For example:
@ CosemMethod(id = 1)
public void hello() throws IllegalMethodAccessException {
System.out.println("Has been called");
return;
}
@ CosemMethod(id = 2, consumes = Type.OCTET_STRING)

public DataObject hello2(DataObject datO) throws IllegalMethodAccessException {
throw new IllegalMethodAccessException(MethodResultCode.OTHER_REASON);
}
Such a method will be called when os gp fires ClientConnection.action, the DataO bject that may be returned will become
available in os gp on the MethodRes ult object.
Pe r command d e s ig n
DLMS device s imulator 218

T he way to implement reques t/res pons e for a command in the s imulator is as follows .
create a s eparate package per command

create a java clas s for each combination of clas s id and obis code
in this clas s implement the attribute id's and the methods that will be reques ted as explained above
DLMS device s imulator 219

OSLP
OSLP Documentation
The Open Street Light Protocol
T he O SLP is a lightweight mes s age bas ed protocol. O SLP us es Google Protocol Buffers and is us ed for communication with
SSLD devices (and device s imulators ). It is defined as a contract/interface. T he interface defines datatypes and mes s ages
which us e thos e data types . Google Protocol Buffers is us ed to generate the protocol implementations for Java (for the
platform) and C/C++ (for the SSLD devices ).
O pen s treet light protocol does not us e ASN.1 but Google Protocol Buffers . T he main reas on for this is the lack of a good
quality free ASN.1 compiler for Java or C. Google Protocol Buffers offers a fas t and free compiler for Java and C which
produces s mall mes s age s izes .
Protocol security
Public/private key pair
Signing of mes s ages through Elliptic Curve DSA 256 bit Inte g rity of the me s s ag e is e ns ure d Sender identity is
ens ured ** No encryption, becaus e content is not confidential
Replay attack prevention
Special note on Java security provider:
When both the DLMS and O SLP providers are deloyed within the s ame Java VM, the SunEC provider will not work properly.
T o workaround this is s ue, the SunPKCS11-NSS provider mus t be us ed for the O SLP protocol adapter. By default this
provider is enabled on the development VM.
OSLP v0.5.1 (Deprecated)

T he protobuf contract for O SLP v0.5.1. For v0.5.1 port number 12121 is us ed.
OSLP v0.6.1
T he protobuf contract for O SLP v0.6.1. For v0.6.1 port number 12122 is us ed.
OSLP Envelope
T he reques ts and res pons es are s ent us ing an O SLP envelope. T his s tructure contains the following fields : s ecurityKey,
s equenceNumber, deviceId and payloadMes s age. T he firs t 3 field are byte arrays , the payloadMes s age is a protobuf type
which is s erializable.
class OslpEnvelope {
/**
* Length of the security hash.
* Length for ECDSA is 71 or 72 or 73 bytes.
* Length for RSA is 128 bytes.
*/
public static final int SECURITY_KEY_LENGTH = 128;
/**
* Length of the sequence number.
*/
public static final int SEQUENCE_NUMBER_LENGTH = 2;
/**
* Length of the manufacturer id.
*/
public static final int MANUFACTURER_ID_LENGTH = 2;
/**
* Length of the device id.
*/
public static final int DEVICE_ID_LENGTH = 10;
/**
* Length of the length.
*/
public static final int LENGTH_INDICATOR_LENGTH = 2;
O SLP 220
/**
* Buffer for security key bytes.
*/
public byte[] securityKey = new byte[SECURITY_KEY_LENGTH];
/**
* Buffer for sequence number bytes.
*/
public byte[] sequenceNumber = new byte[SEQUENCE_NUMBER_LENGTH];
/**
* Buffer for deviceid bytes.
*/
public byte[] deviceId = new byte[DEVICE_ID_LENGTH + MANUFACTURER_ID_LENGTH];
/**
* Buffer for OSLP payload.
*/
public Message payloadMessage;
}
O SLP 221
OSLP v0.5.1
Contract
NO T E: O SLP v0.5.1 is deprecated.
Contract for v0.5.1
O SLP v0.5.1 222

Protobuf Contract
OSLP protobuf file, v0.5.1
// import "nanopb.proto";
package oslp;
option java_package = "com.alliander.osgp.oslp";
message Message {
optional RegisterDeviceRequest registerDeviceRequest = 1;
optional RegisterDeviceResponse registerDeviceResponse = 2;
optional StartSelfTestRequest startSelfTestRequest = 3;
optional StartSelfTestResponse startSelfTestResponse = 4;
optional StopSelfTestRequest stopSelfTestRequest = 5;
optional StopSelfTestResponse stopSelfTestResponse = 6;
optional UpdateFirmwareRequest updateFirmwareRequest = 7;
optional UpdateFirmwareResponse updateFirmwareResponse = 8;
optional SetLightRequest setLightRequest = 9;
optional SetLightResponse setLightResponse = 10;
optional GetStatusRequest getStatusRequest = 11;
optional GetStatusResponse getStatusResponse = 12;
optional ResumeScheduleRequest resumeScheduleRequest = 13;
optional ResumeScheduleResponse resumeScheduleResponse = 14;
optional SetEventNotificationsRequest setEventNotificationsRequest = 15;
optional SetEventNotificationsResponse setEventNotificationsResponse = 16;
optional EventNotificationRequest eventNotificationRequest = 17;
optional EventNotificationResponse eventNotificationResponse = 18;
optional GetFirmwareVersionRequest getFirmwareVersionRequest = 19;
optional GetFirmwareVersionResponse getFirmwareVersionResponse = 20;
optional SetScheduleRequest setScheduleRequest = 21;
optional SetScheduleResponse setScheduleResponse = 22;
optional SetConfigurationRequest setConfigurationRequest = 25;
optional SetConfigurationResponse setConfigurationResponse = 26;
optional GetPowerUsageHistoryRequest getPowerUsageHistoryRequest = 27;
optional GetPowerUsageHistoryResponse getPowerUsageHistoryResponse = 28;
optional GetActualPowerUsageRequest getActualPowerUsageRequest = 29;
optional GetActualPowerUsageResponse getActualPowerUsageResponse = 30;
optional SetRebootRequest setRebootRequest = 31;
optional SetRebootResponse setRebootResponse = 32;
optional SetTransitionRequest setTransitionRequest = 33;
optional SetTransitionResponse setTransitionResponse = 34;
optional GetConfigurationRequest getConfigurationRequest = 35;
optional GetConfigurationResponse getConfigurationResponse = 36;
optional ConfirmRegisterDeviceRequest confirmRegisterDeviceRequest = 37;
optional ConfirmRegisterDeviceResponse confirmRegisterDeviceResponse = 38;
}
// ========= Device Installation

message RegisterDeviceRequest {
required string deviceIdentification = 1; // [(nanopb).max_size = 41];
required bytes ipAddress = 2; // [(nanopb).max_size = 4];
required DeviceType deviceType = 3;
required bool hasSchedule = 4;
required uint32 randomDevice = 5; // 16 bits
}
message RegisterDeviceResponse {
required Status status = 1;
required string currentTime = 2; // [(nanopb).max_size = 15];// - format YYYYMMDDhhmmss UTC
required uint32 randomDevice = 3;
required uint32 randomPlatform = 4;
optional LocationInfo locationInfo = 5; // Location information of device
}
message StartSelfTestRequest {
optional bool present = 1 [default = true];
}
message StartSelfTestResponse {
O SLP v0.5.1 223


}
message StopSelfTestRequest {
}
message StopSelfTestResponse {
required bytes selfTestResult = 2; // [(nanopb).max_size = 1];
}
// ========= Firmware Management

message GetFirmwareVersionRequest {
}
message GetFirmwareVersionResponse {
required string firmwareVersion = 1; // [(nanopb).max_size = 7]; // RXX
}
message UpdateFirmwareRequest {
required string firmwareDomain = 1; // [(nanopb).max_size = 100]; // Servername
required string firmwareUrl = 2; // [(nanopb).max_size = 255]; // /firmware/PSLD/RXX
}
message UpdateFirmwareResponse {
}
// ========= Ad-Hoc & Status

message SetLightRequest {
repeated LightValue values = 1; // [(nanopb).max_count = 6];
}
message SetLightResponse {
}
message GetStatusRequest {
}
message GetStatusResponse {
repeated LightValue value = 2; // [(nanopb).max_count = 6];
required LinkType preferredLinktype = 3;
required LinkType actualLinktype = 4;
required LightType lightType = 5;
required uint32 eventNotificationMask = 6; // Bitmask for max 32 events, using NotificationBit for bi
}
message ResumeScheduleRequest {
optional bytes index = 1; // [(nanopb).max_size = 1]; // index number of connected light (DALI), none
required bool immediate = 2; // [default = false]; // Resume at next schedule item or direct
}
message ResumeScheduleResponse {
}
message SetRebootRequest {
}
message SetRebootResponse {
}
message SetTransitionRequest {
required TransitionType transitionType = 1; // Night-Day or Day-Night transition
optional string time = 2; // [(nanopb).max_size = 7]; // - format hhmmss UTC
O SLP v0.5.1 224

message SetTransitionResponse {
}
message SetEventNotificationsRequest {
required uint32 NotificationMask = 1; // Bitmask for max 32 events, using NotificationBit for bit po
}
message SetEventNotificationsResponse {
}
message EventNotificationRequest {
repeated EventNotification notifications = 1; // [(nanopb).max_count = 6];
}
message EventNotificationResponse {
}
// ========= Scheduling
message SetScheduleRequest {
repeated Schedule schedules = 1; // [(nanopb).max_count = 50];
optional PageInfo pageInfo = 2;
required RelayType scheduleType = 3; // RT_NOT_SET is NOT supported!
}
message SetScheduleResponse {
}
// ========= Configuration
message SetConfigurationRequest {
optional LightType lightType = 1;
optional DaliConfiguration daliConfiguration = 2; // contains specific configuration for DALI contro
optional RelayConfiguration relayConfiguration = 3; // contains specific configuration for Relay
optional uint32 shortTermHistoryIntervalMinutes = 4;
optional LinkType preferredLinkType = 5;
optional MeterType meterType = 6;
optional uint32 longTermHistoryInterval = 7;
optional LongTermIntervalType longTermHistoryIntervalType = 8;
}
message SetConfigurationResponse {
}
message GetConfigurationRequest {
}
message GetConfigurationResponse {
optional DaliConfiguration daliConfiguration = 3; // contains specific configuration for DALI contro
optional RelayConfiguration relayConfiguration = 4; // contains specific configuration for Relay
}
message ConfirmRegisterDeviceRequest {
}
message ConfirmRegisterDeviceResponse {
O SLP v0.5.1 225


required uint32 sequenceWindow = 4;
}
// ========= Monitoring
message GetPowerUsageHistoryRequest {
required TimePeriod timePeriod = 1;
optional uint32 page = 2;
required HistoryTermType termType = 3;
}
message GetPowerUsageHistoryResponse {
repeated PowerUsageData powerUsageData = 2; // [(nanopb).max_count = 20];
}
message GetActualPowerUsageRequest {
}
message GetActualPowerUsageResponse {
required PowerUsageData powerUsageData = 2;
}
// ========= Types
message LocationInfo {
optional sint32 timeOffset = 1; // correction in minutes with respect to UTC
optional sint32 latitude = 2; // divide by 1000000 to get float value
optional sint32 longitude = 3; // divide by 1000000 to get float value
}
message LightValue {
required bool on = 2;
optional bytes dimValue = 3; // [(nanopb).max_size = 1]; // 1 - 100 %
}
message EventNotification {
required Event event = 1;
optional bytes index = 2; // [(nanopb).max_size=1];
optional string description = 3; // [(nanopb).max_size = 81];
}
message Schedule {
required Weekday weekday = 1;
optional string startDay = 2; // [(nanopb).max_size = 9]; //- format YYYYMMDD UTC, indicates the ran
optional string endDay = 3; // [(nanopb).max_size = 9]; // - format YYYYMMDD UTC, including endDay
required ActionTime actionTime = 4;
optional string time = 5; // [(nanopb).max_size = 7]; // - format hhmmss localtime set when actionTim
optional Window window = 6; // window to wait for light sensor trigger
optional TriggerType triggerType = 8; // React to setTransition or switch astronomical
}
message Window {
required uint32 minutesBefore = 1; // minutes before sunset / sunrise
required uint32 minutesAfter = 2; // minutes after sunset / sunrise
}
message DaliConfiguration {
optional bytes numberOfLights = 1; // [(nanopb).max_size = 1]; // number of lights connected to DALI
repeated IndexAddressMap addressMap = 2; // [(nanopb).max_count = 4];
}
message RelayConfiguration {
}
message IndexAddressMap {
O SLP v0.5.1 226

required bytes index = 1; // [(nanopb).max_size = 1]; // external index, for example 1

required bytes address = 2; // [(nanopb).max_size = 1]; // internal address, for example 2
required RelayType relayType = 3;
}
message PageInfo {
required uint32 currentPage = 1; // Pages start from 1
required uint32 pageSize = 2;
required uint32 totalPages = 3;
}
message TimePeriod {
required string startTime = 1; // [(nanopb).max_size = 15]; // - format YYYYMMDDhhmmss UTC
required string endTime = 2; // [(nanopb).max_size = 15]; // - format YYYYMMDDhhmmss UTC
}
message PowerUsageData {
required string recordTime = 1; // [(nanopb).max_size = 15]; // Record time - format YYYYMMDDhhmm
required MeterType meterType = 2; // Meter type (P1, Pulse, Aux)
required uint64 totalConsumedEnergy = 3; // Electricity delivered to client (T
required uint32 actualConsumedPower = 4; // Actual Electricity power delivered
optional PsldData psldData = 5;
optional SsldData ssldData = 6;
}
message PsldData {
required uint32 totalLightingHours = 1; // Total lighting hours
}
message SsldData {
required uint32 actualCurrent1 = 1; // Instantaneous current L1 in mA
required uint32 actualPower1 = 4; // Instantaneous active power L1 in W
required uint32 averagePowerFactor1 = 7; // Power factor L1 (in 1/2^32) in steps of 0.1, 10 e
repeated RelayData relayData = 10; // [(nanopb).max_count = 4]; // Measurement data per relay
}
message RelayData {
required uint32 totalLightingMinutes = 2; // Total lighting minutes for lighting relay
}
// ========= Enumerations
// ========= Event Notification

enum NotificationBit {
DIAG_EVENTS = 1;
HARDWARE_FAILURE = 2;
LIGHT_EVENTS = 4; // For example LightValue changes
TARIFF_EVENTS = 8; // For example Tariff changes
MONITOR_EVENTS = 16; // For example monitor buffer is almost full
FIRMWARE_EVENTS = 32; // For example firmware activation
COMM_EVENTS = 64; // For example alternative channel
SECURITY_EVENTS = 128; // For example out of sequence
}
//Events must map to their notification bit:

//EG: 0000-0999 =1
// 1000-1999 =2
// 2000-2999 =4
// 3000-3999 =8
// 4000-4999 =16
// 5000-5999 =32
// 6000-6999 =64
// 7000-7999 =128
// OR to check 2^((event num)/1000)=notification bit
O SLP v0.5.1 227

enum Event {
// 0 - 999 Diagnostics
DIAG_EVENTS_GENERAL = 0;
// 1000 - 1999 Hardware Failures

HARDWARE_FAILURE_RELAY = 1000; // Index indicates relay (not supported yet)
// 2000 - 2999 Light Events

LIGHT_EVENTS_LIGHT_ON = 2000; // Index indicates light
LIGHT_EVENTS_LIGHT_OFF = 2001; // Index indicates light
LIGHT_FAILURE_DALI_COMMUNICATION = 2500; // DALI communication failure
LIGHT_FAILURE_BALLAST = 2501; // Ballast failure detected (DALI only)
LIGHT_FAILURE_TARIFF_SWITCH_ATTEMPT = 2502; // Attempt to switch an endpoint configured as tariff fro
// 3000 - 3999 Tariff Events

TARIFF_EVENTS_TARIFF_ON = 3000; // Tariff switched on
TARIFF_EVENTS_TARIFF_OFF = 3001; // Tariff switched off
// 4000 - 4999
MONITOR_EVENTS_LONG_BUFFER_FULL = 4000; // Long term monitoring buffer overrun occurred
MONITOR_FAILURE_P1_COMMUNICATION = 4500; // P1 meter could not be read
MONITOR_SHORT_DETECTED = 4600;
MONITOR_SHORT_RESOLVED = 4601;
MONITOR_DOOR_OPENED = 4700;
MONITOR_DOOR_CLOSED = 4701;
// 5000 - 5999 Firmware Events

FIRMWARE_EVENTS_ACTIVATING = 5000; // Start activating new firmware, after downloading
FIRMWARE_EVENTS_DOWNLOAD_NOTFOUND = 5501; // Download of firmware failed, i.e. location incorrect
FIRMWARE_EVENTS_DOWNLOAD_FAILED = 5502; // Download of firmware failed, image incorrect
// 6000 – 6999
COMM_EVENTS_ALTERNATIVE_CHANNEL = 6000; // Alternative channel selected for communication (descripti
COMM_EVENTS_RECOVERED_CHANNEL = 6001; // Communication has been recovered for this channel
// 7000 - 7999
SECURITY_EVENTS_OUT_OF_SEQUENCE = 7000; // Out of sequence occurred and sequence number is renegotia
}
// ========= Enums
enum TriggerType {
TT_NOT_SET = 0;
LIGHT_TRIGGER = 1;
ASTRONOMICAL = 2;
}
enum TransitionType {
NIGHT_DAY = 0;
DAY_NIGHT = 1;
}
enum Weekday {
MONDAY = 1;
TUESDAY = 2;
WEDNESDAY = 3;
THURSDAY = 4;
FRIDAY = 5;
SATURDAY = 6;
SUNDAY = 7;
WEEKDAY = 8;
WEEKEND = 9;
ABSOLUTEDAY = 10;
ALL = 11;
}
enum ActionTime {
ABSOLUTETIME = 1;
SUNRISE = 2;
SUNSET = 3;
}
O SLP v0.5.1 228

enum DeviceType {
PSLD = 0;
SSLD = 1;
}
enum Status {
OK = 0;
FAILURE = 1; // general failure
REJECTED = 2; // request received in wrong state
}
enum LightType {
LT_NOT_SET = 0;
RELAY = 1;
ONE_TO_TEN_VOLT = 2;
ONE_TO_TEN_VOLT_REVERSE = 3;
DALI = 4;
}
enum RelayType {
RT_NOT_SET = 0;
LIGHT = 1;
TARIFF = 2;
}
enum MeterType {
MT_NOT_SET = 0;
P1 = 1;
PULSE = 2;
AUX = 3;
}
enum LinkType {
LINK_NOT_SET = 0;
GPRS = 1;
CDMA = 2;
ETHERNET = 3;
}
enum LongTermIntervalType {
LT_INT_NOT_SET = 0;
DAYS = 1;
MONTHS = 2;
}
enum HistoryTermType {
Short = 0;
Long = 1;
}
O SLP v0.5.1 229

OSLP v0.6.1
Contract
Contract for v0.6.1
Mes s ag es
T hes e mes s ages below are part of O SLP v0.6.1. Note that O SLP v0.6.1 is backwards compatible with O SLP v0.5.1.
T herefore, v0.6.1 offers the s ame Regis terDeviceReques t as v0.5.1 for example.
Re g is te rDe vice Re q ue s t (from device to platform) is a reques t that notifies the platform a device which wants to
regis ter. During the regis tration the s equence number is res et to a random value, the platform is notified if the device
has a light s chedule, the type of the device, the device identification, and the device communicates its IP addres s to
the platform.
Re g is te rDe vice Re s p ons e (from platform to device) is a res pons e which holds the time of the platform s o the device
can s ynchronize the time, contains location information for the device like GPS coordinates and Day Light Saving time
information. T he device will s ent ConfirmRegis terDeviceReques t after receiving the Regis terDeviceRes pons e.
ConfirmRe g is te rDe vice Re q ue s t (from device to platform) is a reques t that notifies the platform that a device
wants to perform the s econd s tep of the regis tration proces s .
ConfirmRe g is te rDe vice Re s p ons e (from platform to device) is a res pons e which confirms the
ConfirmRegis terDeviceReques t has been executed or rejected.
S tartS e lfT e s tRe q ue s t (from platform to device) is a reques t that notifies the device to s witch all relays on.
S tartS e lfT e s tRe s p ons e (from device to platform) is a res pons e which confirms the StartSelfT es tReques t has been
executed or rejects the StartSelfT es tReques t.
S top S e lfT e s tRe q ue s t (from platform to device) is a reques t that notifies the device to s witch all relays off.
S top S e lfT e s tRe s p ons e (from device to platform) is a res pons e which confirms the StopSelfT es tRes pons e has been
executed or rejects the StopSelfT es tRes pons e.
Up d ate Firmware Re q ue s t (from platform to device) is a reques t which notifies the device to download a new
firmware vers ion from a s erver us ing a URL.
Up d ate Firmware Re s p ons e (from device to platform) is a res pons e which confirms the UpdateFirmwareReques t
has been executed or rejects the UpdateFirmwareReques t. Pleas e note there are s everal events which are s ent from
the device to the platform to inform the platform when the firmware has been downloaded and whether or not the
firmware was s ucces s fully activated.
S e tLig htRe q ue s t (from platform to device) is a reques t that notifies the device to s witch on or off one ore s everal
light relays , optionally with a dim-value per relay.
S e tLig htRe s p ons e (from device to platform) is a res pons e which confirms the SetLightReques t has been executed
or rejected.
Ge tS tatus Re q ue s t (from platform to device) is a reques t that requires the device to s end the s tatus of all relays ,
current network link and preferred network link, the type of configuration (PSLD vs SSLD), and the event notification
mas k which has been s et.
Ge tS tatus Re s p ons e (from device to platform) is a res pons e which confirms the GetStatus Reques t has been
executed and returns the current s tatus for all of the relays and other information or rejects the GetStatus Reques t.
Re s ume S che d ule Re q ue s t (from platform to device) is a reques t that notifies the device to continue the current
s chedule after the current s chedule was interrupted (for example by s witching by hand us ing SetLightReques t). T his
reques t can operate on a s ingle relay or on all relays and the res uming of the s chedule can be immediate or at the next
s chedule-entry.
Re s ume S che d ule Re s p ons e (from device to platform) is a res pons e which confirms the Res umeScheduleReques t
has been executed or rejected.
S e tEve ntNotifications Re q ue s t (from platform to device) is a reques t that s ets the event notification mas k.
S e tEve ntNotifications Re s p ons e (from device to platform) is a res pons e which confirms the SetEventNotifications
reques t has been executed or rejected.
Eve ntNotificationRe q ue s t (from device to platform) is a reques t that pus hes an event notification from a device to
the platform.
O SLP v0.6.1 230

Eve ntNotificationRe s p ons e (from platform to device) is a res pons e which confirms the EventNotificationReques t
Ge tFirmware Ve rs ionRe q ue s t (from platform to device) is a reques t that reques ts the device to s ent its current
firmware vers ion.
Ge tFirmware Ve rs ionRe s p ons e (from device to platform) is a res pons e that s ends the current firmware vers ion to
the platform.
S e tS che d ule Re q ue s t (from platform to device) is a reques t that s ends a light or tariff s chedule to the device.
S e tS che d ule Re s p ons e (from device to platform) is a res pons e which confirms the SetScheduleReques t has been
executed or rejected.
S e tConfig urationRe q ue s t (from platform to device) is a reques t that s ends configuration s ettings to the device.
S e tConfig urationRe s p ons e (from device to platform) is a res pons e which confirms the SetConfigurationReques t
Ge tConfig urationRe q ue s t (from platform to device) is a reques t that reques ts the device to s end its current
configuration s ettings .
Ge tConfig urationRe s p ons e (from device to platform) is a res pons e which confirms the GetConfigurationReques t
Ge tPowe rUs ag e His toryRe q ue s t (from platform to device) is a reques t that reques ts the device to s end the content
of its power us age regis ters .
Ge tPowe rUs ag e His toryRe s p ons e (from device to platform) is a res pons e which confirms the
GetPowerUs ageHis toryReques t has been executed or rejected and contains the power us age data.
S e tRe b ootRe q ue s t (from platform to device) is a reques t that notifies the device to reboot immediately.
S e tRe b ootRe s p ons e (from device to platform) is a res pons e which confirms the SetRebootReques t has been
S e tT rans itionRe q ue s t (from platform to device) is a reques t that notifies the device to s witch its light relays
according to light meas urement s chedule-entries .
S e tT rans itionRe s p ons e (from device to platform) is a res pons e which confirms the SetT rans itionReques t has been
Up d ate De vice S s lCe rtificationRe q ue s t (from platform to device)
Up d ate De vice S s lCe rtificationRe s p ons e (from platform to device)
S e tDe vice Ve rificationKe yRe q ue s t (from platform to device)
S e tDe vice Ve rificationKe yRe s p ons e (from platform to device)
S witchFirmware Re q ue s t (from platform to device)
S witchFirmware Re s p ons e (from platform to device)
S witchConfig urationRe q ue s t (from platform to device)
S witchConfig urationRe s p ons e (from platform to device)
O SLP v0.6.1 231

RegisterDevice
RegisterDevice messages
Des cription
Note: the device regis tration is a 2 s tep proces s . Firs t Regis terDeviceReques t and Regis terDeviceRes pons e are exchanged
between device and platform. Second ConfirmRegis terDeviceReques t and ConfirmRegis terDeviceRes pons e mes s ages are
exchanged.
Reques t that notifies the platform a device which wants to regis ter. During the regis tration the s equence number is res et to a
random value the platform is notified if the device has a light s chedule, the type of the device, the device identification, and the
device communicates its IP addres s to the platform. Als o a random number is determined by the device and this
'randomDevice' s hould be pres ent in the res pons e form the platform.
Res pons e which holds the time of the platform s o the device can s ynchronize the time, contains location information for the
device like GPS coordinates and Daylight Saving T ime information. T he device will s ent ConfirmRegis terDeviceReques t after
receiving the Regis terDeviceRes pons e. Als o a random number is determined by the platform and this 'randomPlatform'
s hould be pres ent in the next reques t 'ConfirmRegis terDeviceReques t' by the device.
Mes s ag e definitions
}
required string currentTime = 2; // [(nanopb).max_size = 15];// - format YYYYMMDDhhmmss UTC
optional LocationInfo locationInfo = 5; // Location information of device
}
Datatypes
enum DeviceType {
PSLD = 0;
SSLD = 1;
}
enum Status {
OK = 0;
}
optional sint32 timeOffset = 1; // correction in minutes with respect to UTC
optional sint32 latitude = 2; // divide by 1000000 to get float value
optional sint32 longitude = 3; // divide by 1000000 to get float value
}
Example
O SLP Regis terDeviceReques t s ent from 'device-01' to platform:
registerDeviceRequest {
deviceIdentification: "device-01"
ipAddress: "#\000\000\001"
deviceType: SSLD
hasSchedule: false
randomDevice: 13246
}
O SLP Regis terDeviceRes pons e s ent from platform to 'device-01':
O SLP v0.6.1 232

registerDeviceResponse {
status: OK
currentTime: "20160106135210"
randomDevice: 13246
randomPlatform: 44765
locationInfo {
timeOffset: 60
latitude: 50889228
longitude: 5974140
}
}
O SLP v0.6.1 233

ConfirmRegisterDevice
ConfirmRegisterDevice messages
Des cription
Reques t which contains the 2 random numbers from Regis terDeviceReques t and Regis terDeviceRes pons e. T he numbers
s hould match with the previous reques t and res pons e and this is checked by the platform.
Res pons e which contains the s equenceWindow which is the maximum allowed difference between s equence numbers for
future mes s ages . Further the res pons e contains the 2 random numbers from the ConfirmRegis terDeviceReques t. T he
numbers s hould match with the previous reques t and res pons e and this is checked by the device.
}
}
Datatypes
enum Status {
OK = 0;
}
Example
O SLP ConfirmRegis terDeviceReques t s ent from 'device-01' to platform:
confirmRegisterDeviceRequest {
randomDevice: 13246
}
O SLP ConfirmRegis terDeviceRes pons e s ent from platform to 'device-01':
confirmRegisterDeviceResponse {
status: OK
randomDevice: 13246
sequenceWindow: 6
}
O SLP v0.6.1 234

GetConfiguration
GetConfiguration messages
Des cription
Reques t to fetch the current configuration of a device.
Res pons e communicates if the reques t was executed. If 's tatus = O K' then the optional fields will be partly populated. Note
that DaliConfiguration is only pres ent for devices with 'lightT ype = DALI', which are of device type PSLD. Note that
RelayConfiguration is only pres ent for devices with 'lightT ype = RELAY | O NE_T O _T EN_VO LT |
O NE_T O _T EN_VO LT _REVERSE', which are of device type SSLD.
}
optional DaliConfiguration daliConfiguration = 3; // Contains spec
optional RelayConfiguration relayConfiguration = 4; // Contains spec
optional uint32 timeSyncFrequency = 10 [default = 86400]; // Time synch fr
optional bytes deviceFixIpValue = 11; // [(nanopb).max_count = 4]; // The fixed IP a
optional bytes netMask = 12; // [(nanopb).max_count = 4]; // Network mask
optional bytes gateWay = 13; // [(nanopb).max_count = 4]; // Gateway addre
optional bool isDhcpEnabled = 14 [default = true]; // Is DHCP enabl
optional bool isTlsEnabled = 15; // Defines if TLS
optional uint32 oslpBindPortNumber = 16; // The port used
optional string commonNameString = 17 [default = 'TLS Test']; //[default = 'TLS Test',(nanopb).max_co
optional uint32 communicationTimeout = 18 [default = 20]; // Communication
optional uint32 communicationNumberOfRetries = 19 [default = 3]; // Communication
optional uint32 communicationPauseTimeBetweenConnectionTrials = 20 [default = 60]; // Time between
optional bytes ospgIpAddress = 21; // [(nanopb).max_count = 4]; // The IP addres
optional uint32 osgpPortNumber = 22; // The port numb
optional bool isTestButtonEnabled = 23 [default = true]; // Is the test b
optional bool isAutomaticSummerTimingEnabled = 24 [default = true]; // Is the automa
optional sint32 astroGateSunRiseOffset = 25 [default = 0]; // The calculate
optional sint32 astroGateSunSetOffset = 26 [default = 0]; // The calculate
repeated uint32 switchingDelay = 27; // [(nanopb).max_count = 4]; // Switching dela
repeated RelayMatrix relayLinking = 28; // Relay linking
optional bool relayRefreshing = 29 [default = true]; // Is relayRefre
optional string summerTimeDetails = 30 [default = '0360100']; //[default = '0360100',(nanopb).max_co
optional string winterTimeDetails = 31 [default = '1060200']; //[default = '1060200',(nanopb).max_co
}
Datatypes
enum Status {
OK = 0;
}
enum LightType {
LT_NOT_SET = 0;
RELAY = 1;
DALI = 4;
}
O SLP v0.6.1 235


}
}
}
enum RelayType {
RT_NOT_SET = 0;
LIGHT = 1;
TARIFF = 2;
}
enum LinkType {
LINK_NOT_SET = 0;
GPRS = 1;
CDMA = 2;
ETHERNET = 3;
}
enum MeterType {
MT_NOT_SET = 0;
P1 = 1;
PULSE = 2;
AUX = 3;
}
LT_INT_NOT_SET = 0;
DAYS = 1;
MONTHS = 2;
}
message RelayMatrix {
required bytes masterRelayIndex = 1; // [(nanopb).max_count = 1];
required bool masterRelayOn = 2; // [(nanopb).max_count = 1];
optional bytes indicesOfControlledRelaysOn = 3; // [(nanopb).max_count = 4]; // IndexNumber of outp
optional bytes indicesOfControlledRelaysOff = 4; // [(nanopb).max_count = 4]; // IndexNumber of outp
}
Example
Soap reques ts and res pons es s ent to and from platform:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:com="http://www.alliand

<soapenv:Header>
<com:OrganisationIdentification>LianderNetManagement</com:OrganisationIdentification>
<com:UserName>Kevin</com:UserName>
<com:ApplicationName>SoapUI</com:ApplicationName>
</soapenv:Header>
<soapenv:Body>
<con:GetConfigurationRequest>
<con:DeviceIdentification>device-01</con:DeviceIdentification>
</con:GetConfigurationRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:GetConfigurationAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/configurationm
<ns2:AsyncResponse>
<ns3:CorrelationUid>LianderNetManagement|||device-01|||20161007142028655</ns3:CorrelationUid
<ns3:DeviceId>device-01</ns3:DeviceId>
</ns2:GetConfigurationAsyncResponse>
O SLP v0.6.1 236

</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<con:GetConfigurationAsyncRequest>
<con:AsyncRequest>
<com:CorrelationUid>LianderNetManagement|||device-01|||20161007142028655</com:CorrelationUi
<com:DeviceId>device-01</com:DeviceId>
</con:AsyncRequest>
</con:GetConfigurationAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:GetConfigurationResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/configurationmanage
<ns2:Result>OK</ns2:Result>
<ns2:Configuration>
<ns2:LightType>RELAY</ns2:LightType>
<ns2:RelayConfiguration>
<ns2:RelayMap>
<ns2:Address>1</ns2:Address>
<ns2:RelayType>TARIFF</ns2:RelayType>
</ns2:RelayMap>
<ns2:RelayMap>
<ns2:RelayType>LIGHT</ns2:RelayType>
</ns2:RelayMap>
<ns2:RelayMap>
</ns2:RelayMap>
<ns2:RelayMap>
</ns2:RelayMap>
</ns2:RelayConfiguration>
<ns2:ShortTermHistoryIntervalMinutes>15</ns2:ShortTermHistoryIntervalMinutes>
<ns2:PreferredLinkType>ETHERNET</ns2:PreferredLinkType>
<ns2:LongTermHistoryInterval>1</ns2:LongTermHistoryInterval>
<ns2:TimeSyncFrequency>86400</ns2:TimeSyncFrequency>
<ns2:DeviceFixedIp>
<ns2:IpAddress>192.168.0.100</ns2:IpAddress>
<ns2:NetMask>255.255.255.0</ns2:NetMask>
<ns2:GateWay>192.168.0.1</ns2:GateWay>
</ns2:DeviceFixedIp>
<ns2:DhcpEnabled>false</ns2:DhcpEnabled>
<ns2:TlsEnabled>true</ns2:TlsEnabled>
<ns2:TlsPortNumber>1234</ns2:TlsPortNumber>
<ns2:CommonNameString>TLS Test</ns2:CommonNameString>
<ns2:CommunicationTimeout>30</ns2:CommunicationTimeout>
<ns2:CommunicationNumberOfRetries>5</ns2:CommunicationNumberOfRetries>
<ns2:CommunicationPauseTimeBetweenConnectionTrials>120</ns2:CommunicationPauseTimeBetweenCon
<ns2:OsgpIpAddress>168.63.97.65</ns2:OsgpIpAddress>
<ns2:OsgpPortNumber>12122</ns2:OsgpPortNumber>
<ns2:TestButtonEnabled>false</ns2:TestButtonEnabled>
<ns2:AutomaticSummerTimingEnabled>false</ns2:AutomaticSummerTimingEnabled>
<ns2:AstroGateSunRiseOffset>-15</ns2:AstroGateSunRiseOffset>
<ns2:AstroGateSunSetOffset>15</ns2:AstroGateSunSetOffset>
<ns2:SwitchingDelays>1</ns2:SwitchingDelays>
O SLP v0.6.1 237

<ns2:RelayLinking>
<ns2:MasterRelayIndex>2</ns2:MasterRelayIndex>
<ns2:MasterRelayOn>false</ns2:MasterRelayOn>
<ns2:IndicesOfControlledRelaysOn>3</ns2:IndicesOfControlledRelaysOn>
<ns2:IndicesOfControlledRelaysOn>4</ns2:IndicesOfControlledRelaysOn>
<ns2:IndicesOfControlledRelaysOff>3</ns2:IndicesOfControlledRelaysOff>
<ns2:IndicesOfControlledRelaysOff>4</ns2:IndicesOfControlledRelaysOff>
</ns2:RelayLinking>
<ns2:RelayRefreshing>false</ns2:RelayRefreshing>
<ns2:SummerTimeDetails>2016-03-27T01:00:00.000+01:00</ns2:SummerTimeDetails>
<ns2:WinterTimeDetails>2016-10-30T02:00:00.000+02:00</ns2:WinterTimeDetails>
</ns2:Configuration>
</ns2:GetConfigurationResponse>
</SOAP-ENV:Body>
O SLP GetConfigurationReques t mes s age s ent to 'device-01':
getConfigurationRequest {
}
O SLP GetConfigurationRes pons e mes s age s ent to platform:
getConfigurationResponse {
status: OK
lightType: RELAY
relayConfiguration {
addressMap {
index: "\001"
address: "\001"
relayType: TARIFF
}
addressMap {
index: "\002"
address: "\002"
relayType: LIGHT
}
addressMap {
index: "\003"
address: "\003"
relayType: LIGHT
}
addressMap {
index: "\004"
address: "\004"
relayType: LIGHT
}
}
shortTermHistoryIntervalMinutes: 15
preferredLinkType: ETHERNET
meterType: MT_NOT_SET
longTermHistoryInterval: 1
longTermHistoryIntervalType: LT_INT_NOT_SET
timeSyncFrequency: 86400
deviceFixIpValue: "\300\250\000d"
netMask: "\377\377\377\000"
gateWay: "\300\250\000\001"
isDhcpEnabled: false
isTlsEnabled: true
oslpBindPortNumber: 1234
commonNameString: "TLS Test"
communicationTimeout: 30
communicationNumberOfRetries: 5
communicationPauseTimeBetweenConnectionTrials: 120
ospgIpAddress: "\250?aA"
osgpPortNumber: 12122
isTestButtonEnabled: false
isAutomaticSummerTimingEnabled: false
astroGateSunRiseOffset: -15
astroGateSunSetOffset: 15
switchingDelay: 1
O SLP v0.6.1 238

switchingDelay: 2
switchingDelay: 3
switchingDelay: 4
relayLinking {
masterRelayIndex: "\002"
masterRelayOn: false
indicesOfControlledRelaysOn: "\003\004"
indicesOfControlledRelaysOff: "\003\004"
}
relayRefreshing: false
summerTimeDetails: "0360100"
winterTimeDetails: "1060200"
}
O SLP v0.6.1 239

SetConfiguration
SetConfiguration messages
Des cription
Reques t to pus h configuration s ettings to a device.
Res pons e communicates s tatus .
optional bytes deviceFixIpValue = 10; // [(nanopb).max_count = 4]; // The fixed IP
}
// summerTimeDetails string, winterTimeDetails:
//MMWHHmi
//
//where: (note, north hemisphere summer begins at the end of march)
//MM: month
//W: day of the week (0- Monday, 6- Sunday)
//HH: hour of the changing time
//mi: minutes of the changing time
}
Datatypes
enum LightType {
LT_NOT_SET = 0;
RELAY = 1;
DALI = 4;
}
}
O SLP v0.6.1 240

}
}
enum RelayType {
RT_NOT_SET = 0;
LIGHT = 1;
TARIFF = 2;
}
enum LinkType {
LINK_NOT_SET = 0;
GPRS = 1;
CDMA = 2;
ETHERNET = 3;
}
enum MeterType {
MT_NOT_SET = 0;
P1 = 1;
PULSE = 2;
AUX = 3;
}
LT_INT_NOT_SET = 0;
DAYS = 1;
MONTHS = 2;
}
}
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<con:SetConfigurationRequest>
<con:DeviceIdentification>device-01</con:DeviceIdentification>

<con:Configuration>


<con:LightType>RELAY</con:LightType>

<con:RelayConfiguration>
O SLP v0.6.1 241

<con:RelayMap>
<con:Index>1</con:Index>
<con:Address>1</con:Address>

<con:RelayType>TARIFF</con:RelayType>
</con:RelayMap>
<con:RelayMap>
<con:RelayType>LIGHT</con:RelayType>
</con:RelayMap>
<con:RelayMap>
</con:RelayMap>
<con:RelayMap>
</con:RelayMap>
</con:RelayConfiguration>


<con:ShortTermHistoryIntervalMinutes>15</con:ShortTermHistoryIntervalMinutes>


<con:PreferredLinkType>ETHERNET</con:PreferredLinkType>


<con:MeterType>PULSE</con:MeterType>


<con:LongTermHistoryInterval>1</con:LongTermHistoryInterval>


<con:LongTermHistoryIntervalType>DAYS</con:LongTermHistoryIntervalType>
<con:TimeSyncFrequency>864000</con:TimeSyncFrequency>
<con:DeviceFixedIp>
<con:IpAddress>192.168.0.110</con:IpAddress>
<con:NetMask>255.255.255.0</con:NetMask>
<con:GateWay>192.168.0.1</con:GateWay>
</con:DeviceFixedIp>
<con:DhcpEnabled>false</con:DhcpEnabled>
<con:TlsEnabled>false</con:TlsEnabled>
<con:TlsPortNumber>1234</con:TlsPortNumber>
<con:CommonNameString>TLS Test</con:CommonNameString>
<con:CommunicationTimeout>15</con:CommunicationTimeout>
<con:CommunicationNumberOfRetries>2</con:CommunicationNumberOfRetries>
<con:CommunicationPauseTimeBetweenConnectionTrials>120</con:CommunicationPauseTimeBetweenCon
<con:OsgpIpAddress>192.168.100.42</con:OsgpIpAddress>
<con:OsgpPortNumber>12122</con:OsgpPortNumber>
<con:TestButtonEnabled>false</con:TestButtonEnabled>
<con:AutomaticSummerTimingEnabled>false</con:AutomaticSummerTimingEnabled>
<con:AstroGateSunRiseOffset>-15</con:AstroGateSunRiseOffset>
<con:AstroGateSunSetOffset>15</con:AstroGateSunSetOffset>

<con:SwitchingDelays>100</con:SwitchingDelays>
O SLP v0.6.1 242



<con:RelayLinking>
<con:MasterRelayIndex>1</con:MasterRelayIndex>
<con:MasterRelayOn>true</con:MasterRelayOn>



</con:SetConfigurationRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetConfigurationAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/configurationm
<ns2:AsyncResponse>
</ns2:SetConfigurationAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<con:SetConfigurationAsyncRequest>
<con:AsyncRequest>
</con:AsyncRequest>
</con:SetConfigurationAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetConfigurationResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/configurationmanage
O SLP v0.6.1 243

</ns2:SetConfigurationResponse>
</SOAP-ENV:Body>
O SLP SetConfigurationReques t s ent to 'device-01':
setConfigurationRequest {
lightType: RELAY
relayConfiguration {
addressMap {
index: "\001"
address: "\001"
relayType: TARIFF
}
addressMap {
index: "\002"
address: "\002"
relayType: LIGHT
}
addressMap {
index: "\003"
address: "\003"
relayType: LIGHT
}
addressMap {
index: "\004"
address: "\004"
relayType: LIGHT
}
}
shortTermHistoryIntervalMinutes: 15
preferredLinkType: ETHERNET
meterType: PULSE
longTermHistoryInterval: 1
longTermHistoryIntervalType: DAYS
timeSyncFrequency: 864000
deviceFixIpValue: "\300\250\000n"
netMask: "\377\377\377\000"
gateWay: "\300\250\000\001"
isDhcpEnabled: false
isTlsEnabled: false
oslpBindPortNumber: 1234
commonNameString: "TLS Test"
communicationTimeout: 15
communicationNumberOfRetries: 2
communicationPauseTimeBetweenConnectionTrials: 120
ospgIpAddress: "\300\250d*"
osgpPortNumber: 12122
isTestButtonEnabled: false
isAutomaticSummerTimingEnabled: false
astroGateSunRiseOffset: -15
astroGateSunSetOffset: 15
switchingDelay: 100
switchingDelay: 200
switchingDelay: 300
switchingDelay: 400
relayLinking {
masterRelayOn: true
indicesOfControlledRelaysOn: "\001\002\003\004"
indicesOfControlledRelaysOff: "\001\002\003\004"
}
relayLinking {
masterRelayOn: true
indicesOfControlledRelaysOn: "\003"
indicesOfControlledRelaysOff: "\003"
}
relayRefreshing: true
summerTimeDetails: "0360100"
winterTimeDetails: "1060200"
O SLP v0.6.1 244

O SLP SetConfigurationRes pons e s ent to platform:
setConfigurationResponse {
status: OK
}
O SLP v0.6.1 245

SetEventNotifications
SetEventNotifications messages
Des cription
Reques t which contains the EventNotification mas k.
}
}
Data types
enum Status {
OK = 0;
}
Example

<soapenv:Header>
<com:UserName>liander gebruiker</com:UserName>
<com:ApplicationName>WEB_NET_MANAGEMENT</com:ApplicationName>
</soapenv:Header>
<soapenv:Body>
<dev:SetEventNotificationsRequest>
<dev:DeviceIdentification>device-01</dev:DeviceIdentification>
<dev:EventNotifications>DIAG_EVENTS</dev:EventNotifications>
<dev:EventNotifications>HARDWARE_FAILURE</dev:EventNotifications>
<dev:EventNotifications>LIGHT_EVENTS</dev:EventNotifications>
<dev:EventNotifications>TARIFF_EVENTS</dev:EventNotifications>
<dev:EventNotifications>MONITOR_EVENTS</dev:EventNotifications>
<dev:EventNotifications>FIRMWARE_EVENTS</dev:EventNotifications>
<dev:EventNotifications>COMM_EVENTS</dev:EventNotifications>
<dev:EventNotifications>SECURITY_EVENTS</dev:EventNotifications>
</dev:SetEventNotificationsRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetEventNotificationsAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp
<ns2:AsyncResponse>
</ns2:SetEventNotificationsAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
O SLP v0.6.1 246

</soapenv:Header>
<soapenv:Body>
<dev:SetEventNotificationsAsyncRequest>
<dev:AsyncRequest>
</dev:AsyncRequest>
</dev:SetEventNotificationsAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetEventNotificationsResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/devicemanagemen
</ns2:SetEventNotificationsResponse>
</SOAP-ENV:Body>
O SLP SetEventNotifications Reques t s ent to 'device-01' to s et EventNotifications :
setEventNotificationsRequest {
NotificationMask: 255
}
O SLP SetEventNotifications Res pons e s ent to platform:
setEventNotificationsResponse {
status: OK
}
O SLP v0.6.1 247

EventNotification
EventNotification messages
Des cription
Reques t s ent from device to platform containing information about 1 to 6 events .
Res pons e s ent from platform to 'device-01' communicates s tatus .
}
}
Datatypes
optional string timestamp = 4; // [(nanopb).max_size = 15]; // - Format YYYYMMDDhhmmss UTC, indicates
}
enum Status {
OK = 0;
}
Example
O SLP reques t s ent from 'device-01' to platform:
eventNotificationRequest {
notifications {
event: TARIFF_EVENTS_TARIFF_OFF
index: "\001"
description: "Tariff Off Example Event"
timestamp: "20170404093500"
}
}
O SLP res pons e s ent to 'device-01':
eventNotificationResponse {
status: OK
}
O SLP v0.6.1 248

SetSchedule
SetSchedule messages
Des cription
Reques t to s et a light or tariff s chedule on a device.
}
}
Datatypes
message Schedule {
optional string startDay = 2; // [(nanopb).max_size = 9]; //- Format YYYYMMDD UTC, indicates the ran
optional string endDay = 3; // [(nanopb).max_size = 9]; // - Format YYYYMMDD UTC, including endDay.
optional string time = 5; // [(nanopb).max_size = 7]; // - Format hhmmss localtime set when actionTim
optional Window window = 6; // Window to wait for light sensor trigger.
optional TriggerType triggerType = 8; // React to setTransition or switch astronomical.
optional uint32 minimumLightsOn = 9; // Minimal time (in seconds) the lights should burn before deci
optional uint32 index = 10; // Index of schedule entry in the schedule list.
optional bool isEnabled = 11; // Is this schedule entry enabled?
}
enum Weekday {
MONDAY = 1;
TUESDAY = 2;
WEDNESDAY = 3;
THURSDAY = 4;
FRIDAY = 5;
SATURDAY = 6;
SUNDAY = 7;
WEEKDAY = 8;
WEEKEND = 9;
ABSOLUTEDAY = 10;
ALL = 11;
}
enum ActionTime {
ABSOLUTETIME = 1;
SUNRISE = 2;
SUNSET = 3;
}
message Window {
required uint32 minutesBefore = 1; // minutes before sunset / sunrise
required uint32 minutesAfter = 2; // minutes after sunset / sunrise
}
}
enum TriggerType {
TT_NOT_SET = 0;
O SLP v0.6.1 249

LIGHT_TRIGGER = 1;
ASTRONOMICAL = 2;
}
message PageInfo {
}
enum RelayType {
RT_NOT_SET = 0;
LIGHT = 1;
TARIFF = 2;
}
enum Status {
OK = 0;
}
Examples
Examp le 1: Lig ht s che d ule b as e d on lig ht-me as ure me nt
Screens hot of this s chedule in an O SGP client application.
SO AP Reques t Mes s age for Platform web-s ervice:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:com="http://www.alliander.com/schemas/osgp/publiclighting/2014/10"
xmlns:sch="http://www.alliander.com/schemas/osgp/publiclighting/schedulemanagement/2014/10">
<soapenv:Header>
O SLP v0.6.1 250

</soapenv:Header>
<soapenv:Body>
<sch:SetScheduleRequest>
<sch:DeviceIdentification>device-01</sch:DeviceIdentification>
<sch:Schedules>

<sch:ActionTime>SUNRISE</sch:ActionTime>

<sch:TriggerWindow>

<sch:minutesBefore>15</sch:minutesBefore>

<sch:minutesAfter>15</sch:minutesAfter>
</sch:TriggerWindow>
<sch:LightValue>

<sch:Index>0</sch:Index>
<sch:On>false</sch:On>
</sch:LightValue>


<sch:TriggerType>LIGHT_TRIGGER</sch:TriggerType>
</sch:Schedules>
<sch:Schedules>
<sch:ActionTime>SUNSET</sch:ActionTime>

<sch:TriggerWindow>


<sch:LightValue>

<sch:On>true</sch:On>
</sch:LightValue>

</sch:Schedules>
<sch:Schedules>
<sch:ActionTime>ABSOLUTETIME</sch:ActionTime>


<sch:Time>23:00:00</sch:Time>

<sch:TriggerWindow>


O SLP v0.6.1 251

<sch:LightValue>

</sch:LightValue>
</sch:Schedules>
<sch:Schedules>



<sch:TriggerWindow>


<sch:LightValue>



</sch:LightValue>
</sch:Schedules>
</sch:SetScheduleRequest>
</soapenv:Body>
</soapenv:Envelope>
SO AP Res pons e Mes s age:
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:SetScheduleAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
<ns3:AsyncResponse>
</ns3:SetScheduleAsyncResponse>
</SOAP-ENV:Body>
O SLP SetScheduleReques t s ent to 'device-01' to s et a Light Schedule (1 page in this cas e, therefore no pagingInfo needed):
setScheduleRequest {
schedules {
weekday: ALL
actionTime: SUNRISE
window {
minutesBefore: 15
minutesAfter: 15
}
value {
index: "\000"
on: false
}
O SLP v0.6.1 252

triggerType: LIGHT_TRIGGER
}
schedules {
weekday: ALL
actionTime: SUNSET
window {
minutesBefore: 15
minutesAfter: 15
}
value {
index: "\000"
on: true
}
}
schedules {
weekday: ALL
actionTime: ABSOLUTETIME
time: "230000"
window {
minutesBefore: 30
minutesAfter: 30
}
value {
index: "\002"
on: false
}
}
schedules {
weekday: ALL
time: "070000"
window {
minutesBefore: 150
minutesAfter: 41
}
value {
index: "\002"
on: true
}
}
scheduleType: LIGHT
}
O SLP SetScheduleRes pons e from 'device-01':
setScheduleResponse {
status: OK
}
Des cription for this s chedule:
T his s chedule combines a 'morning/evening light' with an 'all night light'. Relay 1 and 2 will be s witched on us ing a light-
meas urement trigger. Relay 2 will be s witched off at 23:00 us ing an abs olute time. Relay 2 will be s witched on at 07:00, but
only when no light-meas urement trigger has been received yet. Relay 1 and 2 will be s witched off us ing a light-meas urement
trigger.
T he firs t s chedule-entry:
schedules {
weekday: ALL
actionTime: SUNRISE
window {
minutesBefore: 15
minutesAfter: 15
}
value {
index: "\000"
on: false
}
}
O SLP v0.6.1 253

Definitions :
'index: "\000"' means : all device relays configured as LIGHT relays (s ee SetConfigurationReques t mes s age)
'light-meas urement trigger' is defined as : a SetT rans itionReques t mes s age containing a T rans itionT ype matching the
s chedule-entry's actionT ime value (SUNRISE matches NIGHT _DAY and SUNSET matches DAY_NIGHT )
Specifies : For all (weekday: ALL) 7 days of the week, when a light-meas urement trigger is received in the morning
(actionT ime: SUNRISE), then all device relays configured as LIGHT relays have to s witch off (on: fals e).
When and only when a SUNRISE trans ition is received via a light-meas urement trigger (LIGHT _T RIGGER) within a window of
15 minutes Before and 15 minutes After the calculated as tronomical time for s unris e, then the device s hall s witch for the
received light-meas urement trigger.
When no SUNRISE trans ition is received via a light-meas urement trigger (LIGHT _T RIGGER) within a window of 15
minutes Before and 15 minutes After the calculated as tronomical time for s unris e, then the device s hall s witch at the end of the
window.
T he triggerT ype (LIGHT _T RIGGER) defines how a SUNRISE (actionT ime) trans ition will be triggered.
T he s econd s chedule-entry:
schedules {
weekday: ALL
actionTime: SUNSET
window {
minutesBefore: 15
minutesAfter: 15
}
value {
index: "\000"
on: true
}
}
Definitions :
'index: "\000"' means : all device relays configured as LIGHT relays (s ee SetConfigurationReques t mes s age)
'light-meas urement trigger' is defined as : a SetT rans itionReques t mes s age containing a T rans itionT ype matching the
s chedule-entry's actionT ime value (SUNRISE matches NIGHT _DAY and SUNSET matches DAY_NIGHT )
Specifies : For all (weekday: ALL) 7 days of the week, when a light-meas urement trigger is received in the morning
(actionT ime: SUNSET ), then all device relays configured as LIGHT relays have to s witch on (on: true).
When and only when a SUNSET trans ition is received via a light-meas urement trigger (triggerT ype: LIGHT _T RIGGER) within
a window of 15 minutes Before and 15 minutes After the calculated as tronomical time for s uns et, then the device s hall s witch
for the received light-meas urement trigger.
When no SUNSET trans ition is received via a light-meas urement trigger (triggerT ype: LIGHT _T RIGGER) within a window of
15 minutes Before and 15 minutes After the calculated as tronomical time for s unris e, then the device s hall s witch at the end of
the window.
T he triggerT ype (LIGHT _T RIGGER) defines how a SUNSET (actionT ime) trans ition will be triggered.
T he third s chedule-entry:
schedules {
weekday: ALL
time: "230000"
window {
minutesBefore: 30
minutesAfter: 30
}
value {
index: "\002"
on: false
}
}
Specifies : For all (weekday: ALL) 7 days of the week, when its 11 'o clock in the evening (actionT ime: ABSO LUT ET IME and
time: "230000") then device relay 2 has to s witch off (on: fals e).
Since actionT ime is ABSO LUT ET IME, the triggerT ype value mus t be omitted from this s chedule-entry.
O SLP v0.6.1 254

T he fourth s chedule-entry:
schedules {
weekday: ALL
time: "070000"
window {
minutesBefore: 150
minutesAfter: 41
}
value {
index: "\002"
on: true
}
}
For all (weekday: ALL) 7 days of the week, when its 7 'o clock in the morning (actionT ime: ABSO LUT ET IME and time:
"070000") and there are no other s chedule-entries that have caus ed the s witching of device relay 2 within the window defined
(minutes Before: 150 and minutes After) then device relay 2 has to s witch on (on: true).
Since actionT ime is ABSO LUT ET IME, the triggerT ype value mus t be omitted from this s chedule-entry.
T he las t element of the SetScheduleReques t:
scheduleType: LIGHT
s pecifies that this is a light s chedule.
SO AP Reques t to obtain res pons e from 'device-01':
<soapenv:Envelope
xmlns:com="http://www.alliander.com/schemas/osgp/common/2014/10"
<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<sch:SetScheduleAsyncRequest>
<sch:AsyncRequest>
</sch:AsyncRequest>
</sch:SetScheduleAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
`
SO AP Res pons e containing res pons e from 'device-01':
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:SetScheduleResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
</ns3:SetScheduleResponse>
</SOAP-ENV:Body>
Examp le 2: Lig ht s che d ule b as e d on ab s olute time and d ay
SO AP mes s ages :
<SOAP-ENV:Header>
<OrganisationIdentification xmlns="http://www.alliander.com/schemas/osp/common">LianderNetManageme
<ApplicationName xmlns="http://www.alliander.com/schemas/osp/common">SoapUI</ApplicationName
<UserName xmlns="http://www.alliander.com/schemas/osp/common">Kevin</UserName>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns3:SetScheduleRequest xmlns:ns3="http://www.alliander.com/schemas/osgp/publiclighting/scheduleman
O SLP v0.6.1 255

<ns3:DeviceIdentification>device-01</ns3:DeviceIdentification>
<ns3:Schedules>
<ns3:WeekDay>ABSOLUTEDAY</ns3:WeekDay>
<ns3:startDay>2016-01-01Z</ns3:startDay>
<ns3:ActionTime>ABSOLUTETIME</ns3:ActionTime>
<ns3:Time>07:00:00.000</ns3:Time>
<ns3:LightValue>
<ns3:On>false</ns3:On>
</ns3:LightValue>
</ns3:Schedules>
</ns3:SetScheduleRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns3:SetScheduleAsyncResponse xmlns:ns3="http://www.alliander.com/schemas/osgp/publiclighting/sched
<ns3:AsyncResponse>
</SOAP-ENV:Body>
<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns3:SetScheduleAsyncRequest xmlns:ns3="http://www.alliander.com/schemas/osgp/publiclighting/schedu
<ns3:AsyncRequest>
</ns3:AsyncRequest>
</ns3:SetScheduleAsyncRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns3:SetScheduleResponse xmlns:ns3="http://www.alliander.com/schemas/osgp/publiclighting/schedulema
</SOAP-ENV:Body>
O SLP SetScheduleReques t s ent to 'device-01' to s et a Light Schedule:
schedules {
weekday: ABSOLUTEDAY
startDay: "20160101"
time: "070000"
value {
index: "\001"
on: false
}
}
scheduleType: LIGHT
}
O SLP SetScheduleRes pons e s ent to platform:
status: OK
}
O SLP v0.6.1 256

T his s chedule has one entry which s witches light relay 1 (index: "\001") off at January 1s t 2016 at 7 'o clock in the morning.
When 'weekday' is s et to ABSO LUT EDAY, the date will be placed in 's tartDay'.
Examp le 3: S che d ule us ing OS LP v0.6.1 s p e cific p rop e rtie s
SO AP mes s ages :
<soapenv:Envelope
xmlns:com="http://www.alliander.com/schemas/osgp/publiclighting/2014/10"
<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<sch:Schedules>
<sch:ActionTime>SUNRISE</sch:ActionTime>

<sch:TriggerWindow>


<sch:LightValue>

</sch:LightValue>




<sch:IsEnabled>true</sch:IsEnabled>



</sch:Schedules>
<sch:Schedules>
<sch:ActionTime>SUNSET</sch:ActionTime>

<sch:TriggerWindow>


<sch:LightValue>

O SLP v0.6.1 257

</sch:LightValue>




</sch:Schedules>
<sch:Schedules>



<sch:TriggerWindow>


<sch:LightValue>

</sch:LightValue>



</sch:Schedules>
<sch:Schedules>



<sch:TriggerWindow>


<sch:LightValue>

O SLP v0.6.1 258



</sch:LightValue>



<sch:minimumLightsOn>300</sch:minimumLightsOn>
</sch:Schedules>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetScheduleAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/sched
<ns2:AsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
<ns:ApplicationName>SoapUI</ns:ApplicationName>
<ns:UserName>Kevin</ns:UserName>
<ns:OrganisationIdentification>LianderNetManagement</ns:OrganisationIdentification>
</soapenv:Header>
<soapenv:Body>
<ns1:SetScheduleAsyncRequest>
<ns1:AsyncRequest>
<ns:CorrelationUid>LianderNetManagement|||device-01|||20160313162236547</ns:CorrelationUid
<ns:DeviceId>device-01</ns:DeviceId>
</ns1:AsyncRequest>
</ns1:SetScheduleAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetScheduleResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/schedulema
</SOAP-ENV:Body>
O SLP SetScheduleReques t s ent to 'device-01':
schedules {
weekday: ALL
actionTime: SUNRISE
window {
minutesBefore: 15
minutesAfter: 15
}
value {
index: "\000"
on: false
}
O SLP v0.6.1 259

index: 0
isEnabled: true
}
schedules {
weekday: ALL
actionTime: SUNSET
window {
minutesBefore: 15
minutesAfter: 15
}
value {
index: "\000"
on: true
}
index: 1
isEnabled: true
}
schedules {
weekday: ALL
time: "230000"
window {
minutesBefore: 30
minutesAfter: 30
}
value {
index: "\001"
on: false
}
index: 2
isEnabled: true
}
schedules {
weekday: ALL
time: "070000"
window {
minutesBefore: 30
minutesAfter: 30
}
value {
index: "\001"
on: true
}
minimumLightsOn: 300
index: 3
isEnabled: true
}
scheduleType: LIGHT
}
O SLP SetScheduleRes pons e from 'device-01':
status: OK
}
T his s chedule cons is ts of 1 page, and us es 'minimumLightO n' to indicate a minimal burning time in s econds . Further it us es
'index' and 'is Enabled' variables for the Schedule s truct, to indicate what index this s chedule-entry has within the lis t of
s chedule-entries and whether or not the s chedule-entry is enabled.
Examp le 4 : T ariff S che d ule
SO AP Reques t Mes s age for Platform web-s ervice:

<soapenv:Header>
O SLP v0.6.1 260

</soapenv:Header>
<soapenv:Body>
<sch:Schedules>
<sch:WeekDay>WEEKDAY</sch:WeekDay>
<sch:StartDay>2015-01-01</sch:StartDay>
<sch:EndDay>2016-02-01</sch:EndDay>
<sch:TariffValue>
<sch:High>0</sch:High>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
O SLP v0.6.1 261

<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
<sch:Schedules>
<sch:TariffValue>
</sch:TariffValue>
</sch:Schedules>
</soapenv:Body>
</soapenv:Envelope>
SO AP Res pons e Mes s age:
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:SetScheduleAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
<ns3:AsyncResponse>
</SOAP-ENV:Body>
O SLP v0.6.1 262

O SLP SetScheduleReques t s ent to 'device-01' to s et a T ariff Schedule (2 pages in this cas e):
schedules {
weekday: WEEKDAY
endDay: "20160201"
time: "230000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20160201"
time: "070000"
value {
index: "\003"
on: false
}
}
schedules {
weekday: WEEKDAY
endDay: "20150101"
time: "070000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20150406"
time: "070000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20150427"
time: "070000"
value {
index: "\003"
on: true
}
}
pageInfo {
currentPage: 1
pageSize: 5
totalPages: 2
}
scheduleType: TARIFF
}
O SLP SetScheduleRes pons e from 'device-01' for page 1:
status: OK
}
O SLP v0.6.1 263

schedules {
weekday: WEEKDAY
endDay: "20150514"
time: "070000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20150525"
time: "070000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20151225"
time: "070000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20151226"
time: "070000"
value {
index: "\003"
on: true
}
}
schedules {
weekday: WEEKDAY
endDay: "20160101"
time: "070000"
value {
index: "\003"
on: true
}
}
pageInfo {
currentPage: 2
pageSize: 5
totalPages: 2
}
}
O SLP SetScheduleRes pons e from 'device-01' for page 2:
status: OK
}
T his s chedule defines the tariff s witching moments . For mos t weekdays of the year the tariff is high from 7 'o clock in the
morning until 11 'o clock in the evening. During the night and weekend, the tariff is low. However for certain days , like
O SLP v0.6.1 264

Chris tmas Day, the tariff has to be low as well (Chris tmas Day may be weekday).
T he firs t s chedule-entry:
schedules {
weekday: WEEKDAY
endDay: "20160201"
time: "230000"
value {
index: "\003"
on: true
}
}
s pecifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 1s t of January
2015 until 1s t of February 2016 (s tartDay: "20150101" and endDay: "20160201") at 11 'o clock in the evening (actionT ime:
ABSO LUT ET IME and time: "230000") the relay with index 3 (index: "\003") has to s witch on (on: true). When a device is
configured to have relay 3 as T ARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as
T ARIFF_REVERSED, this means the tariff will be high.
T he s econd s chedule-entry:
schedules {
weekday: WEEKDAY
endDay: "20160201"
time: "070000"
value {
index: "\003"
on: false
}
}
2015 until 1s t of February 2016 (s tartDay: "20150101" and endDay: "20160201") at 7 'o clock in the morning (actionT ime:
ABSO LUT ET IME and time: "070000") the relay with index 3 (index: "\003") has to s witch off (on: fals e). When a device is
configured to have relay 3 as T ARIFF relay, this means the tariff will be high. When a device is configured to have relay 3 as
T ARIFF_REVERSED, this means the tariff will be low.
T he third s chedule-entry:
schedules {
weekday: WEEKDAY
endDay: "20150101"
time: "070000"
value {
index: "\003"
on: true
}
}
2015 until 1s t of January 2015 (s tartDay: "20150101" and endDay: "20150101") at 7 'o clock in the morning (actionT ime:
T ARIFF_REVERSED, this means the tariff will be high. T his s chedule entry is needed to make s ure that the tariff is low for a
particular day of the year (New Year's Day).
T he fourth s chedule-entry:
schedules {
weekday: WEEKDAY
endDay: "20150406"
time: "070000"
value {
index: "\003"
on: true
O SLP v0.6.1 265

}
}
s pecifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 6s t of April
2015 until 6s t of April 2015 (s tartDay: "20150406" and endDay: "20150406") at 7 'o clock in the morning (actionT ime:
particular day of the year (Eas ter Monday).
T he fifth s chedule-entry:
schedules {
weekday: WEEKDAY
endDay: "20150427"
time: "070000"
value {
index: "\003"
on: true
}
}
s pecifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 27s t of April
2015 until 27s t of April 2015 (s tartDay: "20150427" and endDay: "20150427") at 7 'o clock in the morning (actionT ime:
particular day of the year (Dutch Kings Day).
T he pagination info:
pageInfo {
currentPage: 1
pageSize: 5
totalPages: 2
}
s pecifies that this is the firs t page of a total of 2 pages . T he pageSize is s et by the platform and can be any value from 1 to
50.
s pecifies that this is a tariff s chedule.
T he s ixth s chedule-entry (page 2):
weekday: WEEKDAY
endDay: "20150514"
time: "070000"
value {
index: "\003"
on: true
}
}
s pecifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 14th of May
2015 until 14th of May 2015 (s tartDay: "20150514" and endDay: "20150514") at 7 'o clock in the morning (actionT ime:
particular day of the year (As cens ion Day).
T he s eventh s chedule-entry (page 2):
schedules {
weekday: WEEKDAY
endDay: "20150525"
O SLP v0.6.1 266

time: "070000"
value {
index: "\003"
on: true
}
}
s pecifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 25th of May
2015 until 25th of May 2015 (s tartDay: "20150525" and endDay: "20150525") at 7 'o clock in the morning (actionT ime:
particular day of the year (Whit Monday).
T he eighth s chedule-entry (page 2):
schedules {
weekday: WEEKDAY
endDay: "20151225"
time: "070000"
value {
index: "\003"
on: true
}
}
s pecifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 25th of
December 2015 until 25th of December 2015 (s tartDay: "20151225" and endDay: "20151225") at 7 'o clock in the morning
(actionT ime: ABSO LUT ET IME and time: "070000") the relay with index 3 (index: "\003") has to s witch on (on: true). When a
device is configured to have relay 3 as T ARIFF relay, this means the tariff will be low. When a device is configured to have
relay 3 as T ARIFF_REVERSED, this means the tariff will be high. T his s chedule entry is needed to make s ure that the tariff is
low for a particular day of the year (Chris tmas Day).
T he ninth s chedule-entry (page 2):
schedules {
weekday: WEEKDAY
endDay: "20160101"
time: "070000"
value {
index: "\003"
on: true
}
2016 until 1s t of January 2016 (s tartDay: "20160101" and endDay: "20160101") at 7 'o clock in the morning (actionT ime:
particular day of the year (New Year's Day).
T he pagination info (page 2):
pageInfo {
currentPage: 2
pageSize: 5
totalPages: 2
}
s pecifies that this is the s econd page of a total of 2 pages . T he pageSize is s et by the platform and can be any value from 1 to
50.
s pecifies that this is a tariff s chedule.
SO AP Reques t to obtain res pons e from 'device-01':
O SLP v0.6.1 267


<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<sch:SetScheduleAsyncRequest>
<sch:AsyncRequest>
</sch:AsyncRequest>
</sch:SetScheduleAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
SO AP Res pons e containing res pons e from 'device-01':
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:SetScheduleResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
</SOAP-ENV:Body>
O SLP v0.6.1 268

ResumeSchedule
ResumeSchedule messages
Des cription
Reques t that notifies the device to continue the current s chedule after the current s chedule was interrupted (for example by
s witching by hand us ing SetLightReques t). T his reques t can operate on a s ingle relay or on all relays and the res uming of the
s chedule can be immediate or at the next s chedule-entry.
Res pons e which confirms the Res umeScheduleReques t has been executed or rejects the Res umeScheduleReques t.
required bool immediate = 2; // [default = false]; // Resume at next schedule item or direct
}
}
Data types
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<adh:ResumeScheduleRequest>
<adh:DeviceIdentification>device-01</adh:DeviceIdentification>

<adh:Index>1</adh:Index>
<adh:IsImmediate>1</adh:IsImmediate>
</adh:ResumeScheduleRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:ResumeScheduleAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/ad
<ns2:AsyncResponse>
</ns2:ResumeScheduleAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<adh:ResumeScheduleAsyncRequest>
O SLP v0.6.1 269

<adh:AsyncRequest>
</adh:AsyncRequest>
</adh:ResumeScheduleAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:ResumeScheduleResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocma
</ns2:ResumeScheduleResponse>
</SOAP-ENV:Body>
O SLP Res umeScheduleReques t s ent to 'device-01':
resumeScheduleRequest {
index: "\001"
immediate: true
}
O SLP Res umeScheduleRes pons e s ent to platform:
resumeScheduleResponse {
status: OK
}
O SLP v0.6.1 270

GetFirmwareVersion
GetFirmwareVersion messages
Des cription
Reques t which notifies the device to s ent the current firmware vers ion.
Res pons e containing the firmware vers ion.
}
}
Datatypes
Example

<soapenv:Header>
<com:UserName>KevinSmeets</com:UserName>
</soapenv:Header>
<soapenv:Body>
<fman:GetFirmwareVersionRequest xmlns:fman="http://www.alliander.com/schemas/osgp/common/firmwarem
<fman:DeviceIdentification>device-01</fman:DeviceIdentification>
</fman:GetFirmwareVersionRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:GetFirmwareVersionAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/firmw
<ns2:AsyncResponse>
<ns3:CorrelationUid>LianderNetManagement|||device-01|||20160104150323405</ns3:CorrelationUi
</ns2:GetFirmwareVersionAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<fman:GetFirmwareVersionAsyncRequest xmlns:fman="http://www.alliander.com/schemas/osgp
<fman:AsyncRequest>
</fman:AsyncRequest>
</fman:GetFirmwareVersionAsyncRequest>
</soapenv:Body>
O SLP v0.6.1 271

</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:GetFirmwareVersionResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/firmwarema
<ns2:FirmwareVersion>R01</ns2:FirmwareVersion>
</ns2:GetFirmwareVersionResponse>
</SOAP-ENV:Body>
O SLP GetFirmwareReques t mes s age s ent to 'device-01':
getFirmwareVersionRequest {
}
O SLP GetFirmwareRes pons e mes s age s ent to platform:
getFirmwareVersionResponse {
firmwareVersion: "R01"
}
O SLP v0.6.1 272

UpdateFirmware
UpdateFirmware messages
Des cription
Reques t for a device to download and ins tall new firmware. T he reques t contains a URL defining the location of the new
firmware image. T he device s hould download the firmware from that location.
required string firmwareDomain = 1; // [(nanopb).max_size = 100]; // Servername
required string firmwareUrl = 2; // [(nanopb).max_size = 255]; // /firmware/PSLD/RXX
}
}
Data types
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<fir1:UpdateFirmwareRequest xmlns:fir1="http://www.alliander.com/schemas/osgp/common/firmwaremanag
<fir1:DeviceIdentification>device-01</fir1:DeviceIdentification>
<fir1:FirmwareIdentification>SSLD-V17</fir1:FirmwareIdentification>
</fir1:UpdateFirmwareRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:UpdateFirmwareAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/firmwarema
<ns2:AsyncResponse>
</ns2:UpdateFirmwareAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<fir1:UpdateFirmwareAsyncRequest xmlns:fir1="http://www.alliander.com/schemas/osgp/common/firmware
<fir1:AsyncRequest>
O SLP v0.6.1 273

</fir1:AsyncRequest>
</fir1:UpdateFirmwareAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:UpdateFirmwareResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/firmwaremanagem
</ns2:UpdateFirmwareResponse>
</SOAP-ENV:Body>
O SLP UpdateFirmwareReques t s ent to 'device-01' to update firmware:
updateFirmwareRequest {
firmwareDomain: "flexovltest.cloudapp.net"
firmwareUrl: "/firmware/SSLD/SSLD-V17.hex"
}
O SLP UpdateFirmwareRes pons e s ent to the platform:
updateFirmwareResponse {
status: OK
}
O SLP v0.6.1 274

SetReboot
SetReboot messages
Des cription
Reques t which notifies the device to reboot immediately. After a reboot, the device will s witch its relays according to its
s chedule. Any ad hoc changes to relays will be los t.
}
}
Data types
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SetRebootRequest>
</ns1:SetRebootRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:SetRebootAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
<ns3:AsyncResponse>
</ns3:SetRebootAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SetRebootAsyncRequest>
<ns1:AsyncRequest>
O SLP v0.6.1 275

</ns1:AsyncRequest>
</ns1:SetRebootAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:SetRebootResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
</ns3:SetRebootResponse>
</SOAP-ENV:Body>
O SLP SetRebootReques t mes s age s ent to 'device-01':
setRebootRequest {
}
O SLP SetRebootRes pons e s ent to platform:
setRebootResponse {
status: OK
}
O SLP v0.6.1 276

StartSelfTest
StartSelfTest messages
Des cription
Reques t that notifies the device to s witch all relays on.
}
}
Data types
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<dev:StartDeviceTestRequest>
</dev:StartDeviceTestRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:StartDeviceTestAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/deviceinstallati
<ns2:AsyncResponse>
</ns2:StartDeviceTestAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<dev:StartDeviceTestAsyncRequest>
<dev:AsyncRequest>
</dev:AsyncRequest>
</dev:StartDeviceTestAsyncRequest>
</soapenv:Body>
O SLP v0.6.1 277

</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:StartDeviceTestResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/deviceinstallation/20
</ns2:StartDeviceTestResponse>
</SOAP-ENV:Body>
O SLP StartSelfT es tReques t mes s age s ent to 'device-01':
startSelfTestRequest {
}
O SLP StartSelfT es tRes pons e mes s age s ent to platform:
startSelfTestResponse {
status: OK
}
O SLP v0.6.1 278

StopSelfTest
StopSelfTest messages
Des cription
Reques t that notifies the device to s witch all relays off.
Res pons e communicates s tatus and the res ult of the tes t.
}
}
Data types
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<dev:StopDeviceTestRequest>
</dev:StopDeviceTestRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:StopDeviceTestAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/deviceinstallatio
<ns2:AsyncResponse>
</ns2:StopDeviceTestAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<dev:StopDeviceTestAsyncRequest>
<dev:AsyncRequest>
</dev:AsyncRequest>
</dev:StopDeviceTestAsyncRequest>
O SLP v0.6.1 279

</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:StopDeviceTestResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/deviceinstallation/201
</ns2:StopDeviceTestResponse>
</SOAP-ENV:Body>
O SLP StopSelfT es tReques t s ent to 'device-01':
stopSelfTestRequest {
}
O SLP StopSelfT es tRes pons e s ent to platform:
stopSelfTestResponse {
status: OK
selfTestResult: "\000"
}
O SLP v0.6.1 280

SetLight
SetLight messages
Des cription
Reques t that notifies the device to s witch on or off one or s everal light relays , optionally with a dim-value per relay. If
optional value 'index' is omitted, all relays configured as light are s witched. In that cas e, all light relays will s witch us ing only 1
LightValue ins tance for 'values '. In cas e the value 'index' is included, multiple ins tances of LightValue can be us ed (up to 6),
each indicating a particular relay. If optional value 'dimValue' is omitted, then default values of 0 and 100 will be as s umed for
either 'on = fals e' or 'on = true'.
}
}
Data types
}
enum Status {
OK = 0;
}
Example
<SOAP-ENV:Header>
<ApplicationName xmlns="http://www.alliander.com/schemas/osp/common">WEB_OWNER</ApplicationName
<UserName xmlns="http://www.alliander.com/schemas/osp/common">liander gebruiker</UserName
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:SetLightRequest xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocmanagemen
<ns2:LightValue>
</ns2:LightValue>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns2:SetLightAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocman
<ns2:AsyncResponse>
</ns2:SetLightAsyncResponse>
</SOAP-ENV:Body>
O SLP v0.6.1 281

<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:SetLightAsyncRequest xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocmana
<ns2:AsyncRequest>
</ns2:AsyncRequest>
</ns2:SetLightAsyncRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns2:SetLightResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocmanageme
</ns2:SetLightResponse>
</SOAP-ENV:Body>
O SLP SetLightReques t s ent to 'device-01':
setLightRequest {
values {
on: true
}
}
O SLP SetLightRes pons e s ent to platform:
setLightResponse {
status: OK
}
O SLP v0.6.1 282

SetTransition
SetTransition messages
Des cription
Reques t which notifies the device that it s hould s witch all relays configured as light relays according to a light s chedule-entry.
T he optional 'time' value can be us ed to indicate a s witch time. If the optional 'time' value is omitted the device s hould s witch
immediately.
required TransitionType transitionType = 1; // Night-Day or Day-Night transition
optional string time = 2; // [(nanopb).max_size = 7]; // - format hhmmss UTC
}
}
Data types
NIGHT_DAY = 0;
DAY_NIGHT = 1;
}
enum Status {
OK = 0;
}
Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:adh="http://www.alliand

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<adh:SetTransitionRequest>
<adh:DeviceIdentification>device-01</adh:DeviceIdentification>
<adh:TransitionType>NIGHT_DAY</adh:TransitionType>

<adh:Time>07:55:01</adh:Time>
</adh:SetTransitionRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetTransitionAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adh
<ns2:AsyncResponse>
</ns2:SetTransitionAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
O SLP v0.6.1 283

</soapenv:Header>
<soapenv:Body>
<adh:SetTransitionAsyncRequest>
<adh:AsyncRequest>
<com:CorrelationUid>LianderNetManagement|||device-01|||20160106155501582</com:CorrelationUid
</adh:AsyncRequest>
</adh:SetTransitionAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetTransitionResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocman
</ns2:SetTransitionResponse>
</SOAP-ENV:Body>
O SLP SetT rans itionReques t s ent to 'device-01':
setTransitionRequest {
transitionType: NIGHT_DAY
time: "075501"
}
O SLP SetT rans itionRes pons e s ent to platform:
setTransitionResponse {
status: OK
}
O SLP v0.6.1 284

GetStatus
GetStatus messages
Des cription
Reques t that requires the device to s end the s tatus of all relays , current network link and preferred network link, the type of
configuration (PSLD vs SSLD), and the event notification mas k which has been s et. Further, many optional values can be s et
by the device, like s erial number, MAC addres s , memory s izes , current firmware vers ion, current IP addres s , etc.
Res pons e which confirms the GetStatus Reques t has been executed and returns the current s tatus for all of the relays and
other information or rejects the GetStatus Reques t.
}
required uint32 eventNotificationMask = 6; // Bitmask for max 32 events, using NotificationBi
optional uint32 numberOfOutputs = 7; // Hardware - The number of outputs of this device
optional uint32 dcOutputVoltageMaximum = 8; // Hardware - DC output voltage MAXimum (in mV).
optional uint32 dcOutputVoltageCurrent = 9; // Hardware - DC output current voltage (in mV).
optional uint32 maximumOutputPowerOnDcOutput = 10; // Hardware - Maximum output power on DC output (
optional bytes serialNumber = 11; // [(nanopb).max_size = 18]; // Hardware - Serial number of this de
optional bytes macAddress = 12; // [(nanopb).max_size = 6]; // Hardware - MAC-address of this device.
optional string hardwareId = 13; // [(nanopb).min_size = 10, (nanopd).max_size = 25] ; // Hardware -
optional uint32 internalFlashMemSize = 14; // Hardware - The internal flash memory size.
optional uint32 externalFlashMemSize = 15; // Hardware - The external flash memory size.
optional uint32 lastInternalTestResultCode = 16; // Hardware - The last internal test result code.
optional uint32 startupCounter = 17; // Hardware - The startup counter.
optional string bootLoaderVersion = 18; // Software - The boot loader version.
optional string firmwareVersion = 19; // Software - The firmware version.
optional bytes currentConfigurationBackUsed = 20; // [(nanopb).max_size = 6]; // Software - The curr
optional string name = 21; // Device - The name of this device.
optional string currentTime = 22; // Device - Not UTC, the time used in timing opera
optional string currentIp = 23; // Device - The current IP address of this device.
}
Datatypes
enum Status {
OK = 0;
}
}
enum LinkType {
LINK_NOT_SET = 0;
GPRS = 1;
CDMA = 2;
ETHERNET = 3;
}
enum LightType {
LT_NOT_SET = 0;
RELAY = 1;
O SLP v0.6.1 285

DALI = 4;
}
Example
<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:GetStatusRequest xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocmanageme
</ns2:GetStatusRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns2:GetStatusAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocma
<ns2:AsyncResponse>
</ns2:GetStatusAsyncResponse>
</SOAP-ENV:Body>
<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:GetStatusAsyncRequest xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/adhocman
<ns2:AsyncRequest>
</ns2:AsyncRequest>
</ns2:GetStatusAsyncRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:GetStatusResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/2014/10"
<ns3:DeviceStatus>
<ns3:LightValues>
</ns3:LightValues>
<ns3:LightValues>
</ns3:LightValues>
<ns3:TariffValues>
<ns3:High>true</ns3:High>
</ns3:TariffValues>
<ns3:PreferredLinkType>ETHERNET</ns3:PreferredLinkType>
<ns3:ActualLinkType>ETHERNET</ns3:ActualLinkType>
<ns3:LightType>RELAY</ns3:LightType>
<ns3:EventNotifications>DIAG_EVENTS</ns3:EventNotifications>
<ns3:EventNotifications>HARDWARE_FAILURE</ns3:EventNotifications>
<ns3:EventNotifications>LIGHT_EVENTS</ns3:EventNotifications>
O SLP v0.6.1 286

<ns3:EventNotifications>TARIFF_EVENTS</ns3:EventNotifications>
<ns3:EventNotifications>MONITOR_EVENTS</ns3:EventNotifications>
<ns3:EventNotifications>FIRMWARE_EVENTS</ns3:EventNotifications>
<ns3:EventNotifications>COMM_EVENTS</ns3:EventNotifications>
<ns3:EventNotifications>SECURITY_EVENTS</ns3:EventNotifications>
<ns3:NumberOfOutputs>4</ns3:NumberOfOutputs>
<ns3:DcOutputVoltageMaximum>24000</ns3:DcOutputVoltageMaximum>
<ns3:DcOutputVoltageCurrent>0</ns3:DcOutputVoltageCurrent>
<ns3:MaximumOutputPowerOnDcOutput>15000</ns3:MaximumOutputPowerOnDcOutput>
<ns3:MacAddress>D8-80-39-46-17-4E</ns3:MacAddress>
<ns3:HardwareId>SB10</ns3:HardwareId>
<ns3:InternalFlashMemSize>1048576</ns3:InternalFlashMemSize>
<ns3:ExternalFlashMemSize>8388608</ns3:ExternalFlashMemSize>
<ns3:LastInternalTestResultCode>0</ns3:LastInternalTestResultCode>
<ns3:StartupCounter>2</ns3:StartupCounter>
<ns3:BootLoaderVersion>v1.0</ns3:BootLoaderVersion>
<ns3:FirmwareVersion>W0311g</ns3:FirmwareVersion>
<ns3:CurrentConfigurationBackUsed>0</ns3:CurrentConfigurationBackUsed>
<ns3:Name>device-01</ns3:Name>
<ns3:CurrentTime>20160313141247</ns3:CurrentTime>
<ns3:CurrentIp>192.168.178.16</ns3:CurrentIp>
</ns3:DeviceStatus>
</ns3:GetStatusResponse>
</SOAP-ENV:Body>
O SLP GetStatus Reques t s ent to 'device-01':
getStatusRequest {
}
O SLP GetStatus Res pons e s ent to platform:
getStatusResponse {
status: OK
value {
index: "\001"
on: false
}
value {
index: "\002"
on: false
}
value {
index: "\003"
on: false
}
value {
index: "\004"
on: false
}
preferredLinktype: ETHERNET
actualLinktype: ETHERNET
lightType: RELAY
eventNotificationMask: 255
numberOfOutputs: 4
dcOutputVoltageMaximum: 24000
dcOutputVoltageCurrent: 0
maximumOutputPowerOnDcOutput: 15000
serialNumber: "123456789123456789"
macAddress: "\330\2009F\027N"
hardwareId: "SB10 "
internalFlashMemSize: 1048576
externalFlashMemSize: 8388608
lastInternalTestResultCode: 0
startupCounter: 2
bootLoaderVersion: "v1.0"
firmwareVersion: "W0311g"
currentConfigurationBackUsed: "\000"
name: "device-01"
currentTime: "20160313141247"
currentIp: "192.168.178.16"
}
O SLP v0.6.1 287

O SLP v0.6.1 288

GetPowerUsageHistory
GetPowerUsageHistory messages
Des cription
Reques t to fetch the power us age data from the regis ters of the device.
Res pons e contains s tatus and the power us age data, for the reques ted time period.
}
}
Datatypes
required string startTime = 1; // [(nanopb).max_size = 15]; // - format YYYYMMDDhhmmss UTC
required string endTime = 2; // [(nanopb).max_size = 15]; // - format YYYYMMDDhhmmss UTC
}
Short = 0;
Long = 1;
}
enum Status {
OK = 0;
}
required MeterType meterType = 2; // Meter type (P1, Pulse, Aux)
}
enum MeterType {
MT_NOT_SET = 0;
P1 = 1;
PULSE = 2;
AUX = 3;
}
message PsldData {
}
message SsldData {
O SLP v0.6.1 289


repeated RelayData relayData = 10; // [(nanopb).max_count = 4]; // Measurement data per relay
}
message RelayData {
}
message PageInfo {
}
Example
<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:GetPowerUsageHistoryRequest xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/de
<ns2:TimePeriod>
<ns2:StartTime>2016-01-04T00:00:00.000+01:00</ns2:StartTime>
<ns2:EndTime>2016-01-05T00:00:00.000+01:00</ns2:EndTime>
</ns2:TimePeriod>
<ns2:HistoryTermType>SHORT</ns2:HistoryTermType>
</ns2:GetPowerUsageHistoryRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns2:GetPowerUsageHistoryAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp
<ns2:AsyncResponse>
</ns2:GetPowerUsageHistoryAsyncResponse>
</SOAP-ENV:Body>
<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:GetPowerUsageHistoryAsyncRequest xmlns:ns2="http://www.alliander.com/schemas/osgp
<ns2:AsyncRequest>
</ns2:AsyncRequest>
</ns2:GetPowerUsageHistoryAsyncRequest>
</SOAP-ENV:Body>
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns2:GetPowerUsageHistoryResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/publiclighting/d
<ns2:PowerUsageData>
<ns2:RecordTime>2016-01-04T22:00:00.000Z</ns2:RecordTime>
O SLP v0.6.1 290

<ns2:MeterType>P1</ns2:MeterType>
<ns2:TotalConsumedEnergy>55229</ns2:TotalConsumedEnergy>
<ns2:ActualConsumedPower>2370</ns2:ActualConsumedPower>
<ns2:PsldData>
<ns2:TotalLightingHours>7110</ns2:TotalLightingHours>
</ns2:PsldData>
<ns2:SsldData>
<ns2:actualCurrent1>10</ns2:actualCurrent1>
<ns2:actualPower1>10</ns2:actualPower1>
<ns2:averagePowerFactor1>10</ns2:averagePowerFactor1>
<ns2:relayData>
<ns2:index>1</ns2:index>
<ns2:totalLightingMinutes>99897</ns2:totalLightingMinutes>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
</ns2:PowerUsageData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 291

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 292

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 293

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 294

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 295

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 296

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 297

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 298

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 299

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 300

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
O SLP v0.6.1 301

<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
<ns2:PsldData>
</ns2:PsldData>
<ns2:SsldData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
<ns2:relayData>
</ns2:relayData>
</ns2:SsldData>
</ns2:GetPowerUsageHistoryResponse>
</SOAP-ENV:Body>
O SLP v0.6.1 302

O SLP GetPowerUs ageHis toryReques t s ent to 'device-01':
getPowerUsageHistoryRequest {
timePeriod {
startTime: "20160103230000"
endTime: "20160104230000"
}
page: 1
termType: Short
}
pages 2 to 11 have been skipped ...
getPowerUsageHistoryRequest {
timePeriod {
startTime: "20160103230000"
endTime: "20160104230000"
}
page: 12
termType: Short
}
O SLP GetPowerUs ageHis toryRes pons e s ent to platform:
getPowerUsageHistoryResponse {
status: OK
powerUsageData {
recordTime: "20160104220000"
meterType: P1
totalConsumedEnergy: 55229
actualConsumedPower: 2370
psldData {
totalLightingHours: 7110
}
ssldData {
actualCurrent1: 10
actualCurrent2: 20
actualCurrent3: 30
actualPower1: 10
actualPower2: 20
actualPower3: 30
averagePowerFactor1: 10
relayData {
index: "\001"
totalLightingMinutes: 99897
}
relayData {
index: "\002"
}
relayData {
index: "\003"
}
relayData {
index: "\004"
}
}
}
powerUsageData {
recordTime: "20160104210000"
meterType: P1
psldData {
}
ssldData {
O SLP v0.6.1 303

actualCurrent1: 10
actualCurrent2: 20
actualCurrent3: 30
actualPower1: 10
actualPower2: 20
actualPower3: 30
relayData {
index: "\001"
}
relayData {
index: "\002"
}
relayData {
index: "\003"
}
relayData {
index: "\004"
}
}
}
pageInfo {
currentPage: 1
pageSize: 2
totalPages: 12
}
}
pages 2 to 11 have been skipped ...
getPowerUsageHistoryResponse {
status: OK
powerUsageData {
recordTime: "20160104000000"
meterType: P1
psldData {
}
ssldData {
actualCurrent1: 10
actualCurrent2: 20
actualCurrent3: 30
actualPower1: 10
actualPower2: 20
actualPower3: 30
relayData {
index: "\001"
}
relayData {
index: "\002"
}
relayData {
index: "\003"
}
relayData {
index: "\004"
}
O SLP v0.6.1 304

}
}
powerUsageData {
recordTime: "20160103230000"
meterType: P1
psldData {
}
ssldData {
actualCurrent1: 10
actualCurrent2: 20
actualCurrent3: 30
actualPower1: 10
actualPower2: 20
actualPower3: 30
relayData {
index: "\001"
}
relayData {
index: "\002"
}
relayData {
index: "\003"
}
relayData {
index: "\004"
}
}
}
pageInfo {
currentPage: 12
pageSize: 2
totalPages: 12
}
}
O SLP v0.6.1 305

UpdateDeviceSslCertification
UpdateDeviceSslCertification messages
Des cription
Reques t to download a new SSL certificate from the certificate s erver. T he device will be given the domain name and URL
where the certificate is located.
message UpdateDeviceSslCertificationRequest {
required string certificateDomain = 1; // [(nanopb).max_size = 100]; // The domain name of the certif
required string certificateUrl = 2; // [(nanopb).max_size = 255]; // The relative path of the cert
}
message UpdateDeviceSslCertificationResponse {
}
Datatypes
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:UpdateDeviceSslCertificationRequest>
<ns1:Certification>
<ns1:certificateDomain>cert-server</ns1:certificateDomain>
<ns1:certificateUrl>/certs/new-cert.pem</ns1:certificateUrl>
</ns1:Certification>
</ns1:UpdateDeviceSslCertificationRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:UpdateDeviceSslCertificationAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/
<ns2:AsyncResponse>
</ns2:UpdateDeviceSslCertificationAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:UpdateDeviceSslCertificationAsyncRequest>
<ns1:AsyncRequest>
O SLP v0.6.1 306

</ns1:AsyncRequest>
</ns1:UpdateDeviceSslCertificationAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:UpdateDeviceSslCertificationResponse xmlns:ns2="http://www.alliander.com/schemas/osgp
</ns2:UpdateDeviceSslCertificationResponse>
</SOAP-ENV:Body>
O SLP mes s ages :
updateDeviceSslCertificationRequest {
certificateDomain: "cert-server"
certificateUrl: "/certs/new-cert.pem"
}
updateDeviceSslCertificationResponse {
status: OK
}
O SLP v0.6.1 307

SetDeviceVerificationKey
SetDeviceVerificationKey messages
Des cription
Reques t to s witch to a new Platform public key us ed for verifying O SLP envelopes by the device. T he bas e-64 encoded
vers ion of the key will be s ent to the device, which is equivalent to the content of a PEM file (only the certificate chunk, not the
headers ).
message SetDeviceVerificationKeyRequest {
required bytes certificateChunk = 1; // [(nanopb).max_size = 138]; // Verification key / public key o
}
message SetDeviceVerificationKeyResponse {
}
Datatypes
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SetDeviceVerificationKeyRequest>

<ns1:VerificationKey>MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEow7CWR7EiNDRt1XQ/h1UrLE24zY3BkA582mfi
</ns1:SetDeviceVerificationKeyRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetDeviceVerificationKeyAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/
<ns2:AsyncResponse>
</ns2:SetDeviceVerificationKeyAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SetDeviceVerificationKeyAsyncRequest>
<ns1:AsyncRequest>
O SLP v0.6.1 308

</ns1:AsyncRequest>
</ns1:SetDeviceVerificationKeyAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SetDeviceVerificationKeyResponse xmlns:ns2="http://www.alliander.com/schemas/osgp
</ns2:SetDeviceVerificationKeyResponse>
</SOAP-ENV:Body>
O SLP mes s ages :
setDeviceVerificationKeyRequest {
certificateChunk: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEow7CWR7EiNDRt1XQ/h1UrLE24zY3BkA582mfiywZ2h8tPk
}
setDeviceVerificationKeyResponse {
status: OK
}
O SLP v0.6.1 309

SwitchFirmware
SwitchFirmware messages
Des cription
Reques t to s witch from the current firmware vers ion to the other firmware vers ion, indicated by the argument
newFirmwareVers ion.
message SwitchFirmwareRequest {
required string newFirmwareVersion = 1; // [(nanopb).max_size = 6]; // The version of the firmware wh
}
message SwitchFirmwareResponse {
required Status status = 1; // FIRMWARE_EVENTS_ACTIVATING Event will be sent, after the firmware chan
}
Datatypes
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SwitchFirmwareRequest>

<ns1:Version>W0311g</ns1:Version>
</ns1:SwitchFirmwareRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SwitchFirmwareAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/firmwarem
<ns2:AsyncResponse>
</ns2:SwitchFirmwareAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SwitchFirmwareAsyncRequest>
<ns1:AsyncRequest>
O SLP v0.6.1 310

</ns1:AsyncRequest>
</ns1:SwitchFirmwareAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SwitchFirmwareResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/common/firmwaremanage
</ns2:SwitchFirmwareResponse>
</SOAP-ENV:Body>
O SLP mes s ages :
switchFirmwareRequest {
newFirmwareVersion: "W0311g"
}
switchFirmwareResponse {
status: OK
}
O SLP v0.6.1 311

SwitchConfiguration
SwitchConfiguration messages
Des cription
Reques t to s witch from the current (active) configuration s et to the other configuration s et, indicated by the configuration s et
index.
message SwitchConfigurationRequest {
required bytes newConfigurationSet = 1; // [(nanopb).max_count = 1]; // The index of the configuratio
}
message SwitchConfigurationResponse {
required Status status = 1; // FIRMWARE_EVENTS_CONFIGURATION_CHANGED Event will be sent, after the C
}
Datatypes
enum Status {
OK = 0;
}
Example

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SwitchConfigurationRequest>

<ns1:ConfigurationBank>1</ns1:ConfigurationBank>
</ns1:SwitchConfigurationRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SwitchConfigurationAsyncResponse xmlns:ns2="http://www.alliander.com/schemas/osgp
<ns2:AsyncResponse>
</ns2:SwitchConfigurationAsyncResponse>
</SOAP-ENV:Body>

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<ns1:SwitchConfigurationAsyncRequest>
<ns1:AsyncRequest>
O SLP v0.6.1 312

</ns1:AsyncRequest>
</ns1:SwitchConfigurationAsyncRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns2:SwitchConfigurationResponse xmlns:ns2="http://www.alliander.com/schemas/osgp/configurationman
</ns2:SwitchConfigurationResponse>
</SOAP-ENV:Body>
O SLP mes s ages :
switchConfigurationRequest {
newConfigurationSet: "1"
}
switchConfigurationResponse {
status: OK
}
O SLP v0.6.1 313

Protobuf Contract
OSLP protobuf file, v0.6.1
// import "nanopb.proto";
package oslp;
option java_package = "com.alliander.osgp.oslp";
message Message {
optional RegisterDeviceRequest registerDeviceRequest = 1;
optional RegisterDeviceResponse registerDeviceResponse = 2;
optional StartSelfTestRequest startSelfTestRequest = 3;
optional StartSelfTestResponse startSelfTestResponse = 4;
optional StopSelfTestRequest stopSelfTestRequest = 5;
optional StopSelfTestResponse stopSelfTestResponse = 6;
optional UpdateFirmwareRequest updateFirmwareRequest = 7;
optional UpdateFirmwareResponse updateFirmwareResponse = 8;
optional SetLightRequest setLightRequest = 9;
optional SetLightResponse setLightResponse = 10;
optional GetStatusRequest getStatusRequest = 11;
optional GetStatusResponse getStatusResponse = 12;
optional ResumeScheduleRequest resumeScheduleRequest = 13;
optional ResumeScheduleResponse resumeScheduleResponse = 14;
optional SetEventNotificationsRequest setEventNotificationsRequest = 15;
optional SetEventNotificationsResponse setEventNotificationsResponse = 16;
optional EventNotificationRequest eventNotificationRequest = 17;
optional EventNotificationResponse eventNotificationResponse = 18;
optional GetFirmwareVersionRequest getFirmwareVersionRequest = 19;
optional GetFirmwareVersionResponse getFirmwareVersionResponse = 20;
optional SetScheduleRequest setScheduleRequest = 21;
optional SetScheduleResponse setScheduleResponse = 22;
optional SetConfigurationRequest setConfigurationRequest = 25;
optional SetConfigurationResponse setConfigurationResponse = 26;
optional GetPowerUsageHistoryRequest getPowerUsageHistoryRequest = 27;
optional GetPowerUsageHistoryResponse getPowerUsageHistoryResponse = 28;
optional GetActualPowerUsageRequest getActualPowerUsageRequest = 29;
optional GetActualPowerUsageResponse getActualPowerUsageResponse = 30;
optional SetRebootRequest setRebootRequest = 31;
optional SetRebootResponse setRebootResponse = 32;
optional SetTransitionRequest setTransitionRequest = 33;
optional SetTransitionResponse setTransitionResponse = 34;
optional GetConfigurationRequest getConfigurationRequest = 35;
optional GetConfigurationResponse getConfigurationResponse = 36;
optional ConfirmRegisterDeviceRequest confirmRegisterDeviceRequest = 37;
optional ConfirmRegisterDeviceResponse confirmRegisterDeviceResponse = 38;
optional UpdateDeviceSslCertificationRequest updateDeviceSslCertificationRequest = 39;
optional UpdateDeviceSslCertificationResponse updateDeviceSslCertificationResponse = 40;
optional SetDeviceVerificationKeyRequest setDeviceVerificationKeyRequest = 41;
optional SetDeviceVerificationKeyResponse setDeviceVerificationKeyResponse = 42;
optional SwitchFirmwareRequest switchFirmwareRequest = 43;
optional SwitchFirmwareResponse switchFirmwareResponse = 44;
optional SwitchConfigurationRequest switchConfigurationRequest = 45;
optional SwitchConfigurationResponse switchConfigurationResponse = 46;
}
// ========= Device Installation

}
required string currentTime = 2; // [(nanopb).max_size = 15];// - Format YYYYMMDDhhmmss UTC.
O SLP v0.6.1 314

optional LocationInfo locationInfo = 5; // Location information of device.

}
}
}
}
}
// ========= Firmware Management

}
}
required string firmwareDomain = 1; // [(nanopb).max_size = 100]; // Server-name without protocol li
required string firmwareUrl = 2; // [(nanopb).max_size = 255]; // Relative URL like this example: /fi
}
}
message SwitchFirmwareRequest {
required string newFirmwareVersion = 1; // [(nanopb).max_size = 6]; // The version of the firmware wh
}
message SwitchFirmwareResponse {
required Status status = 1; // FIRMWARE_EVENTS_ACTIVATING Event will be sent, after the firmware chan
}
// ========= Ad-Hoc & Status

}
}
}
required uint32 eventNotificationMask = 6; // Bitmask for max 32 events, using NotificationBi
optional uint32 numberOfOutputs = 7; // Hardware - The number of outputs of this device
optional uint32 dcOutputVoltageMaximum = 8; // Hardware - DC output voltage MAXimum (in mV).
optional uint32 dcOutputVoltageCurrent = 9; // Hardware - DC output current voltage (in mV).
optional uint32 maximumOutputPowerOnDcOutput = 10; // Hardware - Maximum output power on DC output (
optional bytes serialNumber = 11; // [(nanopb).max_size = 18]; // Hardware - Serial number of this de
optional bytes macAddress = 12; // [(nanopb).max_size = 6]; // Hardware - MAC-address of this device.
O SLP v0.6.1 315

optional string hardwareId = 13; // [(nanopb).min_size = 10, (nanopd).max_size = 25] ; // Hardware -

optional uint32 internalFlashMemSize = 14; // Hardware - The internal flash memory size.
optional uint32 externalFlashMemSize = 15; // Hardware - The external flash memory size.
optional uint32 lastInternalTestResultCode = 16; // Hardware - The last internal test result code.
optional uint32 startupCounter = 17; // Hardware - The startup counter.
optional string bootLoaderVersion = 18; // Software - The boot loader version.
optional string firmwareVersion = 19; // Software - The firmware version.
optional bytes currentConfigurationBackUsed = 20; // [(nanopb).max_size = 6]; // Software - The curr
optional string name = 21; // Device - The name of this device.
optional string currentTime = 22; // Device - Not UTC, the time used in timing opera
optional string currentIp = 23; // Device - The current IP address of this device.
}
optional bytes index = 1; // [(nanopb).max_size = 1]; // Index number of connected light (DALI), none
required bool immediate = 2; // [default = true]; // Resume at next schedule item or direct.
}
}
}
}
required TransitionType transitionType = 1; // Night-Day or Day-Night transition.
optional string time = 2; // [(nanopb).max_size = 7]; // - Format hhmmss UTC.
}
}
}
}
}
}
// ========= Scheduling
}
}
// ========= Configuration
O SLP v0.6.1 316


optional bytes deviceFixIpValue = 10; // [(nanopb).max_count = 4]; // The fixed IP
}
// summerTimeDetails string, winterTimeDetails:
//MMWHHmi
//
//where: (note, north hemisphere summer begins at the end of march)
//MM: month
//W: day of the week (0- Monday, 6- Sunday)
//HH: hour of the changing time
//mi: minutes of the changing time
}
}
optional bytes deviceFixIpValue = 11; // [(nanopb).max_count = 4]; // The fixed IP a
O SLP v0.6.1 317


}
message SwitchConfigurationRequest {
required bytes newConfigurationSet = 1; // [(nanopb).max_count = 1]; // The index of the configuratio
}
message SwitchConfigurationResponse {
required Status status = 1; // FIRMWARE_EVENTS_CONFIGURATION_CHANGED Event will be sent, after the C
}
}
}
// ========= Monitoring
}
}
message GetActualPowerUsageRequest {
}
message GetActualPowerUsageResponse {
required PowerUsageData powerUsageData = 2;
}
// ========= Certificate Management

message UpdateDeviceSslCertificationRequest {
required string certificateDomain = 1; // [(nanopb).max_size = 100]; // The domain name of the certif
required string certificateUrl = 2; // [(nanopb).max_size = 255]; // The relative path of the cert
}
message UpdateDeviceSslCertificationResponse {
}
// ========= Key Management

message SetDeviceVerificationKeyRequest {
required bytes certificateChunk = 1; // [(nanopb).max_size = 138]; // Verification key / public key o
}
message SetDeviceVerificationKeyResponse {
}
// ========= Types
optional sint32 timeOffset = 1; // Correction in minutes with respect to UTC.
optional sint32 latitude = 2; // Divide by 1000000 to get float value.
optional sint32 longitude = 3; // Divide by 1000000 to get float value.
O SLP v0.6.1 318

optional bytes index = 1; // [(nanopb).max_size = 1]; // Index number of connected light (DALI), none
}
optional string timestamp = 4; // [(nanopb).max_size = 15]; // - Format YYYYMMDDhhmmss UTC, indicates
}
message Schedule {
optional string startDay = 2; // [(nanopb).max_size = 9]; //- Format YYYYMMDD UTC, indicates the ran
optional string endDay = 3; // [(nanopb).max_size = 9]; // - Format YYYYMMDD UTC, including endDay.
optional string time = 5; // [(nanopb).max_size = 7]; // - Format hhmmss localtime set when actionTim
optional Window window = 6; // Window to wait for light sensor trigger.
optional TriggerType triggerType = 8; // React to setTransition or switch astronomical.
optional uint32 minimumLightsOn = 9; // Minimal time (in seconds) the lights should burn before deci
optional uint32 index = 10; // Index of schedule entry in the schedule list.
optional bool isEnabled = 11; // Is this schedule entry enabled?
}
message Window {
required uint32 minutesBefore = 1; // Minutes before sunset / sunrise.
required uint32 minutesAfter = 2; // Minutes after sunset / sunrise.
}
optional bytes numberOfLights = 1; // [(nanopb).max_size = 1]; // Number of lights connected to DALI
}
}
}
required bytes index = 1; // [(nanopb).max_size = 1]; // External index, for example 1.
required bytes address = 2; // [(nanopb).max_size = 1]; // Internal address, for example 2.
}
message PageInfo {
required uint32 currentPage = 1; // Pages start from 1.
}
required string startTime = 1; // [(nanopb).max_size = 15]; // - Format YYYYMMDDhhmmss UTC.
required string endTime = 2; // [(nanopb).max_size = 15]; // - format YYYYMMDDhhmmss UTC.
}
required MeterType meterType = 2; // Meter type (P1, Pulse, Aux).
O SLP v0.6.1 319


}
message PsldData {
}
message SsldData {
required uint32 actualCurrent1 = 1; // Instantaneous current L1 in mA.
required uint32 actualPower1 = 4; // Instantaneous active power L1 in W.
repeated RelayData relayData = 10; // [(nanopb).max_count = 4]; // Measurement data per relay.
}
message RelayData {
}
// ========= Enumerations
// ========= Event Notification

enum NotificationBit {
DIAG_EVENTS = 1;
HARDWARE_FAILURE = 2;
LIGHT_EVENTS = 4; // For example LightValue changes.
TARIFF_EVENTS = 8; // For example Tariff changes.
MONITOR_EVENTS = 16; // For example monitor buffer is almost full.
FIRMWARE_EVENTS = 32; // For example firmware activation.
COMM_EVENTS = 64; // For example alternative channel.
SECURITY_EVENTS = 128; // For example out of sequence.
}
//Events must map to their notification bit:

//EG: 0000-0999 =1
// 1000-1999 =2
// 2000-2999 =4
// 3000-3999 =8
// 4000-4999 =16
// 5000-5999 =32
// 6000-6999 =64
// 7000-7999 =128
// OR to check 2^((event num)/1000)=notification bit
enum Event {
// 0 - 999 Diagnostics
DIAG_EVENTS_GENERAL = 0; // Multi-purpose event, see description of event notification
DIAG_EVENTS_UNKNOWN_MESSAGE_TYPE = 1; // Message type unknown by device.
// 1000 - 1999 Hardware Failures

HARDWARE_FAILURE_RELAY = 1000; // Index indicates relay (not supported yet).
HARDWARE_FAILURE_FLASH_WRITE_ERROR = 1001; // Error while writing to flash memory.
HARDWARE_FAILURE_FLASH_MEMORY_CORRUPT = 1002; // Error while reading from flash memory, flash memor
HARDWARE_FAILURE_RTC_NOT_SET = 1003; // Real Time Clock has not set.
// 2000 - 2999 Light Events

LIGHT_EVENTS_LIGHT_ON = 2000; // Index indicates light.
LIGHT_EVENTS_LIGHT_OFF = 2001; // Index indicates light.
LIGHT_FAILURE_DALI_COMMUNICATION = 2500; // DALI communication failure.
LIGHT_FAILURE_BALLAST = 2501; // Ballast failure detected (DALI only).
LIGHT_FAILURE_TARIFF_SWITCH_ATTEMPT = 2502; // Attempt to switch an end-point configured as tariff fr
// 3000 - 3999 Tariff Events

TARIFF_EVENTS_TARIFF_ON = 3000; // Tariff switched on.
TARIFF_EVENTS_TARIFF_OFF = 3001; // Tariff switched off.
O SLP v0.6.1 320

// 4000 - 4999
MONITOR_EVENTS_LONG_BUFFER_FULL = 4000; // Long term monitoring buffer overrun occurred.
MONITOR_FAILURE_P1_COMMUNICATION = 4500; // P1 meter could not be read.
MONITOR_SHORT_DETECTED = 4600; // A short has been detected.
MONITOR_SHORT_RESOLVED = 4601; // A short has been resolved.
MONITOR_DOOR_OPENED = 4700; // Indicates that the enclose of the has been opened.
MONITOR_DOOR_CLOSED = 4701; // Indicates that the enclosure of the device has been clos
MONITOR_EVENTS_TEST_RELAY_ON = 4702; // Relay was switched on by self-test function.
MONITOR_EVENTS_TEST_RELAY_OFF = 4703; // Relay was switched off by self-test function.
MONITOR_EVENTS_LOSS_OF_POWER = 4800; // The device had a power outage.
MONITOR_EVENTS_LOCAL_MODE = 4900; // Device switched to local mode.
MONITOR_EVENTS_REMOTE_MODE = 4901; // Device switched to remote mode.
// 5000 - 5999 Firmware Events

FIRMWARE_EVENTS_ACTIVATING = 5000; // Start activating new firmware, after downloading. O
FIRMWARE_EVENTS_DOWNLOAD_NOTFOUND = 5501; // Download of firmware failed, i.e. location incorre
FIRMWARE_EVENTS_DOWNLOAD_FAILED = 5502; // Download of firmware failed, image incorrect.
FIRMWARE_EVENTS_CONFIGURATION_CHANGED = 5503; // Configuration changed from one bank to other (after
// 6000 – 6999
COMM_EVENTS_ALTERNATIVE_CHANNEL = 6000; // Alternative channel selected for communication (descripti
COMM_EVENTS_RECOVERED_CHANNEL = 6001; // Communication has been recovered for this channel.
// 7000 - 7999
SECURITY_EVENTS_OUT_OF_SEQUENCE = 7000; // Out of sequence occurred and sequence number is
SECURITY_EVENTS_OSLP_VERIFICATION_FAILED = 7001; // OSLP message could not be verified.
SECURITY_EVENTS_INVALID_CERTIFICATE = 7002; // Invalid TLS certificate.
}
// ========= Enums
enum TriggerType {
TT_NOT_SET = 0;
LIGHT_TRIGGER = 1;
ASTRONOMICAL = 2;
}
NIGHT_DAY = 0;
DAY_NIGHT = 1;
}
enum Weekday {
MONDAY = 1;
TUESDAY = 2;
WEDNESDAY = 3;
THURSDAY = 4;
FRIDAY = 5;
SATURDAY = 6;
SUNDAY = 7;
WEEKDAY = 8;
WEEKEND = 9;
ABSOLUTEDAY = 10;
ALL = 11;
}
enum ActionTime {
ABSOLUTETIME = 1;
SUNRISE = 2;
SUNSET = 3;
}
enum DeviceType {
PSLD = 0;
SSLD = 1;
}
enum Status {
OK = 0;
FAILURE = 1; // General failure.
REJECTED = 2; // Request received in wrong state.
}
O SLP v0.6.1 321

enum LightType {
LT_NOT_SET = 0;
RELAY = 1;
DALI = 4;
}
enum RelayType {
RT_NOT_SET = 0;
LIGHT = 1;
TARIFF = 2;
}
enum MeterType {
MT_NOT_SET = 0;
P1 = 1;
PULSE = 2;
AUX = 3;
}
enum LinkType {
LINK_NOT_SET = 0;
GPRS = 1;
CDMA = 2;
ETHERNET = 3;
}
LT_INT_NOT_SET = 0;
DAYS = 1;
MONTHS = 2;
}
Short = 0;
Long = 1;
}
O SLP v0.6.1 322

Support
CHAPTER 6: Support
T here are multiple options for s upport
Community support
Community members can help you on voluntary bas is . See the open s ource and community s ection for more information
where you can as k your ques tions .
Commercial support
If you'd like profes s ional s upport for your O pen Smart Grid Platform us e cas e, cons ider s upport by one of the companies
below.
Smart Society Services
Webs ite: http://s marts ocietys ervices .com

Contact: http://s marts ocietys ervices .com/contact/
Your company here? Contact us !
http://opens martgridplatform.org/contact/
Support 323
License
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
T ERMS AND CO NDIT IO NS FO R USE, REPRO DUCT IO N, AND DIST RIBUT IO N
1. Definitions .
"Licens e" s hall mean the terms and conditions for us e, reproduction, and dis tribution as defined by Sections 1
through 9 of this document.
"Licens or" s hall mean the copyright owner or entity authorized by the copyright owner that is granting the Licens e.
"Legal Entity" s hall mean the union of the acting entity and all other entities that control, are controlled by, or are
under common control with that entity. For the purpos es of this definition, "control" means (i) the power, direct or
indirect, to caus e the direction or management of s uch entity, whether by contract or otherwis e, or (ii) owners hip of
fifty percent (50%) or more of the outs tanding s hares , or (iii) beneficial owners hip of s uch entity.
"You" (or "Your") s hall mean an individual or Legal Entity exercis ing permis s ions granted by this Licens e.
"Source" form s hall mean the preferred form for making modifications , including but not limited to s oftware s ource
code, documentation s ource, and configuration files .
"O bject" form s hall mean any form res ulting from mechanical trans formation or trans lation of a Source form,
including but not limited to compiled object code, generated documentation, and convers ions to other media types .
"Work" s hall mean the work of authors hip, whether in Source or O bject form, made available under the Licens e, as
indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix
below).
"Derivative Works " s hall mean any work, whether in Source or O bject form, that is bas ed on (or derived from) the
Work and for which the editorial revis ions , annotations , elaborations , or other modifications repres ent, as a whole, an
original work of authors hip. For the purpos es of this Licens e, Derivative Works s hall not include works that remain
s eparable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" s hall mean any work of authors hip, including the original vers ion of the Work and any modifications or
additions to that Work or Derivative Works thereof, that is intentionally s ubmitted to Licens or for inclus ion in the
Work by the copyright owner or by an individual or Legal Entity authorized to s ubmit on behalf of the copyright
owner. For the purpos es of this definition, "s ubmitted" means any form of electronic, verbal, or written
communication s ent to the Licens or or its repres entatives , including but not limited to communication on electronic
mailing lis ts , s ource code control s ys tems , and is s ue tracking s ys tems that are managed by, or on behalf of, the
Licens or for the purpos e of dis cus s ing and improving the Work, but excluding communication that is cons picuous ly
marked or otherwis e des ignated in writing by the copyright owner as "Not a Contribution."
"Contributor" s hall mean Licens or and any individual or Legal Entity on behalf of whom a Contribution has been
received by Licens or and s ubs equently incorporated within the Work.
2. Grant of Copyright Licens e. Subject to the terms and conditions of this Licens e, each Contributor hereby grants to
You a perpetual, worldwide, non-exclus ive, no-charge, royalty-free, irrevocable copyright licens e to reproduce,
prepare Derivative Works of, publicly dis play, publicly perform, s ublicens e, and dis tribute the Work and s uch
Derivative Works in Source or O bject form.
3. Grant of Patent Licens e. Subject to the terms and conditions of this Licens e, each Contributor hereby grants to You a
perpetual, worldwide, non-exclus ive, no-charge, royalty-free, irrevocable (except as s tated in this s ection) patent
licens e to make, have made, us e, offer to s ell, s ell, import, and otherwis e trans fer the Work, where s uch licens e
applies only to thos e patent claims licens able by s uch Contributor that are neces s arily infringed by their
Contribution(s ) alone or by combination of their Contribution(s ) with the Work to which s uch Contribution(s ) was
s ubmitted. If You ins titute patent litigation agains t any entity (including a cros s -claim or counterclaim in a laws uit)
alleging that the Work or a Contribution incorporated within the Work cons titutes direct or contributory patent
infringement, then any patent licens es granted to You under this Licens e for that Work s hall terminate as of the date
s uch litigation is filed.
4. Redis tribution. You may reproduce and dis tribute copies of the Work or Derivative Works thereof in any medium,
with or without modifications , and in Source or O bject form, provided that You meet the following conditions :
(a) You mus t give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You mus t caus e any modified files to carry prominent notices
stating that You changed the files; and
Licens e 324
(c) You mus t retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and

attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NO T ICE" text file as part of its
distribution, then any Derivative Works that You distribute must

include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright s tatement to Your modifications and may provide additional or different licens e
terms and conditions for us e, reproduction, or dis tribution of Your modifications , or for any s uch Derivative Works
as a whole, provided Your us e, reproduction, and dis tribution of the Work otherwis e complies with the conditions
s tated in this Licens e.
5. Submis s ion of Contributions . Unles s You explicitly s tate otherwis e, any Contribution intentionally s ubmitted for
inclus ion in the Work by You to the Licens or s hall be under the terms and conditions of this Licens e, without any
additional terms or conditions . Notwiths tanding the above, nothing herein s hall s upers ede or modify the terms of any
s eparate licens e agreement you may have executed with Licens or regarding s uch Contributions .
6. T rademarks . T his Licens e does not grant permis s ion to us e the trade names , trademarks , s ervice marks , or product
names of the Licens or, except as required for reas onable and cus tomary us e in des cribing the origin of the Work and
reproducing the content of the NO T ICE file.
7. Dis claimer of Warranty. Unles s required by applicable law or agreed to in writing, Licens or provides the Work (and
each Contributor provides its Contributions ) on an "AS IS" BASIS, WIT HO UT WARRANT IES O R CO NDIT IO NS O F
ANY KIND, either expres s or implied, including, without limitation, any warranties or conditions of T IT LE, NO N-
INFRINGEMENT , MERCHANT ABILIT Y, or FIT NESS FO R A PART ICULAR PURPO SE. You are s olely res pons ible for
determining the appropriatenes s of us ing or redis tributing the Work and as s ume any ris ks as s ociated with Your
exercis e of permis s ions under this Licens e.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or
otherwis e, unles s required by applicable law (s uch as deliberate and gros s ly negligent acts ) or agreed to in writing,
s hall any Contributor be liable to You for damages , including any direct, indirect, s pecial, incidental, or cons equential
damages of any character aris ing as a res ult of this Licens e or out of the us e or inability to us e the Work (including
but not limited to damages for los s of goodwill, work s toppage, computer failure or malfunction, or any and all other
commercial damages or los s es ), even if s uch Contributor has been advis ed of the pos s ibility of s uch damages .
9. Accepting Warranty or Additional Liability. While redis tributing the Work or Derivative Works thereof, You may
choos e to offer, and charge a fee for, acceptance of s upport, warranty, indemnity, or other liability obligations and/or
rights cons is tent with this Licens e. However, in accepting s uch obligations , You may act only on Your own behalf and
on Your s ole res pons ibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and
hold each Contributor harmles s for any liability incurred by, or claims as s erted agains t, s uch Contributor by reas on
of your accepting any s uch warranty or additional liability.
END O F T ERMS AND CO NDIT IO NS
Licens e 325
Glossary
Glossary
COSEM
CO mpanion Specification for Energy Metering, defines a s et of objects to exchange data with Smart Meters us ing DLMS
protocol.
1.5. Platform components des cription

1.2. Architecture introduction
1.9.5. T echnology Stack
4.6.3. Us e cas es
4.6.1.6.27. ConfigureDefinableLoadProfile
5.2.1. DLMS device s imulator
5.2. DLMS / CO SEM
DLMS
Device Language Mes s age Specification, the protocol us ed to communicate with Smart Meters and other s mart grid devices .
1.7. Logical Authoris ation Model

1.2. Architecture introduction
1.9.4. Protocol Layer
4.6. SmartMetering
4.6.3. Us e cas es
4.6.1.9.9. GetProfileGenericData
4.6.1.6.29. SetMbus Us erKeyByChannel
5.2. DLMS / CO SEM
5.3. O SLP
5. Protocols
2.2.1. Add a device
2.1.1.2. Manual Setup
DSMR
Dutch Smart Meter Requirements , a s et of rules that des cribe how to us e Smart Meters us ing DLMS/CO SO M, defined by
Dutch grid operators . For more information [click here](http://www.netbeheernederland.nl/themas /dos s ier/documenten/?
pageindex=7)
4.6.1.8.1. FindEvents
4.6.1.6.25. GetConfigurationO bject
4.6.1.6.15. SetConfigurationO bject
5.2. DLMS / CO SEM
DTO Object
Data T rans fer O bject. See [Wikipedia](https ://en.wikipedia.org/wiki/Data_trans fer_object)
1.9. T echnical O verview
Domain driven design

See [Wikipedia](https ://en.wikipedia.org/wiki/Domain-driven_des ign)
3.2. Developers 101

1.4. Architecture Principles
OSGP
O pen Smart Grid Platform, a s olution to control and monitor s mart devices . T he O SGP project is built us ing open s ource
tools and s tandards .
3.6. Governance
3.2. Developers 101
Glos s ary 326

1.9.3. Core Layer

1.9.2. Domain Layer
1.9.1. Web Services Layer
4.5. Dis tribution automation
4.4. Microgrids
4.6. SmartMetering
4.6.1.7.5. DeCoupleMbus Device
4.6.1.8.8. FindMes s ageLogs
4.6.1.7.1. AddDevice
4.6.1.9.13. RetrievePus hNotificationAlarm
4.6.1.5. Bundle
4.6.1.1. bypas s retry
4.6.1.2. priority
4.6.1.3. s cheduling
4.7. Guidelines to add a new domain to O SGP
0. Introduction
5.3.1.1. Protobuf Contract
5.3.2.11. SetReboot
5.3.2.3. GetConfiguration
5.3.2.9. GetFirmwareVers ion
5.3.2.17. GetPowerUs ageHis tory
5.3.2.16. GetStatus
5.3.2.8. Res umeSchedule
5.3.2.4. SetConfiguration
5.3.2.19. SetDeviceVerificationKey
5.3.2.5. SetEventNotifications
5.3.2.14. SetLight
5.3.2.7. SetSchedule
5.3.2.15. SetT rans ition
5.3.2.12. StartSelfT es t
5.3.2.13. StopSelfT es t
5.3.2.21. SwitchConfiguration
5.3.2.20. SwitchFirmware
5.3.2.18. UpdateDeviceSs lCertification
5.3.2.10. UpdateFirmware
2.1.1.1. Vagrant
2.1.3.1. Us ing SoapUi
2.2.3. Add a new organis ation
OSLP
O pen Street Light Protocol, the protocol us ed to communicate with SSLD and other s mart grid devices .
3.2. Developers 101

1.3. Architecture functional layers
1.8.2. Internationalization and localization
1.7. Logical Authoris ation Model
1.8.6. Performance
1.9.4. Protocol Layer
1.9. T echnical O verview
1.8.1. T imeBehavior
1.8.3. Security
5.3. O SLP
5.3.1. O SLP v0.5.1
5.3.2. O SLP v0.6.1
5.3.2.11. SetReboot
5.3.2.2. ConfirmRegis terDevice
5.3.2.9. GetFirmwareVers ion
5.3.2.17. GetPowerUs ageHis tory
5.3.2.16. GetStatus
5.3.2.1. Regis terDevice
5.3.2.8. Res umeSchedule
5.3.2.4. SetConfiguration
5.3.2.19. SetDeviceVerificationKey
5.3.2.5. SetEventNotifications
Glos s ary 327

5.3.2.14. SetLight
5.3.2.6. EventNotification
5.3.2.7. SetSchedule
5.3.2.15. SetT rans ition
5.3.2.12. StartSelfT es t
5.3.2.13. StopSelfT es t
5.3.2.21. SwitchConfiguration
5.3.2.20. SwitchFirmware
5.3.2.18. UpdateDeviceSs lCertification
5. Protocols
2.2.1. Add a device
2.5. FAQ
2.1. Ins tallation Guide
2.1.3.2. Us ing the Demo App
2.1.1.2. Manual Setup
PSLD
Public Street Lighting Device, a s mart grid device that is us ed to control and monitor a s ingle s treet light.

5.3.2. O SLP v0.6.1
5.3.2.16. GetStatus
SOAP Webservice
T he open s mart grid platform offers a Spring Framework SO AP Webs ervice.
SSLD
Sub Station Lighting Device, a s mart grid device that is us ed to control and monitor public lighting (s everal s treet lights ) and
tariff s witching for an area.
3.2. Developers 101

1.8.1. T imeBehavior
4.2.1. Us e cas es
5.3. O SLP
5.3.2. O SLP v0.6.1
5.3.2.16. GetStatus
5. Protocols
2.1.3.2. Us ing the Demo App
Glos s ary 328

Open Smart Grid Platform Documentation

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Open Smart Grid Platform Documentation

Caricato da

Copyright:

Formati disponibili

O pen Smart Grid Platform Documentation

Introduction to the Open Smart Grid Platform

Us ing the p latform

T he O pen Smart Grid Platform is us ed in the following way:

A us er or operator us es one or more (web) applications to monitor and/or control devices

Example us e cas e for the open s mart g rid platform

Ad-hoc and s cheduled Switching of Public Lighting

General platform architecture

General platform architecture 6

Acts as a conne cting link between (web)applications and s mart devices

Unique features of the Open Smart Grid Platform

T he O pen Smart Grid Platform environment cons is ts of five layers :

1. Web s ervices layer

Web s ervices layer

Domain log ic layer

Open Smart Grid Platform core layer

Architecture functional layers

S tarting archite cture

Image, functional starting architecture

Architecture functional layers 11

Image, functional reference architecture

Vertical clus ters :

Architecture functional layers 12

Device ins tallation

Horizontal Sys tem layers :

Architecture functional layers 13

Domain driven des ig n (DDD)

DDD us es the following building blocks :

Dependency invers ion principle

Behavior driven development (BDD)

For the application of BDD the following frameworks are us ed:

Platform components description

Authentication and authorization

Application integ ration layer

Platform components des cription 16

Domain log ic layer

Open Smart Grid Platform Core Services

T he internal databas e model in the core layer:

Platform components des cription 17

Platform components des cription 18

Image, Overview of platform data model

Data model explanation:

O SLP (O pen Street Light Protocol)

T he protocols can us e one of the s ecurity layers :

T LS (T rans port Layer Security encryption)

Protocol s pecific device attributes are s tored in the protocol adapter DB

Platform components des cription 19

T rans actions on mes s ages to and from the queues

Platform components des cription 20

Message flow examples

Message Flow: Request/Acknowledge/Poll

Message Flow: Request/Acknowledge/Notify

Mes s age flow examples 21

Mes s age flow examples 22

Logical Authorisation Model

Image of Logical Authorisation Data Model

T he logic of the model above:

O wner-group (this contains all functions )

Logical Authoris ation Model 23

T able des cribing the entities in the logical data-model

Entity De s crip tion

Authe ntication of d e vice s

Additional s ecurity may be provided by us ing T LS communication.