SGrJavaDrivers

Index

Summary
Project setup for developers
Build and publish for development
Build and publish a release

Summary

SGrJavaDrivers contains libraries that adapt the commhandler's generic device interface to device specific (communications-) transport layer.

List of current library projects:

• SGrGenDriverAPI4Modbus: Provides the generic driver API definitions for Modbus (as used by the SGr communication handler).
• EasyModbus: Consists of the Modbus driver provideded by 'Copyright (c) 2018-2020 Rossmann-Engineering' together with the SGr generic driver API adapters for ModbusRTU and ModbusTCP.

The chapters following chapters describe the architecture of the device adapters in detail. To support their own Modbus drivers within SmartgridReady, third party providers can implement their own adapters that implement the SGrGenDriverAPI4Modbus interface.

Generic Device Driver API

The Generic Device Driver API makes the SGr communication handler (CommHandler4Modbus) independent from the device driver implementation. The communication handler uses the same interface to communicate with any modbus driver (EasyModbus, 3rdPartyDriver).

Component: Communicator

Implementor:	Communicator provider
Description:	The Communicator is a SGr compliant controlling device that uses the SGr Generic Interface to send commands to any device/product in the SGr environment.
Responsibilities:	Instantiates a concrete device driver adapter (EasyModbusAdapter, 3rdPartyDriverAdapter...) Creates a Commhandler4Modbus instance (provided by the commhandler4Modbus library) Uses the CommHandler4Modbus instance to send commands to the device (readVal(), getVal())
Library:	n.a.
SGrProject:	SGrJavaSamples/SampleCommunicator

Component: CommHandler4Modbus

Implementor:	SGr core development team
Description:	SGr core component that maps SGr Generic Interface commands to commands of a specific product/device (External Interface), based on a device description provided in XML.
Responsibilities:	Provides the SGr Generic Interface to read and set values on the external product/device getVal(), setVal()... Converts the Generic Interface commands to device specific commands. Uses the generic interface GenDriverAPI4Modbus to send commands to the product/device
Library:	commmHandler4modbus.jar includes: sgr-driver-api.jar easymodbus.jar
SGrProject:	SGrJava/InterfaceFactory/CommHandler4Modbus

Component: SGrGenDriverAPI4Modbus

Implementor:	SGr core development team
Description:	Defines the Java interface that must be implemented by any SGr compliant modbus device driver or driver adapter. This interface must be implemented by any modbus device SGr compliant modbus device driver.
Responsibilities:	Definition of the generic device driver API used by the SGrDevice component to send commands to the products.
Library:	sgr-driver-api.jar
SGrProject:	SGrJavaDrivers/GenDriverAPI

Component: EasyModbusAdapter

Implementor:	SGr core development team
Description:	Adapts the generic device driver API to the EasyModbus device driver.
Responsibilities:	Maps SGrGenDriverAPI4Modbus commands to EasyModbus commands. Maps EasyModbus specific exceptions to SGrGenDriverAPI4Modbus exceptions.
Library:	sgr-driver-api.jar
SGrProject:	SGrJavaDrivers/EasyModbus

Component: EasyModbus

Implementor:	SGr core development team
Description:	Modbus device driver provided by the SGr core development team.
Responsibilities:	Implements a modbus device driver that supports modbus RTU and modbus overTCP
Library:	easymodbus.jar
SGrProject:	SGrJavaDrivers/EasyModbus

Component: 3rdPartyAdapter

Implementor:	3rd party provider
Description:	Adapts the generic device driver API to the 3rd party device driver.
Responsibilities:	Maps SGrGenDriverAPI4Modbus commands to 3rd party driver commands Maps 3rd party driver specific exceptions to 3rd party driver exceptions.

Component: 3rdPartyDriver

Implementor:	3rd party provider
Description:	Proprietary Modbus driver provided by a 3rd party.
Responsibilities:	Implements a 3rd party modbus driver Receive commands from the 3rdPartyAdapter.

Project Setup

Prerquisites

• Gradle version >= 7.3.3. Note: If no IDE with Gradle integration is used, Gradle must first be installed locally: https://gradle.org/install/
• Java JDK version >= Java 11

Clone from GitHub

• Clone this repo to your local machine: https://github.com/SmartgridReady/SGrJavaDrivers.git

Build and publish for development

• Change to the local {project-root}/SGrJavaDrivers/GenDriverAPI directory.
• Run the command:

  bash>gradle publishToMavenLocal
  

• Change to the local {project-root}/SGrJavaDrivers/EasyModbus dirctory.
• Run the command:

  bash>gradle publishToMavenLocal
  

When using an IDE (Intellij/Eclipse...) you can also use the IDE's Gradle integration to run 'publishToMavenLocal'.

The steps above will compile, build the library jar's and publish the libraries to the local Maven repository.

Rem:The libraries are the most current and used for SGr core development such as the communication handler ( see https://github.com/SmartgridReady/SGrJava ).

Build and publish a release

• Obtain a Github access token for your Github account. This has to be done once before you can publish to GitHub. See Obtaining a GitHub token for publishing

• Change to the local {project-root}/SGrJavaDrivers/GenDriverAPI directory.

• Check that the build.gradle file has the correct version number for the sgr-driver-api.jar file:

  publishing {
      publications {
          api(MavenPublication) {
              groupId = 'ch.smartgridready'
              artifactId = 'sgr-driver-api'
              version = '<correct-version>'
  
              from components.java        
          }
      }
  }
  

  Rem: GitHub will not accept publishing a version that already exists within the repository. If you want to override published version you must delete the existing package of the library first.

• Run the command:

  bash>gradle publishAllPublicationsToGitHubRepository
  

• Change to the local {project-root}/SGrJavaDrivers/EasyModbus dirctory.

• Check that the build.gradle file has the correct version number for the easy-modbus. jar file:

  publishing {
      publications {
          maven(MavenPublication) {
              groupId = 'ch.smartgridready'
              artifactId = 'easymodbus'
              version = '<correct-version>'
  
              from components.java
          }
      }
  }
  

• Run the command:

  bash>gradle publishAllPublicationsToGitHubRepository
  

The steps above will compile, build the library jar's and publish the libraries to the Maven repository on GitHub. The libaries are now published on GitHub, therefore public and can be used by integrators of SGr communicators.

Rem: The SGr starter projects/code samples use the driver libraries from GitHub (see: https://github.com/SmartgridReady/SGrJavaSamples)

Obtaining a GitHub token for publishing

Creating the token on GitHub

• Go to your GitHub profile settings page: https://github.com/settings/profile
• On the left menu scroll down and select [<>Developer settings]
• On the left menu select [<>Personal access tokens]
• Select [Generate new token] on the top right.
• When asked, enter your GitHub password
• Fill in the new token form:
  • give the token a name for example 'TOKEN_4_GRADLE_PUBLISH'
  • choose an expiry date
  • check only the packages:write and packages:read permissions
  • push the [Generate token] button on the bottom right.

Use the GitHub token on the local machine for publishing

• On Windows go to c:\users\<username>\.gradle directory.
• On Unix go to to your ~/.gradle directory.
• Create a file called gradle.properties
• Add the following entries in gradle.properties:

github.username=ergo-furrer
github.token=<-- add your GitHub publising token here-->