Commit e6a7ed9e authored by Martin Hoppen's avatar Martin Hoppen
Browse files

doc review

parent 9f8cf1d1
Pipeline #374160 passed with stages
in 1 minute and 1 second
fml40 python reference implementation
==============================
Reference implementation of the Forest Modelling Language 4.0 (fml40) which is explained in the [KWH ForestML 4.0 white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf), currently only in German.
To use the fml40 reference implementation package in your own project you need to install it using the latest [wheel](https://git.rwth-aachen.de/kwh40/fml40-reference-implementation/-/jobs/artifacts/master/raw/public/ml-0.1-py3-none-any.whl?job=wheel).
Reference implementation for building a Digital Twin based on the Forest Modeling Language 4.0 (fml40), as specified in [this white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf) (in German).
To use the fml40 reference implementation package in your own project, you need to install it using the latest [wheel](https://git.rwth-aachen.de/kwh40/fml40-reference-implementation/-/jobs/artifacts/master/raw/public/ml-0.1-py3-none-any.whl?job=wheel).
To install this wheel, go to the respective directory or switch to your designated virtual environment and install the `.whl` file, just run
```
pip install https://git.rwth-aachen.de/kwh40/fml40-reference-implementation/-/jobs/artifacts/master/raw/public/ml-0.1-py3-none-any.whl?job=wheel
......@@ -16,8 +16,8 @@
--------
This package provides two different modes to launch your Digital Twins:
- Launching Digital Twin quickly in persistent mode via `fml40s.py`. You need to register a thing identity for your Digital Twin via [S³I Config REST API](https://config.s3i.vswf.dev/apidoc) and prepare a respective config file which describes a ForestML 4.0 conform DT in JSON. For more details refer to the example `MyDigitalTwin.json` in the section `Config files`.
- Extending the capabilities with user defined Digital Twins, which means you can additionally define and insert a function according to ForestML 4.0 into the Digital Twin. We provide an exemplary Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master), refer to notebooks `08a`, `08b`, `08d` and `08e` .
- Launching Digital Twin quickly in persistent mode via `fml40s.py`. You need to register a thing identity for your Digital Twin via [S³I Config REST API](https://config.s3i.vswf.dev/apidoc) and prepare a respective config file that describes a fml40-compliant DT in JSON. For more details, refer to the example `MyDigitalTwin.json` in the section `Config files`.
- Extending the capabilities with user defined Digital Twins, which means you can additionally define and insert a function according to ForestML 4.0 into the Digital Twin. We provide an exemplary Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master), refer to notebooks `08a`, `08b`, `08d` and `08e`.
Usage
-----
......@@ -36,14 +36,14 @@ ### Using fml40s.py
```
### Develop your Digital Twin using this package
We introduce here briefly how to develop a user-specified Digital Twin. For more details refer to the created cloud and edge Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master).
The following steps can be only carried out after you have created the identity of your Digital Twin via Config REST API and made a respective config file. We use the config file `MyDigitalTwin.json` appearing in the section `Config files` to build a Digital Twin. Now we continue the following steps.
Here, we introduce briefly how to develop a user-specified Digital Twin. For more details, refer to the cloud/edge Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master).
The following steps can only be carried out after you have created the thing identity of your Digital Twin via S³I Config REST API and made a respective config file. Here, we use the config file `MyDigitalTwin.json` from section `Config files`. Now we continue the following steps:
- Optionally set a logger using the function `setup_logger`. The generated log file will be then located in the folder `logs`.
- Optionally, set a logger using the function `setup_logger`. The generated log file will then be located in the folder `logs`.
```
ml.setup_logger("MyDigitalTwin")
```
- Set the path of config file and import it in JSON format.
- Set the path of the config file and import it in JSON format.
```
config_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "configs"))
......@@ -58,7 +58,7 @@ ### Develop your Digital Twin using this package
is_broker_rest=False, is_broker=True, is_repo=True
)
```
- As written in the config file, the Digital Twin has a feature named fml40::ProvidesProductionData. In the next step we extend/implement this class with our own logic.
- As specified in the config file, the Digital Twin has a feature named fml40::ProvidesProductionData. In the next step, we extend/implement this class with our own logic.
```
class ProvidesProductionDataImpl(ProvidesProductionData):
def __init__(self, name="", identifier=""):
......@@ -82,18 +82,18 @@ ### Develop your Digital Twin using this package
```
thing.run_forever()
```
So far, your Digital Twin has been created. In the meantime you can establish a connection with it using S3I-B messages.
So far, your Digital Twin has been created. In the meantime, you can establish a connection with it using S³I-B messages.
Config files
------------
A valid configuration consists of exactly one json object. Mandatory fields of the json object are
A valid configuration consists of exactly one JSON object. Mandatory fields of the JSON object are
- thingId
- policyId and
- attributes
The configuration file must be created in accordance with ForestML 4.0, refer to Cap. 7.1 of the [KWH ForestML 4.0 White Paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf). We provide in addition here an example JSON config file, see below.
The configuration file must be created in accordance with ForestML 4.0, refer to Cap. 7.1 of the [KWH3.0 ForestML 4.0 white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf). Additionally, we provide an exemplary JSON config file, see below.
MyDigitalTwin.json:
```
......@@ -187,16 +187,16 @@ ### Configs
### ml
This directory includes the implementations of the fml40 python reference implementation as described in the KWH ForestML 4.0 White Paper.
This directory includes the implementations of the fml40 python reference implementation as described in the KWH ForestML 4.0 white paper.
### demo
Example of creating and launching a HMIm which is used to communicate with the permanent Digital Twin using S³I-B protocol.
Example for creating and launching an HMI, which is used to communicate with the permanent Digital Twin using S³I-B protocol.
### logs
This folder is composed of the logging files of the created and launched Digital Twins.
This folder contains the log files of the created and launched Digital Twins.
### tests
......
......@@ -6,7 +6,7 @@
Welcome to the documentation of the fml40 python reference implementation!
==========================================================================
The documentation is composed of some preliminaries for installation, a quick start and the reference implementation package.
We have implemented a permanent Digital Twin which runs in our internal server. In order to communicate with it, you can use the `hmi.py` in the folder `demo`
We have implemented a permanent Digital Twin, which runs on our internal servers. In order to communicate with it, you can use the `hmi.py` in the folder `demo`
Table of Contents
-----------------
......
# Permanent Digital Twin
# Permanent Digital Twin of a harvester
With the fml40 python reference implementation package, we have developed a Digital Twin, which is modeled based on the ForestML 4.0 and runs permanently. The Digital Twin is implemented using fog approach, which means it is composed of the part of edge DT, which lives in our internal server, and the part of cloud DT, which runs at the S³I Repository. The S³I Interface is enabled in the DT. To communicate with the DT, we provided a python script named `hmi.py` in the folder `demo`. Please feel free to contact with us in order to get the credentials file for the HMI. Put the credentials in the folder `config` and then you can run the script `hmi.py` to speak with the DT after installing the corresponding python virtual environment. This documentation introduces various services the Digital Twin provides and show its JSON entries in the S³I Directory and Repository.
With the fml40 python reference implementation package, we have developed a Digital Twin of a harvester, which is modeled based on the ForestML 4.0 language and runs permanently. The Digital Twin is implemented using the fog approach, i.e., it has an edge DT part (living on our internal servers) and a cloud DT part (within the S³I Repository). The DT is reachable via S³I-B messages. To communicate with the DT, we provide a python script named `hmi.py` in the folder `demo`. Please feel free to contact us in order to get the necessary credentials file for this HMI. Put the credentials in the folder `config` and you can run `hmi.py`. This documentation introduces various service functions the Digital Twin provides and show its JSON-based structure within the S³I Directory and Repository.
## S³I Directory entry
S³I Directory entry describes a thing at the layer of the metadata, which can be mapped to a JSON file. In order to query the JSON file, you can send a HTTP Request to the S³I Directory. For information about how to send a HTTP Request, refer to [the S³I Document](https://kwh40.pages.rwth-aachen.de/-/s3i/-/jobs/1095388/artifacts/public/html/md/communication.html). The Digital Twin has a directory entry shown below:
S³I Directory provides a thing's metadata, i.e., what it looks like and how it is reachable (endpoints) - just like the yellow pages. S³I Directory provides its own meta model the fml40 data model is mapped to. In order to query the corresponding JSON data, you can send an HTTP request to the S³I Directory (see [this S³I document](https://kwh40.pages.rwth-aachen.de/-/s3i/-/jobs/1095388/artifacts/public/html/md/communication.html)). The Digital Twin of the harvester has the following directory entry (note the two endpoints: one for S³I-B and one for S³I Repository):
```
{
"thingId": "s3i:b6d1cc6d-896c-40fe-9403-b5b7682b1d03",
......@@ -124,7 +124,7 @@ ## S³I Directory entry
```
## S³I Repository entry
In a run time environment like edge device or S³I Repository, a conceptual fml40 data model can be directly mapped to a JSON file which describes the thing itself. The Repository entry can be queried via HTTP REST Request, refer to [S³I Documentation](https://kwh40.pages.rwth-aachen.de/-/s3i/-/jobs/1095388/artifacts/public/html/md/communication.html). The permanent Digital Twin has a repository entry which is shown in the following:
In contrast to the S³I Directory's metadata, fml40 data is directly mapped to JSON when using a run time environment like an edge device or S³I Repository that contains the DT's data itself. The repository entry can be queried via HTTP REST request, refer to [S³I Documentation](https://kwh40.pages.rwth-aachen.de/-/s3i/-/jobs/1095388/artifacts/public/html/md/communication.html). The permanent Digital Twin of the harvester has a repository entry which is shown in the following:
```
{
"thingId": "s3i:b6d1cc6d-896c-40fe-9403-b5b7682b1d03",
......@@ -290,35 +290,35 @@ ## S³I Repository entry
```
## Service Call
As shown in the directory entry, the DT provided diverse service functions. A list containing all implemented and embedded service functions can be found below:
As shown in the directory entry, the DT provides several service functions, which is summarized here:
```
class: fml40::AcceptsFellingJobs
methods:
service functions:
- acceptJob(job)
- queryJobStatus(identifier)
- removeJob(identifier)
class: fml40::ProvidesProductionData
methods:
service functions:
- getProductionData(name)
```
In order to call those functions remotely, we need to send a S³I-B ServiceRequest to the Digital Twin via the S³I Broker. The class/method name and parameters need to be declared within the message.
The following example shows how to call `removeJob` of the class `fml40::AcceptsFellingJob`
In order to call remotely them, we need to send an S³I-B ServiceRequest message to the Digital Twin via S³I Broker. The class/service function name and parameters need to be declared within the message.
The following example shows how to call `removeJob` from class `fml40::AcceptsFellingJob`
```
{
"identifier": "s3i:94f8c4d1-9d6c-45e8-a137-3bb33b1004b6" # message ID
"sender": "s3i:7f46a255-3245-439e-84f0-090f0b221965", # ID of my private HMI
"receivers": ["s3i:b6d1cc6d-896c-40fe-9403-b5b7682b1d03"], # ID of the Digital Twin
"serviceType": "fml40::AcceptsFellingJob/removeJob", # specifies the method and class, which should be called
"parameters": {"identifier": "s3i:3ba16ab9-a472-42b7-af97-c19acef55196"}, # specifies the input
"receivers": ["s3i:b6d1cc6d-896c-40fe-9403-b5b7682b1d03"], # ID of the receiving Digital Twin
"serviceType": "fml40::AcceptsFellingJob/removeJob", # specifies the service function and class, which should be called
"parameters": {"identifier": "s3i:3ba16ab9-a472-42b7-af97-c19acef55196"}, # specifies the input to this service function
"messageType": "ServiceRequest", # message type
"replyToEndpoint": "s3ib://s3i:7f46a255-3245-439e-84f0-090f0b221965" # Endpoint of my private HMI,
}
```
The message can be sent directly via [the S³I Broker API](https://broker.s3i.vswf.dev/apidoc) or using [S³I Python Lib](https://kwh40.pages.rwth-aachen.de/-/s3i/-/jobs/1095388/artifacts/public/html/S3I-Package.html), An example can be found [here](https://git.rwth-aachen.de/kwh40/s3i/-/blob/master/demo/demo2_sender_hmi.py)
The message can be sent directly via [the S³I Broker API](https://broker.s3i.vswf.dev/apidoc) or using [S³I Python Lib](https://kwh40.pages.rwth-aachen.de/-/s3i/-/jobs/1095388/artifacts/public/html/S3I-Package.html). An example can be found [here](https://git.rwth-aachen.de/kwh40/s3i/-/blob/master/demo/demo2_sender_hmi.py)
## Query Value
A service is implemented in the DT with the purpose of handling S³I GetValueRequest, so we can send a getValueRequest message to query a specified value of the original JSON model in the edge DT. In the following, we provide also an example to query the current motor rpm value.
The DT can also handle S³I GetValueRequest messages like this example for querying its engine's rpm:
```
{
'sender': 's3i:7f46a255-3245-439e-84f0-090f0b221965', # ID of my private HMI
......@@ -329,5 +329,4 @@ ## Query Value
'attributePath': 'attributes/features/ml40::Composite/targets/ml40::Engine/features/ml40::RotationalSpeed/rpm' # the path of rpm value
}
```
You can also query the whole JSON file and in this case, you just need to replace the `attributePath` with empty string.
The S³I GetValueRequest can be sent via the S³I Broker API or using S³I Python lib as well.
\ No newline at end of file
You can also query the whole JSON file and, in this case, you just need to replace the `attributePath` with an empty string.
\ No newline at end of file
Quick Start
==============================
Reference implementation of the Forest Modelling Language 4.0 (fml40) which is explained in the [KWH ForestML 4.0 white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf), currently only in German.
To use the fml40 reference implementation package in your own project you need to install it using the latest [wheel](https://git.rwth-aachen.de/kwh40/fml40-reference-implementation/-/jobs/artifacts/master/raw/public/ml-0.1-py3-none-any.whl?job=wheel).
Reference implementation for building a Digital Twin based on the Forest Modeling Language 4.0 (fml40), as specified in [this white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf) (in German).
To use the fml40 reference implementation package in your own project, you need to install it using the latest [wheel](https://git.rwth-aachen.de/kwh40/fml40-reference-implementation/-/jobs/artifacts/master/raw/public/ml-0.1-py3-none-any.whl?job=wheel).
To install this wheel, go to the respective directory or switch to your designated virtual environment and install the `.whl` file, just run
```
pip install https://git.rwth-aachen.de/kwh40/fml40-reference-implementation/-/jobs/artifacts/master/raw/public/ml-0.1-py3-none-any.whl?job=wheel
......@@ -12,8 +12,8 @@
--------
This package provides two different modes to launch your Digital Twins:
- Launching Digital Twin quickly in persistent mode via `fml40s.py`. You need to register a thing identity for your Digital Twin via [S³I Config REST API](https://config.s3i.vswf.dev/apidoc) and prepare a respective config file which describes a ForestML 4.0 conform DT in JSON. For more details refer to the example `MyDigitalTwin.json` in the section `Config files`.
- Extending the capabilities with user defined Digital Twins, which means you can additionally define and insert a function according to ForestML 4.0 into the Digital Twin. We provide an exemplary Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master), refer to notebooks `08a`, `08b`, `08d` and `08e` .
- Launching Digital Twin quickly in persistent mode via `fml40s.py`. You need to register a thing identity for your Digital Twin via [S³I Config REST API](https://config.s3i.vswf.dev/apidoc) and prepare a respective config file that describes a fml40-compliant DT in JSON. For more details, refer to the example `MyDigitalTwin.json` in the section `Config files`.
- Extending the capabilities with user defined Digital Twins, which means you can additionally define and insert a function according to ForestML 4.0 into the Digital Twin. We provide an exemplary Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master), refer to notebooks `08a`, `08b`, `08d` and `08e`.
Usage
-----
......@@ -32,14 +32,14 @@ ### Using fml40s.py
```
### Develop your Digital Twin using this package
We introduce here briefly how to develop a user-specified Digital Twin. For more details refer to the created cloud and edge Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master).
The following steps can be only carried out after you have created the identity of your Digital Twin via Config REST API and made a respective config file. We use the config file `MyDigitalTwin.json` appearing in the section `Config files` to build a Digital Twin. Now we continue the following steps.
Here, we introduce briefly how to develop a user-specified Digital Twin. For more details, refer to the cloud/edge Digital Twin built in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master).
The following steps can only be carried out after you have created the thing identity of your Digital Twin via S³I Config REST API and made a respective config file. Here, we use the config file `MyDigitalTwin.json` from section `Config files`. Now we continue the following steps:
- Optionally set a logger using the function `setup_logger`. The generated log file will be then located in the folder `logs`.
- Optionally, set a logger using the function `setup_logger`. The generated log file will then be located in the folder `logs`.
```
ml.setup_logger("MyDigitalTwin")
```
- Set the path of config file and import it in JSON format.
- Set the path of the config file and import it in JSON format.
```
config_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "configs"))
......@@ -54,7 +54,7 @@ ### Develop your Digital Twin using this package
is_broker_rest=False, is_broker=True, is_repo=True
)
```
- As written in the config file, the Digital Twin has a feature named fml40::ProvidesProductionData. In the next step we extend/implement this class with our own logic.
- As specified in the config file, the Digital Twin has a feature named fml40::ProvidesProductionData. In the next step, we extend/implement this class with our own logic.
```
class ProvidesProductionDataImpl(ProvidesProductionData):
def __init__(self, name="", identifier=""):
......@@ -78,18 +78,18 @@ ### Develop your Digital Twin using this package
```
thing.run_forever()
```
So far, your Digital Twin has been created. In the meantime you can establish a connection with it using S3I-B messages.
So far, your Digital Twin has been created. In the meantime, you can establish a connection with it using S³I-B messages.
Config files
------------
A valid configuration consists of exactly one json object. Mandatory fields of the json object are
A valid configuration consists of exactly one JSON object. Mandatory fields of the JSON object are
- thingId
- policyId and
- attributes
The configuration file must be created in accordance with ForestML 4.0, refer to Cap. 7.1 of the [KWH ForestML 4.0 White Paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf). We provide in addition here an example JSON config file, see below.
The configuration file must be created in accordance with ForestML 4.0, refer to Cap. 7.1 of the [KWH3.0 ForestML 4.0 white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf). Additionally, we provide an exemplary JSON config file, see below.
MyDigitalTwin.json:
```
......@@ -183,16 +183,16 @@ ### Configs
### ml
This directory includes the implementations of the fml40 python reference implementation as described in the KWH ForestML 4.0 White Paper.
This directory includes the implementations of the fml40 python reference implementation as described in the KWH ForestML 4.0 white paper.
### demo
Example of creating and launching a HMIm which is used to communicate with the permanent Digital Twin using S³I-B protocol.
Example for creating and launching an HMI, which is used to communicate with the permanent Digital Twin using S³I-B protocol.
### logs
This folder is composed of the logging files of the created and launched Digital Twins.
This folder contains the log files of the created and launched Digital Twins.
### tests
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment