Skip to content

GitLab

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

review documentation

parent 030313e7
Show whitespace changes
Inline Side-by-side
docs/source/index.rst
View file @ fa9e704c
......@@ -16,8 +16,8 @@ Table of Contents
md/preliminaries.md
md/quick_start.md
md/permanent_dt.md
api_reference
md/permanent_dt.md
Indices and tables
==================
......
docs/source/md/permanent_dt.md
View file @ fa9e704c
......@@ -4,7 +4,7 @@ # Permanent Digital Twin
## 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. Regarding 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 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:
```
{
"thingId": "s3i:b6d1cc6d-896c-40fe-9403-b5b7682b1d03",
......@@ -290,7 +290,7 @@ ## S³I Repository entry
```
## Service Call
As shown in the directory entry, the DT provided diverse service functions. A list containing all embedded service functions can be found below:
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:
```
class: fml40::AcceptsFellingJobs
methods:
......@@ -329,4 +329,5 @@ ## Query Value
'attributePath': 'attributes/features/ml40::Composite/targets/ml40::Engine/features/ml40::RotationalSpeed/rpm' # the path of rpm value
}
```
The message 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 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
ml/dt_factory.py
View file @ fa9e704c
""" Implements a factory for managing digital twins."""
""" This module implements a factory for managing and creating digital twins."""
from ml.app_logger import APP_LOGGER
from ml.tools import remove_namespace
......@@ -162,7 +162,7 @@
def build_sub_features(feature_ins, feature):
"""
Build a ml40/fml40 sub features
Instantiates and inserts ml40/fml40 sub features object into feature instance
:param feature_ins: ml40/fml40 feature instance, which has a sub feature to be built
:type feature_ins: object
......@@ -191,7 +191,7 @@ def build_sub_features(feature_ins, feature):
def build_sub_thing(feature_ins, feature):
"""
Build and insert a sub thing into a feature instance
Instantiates and inserts sub thing object into a feature instance
:param feature_ins: ml40/fml40 feature instance
:type feature_ins: object
......@@ -208,7 +208,7 @@ def build_sub_thing(feature_ins, feature):
def build(thing, attributes):
"""
Build a ml40 thing instance
Builds a ml40 thing instance
:param thing: ml40 thing instance
:type thing: object
......@@ -232,7 +232,7 @@ def build(thing, attributes):
def build_role(role):
"""
Build and insert a ml40/fml40 role in a ml40 thing instance
Instantiates and inserts a ml40/fml40 role object into a ml40 thing instance
:param role: ml40/fml40 role
:type role: dict
......@@ -251,7 +251,7 @@ def build_role(role):
def build_feature(feature):
"""
Build and insert a ml40/fml40 feature in a ml40 thing instance
Instantiates and inserts a ml40/fml40 feature object in a ml40 thing instance
:param feature: ml40/fml40 feature
:type feature: dict
......@@ -280,7 +280,7 @@ def build_feature(feature):
def add_function_impl_obj(thing, impl_obj, feature_name):
"""
Add user-specific implemented object to a thing instance
Adds user-specific implemented object to a thing instance
:param thing: ml40 thing instance
:type thing: object
......@@ -307,7 +307,7 @@ def create_thing(model, grant_type="password",
secret="", username=None, password=None,
is_broker_rest=False, is_broker=False, is_repo=False):
"""
Create and launch a ml40 thing with the connection to S³I
Creates and launches a ml40 thing with the connection to S³I
:param model: JSON of a ml40::thing model
:type model: dict
......
ml/role.py
View file @ fa9e704c
......@@ -57,7 +57,7 @@ def name(self, value):
@property
def identifier(self):
"""Returns the object's indentifier.
"""Returns the object's identifier.
:returns: Identifier
:rtype: str
......
ml/thing.py
View file @ fa9e704c
......@@ -96,7 +96,7 @@ def model(self):
@property
def features(self):
"""Returns this object's features.
"""Returns thing's features.
:returns: Features
:rtype: dict
......@@ -107,7 +107,7 @@ def features(self):
@features.setter
def features(self, value):
"""Replaces __features with value.
"""Replaces thing's features with value.
:param value: New collection of features
......@@ -128,7 +128,7 @@ def roles(self):
@roles.setter
def roles(self, value):
"""Replaces __roles with value
"""Replaces thing's roles with value
:param value: New collection of roles
"""
......@@ -148,10 +148,9 @@ def client_secret(self):
@property
def grant_type(self):
"""Returns the method used to obtain java web tokens from the
identity provider.
"""Returns the method used to obtain JSON Web Tokens from the S³I IdentityProvider
:returns: authentication method
:returns: OAuth2 specified grant type [password, client_credentials]
:rtype: str
"""
......@@ -160,9 +159,9 @@ def grant_type(self):
@property
def access_token(self):
"""Returns the current java web token or an empty string.
"""Returns the current JSON Web token.
:returns: java web token
:returns: JSON Web token
:rtype: str
"""
......@@ -217,16 +216,21 @@ def run_forever(self):
@staticmethod
def add_user_def(func):
"""Runs func in a thread.
"""Insert user-specified function in the thing object.
:param func: Function to be executed.
:param func: external defined function to be executed.
"""
threading.Thread(target=func).start()
def __json_syn(self, freq=0.1):
# ???: Does this do anything useful?
"""
Applies local changes to the original model in the thing object
:param freq: Frequency of the update
:type freq: float
"""
while True:
try:
time.sleep(freq)
......@@ -238,6 +242,7 @@ def __dir_syn(self, freq=0.1):
"""Applies local changes to the directory entry in the cloud.
:param freq: Frequency of the update.
:type freq: float
"""
while True:
# try:
......@@ -257,6 +262,7 @@ def __repo_syn(self, freq=0.1):
"""Applies local changes to the repository entry in the cloud.
:param freq: Frequency of the update.
:type freq: float
"""
while self.__is_repo:
try:
......@@ -274,13 +280,13 @@ def __repo_syn(self, freq=0.1):
continue
def __connect_with_idp(self):
"""Establishes a connection to the identity provider which guarantees,
that the java web token needed to use s3i online services will
"""Establishes a connection to the S³I IdentityProvider which guarantees,
that the JSON web token needed to use s3i services.
be renewed if it has expired.
"""
# FIXME: Use logger!
#TODO: Use logger!
print(
BColors.OKBLUE
+ "[S³I][IdP]"
......@@ -301,10 +307,11 @@ def __connect_with_idp(self):
idp.run_forever(token_type=TokenType.ACCESS_TOKEN, on_new_token=self.__on_token)
def __on_token(self, token):
"""Updates the java web token with token and reestablishes connections
to the s3i online services.
"""Updates the JSON Web Token with token and reestablishes connections
to the s3i services .
:param token: New java web token
:param token: New JSON Web token
:type token: str
"""
......@@ -316,7 +323,7 @@ def __on_token(self, token):
def __connect_with_dir(self):
"""Initializes the property dir with a Directory object which can be
used to access the s3i directory online service.
used to access the s3i Directory.
:returns:
:rtype:
......@@ -336,7 +343,7 @@ def __connect_with_dir(self):
def __connect_with_repo(self):
"""Initializes the property repo whit a Repository object which can be
used to access the s3i repository online service.
used to access the s3i Repository.
:returns:
:rtype:
......@@ -356,7 +363,7 @@ def __connect_with_repo(self):
def __connect_with_broker(self):
"""Initializes the property broker with a Broker object. Additionally
a callback function is registered which handles incoming S3I-B
a callback function is registered which handles incoming S³I-B Messages
messages.
"""
......@@ -441,9 +448,9 @@ def __on_broker_callback(self, ch, method, properties, body):
pass
def on_user_message(self, msg):
"""Handles Prints msg to stdout.
"""Handles incoming S³I-B UserMessages.
:param msg: S3I-B message
:param msg: S³I-B UserMessages
"""
......@@ -456,7 +463,7 @@ def on_user_message(self, msg):
)
def on_get_value_request(self, msg):
"""Handles GetValueRequest message. Looks up the value specified in msg and
"""Handles incoming GetValueRequest message. Looks up the value specified in msg and
sends a GetValueReply message back to the sender.
:param msg: GetValueRequest
......@@ -627,8 +634,8 @@ def _findValue(self, json, value):
return False
def on_service_request(self, body_json):
"""Handles ServiceRequest messages. Executes the method of the
functionality specified in body_json and send a ServiceReply
"""Handles S³I-B ServiceRequests. Executes the method of the
functionality specified in serviceType and send a ServiceReply
back to the sender.
:param body_json: ServiceRequest
......@@ -726,7 +733,7 @@ def on_service_request(self, body_json):
+ res.text)
def on_get_value_reply(self, msg):
"""Handles GetValueReply messsage. Prints the content of msg to stdout.
"""Handles incoming S³I-B GetValueReply. Prints the content of msg to stdout.
:param msg: GetValueReply
......@@ -755,7 +762,7 @@ def on_get_value_reply(self, msg):
)
def on_service_reply(self, msg):
"""Handles ServiceReply messages. Prints the content of msg to stdout.
"""Handles incoming S³I-B ServiceReply. Prints the content of msg to stdout.
:param msg: ServiceReply
......
ml/tools.py
View file @ fa9e704c
"""tools.py provivdes a collection of convenience functions."""
"""This module provides a collection of convenience functions."""
import datetime
import time
......@@ -32,7 +32,9 @@ class BColors:
def make_sub_thing(name, roles, features=[]):
"""
create a JSON for a fml40 sub thing.
Creates a dictionary representing this thing in it's current state
as a subordinate thing. This representation should be used for
subordinate things in s3i repository entries
:param name: name of the sub thing
:type name: str
......@@ -57,7 +59,7 @@ def make_sub_thing(name, roles, features=[]):
def make_feature_config(class_name, identifier="", name="", subFeatures=""):
"""
Create a JSON for a fml40 feature
Creates a dictionary representing for its ml/fml40 features
:param class_name: class name of the fml40 feature
:type class_name: str
......@@ -87,7 +89,7 @@ def make_feature_config(class_name, identifier="", name="", subFeatures=""):
def make_thing_config(thing_id, name, roles, features=[], config_path=""):
"""
Create a configuration file (JSON) for a fml40 thing.
Creates a configuration file (JSON) for a fml40 thing.
:param thing_id: identifier of the thing
:type thing_id: str
......@@ -126,7 +128,7 @@ def make_thing_config(thing_id, name, roles, features=[], config_path=""):
def load_config(config_filepath):
"""
Load a json object from a json formatted file found at config_filepath.
Loads a JSON object from a json formatted file found at config_filepath.
:param config_filepath: Path to json formatted file.
:type config_filepath: str
......@@ -139,7 +141,7 @@ def load_config(config_filepath):
def find_broker_endpoint(dir_obj, thing_id):
"""
Find the S3I-B endpoint of a thing
Finds the S3I-B endpoint of a thing
:param dir_obj: S³I Directory Object
:type dir_obj: object
......@@ -156,7 +158,7 @@ def find_broker_endpoint(dir_obj, thing_id):
def remove_namespace(input_str):
"""
Remove the specified namespace like ml40 or fml40
Removes the specified namespace like ml40 or fml40
:param input_str: input with namespace
:type input_str: str
......
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