juniconnlib-core 1.1.1__py3-none-any.whl

juniconnlib_core/__init__.py

@@ -0,0 +1,81 @@
+from agentlib.utils.plugin_import import ModuleImport
+
+import juniconnlib_core._version as package_version
+from juniconnlib_core.modules import (
+    devtools,
+    fiware_iota_communicators,
+    fiware_iota_device_provisioner,
+    fiware_ocb_communicators,
+    fiware_ocb_entity_provisioner,
+    fiware_subscriptions,
+    influxdb_writer,
+    json_schema_parser,
+)
+
+version = package_version.version
+__version__ = package_version.__version__
+__version_tuple__ = package_version.__version_tuple__
+version_tuple = package_version.version_tuple
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "MODULE_TYPES",
+]
+
+
+# This property MODULE_TYPES has to exist with exactly this name, so that the plugin
+# is usable in the agentlib
+
+MODULE_TYPES = {
+    "json_schema_parser": ModuleImport(
+        import_path="juniconnlib_core.modules.json_schema_parser",
+        class_name=json_schema_parser.GeneralJsonSchemaParser.__name__,
+    ),
+    "mqtt_communicator_send_to_iota": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_iota_communicators",
+        class_name=fiware_iota_communicators.MQTTCommunicatorSendToIoTA.__name__,
+    ),
+    "mqtt_communicator_receive_from_iota": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_iota_communicators",
+        class_name=fiware_iota_communicators.MQTTCommunicatorReceiveFromIoTA.__name__,
+    ),
+    "debug_listener": ModuleImport(
+        import_path="juniconnlib_core.modules.devtools",
+        class_name=devtools.DebugListener.__name__,
+    ),
+    "debug_sender": ModuleImport(
+        import_path="juniconnlib_core.modules.devtools",
+        class_name=devtools.DebugSender.__name__,
+    ),
+    "fiware_iota_device_provisioner": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_iota_device_provisioner",
+        class_name=fiware_iota_device_provisioner.FiwareIoTADeviceProvisioner.__name__,
+    ),
+    "influxdb_writer": ModuleImport(
+        import_path="juniconnlib_core.modules.influxdb_writer",
+        class_name=influxdb_writer.InfluxdbWriter.__name__,
+    ),
+    "fiware_ocb_entity_provisioner": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_ocb_entity_provisioner",
+        class_name=fiware_ocb_entity_provisioner.FiwareOCBEntityProvisioner.__name__,
+    ),
+    "fiware_mqtt_subscription_handler": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_subscriptions",
+        class_name=fiware_subscriptions.FiwareMQTTSubscriptionHandler.__name__,
+    ),
+    "fiware_http_subscription_handler": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_subscriptions",
+        class_name=fiware_subscriptions.FiwareHTTPSubscriptionHandler.__name__,
+    ),
+    "mqtt_communicator_receive_from_ocb": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_ocb_communicators",
+        class_name=fiware_ocb_communicators.MQTTCommunicatorReceiveFromOCB.__name__,
+    ),
+    "http_communicator_send_to_ocb": ModuleImport(
+        import_path="juniconnlib_core.modules.fiware_ocb_communicators",
+        class_name=fiware_ocb_communicators.HTTPCommunicatorSendToOCB.__name__,
+    ),
+}

juniconnlib_core/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.1.1'
+__version_tuple__ = version_tuple = (1, 1, 1)
+
+__commit_id__ = commit_id = None

juniconnlib_core/data_models/basic_models.py

