Installation

This document describes the automatic installation procedure for your Open Smart Grid Platform development environment.

Manual installation

If you would like to follow the manual installation procedure, please proceed to the .

Overview

Creating a Virtual Machine using Virtual Box and Vagrant

To improve the usability of the Installation process, a Vagrant file and some puppet scripts are used to automatically set-up an virtual Open Smart Grid Platform development environment. The following steps will describe how to install VirtualBox, Vagrant and kick off the procedure by running the vagrant up command.

System Requirements

The following system requirements are recommended:

• Core i5/i7 ~2.5GHz Dual Core, Quad Core recommended

• At least 16 GB RAM, 32 GB RAM recommended

• At least 20 GB free space, 50 GB free space recommended

The installation procedure has been tested on Windows 10.

Install Vagrant and VirtualBox

Start by downloading VirtualBox by going to And follow the installation steps.

note: If you already have VirtualBox, make sure it is at least version 6.1.38

note: Check whether Virtualbox stores the images on a drive with enough free space. (Open Oracle VM VirtualBox Manager -> Preferences -> General -> Default Machine Folder).

Now download and install Vagrant. Vagrant is available at the following URL:

note: If you already have Vagrant, make sure it is at least version 2.3.0 Complete the installation and restart your PC.

note: If you did a fresh install of Vagrant and already had a command prompt open, make sure you close this command prompt and open it again.

Tip

• Remember to enable Virtualization in your system BIOS.

• Also disable Hyper-V in Windows (can be found in Windows Features)

Download and run the Vagrant file

First create a new directory (for example: D:\My Vagrant Images\OSGP Development\)

Browse to and save the png image and Vagrantfile files in your newly created directory.

Note

• Make sure that the file is named like this: Vagrantfile without an extension!

• If the file has an extension (for example .txt) you can rename the file using the following console command.

  MacOS/Linux:

  Windows:

Now open a Command Prompt and navigate to the newly created directory where you just put the files. Make sure that you run the Command Prompt using administrator rights.

note: When you open the Vagrantfile you see 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 less cpu cores and RAM, but it is recommended to use the provided settings.

Run the following command: vagrant up

note: In case of error bad uri Images/OSGP Development/hashicorp/itc/itc-ubuntu-mate-20.04-amd64 then use the following command;

• vagrant destroy

• vagrant box add itc/itc-ubuntu-mate-20.04-amd64

Vagrant will now automatically download an Ubuntu image (+- 2.6 Gb), create a virtualbox image from it and run the installation puppet script when finished. This might take a while, depending on your internet speed. After some time (while the script is still running) you will notice that a window with an Ubuntu Virtual Machine pops-up. Don't log in yet, wait until the script in the Console is finished.

Tip

• If the script fails for some reason (eg. Errors in the console such as time outs during downloading), you can retry the procedure by running the following command vagrant destroy && vagrant up

Now that the script has ran its course, it will automatically log in on the Ubuntu virtual machine as user dev.

note: For some actions, like sudo, you will have to enter the password of user dev. The password for user dev is dev.

Optimize your Open Smart Grid Platform Development virtualbox image.

At this point you also can adjust the virtualbox settings like cpus and memory size. If you don't want to adjust this proceed to Chapter 2.1.2. Platform Setup.

If you do want to update the virtualbox settings for this image, shut down the image first:

Once the machine has been Shut Down, open VirtualBox and right click on the new virtual machine (called "OSGP Development") and select Settings. Go to System and increase the Base Memory of the system to at least 6144 MB (6 GB) (or the maximum recommended (in green) amount for your system).

Now go to the Processor Tab and increase the amount of Processors to the maximum recommended (in green) amount.

Close the Settings window and Start the Virtual Machine again. Once it is booted, you should be automatically logged in as the 'dev' user.

Post actions

In order to use git correctly you need to execute the following commands in a terminal:

Recap

You just created a virtual machine running Ubuntu with pre-installed tooling. Proceed with of the guide describing how to set-up the open smart grid platform.

Testing the platform using the Web Demo

This chapter will describe the steps needed to test the Open Smart Grid Platform using the Web Demo Application.

If you followed the steps from the 'Platform Setup' then you can skip the following installation steps, because the Web Demo will already be available.

Installing the Web Demo

