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

review documentation

parent 030313e7
...@@ -16,8 +16,8 @@ Table of Contents ...@@ -16,8 +16,8 @@ Table of Contents
md/preliminaries.md md/preliminaries.md
md/quick_start.md md/quick_start.md
md/permanent_dt.md
api_reference api_reference
md/permanent_dt.md
Indices and tables Indices and tables
================== ==================
......
...@@ -4,7 +4,7 @@ # Permanent Digital Twin ...@@ -4,7 +4,7 @@ # Permanent Digital Twin
## S³I Directory entry ## 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", "thingId": "s3i:b6d1cc6d-896c-40fe-9403-b5b7682b1d03",
...@@ -290,7 +290,7 @@ ## S³I Repository entry ...@@ -290,7 +290,7 @@ ## S³I Repository entry
``` ```
## Service Call ## 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 class: fml40::AcceptsFellingJobs
methods: methods:
...@@ -329,4 +329,5 @@ ## Query Value ...@@ -329,4 +329,5 @@ ## Query Value
'attributePath': 'attributes/features/ml40::Composite/targets/ml40::Engine/features/ml40::RotationalSpeed/rpm' # the path of rpm 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. You can also query the whole JSON file and in this case, you just need to replace the `attributePath` with empty string.
\ No newline at end of file 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
""" 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.app_logger import APP_LOGGER
from ml.tools import remove_namespace from ml.tools import remove_namespace
...@@ -162,7 +162,7 @@ ...@@ -162,7 +162,7 @@
def build_sub_features(feature_ins, feature): 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 :param feature_ins: ml40/fml40 feature instance, which has a sub feature to be built
:type feature_ins: object :type feature_ins: object
...@@ -191,7 +191,7 @@ def build_sub_features(feature_ins, feature): ...@@ -191,7 +191,7 @@ def build_sub_features(feature_ins, feature):
def build_sub_thing(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 :param feature_ins: ml40/fml40 feature instance
:type feature_ins: object :type feature_ins: object
...@@ -208,7 +208,7 @@ def build_sub_thing(feature_ins, feature): ...@@ -208,7 +208,7 @@ def build_sub_thing(feature_ins, feature):
def build(thing, attributes): def build(thing, attributes):
""" """
Build a ml40 thing instance Builds a ml40 thing instance
:param thing: ml40 thing instance :param thing: ml40 thing instance
:type thing: object :type thing: object
...@@ -232,7 +232,7 @@ def build(thing, attributes): ...@@ -232,7 +232,7 @@ def build(thing, attributes):
def build_role(role): 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 :param role: ml40/fml40 role
:type role: dict :type role: dict
...@@ -251,7 +251,7 @@ def build_role(role): ...@@ -251,7 +251,7 @@ def build_role(role):
def build_feature(feature): 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 :param feature: ml40/fml40 feature
:type feature: dict :type feature: dict
...@@ -280,7 +280,7 @@ def build_feature(feature): ...@@ -280,7 +280,7 @@ def build_feature(feature):
def add_function_impl_obj(thing, impl_obj, feature_name): 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 :param thing: ml40 thing instance
:type thing: object :type thing: object
...@@ -307,7 +307,7 @@ def create_thing(model, grant_type="password", ...@@ -307,7 +307,7 @@ def create_thing(model, grant_type="password",
secret="", username=None, password=None, secret="", username=None, password=None,
is_broker_rest=False, is_broker=False, is_repo=False): 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 :param model: JSON of a ml40::thing model
:type model: dict :type model: dict
......
...@@ -57,7 +57,7 @@ def name(self, value): ...@@ -57,7 +57,7 @@ def name(self, value):
@property @property
def identifier(self): def identifier(self):
"""Returns the object's indentifier. """Returns the object's identifier.
:returns: Identifier :returns: Identifier
:rtype: str :rtype: str
......
...@@ -96,7 +96,7 @@ def model(self): ...@@ -96,7 +96,7 @@ def model(self):
@property @property
def features(self): def features(self):
"""Returns this object's features. """Returns thing's features.
:returns: Features :returns: Features
:rtype: dict :rtype: dict
...@@ -107,7 +107,7 @@ def features(self): ...@@ -107,7 +107,7 @@ def features(self):
@features.setter @features.setter
def features(self, value): def features(self, value):
"""Replaces __features with value. """Replaces thing's features with value.
:param value: New collection of features :param value: New collection of features
...@@ -128,7 +128,7 @@ def roles(self): ...@@ -128,7 +128,7 @@ def roles(self):
@roles.setter @roles.setter
def roles(self, value): def roles(self, value):
"""Replaces __roles with value """Replaces thing's roles with value
:param value: New collection of roles :param value: New collection of roles
""" """
...@@ -148,10 +148,9 @@ def client_secret(self): ...@@ -148,10 +148,9 @@ def client_secret(self):
@property @property
def grant_type(self): def grant_type(self):
"""Returns the method used to obtain java web tokens from the """Returns the method used to obtain JSON Web Tokens from the S³I IdentityProvider
identity provider.
:returns: authentication method :returns: OAuth2 specified grant type [password, client_credentials]
:rtype: str :rtype: str
""" """
...@@ -160,9 +159,9 @@ def grant_type(self): ...@@ -160,9 +159,9 @@ def grant_type(self):
@property @property
def access_token(self): 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 :rtype: str
""" """
...@@ -217,16 +216,21 @@ def run_forever(self): ...@@ -217,16 +216,21 @@ def run_forever(self):
@staticmethod @staticmethod
def add_user_def(func): 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() threading.Thread(target=func).start()
def __json_syn(self, freq=0.1): 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: while True:
try: try:
time.sleep(freq) time.sleep(freq)
...@@ -238,6 +242,7 @@ def __dir_syn(self, freq=0.1): ...@@ -238,6 +242,7 @@ def __dir_syn(self, freq=0.1):
"""Applies local changes to the directory entry in the cloud. """Applies local changes to the directory entry in the cloud.
:param freq: Frequency of the update. :param freq: Frequency of the update.
:type freq: float
""" """
while True: while True:
# try: # try:
...@@ -257,6 +262,7 @@ def __repo_syn(self, freq=0.1): ...@@ -257,6 +262,7 @@ def __repo_syn(self, freq=0.1):
"""Applies local changes to the repository entry in the cloud. """Applies local changes to the repository entry in the cloud.
:param freq: Frequency of the update. :param freq: Frequency of the update.
:type freq: float
""" """
while self.__is_repo: while self.__is_repo:
try: try:
...@@ -274,13 +280,13 @@ def __repo_syn(self, freq=0.1): ...@@ -274,13 +280,13 @@ def __repo_syn(self, freq=0.1):
continue continue
def __connect_with_idp(self): def __connect_with_idp(self):
"""Establishes a connection to the identity provider which guarantees, """Establishes a connection to the S³I IdentityProvider which guarantees,
that the java web token needed to use s3i online services will that the JSON web token needed to use s3i services.
be renewed if it has expired. be renewed if it has expired.
""" """
# FIXME: Use logger! #TODO: Use logger!
print( print(
BColors.OKBLUE BColors.OKBLUE
+ "[S³I][IdP]" + "[S³I][IdP]"
...@@ -301,10 +307,11 @@ def __connect_with_idp(self): ...@@ -301,10 +307,11 @@ def __connect_with_idp(self):
idp.run_forever(token_type=TokenType.ACCESS_TOKEN, on_new_token=self.__on_token) idp.run_forever(token_type=TokenType.ACCESS_TOKEN, on_new_token=self.__on_token)
def __on_token(self, token): def __on_token(self, token):
"""Updates the java web token with token and reestablishes connections """Updates the JSON Web Token with token and reestablishes connections
to the s3i online services. 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): ...@@ -316,7 +323,7 @@ def __on_token(self, token):
def __connect_with_dir(self): def __connect_with_dir(self):
"""Initializes the property dir with a Directory object which can be """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: :returns:
:rtype: :rtype:
...@@ -336,7 +343,7 @@ def __connect_with_dir(self): ...@@ -336,7 +343,7 @@ def __connect_with_dir(self):
def __connect_with_repo(self): def __connect_with_repo(self):
"""Initializes the property repo whit a Repository object which can be """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: :returns:
:rtype: :rtype:
...@@ -356,7 +363,7 @@ def __connect_with_repo(self): ...@@ -356,7 +363,7 @@ def __connect_with_repo(self):
def __connect_with_broker(self): def __connect_with_broker(self):
"""Initializes the property broker with a Broker object. Additionally """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. messages.
""" """
...@@ -441,9 +448,9 @@ def __on_broker_callback(self, ch, method, properties, body): ...@@ -441,9 +448,9 @@ def __on_broker_callback(self, ch, method, properties, body):
pass pass
def on_user_message(self, msg): 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): ...@@ -456,7 +463,7 @@ def on_user_message(self, msg):
) )
def on_get_value_request(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. sends a GetValueReply message back to the sender.
:param msg: GetValueRequest :param msg: GetValueRequest
...@@ -627,8 +634,8 @@ def _findValue(self, json, value): ...@@ -627,8 +634,8 @@ def _findValue(self, json, value):
return False return False
def on_service_request(self, body_json): def on_service_request(self, body_json):
"""Handles ServiceRequest messages. Executes the method of the """Handles S³I-B ServiceRequests. Executes the method of the
functionality specified in body_json and send a ServiceReply functionality specified in serviceType and send a ServiceReply
back to the sender. back to the sender.
:param body_json: ServiceRequest :param body_json: ServiceRequest
...@@ -726,7 +733,7 @@ def on_service_request(self, body_json): ...@@ -726,7 +733,7 @@ def on_service_request(self, body_json):
+ res.text) + res.text)
def on_get_value_reply(self, msg): 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 :param msg: GetValueReply
...@@ -755,7 +762,7 @@ def on_get_value_reply(self, msg): ...@@ -755,7 +762,7 @@ def on_get_value_reply(self, msg):
) )
def on_service_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 :param msg: ServiceReply
......
"""tools.py provivdes a collection of convenience functions.""" """This module provides a collection of convenience functions."""
import datetime import datetime
import time import time
...@@ -32,7 +32,9 @@ class BColors: ...@@ -32,7 +32,9 @@ class BColors:
def make_sub_thing(name, roles, features=[]): 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 :param name: name of the sub thing
:type name: str :type name: str
...@@ -57,7 +59,7 @@ def make_sub_thing(name, roles, features=[]): ...@@ -57,7 +59,7 @@ def make_sub_thing(name, roles, features=[]):
def make_feature_config(class_name, identifier="", name="", subFeatures=""): 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 :param class_name: class name of the fml40 feature
:type class_name: str :type class_name: str
...@@ -87,7 +89,7 @@ def make_feature_config(class_name, identifier="", name="", subFeatures=""): ...@@ -87,7 +89,7 @@ def make_feature_config(class_name, identifier="", name="", subFeatures=""):
def make_thing_config(thing_id, name, roles, features=[], config_path=""): 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 :param thing_id: identifier of the thing
:type thing_id: str :type thing_id: str
...@@ -126,7 +128,7 @@ def make_thing_config(thing_id, name, roles, features=[], config_path=""): ...@@ -126,7 +128,7 @@ def make_thing_config(thing_id, name, roles, features=[], config_path=""):
def load_config(config_filepath): 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. :param config_filepath: Path to json formatted file.
:type config_filepath: str :type config_filepath: str
...@@ -139,7 +141,7 @@ def load_config(config_filepath): ...@@ -139,7 +141,7 @@ def load_config(config_filepath):
def find_broker_endpoint(dir_obj, thing_id): 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 :param dir_obj: S³I Directory Object
:type dir_obj: object :type dir_obj: object
...@@ -156,7 +158,7 @@ def find_broker_endpoint(dir_obj, thing_id): ...@@ -156,7 +158,7 @@ def find_broker_endpoint(dir_obj, thing_id):
def remove_namespace(input_str): 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 :param input_str: input with namespace
:type input_str: str :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