diff --git a/README.md b/README.md index c3470b0..43cc663 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,33 @@ # SGr-JavaSamples + ## Index [Summary](#summary)
[Installation](#installation)
[Architecture](#architecture)
[Code description](#code-description-for-the-samplecommunicator)
+ ## Summary SGr-JavaSamples provides sample projects that demonstrate the use of the SGr Communication Handler Library. The goal is to set up a test environment that allows to connect SGr components and different 'products' (heat pump, charging station, inverter, battery, electricity meter etc.) through the SGr communication interface. -[German Version](README_DE.md) + ## Installation ### Requirements / Prerequisites -- Gradle version >= 8.7. 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 -- Create a new folder for the project (eg. 'SmartGridCommunicator'). -- Clone the following projects to the new folder: -- https://github.com/SmartgridReady/SGrJavaSamples.git -- https://github.com/SmartgridReady/SGrSpecifications.git +- Create a new folder for the project (eg. 'SGrJavaSamples'). +- Clone the following project to a new folder: https://github.com/SmartgridReady/SGrJavaSamples.git -Rem: The folder [your-local-project-folder]/SGrSpecifications/XMLInstances/ExtInterfaces contains the device description XML-files used by the SGrJavaSamples. +Rem: The folder [your-local-project-folder]/SampleCommunicator/src/main/resources contains the device description XML-files used by the SGrJavaSamples. ### Build -- Open the [your-local-project-folder]\SGrJavaSamples\SampleCommunicator with your IDE. -- Run gradle 'build' target in your IDE -- You can also run Gradle from the command line. Change to the [your-local-project-folder]\SGrJavaSamples\SampleCommunicator directory and run:
-```bash>gradle clean build``` +- Open the [your-local-project-folder]/SampleCommunicator with your IDE. +- Run the Gradle 'build' target in your IDE +- You can also run Gradle from the command line. Change to the directory [your-local-project-folder]/SampleCommunicator and run: `gradlew clean build` -

## Architecture @@ -38,192 +35,237 @@ Rem: The folder [your-local-project-folder]/SGrSpecifications/XMLInstances/ExtIn ### Component: Communicator + - - - - - + + + + + + + + + + + + + + + +
Implementor:Communicator Provider (3rd Party)
Description:The 'Communicator' communicates with one or more 'Products' through the SGr 'Generic Interface'. -
Responsibilities: -

For each product, the communicator instantiates a Communication Handler to which a description of the product interface in XML is given.

-

The Communicator loads a device driver for the communication interface of the product (e.g. Modbus RTU/TCP, REST...).

-

The communicator reads or sets (analyses and/or controls) the data points.

-

SGrProject:SGrJavaSamples/SampleCommunicator
Implementor:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++Communicator Provider (3rd Party)

Description:

The 'Communicator' communicates with one or more 'Products' through the SGr 'Generic Interface'.

Responsibilities:
    +
  • For each product, the communicator instantiates a Communication Handler to which a description of the product interface in XML is given.
    • +
  • The Communicator loads a device driver for the communication interface of the product (e.g. Modbus RTU/TCP, REST...).
    • +
  • The communicator reads or sets (analyses and/or controls) the data points.
    • +
SGrProject:

SGrJavaSamples/SampleCommunicator

-

- ### Component: Generic Interface + - - - - - + + + + + + + + + + + + + + + +
Implementor:SGr Core Team
Description:SGr-defined 'Product'-independent interface. -
Responsibilities: -

The Generic Interface is used by the Communicator to communicate with the products in the SGr network.​

-

SGrProject:SmartgridReady/SGrSpecifications/SchemaDatabase/SGr/Generic
Implementor:

SGr Core Team

Description:

SGr-defined 'Product'-independent interface.

Responsibilities:

The Generic Interface is used by the Communicator to communicate with the products in the SGr network.​

SGrProject:

SmartgridReady/SGrSpecifications/SchemaDatabase/SGr/Generic

-

- ### Component: Communication Handler + - - - - - - + + + + + + + + + + + + + + + + + + + +
Implementor:SGr Core Team
Description:This is the core component of the SGr software and it is responsible for the processing and implementation of the SGr 'Generic Interface' on the 'External Interface' of the 'Product'.
- Instantiated by the 'Communicator' and used to communicate with the connected 'Product'. -
Responsibilities: -

​Responsibilities are:
-- Reading the XML device profiles
-- Processing commands of the Generic Interface
-- Execute the commands on the External Interface of the product (device-specific interface)
-- Sending the commands to the Product through the transport service specified by the Product. -

-

Library:sgr-commhandler-2.0.0.jar
SGrProject:SmartgridReady/SGrJava/CommHandler
Implementor:

SGr Core Team

Description:

This is the core component of the SGr software and it is responsible for the processing and implementation of the SGr 'Generic Interface' on the 'External Interface' of the 'Product'.
+ Instantiated by the 'Communicator' and used to communicate with the connected 'Product'.

Responsibilities:

​Responsibilities are:

+
    +
  • Reading the XML device profiles
    • +
  • Processing commands of the Generic Interface
    • +
  • Execute the commands on the External Interface of the product (device-specific interface)
    • +
  • Sending the commands to the Product through the transport service specified by the Product.
    • +
Library:

sgr-commhandler

SGrProject:

SmartgridReady/SGrJava/CommHandler

-

- ### Component: XML (XML-Profile) + - - - - - + + + + + + + + + + + + + + + +
Implementor:Provider of the 'Product'
Description:​The XML file describes the ''function profiles', data points and attributes that can be addressed over the SGr interface. The XML file also provides general information about the 'Product'. -
Responsibilities: -

Providing general data on the Product.

-

Provide the data necessary for mapping the SGr Generic Interface with the External Interface.

SGrProject:SmartgridReady/SGrSpecifications/XMLInstances/ExtInterfaces
Implementor:

Provider of the 'Product'

Description:​

The XML file describes the ''function profiles', data points and attributes that can be addressed over the SGr interface. The XML file also provides general information about the 'Product'.

Responsibilities:
    +
  • Providing general data on the Product.
    • +
  • Provide the data necessary for mapping the SGr Generic Interface with the External Interface.
    • +
SGrProject:

SmartgridReady/SGrSpecifications/XMLInstances/ExtInterfaces

-

- ### Component: Transport Layer (Transport Service) + - - - - - - - + + + + + + + + + + + + + + + + + + + +
Implementor:- SGr Core Team
- 3rd Party Provider
Description:The 'TransportService' is the link to the physical communication interface of the 'Product'. The SGr Core Team provides the EasyModbus Library for Modbus. -
Responsibilities: -

​The SGr Transport Service supports the following communication technologies to provide the following transport services:
- - Modbus​, REST/JSON​, Sunspec​
- - Support is planned for:​ OCPP 2.0​, IEC-61968-9​, IEC-608070-5-104

-

Library:easymodbus.jar
SGrProject:für Modbus:
SmartgridReady/SGrJavaDrivers/EasyModbus
Implementor:
    +
  • SGr Core Team
    • +
  • 3rd Party Provider
    • +
Description:

The 'TransportService' is the link to the physical communication interface of the 'Product'. The SGr Core Team provides the EasyModbus Library for Modbus.

Responsibilities:

​The SGr Transport Service supports the following communication technologies to provide the following transport services:

+
    +
  • Modbus​, REST/JSON​, Sunspec​
    • +
  • Support is planned for:​ OCPP 2.0​, IEC-61968-9​, IEC-608070-5-104
    • +
+
Library:

+ easymodbus
+ sgr-driver-apachehttp
+ sgr-driver-hivemq

+
SGrProject:

für Modbus: SmartgridReady/SGrJavaDrivers/EasyModbus

+

für REST: SmartgridReady/SGrJavaDrivers/ApacheHttp

+

für MQTT: SmartgridReady/SGrJavaDrivers/HiveMq

+
-

- ### Component: External Interface (EI) + - - + + + + + + + + + + + +
Implementor:Manufacturer of the 'Product'
Description:The 'External Interface' is the interface provided by the 'Product'. -
Responsibilities: -

Provides the External Interface of the product. This is described in the Product XML Profile.

Implementor:

Manufacturer of the 'Product'

Description:

The 'External Interface' is the interface provided by the 'Product'.

Responsibilities:

Provides the External Interface of the product. This is described in the Product XML Profile.

-

+### Component: Product -### Komponente: Product - - + + + + + + + + + + + +
Implementor:Manufacturer of the 'Product'
Description:The Product is a device that provides properties, data points and control options. -E.g. heat pump, charging station, inverter, battery, electricity meter -
Responsibilities: -

-

Implementor:

Manufacturer of the 'Product'

Description:

The Product is a device that provides properties, data points and control options. + E.g. heat pump, charging station, inverter, battery, electricity meter.

Responsibilities:

Product hardware.

-

- ## Description of the Code Samples The code samples demonstrate how to use the commhandler library with a communicator application. -These samples use mocked-devices run without any real device: - - -This sample runs with a real WAGO SmartMeter device: - +These samples use mocked devices and run without any real device: + +- BasicSampleCommunicator, demonstrates all common features +- EnumAndBitmapSampleCommunicator, demonstrates read and write of enums and bitmap registers +- AsynchronousSampleCommunicatorTest, demonstrates how to read multiple devices in parallel +- MqttSampleCommunicator, demonstrates subscribe/unsubscribe +- RestSampleCommunicator, demonstrates read/write on a REST device + +This sample runs only with a real WAGO SmartMeter device: + +- WagoSmartMeterCommunicator ### BasicSampleCommunicator -Step 1: -Use the DeviceDescriptionLoader class to load the device description from an XML file. -

-```String deviceDescFilePath = getDeviceDescriptionFilePath();```
-```DeviceDescriptionLoader loader = new DeviceDescriptionLoader<>();```
-```DeviceFrame sgcpMeter = loader.load( "", deviceDescFilePath);``` -

- -Step2: -Load the suitable device driver to communicate with the device. The example below uses a mocked driver for modbus RTU. -Change the driver to the real driver, suitable for your device. For example: -

-```GenDriverAPI4Modbus mbTCP = new GenDriverAPI4ModbusTCP("127.0.0.1", 502);```
-```GenDriverAPI4Modbus mbRTU = new GenDriverAPI4ModbusRTU("COM1");```
-```GenDriverAPI4Modbus mbRTUMock = new GenDriverAPI4ModbusRTUMock("COM1");``` -

- -Step 2: -Instantiate a modbus device. Provide the device description and the device driver instance to be used for the device.

-```SGrModbusDevice sgcpDevice = new SGrModbusDevice(sgcpMeter, mbRTUMock);``` -

- -Step 3: -Initialize the serial COM port or TCP connection used by the modbus transport service. -```sgcpDevice.connect();``` -

- -Step 4: Read the values from the device. -- "CurrentAC" is the name of the functional profile. -- "CurrentACL1", "CurrentACL2", "CurrentACL3" and "ActiveNetACN" are the names of the Datapoints that report the values corresponding to their names. - -Hint: You can only read values for functional profiles and datapoints that exist in the device description XML.
-```String val1 = sgcpDevice.getVal("VoltageAC", "VoltageL1");```
-```String val2 = sgcpDevice.getVal("VoltageAC", "VoltageL2");```
-```String val3 = sgcpDevice.getVal("VoltageAC", "VoltageL3");```

- -Step 5: Disconnect device. -```sgcpDevice.disconnect();``` -

- -The complete sample code can be found on github:
-https://github.com/SmartgridReady/SGrJavaSamples/blob/master/SampleCommunicator/src/main/java/ch/smartgridready/communicator/example/BasicSampleCommunicator.java +This sample code demonstrates all the comm features provided by a generic device. + +The complete sample code can be found on [github](SampleCommunicator/src/main/java/com/smartgridready/communicator/example/BasicSampleCommunicator.java) ### EnumAndBitmapSampleCommunicator -Sample code on how to read and write enums and bitmap registers using the commhandler library.
-You find the sample code on github: -https://github.com/SmartgridReady/SGrJavaSamples/blob/master/SampleCommunicator/src/main/java/ch/smartgridready/communicator/example/EnumAndBitmapSampleCommunicator.java +Sample code on how to read and write enums and bitmap registers using the commhandler library. + +You find the sample code on [github](SampleCommunicator/src/main/java/com/smartgridready/communicator/example/EnumAndBitmapSampleCommunicator.java) ### AsynchronousSampleCommunicator Sample code on how to read multiple devices in parallel using the async features of the commhandler library. This sample a JUnit5 test. Use the Junit test runner to run the sample code. -You find the sample code on github: -https://github.com/SmartgridReady/SGrJavaSamples/blob/master/SampleCommunicator/src/main/java/ch/smartgridready/communicator/example/AsynchronousSampleCommunicatorTest.java + +You find the sample code on [github](SampleCommunicator/src/main/java/com/smartgridready/communicator/example/AsynchronousSampleCommunicatorTest.java) + +### MqttSampleCommunicator + +Sample code that demonstrates subscribe/unsubscribe, which is only available with MQTT devices. + +You find the sample code on [github](SampleCommunicator/src/main/java/com/smartgridready/communicator/example/MqttSampleCommunicator.java) + +### RestSampleCommunicator + +Sample code that demonstrates read/write on a REST device + +You find the sample code on [github](SampleCommunicator/src/main/java/com/smartgridready/communicator/example/RestSampleCommunicator.java) ### WagoSmartMeterCommunicator -If you are happy owner of a WAGO Smart-Meter you can read the read values from the real device with this sample communicator application.
-You find the sample code on github:
-https://github.com/SmartgridReady/SGrJavaSamples/blob/master/SampleCommunicator/src/main/java/ch/smartgridready/communicator/example/WagoSmartMeterCommunicator.java +If you are happy owner of a WAGO Smart-Meter you can read the read values from the real device with this sample communicator application. + +You find the sample code on [github](SampleCommunicator/src/main/java/com/smartgridready/communicator/example/WagoSmartMeterCommunicator.java) + ## Further information / contact information -Glossary: *ToDo Link* +Webssite: [https://smartgridready.ch/](https://smartgridready.ch/) -Webssite: https://smartgridready.ch/
E-Mail: info@smartgridready.ch