@@ -0,0 +1,150 @@
+import datetime as dt
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional, Type, Union
+
+from fidere.models import Identifier
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+def timestamp_with_timezone():
+    return dt.datetime.now(tz=dt.timezone.utc)
+
+
+class Location(BaseModel):
+    """Representation of a single location.
+
+    It can either identify a specific room together with the building
+    and precise wing it is situated in or a specific wing together with
+    the according building.
+
+    The class is mainly planned to be used in context of the FZJ campus.
+    """
+
+    building: str = Field(
+        description="Building number in a standardized format consisting "
+        "of just 4"
+        "e.g. 2.1 -> 0210, 12.15 -> 1215, 9.7 -> 0970, etc.",
+    )
+    wing: str = Field(
+        description="Building wing, e.g. U, V, Z. The wing is mandatory."
+    )
+    room: str | None = Field(default=None, description="Room number")
+
+    class Config:
+        extra = "ignore"
+
+    @classmethod
+    def number2code(cls: Type[BaseModel], building_number: str | int) -> str:
+        """This function transforms buildings names like "02.1", "12.15"
+        into the standardized format "0210", "1215".
+
+        For more information on the standardized format, please take a
+        look at :class:juniconnlib_core.data_models.fiware_models.BuildingNumber
+
+        Args:
+            building_number (str, int): number of the building
+
+        Returns:
+            building code in the standardized format, e.g. 0210, 1215, 0970
+        """
+        if re.match(r"^\d{4}(\D*)", building_number):
+            return building_number
+        # return '{0[0]:0>2}{0[1]:0<2}'.format(building_number.split('.'))
+        # simpler to understand is below:
+        # (Does the replacement by adding '0' only if after removing ".", we don't have a 4-digit number.)
+        # We keep the building wing, if present.
+        return re.sub(
+            r"^(\d{3})(\D*)$", r"\g<1>0\g<2>", building_number.replace(".", "")
+        )
+
+
+class AttributeUpdate(BaseModel):
+    """Representation of an attribute update of a FIWARE entity.
+
+    This is meant to be used as a container for all necessary information
+    needed to exchange information on updates for or from FIWARE attributes"""
+
+    entity_id: str = Field(description="FIWARE entity identifier")
+    entity_type: str = Field(description="FIWARE entity type")
+    payload: dict[str, Any] = Field(description="MQTT payload")
+    timestamp: dt.datetime | None = Field(
+        description="Timestamp when the attribute update was initiated",
+        default_factory=timestamp_with_timezone,
+    )
+    additional_data: dict[str, Any] | None = Field(
+        default={},
+        description="Additional data that can be added to the for other "
+        "modules to work upon",
+    )
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    @field_serializer("timestamp")
+    def serialize_datetime(self, timestamp: dt.datetime) -> str:
+        return timestamp.isoformat(timespec="milliseconds")
+
+
+class IotaMqttMessage(BaseModel):
+    """Contains data for an MQTT message for the IoT agent such as
+    topic, payload, etc."""
+
+    device_id: str = Field(description="FIWARE device ID")
+    device_type: Optional[str] = Field(
+        default=None, description="FIWARE device type"
+    )
+    apikey: Optional[str] = Field(
+        default=None, description="IoT agent API key"
+    )
+    payload: Dict = Field(description="MQTT payload")
+
+    def topic(self) -> str:
+        """Creates a MQTT-topic in the format required by the FIWARE MQTT IoT
+        agent.
+
+        Returns:
+            MQTT-topic compatible to the requirements of the FIWARE IoT
+            agent.
+        """
+        return f"/json/{self.apikey}/{self.device_id}/attrs"
+
+
+class CredentialsConfig(BaseModel):
+    """Model class for storing username and password (e.g. for use with MQTT)"""
+
+    username: str
+    password: str
+
+    @classmethod
+    def load_from_file(
+        cls: Type[BaseModel], credentials_file: str | Path
+    ) -> BaseModel:
+        """Loads credentials from a file and returns an instance of
+        :class:`CredentialsConfig`
+
+        Args:
+            credentials_file (str, Path): path to credentials file. The file
+                should be in JSON format and contain at least the keys
+                "username" and "password".
+
+        Returns:
+            CredentialsConfig: Credentials read from file and validated
+        """
+        credentials_file = credentials_file
+        if not os.path.exists(credentials_file):
+            raise FileNotFoundError(
+                f"Could not find keycloak credentials file {credentials_file}!"
+            )
+        with open(credentials_file) as json_input:
+            json_data = json.load(json_input)
+
+        return CredentialsConfig.model_validate(json_data)
+
+
+class JsonSchemaInstance(BaseModel):
+    """A JSON schema to be used with the `JsonSchemaParser` module."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, allow_extra=False)
+    instance: dict[str, Any]
+    identifier: Union[str, Identifier]

juniconnlib_core/data_models/fiware_models.py

@@ -0,0 +1,277 @@
+import re
+from typing import Any, Literal, Type
+
+from filip.models import FiwareHeader
+from filip.models.ngsi_v2.context import ContextAttribute, ContextEntity
+from pydantic import Field, field_validator
+
+
+def generate_entity_id(entity_type: str, entity_content: Any) -> str:
+    """Generate an entity id based on the entity type and entity content.
+
+    Args:
+        entity_type (str): Type of the entity, e.g. Building, Wing, MessdasMeter
+        entity_content (Any): Hashable object, e.g. 0970, 0130_W, 0130_W_2001A, etc.
+
+    Returns:
+        unique FIWARE entity id based on a SHAKE256 hash of the `entity_content`.
+    """
+    from hashlib import shake_256
+
+    plain_id = f"{entity_type}_{entity_content}".encode("utf-8")
+    hash_id = shake_256(plain_id).hexdigest(16)
+
+    return f"urn:ngsi-ld:{entity_type}:{hash_id}"
+
+
+def generate_api_key(
+    fiware_header: FiwareHeader, entity_type: str, resource: str = "/iot/json"
+) -> str:
+    """Generate a unique API key based on the FIWARE service, entity type and
+    resource.
+
+    Args:
+        fiware_header (FiwareHeader): FIWARE header.
+        entity_type (str): Type of the entity or more specific device.
+        resource (str): Resource of the devices service group (default is "/iot/json").
+
+    Returns:
+        Unique API key.
+    """
+    from hashlib import shake_256
+
+    plain_id = (
+        f"{fiware_header.service}_{fiware_header.service_path}_"
+        f"{entity_type}_{resource}"
+    ).encode("utf-8")
+    return shake_256(plain_id).hexdigest(16)
+
+
+class BuildingNumber(ContextAttribute):
+    """A string of four numbers to identify a building. The
+    :class:`BuildingNumber` is meant to be used as an attribute in a
+    `ContextEntity`. The building number should be a string consisting of
+    exactly four numbers. For any further usage this formatting of four digits
+    is called the "standardized format".
+
+    A certain amount of conversion between incompatible formats is done
+    as shown in examples.
+
+    Examples:
+        9.7 -> 0970
+        10.21 -> 1021
+        02.1 -> 0210
+    """
+
+    value: str = Field(
+        title="Building number",
+        description="Building number in the standardized format, e.g. 0970, 1021, etc.",
+    )
+
+    @field_validator("value")
+    def validate_number(cls, building_number: str) -> str:
+        """Validate building number. It must be in the standardized format,
+        e.g. 0970, 1021, etc.
+
+        For more information on the standardized format, please take a
+        look at :class:juniconnlib_core.data_models.fiware_models.BuildingNumber
+
+        Args:
+            building_number: building number to validate.
+
+        Returns:
+            str: building number in case of the corrected format.
+
+        Raises:
+            ValueError: If building number is not in the
+                standard format (four digits).
+        """
+        number = BuildingNumber.normalize_building_number_format(
+            building_number
+        )
+        if number != building_number:
+            raise ValueError(
+                "Building number has a wrong format! Expected the "
+                "standardized format, e.g. 0970, 1021, etc."
+            )
+        return building_number
+
+    @classmethod
+    def normalize_building_number_format(cls, building_number: str) -> str:
+        """Format the supplied `building_number` in the standardized format.
+
+        In practice, the buildings are named similar to: 02.1, 12.15, 09.7
+        In the standardized format: 0210, 1215, 0970. Some have 15.83-A,
+        so the regex can be a little more complex. It's idempotent if
+        building_number is already in standardized format or any other
+        format lacking a '.'
+
+        Args:
+            building_number (str): e.g. 09.7
+
+        Returns:
+            str: The normalized number e.g. 0970
+        """
+        if re.match(r"^\d{4}(\D*)", building_number):
+            return building_number
+
+        parts = building_number.split(".")
+        # add leading or trailing zero if necessary
+        area_number = re.sub(r"^(\d)$", r"0\g<1>", parts[0])
+        part2 = re.sub(r"^(\d)(\D*)$", r"\g<1>0\g<2>", parts[1])
+
+        return f"{area_number}{part2}"
+
+
+class Building(ContextEntity):
+    """A data model based `ContextEntity` used as representation of a single
+    building as FIWARE entity. It holds a number for the building in addition
+    to some other data like area.
+
+    For more information on the standardized format, please take a
+    look at :class:juniconnlib_core.data_models.fiware_models.BuildingNumber
+
+    This class is meant to be used in scope of the FZJ campus, but can
+    easily be used for buildings outside this scope as well."""
+
+    type: Literal["Building"] = Field(description="Entity type 'Building'")
+    number: BuildingNumber | ContextAttribute = Field(
+        title="Building number",
+        description="Building number in the standardized format, e.g. "
+        "0970, 1021, etc. or or `ContextAttribute`",
+    )
+    area: ContextAttribute = Field(
+        description="`ContextAttribute`-object containing the area of the "
+        "building in [m^2]"
+    )
+    year: ContextAttribute = Field(
+        description="`ContextAttribute`-object containing the year "
+        "of the building."
+    )
+
+    @field_validator("number")
+    def cast_to_building_number(cls, v):
+        """Convert a possible `ContextAttribute` to a `BuildingNumber` instance"""
+        if isinstance(v, ContextAttribute):
+            v = BuildingNumber(**dict(v))
+        return v
+
+    @classmethod
+    def generate_building_id(
+        cls: Type["Building"], building_number: str
+    ) -> "str":
+        """Generates a FIWARE building ID from a building number.
+
+        Args:
+            building_number (str):  building number in the standardized
+                format, e.g. 0970, 1021, etc.
+
+        Returns:
+            FIWARE building entity ID.
+        """
+        entity_content = BuildingNumber.normalize_building_number_format(
+            building_number
+        )
+        return generate_entity_id(
+            "Building", entity_content=entity_content
+        )  # TODO: should use the type attribute instead of the hardcoded string, but that is not working?
+
+    @field_validator("number", mode="before")
+    def convert_from_context_entity(cls, value):
+        if isinstance(value, ContextAttribute):
+            return value.model_dump()
+        return value
+
+
+class Wing(ContextEntity):
+    type: Literal["Wing"] = Field(description="Has to be 'Wing'")
+    # _WING_TYPE = 'Wing'
+    refBuilding: ContextAttribute = Field(description="number of the building")
+    number: ContextAttribute = Field(
+        description="letter of the wing, e.g. U, V, W"
+    )
+
+    @field_validator("number")
+    def validate_number(cls, number: ContextAttribute):
+        """Validate building number.
+
+        Args:
+            number (ContextAttribute): Wing number as ContextAttribute
+
+        Returns:
+            ContextAttribute: building number
+
+        Raises:
+            ValueError: In case the value of the ContextAttribute is
+                not an uppercase letter
+        """
+        if not number.value.isupper():
+            raise ValueError(
+                "Wing number has a wrong format! Expected upper case, e.g. U, V, W etc."
+            )
+        return number
+
+    @classmethod
+    def generate_wing_id(
+        cls: Type["Wing"], wing_number: str, building_number: str
+    ) -> "str":
+        """Generates a FIWARE wing id by hashing a wing letter and building number.
+
+        Args:
+            wing_number (str): letter of the wing, e.g. U, V, W
+            building_number (str): building number in the standardized
+
+        Returns:
+            str: wing entity ID
+        """
+        normalized_building_number = (
+            BuildingNumber.normalize_building_number_format(building_number)
+        )
+        normalized_wing_number = wing_number.upper()
+        wing_entity_content = (
+            f"{normalized_building_number}_{normalized_wing_number}"
+        )
+        return generate_entity_id(
+            entity_type="Wing", entity_content=wing_entity_content
+        )
+
+
+class Room(ContextEntity):
+    type: Literal["Room"] = Field(description="Has to be 'Room'")
+    # _ROOM_TYPE = 'Room'
+    refBuilding: ContextAttribute = Field(description="id of the building")
+    refWing: ContextAttribute = Field(description="id of the wing")
+    number: ContextAttribute = Field(
+        description="number of the room, e.g. 300, 4002, 120a"
+    )
+
+    @field_validator("number")
+    def validate_number(cls, number: ContextAttribute):
+        """Room numbers have very different formats, so for now no validation
+        is done."""
+        return number
+
+    @classmethod
+    def generate_room_id(
+        cls: Type["Room"],
+        room_number: str,
+        wing_number: str,
+        building_number: str,
+    ) -> "str":
+        """Generates a FIWARE room id by hashing a room descriptor, wing
+        letter and building number.
+
+        Args:
+            room_number (str): number of the room, e.g. 300, 4002, 120a
+            wing_number (str): number of the wing, e.g. U, V, W
+            building_number (str): building number in the standardized format
+        """
+        normalized_building_number = (
+            BuildingNumber.normalize_building_number_format(building_number)
+        )
+        normalized_wing_number = wing_number.upper()
+        normalized_room_number = room_number.upper()
+        room_entity_content = f"{normalized_building_number}_{normalized_wing_number}_{normalized_room_number}"
+        return generate_entity_id(
+            entity_type="Room", entity_content=room_entity_content
+        )

juniconnlib_core/modules/devtools.py

@@ -0,0 +1,106 @@
+from itertools import cycle
+from typing import Any, Dict, List
+
+from agentlib.core import Agent, AgentVariable, BaseModule, BaseModuleConfig
+from pydantic import Field, ValidationError, field_validator
+
+from juniconnlib_core.utils.logging import create_logger_for_module
+
+
+class SendConfig(BaseModuleConfig):
+    delay: float = Field(
+        default=0,
+        ge=0,
+        description="Time delay to tick down before a value "
+        "should be send (again)",
+    )
+    values: List[dict[str, Any]] = Field(
+        None,
+        description="Variable to be send. Should have keys "
+        "'value' and 'alias'",
+        examples=[
+            '[{"value": ..., "alias": ...}, ' '{"value": ..., "alias": ...}]'
+        ],
+    )
+    repeat: bool = Field(
+        False,
+        description="Decision if messages should be send "
+        "repeatedly. Cycles through the list of "
+        "values.",
+    )
+
+    @field_validator("values")
+    def check_keys(cls, values):
+        for val in values:
+            if "value" not in val and "alias" not in val:
+                raise ValidationError(
+                    "Provide 'value' and 'alias' for every "
+                    "variable to be send"
+                )
+        return values
+
+
+class DebugSender(BaseModule):
+    """General sending type module that can be used for debugging purposes.
+    It sends a list of `values` to the agent broker with a given `delay`"""
+
+    config: SendConfig
+
+    def __init__(self, config: Dict, agent: Agent):
+        super().__init__(config=config, agent=agent)
+        # overwrite the logger of agent liv modules, since it has a fixed formatter
+        self.logger = create_logger_for_module(self)
+
+        self.loop = True
+        if self.config.repeat:
+            self.vals = cycle(self.config.values)
+        else:
+            self.vals = iter(self.config.values)
+
+    def process(self):
+        while True:
+            # try getting a value. If the iterator is exhausted
+            try:
+                val = next(self.vals)
+                self.logger.debug(f"Sending {val}")
+            except StopIteration:
+                self.logger.debug("All values have been sent")
+                yield self.env.event()
+
+            var = AgentVariable(**val, name="DevVar", source=self.source)
+            self.agent.data_broker.send_variable(var)
+            yield self.env.timeout(5)
+
+    def terminate(self):
+        self.loop = False
+        self.logger.info(f"Terminated {self.__class__.__name__}")
+
+    def register_callbacks(self):
+        """No callback necessary."""
+        ...
+        #  self.agent.data_broker.register_callback()
+
+
+class DebugListener(BaseModule):
+    """This module ist meant for debugging and development purposes.
+    It logs any variable on the broker on level DEBUG"""
+
+    config: BaseModuleConfig
+
+    def __init__(self, config: Dict, agent: Agent):
+        super().__init__(config=config, agent=agent)
+        # overwrite the logger of agent liv modules, since it has a fixed formatter
+        self.logger = create_logger_for_module(self)
+
+    def process(self):
+        yield self.env.event()
+
+    def terminate(self):
+        self.logger.info(f"Terminated {self.__class__.__name__}")
+
+    def register_callbacks(self):
+        """Registers a simple callback that logs ALL variables on the broker as
+        debug message."""
+        self.agent.data_broker.register_callback(
+            callback=lambda var: self.logger.debug(var)
+        )