• Open Eclipse and import the following folder as Maven project /home/dev/Sources/OSGP/open-smart-grid-platform/public-lighting-demo-app/

• Add the PublicLightingDemoApp components to the Tomcat Server.

• (Re)Start the Tomcat Server.

Creating a device

To access the Demo App go to the following URL: https://localhost/web-demo-app/

If you encounter an Untrusted Connection page, go to 'I Understand the Risks' -> 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 press Submit.

The following screen will appear, it shows that the device has been successfully added to the Platform.

Opening Device Simulator to Add a Device

In order to be able to use the SSLD-000-00-01 Device, the device needs to be simulated in the Device Simulator. To do this we have to create it. In the Firefox Browser, open the Device Simulator by going to the following URL:

Click Add Device

Fill out the fields like this:

• Device Identification: SSLD_000-00-01

• IP Address: 127.0.0.1

• Device Type: SSLD

Click Create Device

You should return to the Devices screen and see the message "Device with identification SSLD_000-00-01 was created."

Registering a Device

Now click on the newly created device and click the 'Register Device' button. After a while the message "Device identification with identification SSLD_000-00-01 was registered at XXXXXXXX" appears.

Then click the 'Confirm Registration' button. The message should read: "Device with identification SSLD_000-00-01 was confirmed to be registered."

Using 'SetLight' Switch the Light On

Now that the Device is known in the platform, and simulated in the Device-Simulator, the device can be used. Let's switch on the Light. Go to the Demo App and press the List button in the Menu. A list should appear, showing the device that has just been added using the Add Device button.

Click on the Manage button to access the Device Details.

Switch on the Light by setting the Light Value to 100 and by checking the 'LightOn' checkbox (as shown in the screenshot below)

Hit submit to submit the request to the Platform. The following screen should appear:

In the home screen of the OSLP device simulator, the lightbulb should light up for SSLD_000-00-01. This means that the request succeeded.

This step also concludes the installation manual.

CDMA throttling

The main config is enabling the throttling client in your application

throttling.client.enabled=true

The throttling client needs to know where to find the throttling service and tell the service what threshold to use. This is configured using the following settings:

throttling.configuration.name=CDMA
throttling.configuration.max.concurrency=1000
throttling.service.url=http://localhost:9090
throttling.service.timeout=PT30S

Multiple clients can use the same configuration by using the same throttling.configuration.name. Throttling will be globally handled across those clients. Make sure all clients that use the same name also use the same throttling.configuration.max.concurrency. The last client to register a configuration will determine the max concurrency (overwriting previous registrations).

The throttling service itself should be deployed only once, it is not suited for load balanced deployment.

Basic configuration

In order to use git correctly you need to execute the following commands in a terminal if you haven't done so already:

Contributors License Agreement (CLA)

GXF is covered by . You have to sign/agree to it in order to commit changes. Most likely you will have to sign the individual agreement, unless you work for a licensed company.

Your pull request will detect if you haven't signed it yet and instructions are given on how to continue.

Developer Certificate of Origin (DCO)

GXF uses GitHub's application, so you need to sign-off your commits.

Your pull request will detect if you haven't signed-off your commits and instructions are given on how to continue.

Command line

Just add -s to git commit ....

Note this is the lower case -s (short for --signoff).

With git merge ... you can add --signoff as the shorter -s is used to set the merge strategy.

Eclipse

In some versions of Eclipse you can click the button to "Add Signed-off-by" in the Git Staging view:

IntelliJ

In the commit toolwindow, click the settings icon and check the 'Sign-off commit' checkbox:

To get started quickly, a Vagrant Installation Guide has been created and a guide for Manual Installation.

The goal of the installation manual is to control a simulated OSLP device through the Platform. Below, is a summary of all steps involved. See the next chapters for a detailed guide with screenshots. Please follow the steps carefully.

A summary of the steps involved:

• Creating a virtual machine using Vagrant and Virtual Box

• Run the puppet script (part of the Vagrant installation), or complete the steps manually (Manual installation)

• Importing Maven Projects into Eclipse

• Creating an Apache Tomcat9 Server

• Setting Up Apache Tomcat9 Server Context

• Deploying all open smart grid platform components to an Apache Tomcat9 Server

• Starting Apache ActiveMQ

• Starting Apache Tomcat9 Server

• Creating the 'test-org' organization in the Database

• Setting up SoapUI

