Commit c20d6bcc authored by Jiahang Chen's avatar Jiahang Chen
Browse files

Update the readme and req

parent f2e7e1f1
Pipeline #351796 passed with stage
in 21 seconds
fml40-reference-implementation
==============================
Reference implementation of the forest modelling language 4.0 (fml 4.0) which is explained in a KWH 4.0 white paper (not public yet).
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
Features
--------
- launching digital twins in single shot or persistent mode via `fml40s.py`
- launching digital twins in persistent mode via `fml40s.py`
- extending the capabilities with user defined digital twins
Requirements
......@@ -19,65 +19,62 @@
Installation
------------
Run `pip install -m requirements`
Run `pip install -m requirements` in your virtual environment. To create a virtual environment run `mkvirtualenv <ENV_NAME>` and `workon <ENV_NAME>`
Usage
-----
A digital twin can be launched in persistent mode by executing
``` example
python fml40s.py launch <path to config file>
```
python fml40s.py launch <CONFIG_FILE>
```
all the config files must be located in the folder `configs`.
For more options call just run
If called with `--singleshot` option the digital twin receives all available messages, potentially sends some messages and shuts down afterwards.
For more options call
``` example
```
python fml40s.py -h
```
Extending with user defined classes
-----------------------------------
A new thing can be implemented by creating a python class which inherits from [ManagingActor](#managing-actor) or an existing [machine](#machines). In order to use the class, it has to be registered to `DT_FACTORY` within `fml40s.py`.
Config files
------------
A valid configuration consists of exactly one json object. Mandatory fields of the json object are
- client\_secret,
- thingId and
- type
- thingId
- policyId and
- attributes
MyDigitalTwin.json:
``` example
{
"client_secret": "secret",
"thingId": "s3i:id",
"type": "Komatsu",
"functionalities": [
{
"type": "AcceptsForwardingJobs",
"proxy": "Forwards"
}
}
```
Optionally a list named `functionalities` can be defined. The objects contained by this list specify the [functionalities](#functionalities) a thing has. Currently a list entry has the following structure:
"policyId": "s3i:id",
"attributes": {
"class": "ml40::Thing",
"name": "my digital twin",
"roles": [
{
"class": "fml40::Harvester"
}
],
"features": [
{
"class": "fml40::ProvidesProductionData"
},
{
"class": "ml40::Location",
"longitude": 5.03424,
"latitude": 52.52345
}
]
``` example
{
"type": "Harvests",
"receiver": "s3i:3154edfa-5b04-4a28-b803-d6ec46135c19",
"proxy": "ManageJobs"
}
}
```
In both cases `type` has to match the exact class name of the thing or functionality. The fields `proxy` and `receiver` are option. `proxy` can be used to specify a functionality that will be executed afterwards. If this functionality is going to send messages, the id of the receiving thing has to be declared in `receiver`.
Structure
---------
......@@ -86,26 +83,19 @@ ### Configs
This folder contains example configuration files in json format for some digital twins.
### Functionalities
This directory includes the implementations of the functionalities as described in the fml40 white paper.
### Machines
Contains base classes for machines. The base classes are implemented as *Managing Actors* since these actors always manage different functionalities, which are *Managed Actors*.
### ml
### Managed Actor
This directory includes the implementations of the fml40 python reference implementation as described in the fml40 white paper.
A managed actor is an actor with reference to the [pykka](https://www.pykka.org/en/latest/) implementation. To instantiate a managed actor, an associated *Managing Actor* is needed. The managed actor registers at this managing actor.
### Managing Actor
### demo
A managing actor has a dict *proxyFunctionalities* that lists all actors/functionalities the managing actor manages. The dict assigns the names of the managed actor to their proxy reference (see also [pykka proxies](https://www.pykka.org/en/latest/api/proxies/)). Also, the managing actor stops all its managed actors listed in its dict before it is stopped itself.
Example of creating and launching a harvester. Additionally, a hmi is created to communicate with the harvester using S³I-B protocol.
### Tools
### logs
Implements service functions that can be used. Currently, also S³I interface functions like *sending a service request* are implemented here. These kind of functions should be outsourced in an *interfaces* directory soon.
is composed of the logging files of the created digital twins.
### Customer code example
### tests
Example implementation of a JohnDeere harvester, Ponsse harvester and Komatsu forwader.
contains all test scripts (currently in development)
\ No newline at end of file
......@@ -8,9 +8,10 @@
import argparse
from ml.tools import load_config
import os
from path.path import PROJECT_ROOT
from ml.dt_factory import create_dt_ref
root_path = os.path.abspath("")
def create_argparser():
parent_parser = argparse.ArgumentParser(prog="", description="FML40 argument parse")
......@@ -36,17 +37,17 @@ def main():
if args.command == "list":
if args.ml[0] == "dts":
g = os.walk(os.path.join(PROJECT_ROOT, "configs"))
g = os.walk(os.path.join(root_path, "configs"))
dt_name = list()
for path, dir_list, file_list in g:
for file_name in file_list:
dt_name.append(load_config(file_name)["attributes"].get("name", None))
dt_name.append(load_config(file_name, root=root_path)["attributes"].get("name", None))
print(dt_name)
elif args.command == "launch":
dt_config = args.dt_config[0]
try:
model = load_config(dt_config)
model = load_config(dt_config, root=root_path)
except FileNotFoundError:
print("{} can not be found".format(dt_config))
return
......
......@@ -18,8 +18,7 @@
url = "https://www.kwh40.de/",
packages=setuptools.find_packages(),
install_requires=[
"pylint",
"requests",
"requests"
],
classifiers=[
"Programming Language :: Python :: 3",
......
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