Commit 4e155be0 authored by Jiahang Chen's avatar Jiahang Chen
Browse files

clean up

parent 152e8ae8
......@@ -50,10 +50,10 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
# html_theme = 'bizstyle'
html_theme = 'classic'
html_theme = 'nature'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_logo = "_static/logo.png"
# Permanent Digital Twin
With the fml40-python-lib, we have developed a Digital Twin, which is modeled based on the language FML40 and runs permanent. 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 and then just run the hmi.py to communicate with the DT after installing the corresponding python virtual environment. This documentation introduces the main features of the Digital Twin and JSON entries in the S³I Directory and Repository.
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.
## S³I Directory entry
......
Quick Start
==============================
Reference implementation of the forest modelling language 4.0 (fml 4.0) which is explained in a [KWH 4.0 white paper](https://www.kwh40.de/wp-content/uploads/2020/03/KWH40-Standpunkt-fml40-Version-1.0.pdf).
To use the fml40 reference implementation package in your own project you can 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
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).
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
```
Features
--------
This package provides two different modes to launch your Digital Twins:
- launching digital twins 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)
- extending the capabilities with user defined digital twins. We provide an example in [Jupyter Notebook](https://mybinder.org/v2/gh/kwh40/notebooks/master), refer to notebooks `08a` and `08b`.
- 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` .
Usage
-----
### Using fml40s.py
A digital twin can be launched in persistent mode by executing
A Digital Twin can be launched in persistent mode by executing
```
python fml40s.py launch <CONFIG_FILE>
```
all the config files must be located in the folder `configs`.
Config files for Digital Twin must be located in the folder `configs`.
For more options call just run
```
python fml40s.py -h
```
### 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.
- Optionally set a logger using the function `setup_logger`. The generated log file will be then located in the folder `logs`.
```
ml.setup_logger("MyDigitalTwin")
```
- Set the path of config file and import it in JSON format.
```
config_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "configs"))
dt_model = ml.load_config(config_filepath=os.path.join(config_path, "MyDigitalTwin.json"))
```
- Create the thing instance.
```
client_secret = "" #To be filled
thing = ml.create_thing(
model=dt_model, grant_type="client_credentials", secret=client_secret,
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.
```
class ProvidesProductionDataImpl(ProvidesProductionData):
def __init__(self, name="", identifier=""):
super(ProvidesProductionData, self).__init__(
name=name,
identifier=identifier)
self.production_data_list = thing.features["ml40::ProductionData"].subFeatures["ml40::Composite"].targets
def getProductionData(self, name):
for key in self.production_data_list.keys():
if key == name:
return self.production_data_list[key].to_subthing_json()
return {"error": "NOT FOUND"}
```
- Insert the class into the respective feature of your Digital Twin
```
ml.add_function_impl_obj(thing, ProvidesProductionDataImpl, "fml40::ProvidesProductionData")
```
- Launch your Digital Twin
```
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.
Config files
------------
......@@ -36,9 +89,10 @@
- policyId and
- attributes
MyDigitalTwin.json:
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.
``` example
MyDigitalTwin.json:
```
{
"thingId": "s3i:id",
"policyId": "s3i:id",
......@@ -54,6 +108,60 @@
{
"class": "fml40::ProvidesProductionData"
},
{
"class": "ml40::ProductionData",
"subFeatures": [
{
"class": "ml40::Composite",
"targets": [
{
"class": "ml40::Thing",
"name": "Stammsegment 4711",
"roles": [
{
"class": "fml40::StemSegment",
}
],
"features": [
{
"class": "ml40::Location",
"latitude": 50.1231,
"longitude": 6.1231
},
{
"class": "fml40::StemSegmentProperties",
"diameter": 0.4,
"length": 2,
"woodType": "Spruce"
}
]
},
{
"class": "ml40::Thing",
"name": "Stammsegment 4712",
"roles": [
{
"class": "fml40::StemSegment",
}
],
"features": [
{
"class": "ml40::Location",
"latitude": 50.1231,
"longitude": 6.1231
},
{
"class": "fml40::StemSegmentProperties",
"diameter": 0.6,
"length": 3,
"woodType": "Spruce"
}
]
}
]
}
]
},
{
"class": "ml40::Location",
"longitude": 5.03424,
......@@ -71,21 +179,21 @@
### Configs
This folder contains example configuration files in json format for some digital twins.
This folder contains configuration files in JSON format for Digital Twins.
### ml
This directory includes the implementations of the fml40 python reference implementation as described in the fml40 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 harvester. Additionally, a hmi is created to communicate with the harvester using S³I-B protocol.
Example of creating and launching a HMIm which is used to communicate with the permanent Digital Twin using S³I-B protocol.
### logs
is composed of the logging files of the created digital twins.
This folder is composed of the logging files of the created and launched Digital Twins.
### tests
contains all test scripts (currently in development)
\ No newline at end of file
This folder contains all test scripts (currently in development).
\ No newline at end of file
Supports Markdown
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