• First SOAP Requests to add a device to the open smart grid platform

• Opening Device Simulator to add a device

• Registering a device

• Using 'SetLight' SOAP Request to switch the light on

Setting Up the Open Smart Grid Platform Development environment

This chapter describes all the steps needed to finalize the open smart grid platform development environment.

Lombok

The platform uses Lombok annotations to generate extra Java methods. Without Lombok the project is not imported correctly by Maven and will not run. If you used the Vagrant installation method it should already be installed. To check if Lombok is properly installed to go Help > About Eclipse IDE and scroll down. Here you will see: Lombok <version> "<version name>" is installed. https://projectlombok.org/. If not follow this to install Lombok.

Importing Maven Projects into Eclipse

Open Eclipse by clicking the shortcut on the Desktop and import the projects.

Go to File -> Import -> Existing Maven Projects, browse to folder /home/dev/Sources/OSGP

Import the projects from location /home/dev/Sources/OSGP/open-smart-grid-platform.

Creating an Apache Tomcat Server

In Eclipse go to Window -> Open Perspective -> Debug

In the 'Debug' perspective, go to the 'Servers' view and add a new Apache Tomcat server, Tomcat is available in the folder /home/dev/Tools/tomcat (or in another location if you didn't set up a VM using Vagrant, the latest version usually works fine).

Click on Next

Click on Finish

After adding the server, double click on the Tomcat server in the 'Servers' view and set the following configuration: under 'Timeouts' set 'Start' to 600 and 'Stop' to 30.

Make sure that Tomcat is using the correct Java Runtime Environment:

Click on 'Runtime Environment', 'Installed JREs' and click 'Add'. Choose 'next' with 'Standard VM' highlighted. Click 'Directory' and in the folder browser that is shown, use the key combination 'Ctrl + h' to show hidden files. Choose '.sdkman/candidates/java/current' and select 'Open' and 'Finish'. In the 'Installed JREs' screen, unselect the default JVM (which will be an Eclipse hotspot JVM) and select '/home/dev/.sdkman/candidates/java/current' then close the screen by clicking 'Apply and Close'. The last step is to choose the new JRE which was just added in the dropdown of the 'Runtime Environment' screen by selecting '17.0.5'. Click 'Finish' to apply.

Click on 'Open 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

Setting Up Apache Tomcat Server Context

All modules contain their own context.xml. In the module specific context.xml are the environment variables defined where the global and module specific configuration files are located. Default they will point to a location in /etc/osp/.

If you want to deviate from this, you might set up the context.xml in Tomcat to be able to redirect in one file to different locations. This is optional and not required. In order to use a custom context.xml, copy the entries in /home/dev/Sources/OSGP/Config/tomcat/context.xml.sample to the Tomcat context.xml in the eclipse Servers folder, to map configuration file names to file paths.

Deploying all Open Smart Grid Platform components to Apache Tomcat Server

Continue by adding the Maven Projects to the Tomcat server by right clicking on the Tomcat server and choosing 'Add and Remove'. Select all available resources, except for osgp-protocol-simulator-61850 (which is for advanced use and requires additional configuration), then click the 'Add' button. At this point, eclipse's auto-build should have built the projects, and the Tomcat server has been setup.

Starting Apache ActiveMQ

Continue with starting Apache ActiveMQ. If you installed an environment as described with Vagrant, you can double click the ActiveMQ shortcut on the desktop.

Alternatively you can open a terminal and run the executable manually by using the following command: (the executable can be found in the folder /home/dev/Tools/activemq/bin)

This starts ActiveMQ as a terminal process (this way, ActiveMQ doesn't detach from the terminal and starts running as a daemon).

Starting Apache Tomcat Server

With ActiveMQ running, the Tomcat server can be started. Go to Eclipse, go to the Servers tab in the Debug view, and right click on the Tomcat server and select 'Start'.

note: In case of an error starting up for the very first time, try and start up only the module: 'osgp.core' first. This makes sure the database scripts are executed.

Probe

This is an optional program that shows the status of the Tomcat resources in real time. To install Probe you can follow this . Note that you need to add the Tomcat users in the guide's Security part in the tomcat-users.xml in your Eclipse environment. To download the war file go to: . You need to copy the war file to: /home/dev/<your Eclipse workspace>/.metadata/.plugins/org.eclipse.wst.server.core/tmp0/webapps.

Starting pgAdmin III and Connect to PostgreSQL

Open pgAdminIII and configure a connection: choose the 'Add a connection to a server.' and fill out the fields using

• Host: localhost

• Port: 5432

• Username: osp_admin

Creating the 'test-org' Organization (in database osgp-core)

Run the script in /home/dev/Sources/OSGP/Config/sql/create-test-org.sql to insert 'test-org' organization into the organisation table of the osgp_core database.

If asked for a password, enter 1234

Go back to PgAdmin III, expand servers, select localhost -> databases -> osgp_core -> Schemas -> public -> Tables. Right click the organisation table and select to view data for the top 100 rows. Confirm that the test-org organisation has been added to the Database.

Now that everything has been set up, continue to the next chapter to start testing the Platform by sending it some requests.

To install the platform you can use one of the following procedures.

1. . This procedure creates and installs a complete image with the Open Smart Grid Platform pre-installed, including all the tools such as Maven, Eclipse, SoapUI, etc.

2. . Follow this guide if you want to install the Open Smart Grid Platform yourself.

There are two procedures for testing the Open Smart Grid Platform.

1. . Create and send Soap requests to the Platform to manage a (simulated) light.

2. . Use the Demo App to send requests to the Platform to manage a (simulated) device.

Sys Admins who are tasked with keeping the Open Source Grid Platform running on a environment, can find some information in this chapter.

Get Started

To get started with Open Source Grid Platform, please read our Introduction. The Introduction offers an excellent overview of the Platform and its features.

A next step could be to have a look at the WSDL's to understand which functions are present per functional domain. Depending on the functional domain one is interested in, one could also have a look at the Protocol Adapter and device simulator for the domain.

Installation

If a full installation is desired, have a look at our . This can be used to setup a development environment which can be used to start the Platform and run it. Installation on one or several servers can be derived from the steps within the Installation Script.

Testing the platform

This chapter will describe the steps needed to test the Open Smart Grid Platform.

Setting Up SoapUI

Start SoapUI by double clicking the shortcut on the Desktop or run it manually by typing the following command in a terminal:

Go to File -> Preferences -> SSL Settings, and browse for the KeyStore to /home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/test-org.pfx and fill out the password (the password is 1234)

Go to WSDL Settings and check 'Generate Example Values in New Requests' and 'Generate Comments with Type Information in New Requests'

Add the SoapUI projects to SoapUI

There are several SoapUI project prepared, see /home/dev/Sources/OSGP/Config/soapui/. Import all SoapUI projects present in the folder mentioned above. Below, 2 projects are shown as examples.

Adding the 'Admin' Soap project

Import the 'admin' project by clicking File -> Import project. Browse to /home/dev/Sources/OSGP/Config/soapui/, select 'admin-soapui-project.xml' and click open.

Alternatively you can create the 'admin' project yourself by following the steps below:

• Create a new SOAP Project and call it 'admin'

• Open the Project View by double-clicking on the 'admin' project. Go to 'WS-Security Configurations' and select the 'Keystores' Tab. Click on the '+' to add the test-org.pfx in /home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/

Adding the 'Public Lighting' Soap project.

Import the 'public-lighting' project by clicking File -> Import project. Browse to /home/dev/Sources/OSGP/Config/soapui/, select 'public-lighting-soapui-project.xml' and click open.

Alternatively you can create the 'public-lighting' project yourself by following the steps below:

• Create another new SOAP Project and call it 'public-lighting'

• Open the Project View by double-clicking on the 'public-lighting' project. Go to 'WS-Security Configurations' and select the 'Keystores' Tab. Click on the '+' to add the test-org.pfx in /home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/

First SOAP requests to add a device to the open smart grid platform

Before sending the request, the test-org.pfx should be added as SSL Keystore: Go to the properties interface for the request (bottom left of the screen, after selecting 'Request 1' under UpdateKey in the 'admin' project'), and choose test-org.pfx from the drop-down box.

Note

• This has to be done for each request!

An SSLD needs to be added to the platform, as well as a manufacturer and a public key for the SSLD. A couple of steps 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 use 5 Set the public key for the SSLD (in case of OSLP)

The AddManufacturer function adds a new manufacturer to OSGP. All devices are coupled to a manufacturer.

The AddDeviceModel function adds a new device model to OSGP. All devices are coupled to a device model.

The AddDevice function adds a new SSLD to OSGP. The device is coupled to a device model and a manufacturer.

The function UpdateDeviceProtocol sets a protocol for a device.

The UpdateKey function of the admin webservice sets a public key for a device. Double click 'Request 1' under UpdateKey in the 'admin' project. Add the following request:

Click the 'play' button to submit the request to the endpoint. You should receive similar response as shown in the screenshot below:

After the SSLD has been added, let's see if the function FindAllDevices shows the SSLD. Continue with the FindAllDevices request from the public-lighting project. Since this is not the same project, we have to change the endpoint; in this case in . Do not forget to set the SSL keystore in the Request Properties. Use the following parameters in the request:

After the request has been submitted, the response should include the SSLD device with ID SSLD_000_00_01

Opening Device Simulator to Add a Device

In order to be able to use the SSLD-000-00-01 Device, the device needs to be simulated in the Device Simulator. To do this we have to create it. In the Firefox Browser, open the Device Simulator by going to the following URL:

If you encounter an Untrusted Connection page, go to 'I Understand the Risks' -> Add Exception.. -> Confirm Security Exception

Click Add Device

Fill out the fields like this:

• Device Identification: SSLD_000-00-01

• IP Address: 127.0.0.1

• Device Type: SSLD

Click Create Device

You should return to the Devices screen and see the message "Device with identification SSLD_000-00-01 was created."

Registering a Device

Now click on the newly created device and click the 'Register Device' button. After a while the message "Device identification with identification SSLD_000-00-01 was registered at XXXXXXXX" appears.

Then click the 'Confirm Registration' button. The message should read: "Device with identification SSLD_000-00-01 was confirmed to be registered."

Using 'SetLight' SOAP Request to Switch the Light On

Now that the Device is known in the platform, and simulated in the Device-Simulator, the device can be used. Let's switch on the Light. Using SoapUI, click on Request 1 under SetLight at the public-lighting project. Set the following parameters in the request (And do not forget to set the Keystore in the request properties):

Submit the request. Take note of the CorrelationUid in the response. You can use this Id in another request to ask the server for the status of this request.

In the home screen of the OSLP device simulator, the lightbulb should light up for SSLD_000-00-01. This means that the request succeeded.

The last request concerns the response from the previous SetLight request. In SoapUi open Request 1 under 'GetSetLightResponse' in the 'public-lighting' project. Set the following parameters in the request (And the keystore in the request properties). Make sure to replace the CorrelationUid with the value from the respons from the SetLight request.

Note

• Do not forget to set the CorrelationUid to value in the response you received from the setLight request.

The server replied Ok, indicicating that the SetLight request has been processed succesfully.

This step also concludes the installation manual.

Manual Installation

This chapter describes the steps for a manual installation (eg. not using the vagrant script and puppet scripts). This chapter is for developers who would like to have more control over the installation procedure.

With the increased control come increased risks of things not working with the versions or configuration of the software involved with the OSGP environment. If you run into issues, you may find clues in the puppet scripts about versions and modifications to the configuration of installed software.

Note

• Skip this chapter if you followed the Vagrant installation! You can continue with next chapter:

Operating System

The Open Smart Grid Platform runs on a Linux environment. It is recommended to set up a machine running Ubuntu.

Software and tools

The Open Smart Grid platform needs the following software and tools installed/downloaded:

• Java 8 openjdk-8

• PostgreSQL and pgAdmin 3

• Git

Settings

User

It is recommended to create a 'dev' user, because some scripts contain hard coded references to this 'dev' user. It is possible to skip this step, but then some of the scripts will have to be adjusted manually.

Tomcat

• Place the PostgreSQL JDBC driver jar in the Tomcat lib directory.

• Change permissions of Tomcat Config files to 644 in the Tomcat conf directory.

Apache HTTPD

• Enable mod_ssl by running the following command:

• Enable proxy_ajp by running the following command:

Java

• Make sure the JAVA_HOME var is set, and points to openjdk-8.

Cloning Sources

Clone the following repo's, it is recommended to create a Sources/OSGP directory in /home/dev/ since some scripts contain hard coded references to those folders.

Make sure you are on the development branch (default).

Creating directories and symlinks

Create the following directories:

• /var/log/osp/logs

• /etc/osp/

Make the dev user (or equivalent) the owner of the log directory with rwx permission. Give the other users read and execute permission.

Execute the script /home/dev/Sources/OSGP/Config/scripts/create-symlinks.sh

Note This script uses hard coded references to /home/dev/Sources/OSGP/*, if you used a different user, please edit the script before executing it.

The script will make symlinks to certificates, to Apache HTTP server configuration and copy configuration settings as samples to locations where these properties may be overridden.

Initiating the Database

To create the database run the following command (Change /home/dev/ in case of no dev user)

And create a backup of the pg_hba.conf file (modify if your version of PostgreSQL is different)

Finally, reload the postgresql service:

Set up the Open Smart Grid Platform

Continue with setting up the Open Smart Grid Platform by following the

We have prepared a full set of configuration (properties files, certificates, key store, ...) which is available in our Config repository. This configuration can be used to setup a trial environment.

Adding an Organisation to the platform

This chapter describes how to add a new Organisation to the platform. This includes creating a certificate for the new organisation.

Creating an Organisation

In SoapUi go to DeviceManagement under the Admin project. Click on request 1 under CreateOrganisation. Fill in the parameters like the example request below. Make sure to sign the request with the test-org.pfx and to use the test-org organisation in the request header.

This request creates a new organisation called "my-org":

Authorise the new Organisation for the device

To use this new organisation to control the SSLD_000-00-01 device, the authorisations need to be updated. To do that the UpdateDeviceAuthorisations request will be used, it can be found under DeviceManagement in the admin project.

Fill in the parameters like shown below. The functionGroup will be set to AdHoc to authorise the 'my-org' organisation for the AdHoc functions.

Make sure to use the test-org as OrganisationIdentification in the request header, and to sign the request with the test-org.pfx.

Creating a certificate for the new organisation

Now that the 'my-org' organisation is authorised to use the SSLD_000-00-01 device, it is time to create a certificate for the my-org organisation. This certificate will be used to sign the requests.

Open a terminal and navigate to /home/dev/Sources/OSGP/Config/certificates/

A script has been created to create the certificates, execute it by running the following command in the terminal:

You should receive similar output as shown in the screenshot below.

Now that the certificate has been created, restart the tomcat server.

Signing a request with the new certificate

When the tomcat server 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 select the keystores tab. Click the '+' button and browse to the my-org.pfx certificate which can be found in /home/dev/Sources/OSGP/Config/certificates/osgp-ca/certs/

Now double-click on 'Request 1' in SetLight in PublicLightingAdHocManagement in the public-lighting project. Set the SSL Keystore to 'my-org.pfx' in the request properties so the request gets signed with the new certificate. Change the request parameters as shown in the example below:

Note the OrganisationIdentification is now set to 'my-org'. Send the new request, you should receive the following response:

Check the device-simulator to see if the dimValue of the SSLD_000-00-01 changed to 50.

You now have successfully created a new organisation, along with a certificate to sign the requests, and changed the device authorisations of the device to accept commands from the new organisation.

All the features of the open smart grid platform are accessible by it's webservices, as defined in the WSDL files. To use these services to communicate with devices through the platform, please keep in mind the following things.

• A Soap request will have to be generated from your Application.

• In the WSDL and xsd files of the Platform the Requests and it's objects are defined.

• Fill in the parameters once you have an empty soap request for a certain function. The restrictions/requirements are defined in the WSDL files.

• The request should have a header where an ApplicationName, UserName and OrganisationId are defined. At the moment User and App name are not used in the Platform (Except for audability and logging). The OrganisationId, however, must match a known organisation within the Platform. This organisation must have the right authortities to make a certain request.

• Furthermore, the Request must be signed with a certificate from the Organization with the OrganisationId in the header.

• The requests use the Secure HTTP protocol (https).

• For Asynchronious requests, the Platform will respond with a correlationId after succesfully making the request. Use this correlationId in the matching Response-Request to obtain the response from the device.

To learn more about the open smart grid platform's webservices, please take a look at the or for hands-on experience with the Platform's webservices follow the .

Rest

It is not possible to communicate with the Platform directly using REST webservices. As mentioned above, the open smart grid platform uses SOAP (For reasons defined ). If you want to use REST for your front end, you can write an Integration Layer that serves as a Soap Client and exposes the Soap calls through Rest web services that you can access from your front end.

Flows

When using the SOAP Web service, there are 2 flows that can occur:

• some calls are synchronous: a response is returned immediately;

• other calls are a-synchronous: an initial response contains a correlation id, which can be used to obtain the actual response.

Soap Requests in GXF have fields for an User name and an Application name in the Header. These are only used for logging and auditing. There are no restrictions (e.g. Authorizations) with regard to these fields. However, it is recommended to use names for Logging and Auditing purposes.

Deployment options

Hosting the open smart grid platform in the cloud is possible, as well as on premises.

Active-active setup over multiple datacenters

If you like to setup an active-active installation over multiple datacenters. Make sure that the open smart grid platform database runs redundant over both datacenters (master-slave configuration).

Maintenance

There's not much maintenance that needs to be performed. Archiving some old log files, checking up on available disk space and creating a backup of the databases. Looking into the queues to see if there are no messages in the dead letter queue.

• How to start everything up? Make sure that PostgreSQL is running. Make sure that Apache HTTPD web server and Apache ActiveMQ are running. Then start Apache Tomcat application server as described in the installation manual.

• Where are the log files? The Apache Tomcat application server logs can be found in /var/log/tomcat. The Apache HTTPD web server logs can be found in /var/log/httpd. The PostgreSQL log files can be found in /var/lib/pgsql/9.3/data/pg_log. The platform log files can be found in /var/log/osp/logs/.

• Help: SELinux is preventing < something >? Make sure to set SELinux to 'permissive' mode. Then try again and it should work as SELinux will no longer enforce the current policy. Later, one can use the SELinux tools to create a proper policy that allows everything that was prevented before.

• How to add or update a component? Make sure to place the properties file(s) for the component in /etc/osp. Add the locations of the properties file(s) to Apache Tomcat context.xml file. Add the war file to /usr/share/tomcat/webapps. Restart Apache Tomcat.

• How to configure a component? Most (if not all) components of the open smart grid platform are de-coupled using queues. Configure the broker URL in the properties file and take notice of the queues that a component uses/needs. Make sure to double check the connectionstring for PostgreSQL.

• How to configure URL's for a component? In this case the Apache HTTPD vhost needs to be updated. The vhost config file can be found in /etc/httpd/conf.d. We use redirects from HTTP to HTTPS and AJP proxy to send the requests to Apache Tomcat.

• How to check up on Apache ActiveMQ? Apache ActiveMQ offers a web interface (the default port is 8161, default credentials: admin/admin). Using the web interface one can check the queues and especially the dead letter queue (DLQ).

• How do I obtain a public key for a device? Public Keys are usually manufacterer supplied for Smart Metering. For the Open Source part you can use the OSLP device simulator. In Sources/OSGP/Config/certificates/oslp/ you can find instructions for generating a OSLP device public key, and a folder with 5 pre-generated keys for test devices.

• My code gives a lot of errors in Eclipse after importing Try the following things: run mvn clean install in the open-smart-grid-platform directory. Right-click on a project in Eclipse and select 'Maven -> Update project..', select all projects and update.

• The Vagrant script fails If you are receiving errors while downloading the ubuntu iso, sources, etc. or if the puppet script does not start; try running the Vagrant script again by typing vagrant destroy && vagrant up in the directory with the vagrant file.

• I want to update my code from Github If you want to update your code, just run git pull in the repository you want to update. You can also create a fresh Virtual Machine using the vagrant installation, this procedure makes sure you have the most recent code.

• Is a user required to consume platform services? No, an organization is required.

_If your question is not in this list, please create an [issue on Github in the documentation repository ]

Platform uses single device calls.

In order to add a device to the platform, call the add device method in the device installation web service (for a specific domain) for each device.

Implementation may differ for different device types

Each device type may require its own set of attributes, security settings, etc. Each device type may have its own registration mechanism.

• To add a DLMS Device to the Platform, take a look at the documentation of the Soap call as defined in the .

• To add an OSLP Device to the Platform, the Soap call defined in can be used, or the .

Please take a look at the chapter in the installation manual for a detailed guide of how to add a OSLP device to the platform.

Additional Device actions

In the of the documentation more information of the Web Service calls can be found for Adding devices, setting configuration, authorizations, schedules, firmware updates, etc.