mrg-iot 1.1.8__tar.gz

mrg_iot-1.1.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sphere / NEU IoT Testbed contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mrg_iot-1.1.8/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: mrg-iot
+Version: 1.1.8
+Summary: IoT Testbed Experiment Automation CLI for MergeTB / Sphere Testbed
+Author: Sphere / NEU IoT Testbed contributors
+License: MIT
+Project-URL: Homepage, https://gitlab.com/sphere-neu/mrg-iot
+Project-URL: Repository, https://gitlab.com/sphere-neu/mrg-iot
+Project-URL: Issues, https://gitlab.com/sphere-neu/mrg-iot/-/issues
+Keywords: iot,testbed,mergetb,sphere,automation,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bcrypt>=5.0.0
+Requires-Dist: betterproto==2.0.0b7
+Requires-Dist: certifi
+Requires-Dist: cffi>=2.0.0
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: grpclib>=0.4.8
+Requires-Dist: h2>=4.3.0
+Requires-Dist: hpack>=4.1.0
+Requires-Dist: hyperframe>=6.1.0
+Requires-Dist: mergetbapi==1.3.41
+Requires-Dist: multidict>=6.7.0
+Requires-Dist: packaging>=25.0
+Requires-Dist: paramiko>=4.0.0
+Requires-Dist: pycparser>=2.23
+Requires-Dist: PyNaCl>=1.6.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: six>=1.17.0
+Requires-Dist: typing_extensions>=4.15.0
+Provides-Extra: dev
+Requires-Dist: astroid==4.0.1; extra == "dev"
+Requires-Dist: black==25.9.0; extra == "dev"
+Requires-Dist: dill==0.4.0; extra == "dev"
+Requires-Dist: invoke==2.2.1; extra == "dev"
+Requires-Dist: isort==7.0.0; extra == "dev"
+Requires-Dist: mccabe==0.7.0; extra == "dev"
+Requires-Dist: mypy_extensions==1.1.0; extra == "dev"
+Requires-Dist: pathspec==0.12.1; extra == "dev"
+Requires-Dist: platformdirs==4.5.0; extra == "dev"
+Requires-Dist: pylint==4.0.2; extra == "dev"
+Requires-Dist: pytokens==0.2.0; extra == "dev"
+Requires-Dist: tomlkit==0.13.3; extra == "dev"
+Requires-Dist: types-paramiko; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-python
+
+# mrg-iot
+
+A Python CLI for automating IoT testbed experiments on the
+[Sphere / Merge Testbed](https://sphere-testbed.net) platform.
+
+`mrg-iot` drives the full experiment lifecycle so you don't have to:
+
+- Create an experiment and its network model for the selected devices.
+- Realize and materialize the model.
+- Create an XDC (eXperimental Data Center) and attach it to the
+  materialization.
+- Set up SSH port forwarding for RTSP streams and file downloads.
+- (Optional) De-materialize and clean up resources when you're done.
+
+## Installation
+
+```bash
+pipx install mrg-iot
+```
+
+(Or `pip install mrg-iot` inside a virtualenv.)
+
+`mrg-iot` requires **Python 3.9+** and a working
+[VLC](https://www.videolan.org/vlc/) install on the host for RTSP
+playback — `pip` can't install VLC for you.
+
+## Usage
+
+### Interactive mode
+
+```bash
+mrg-iot login        # save credentials to ~/.mrg-iot/config.json
+mrg-iot              # walk through the experiment flow
+```
+
+### Non-interactive mode
+
+```bash
+mrg-iot --non-interactive \
+    --project neuiot \
+    --devices s-echodot-1 \
+    --exp-name myexp \
+    --exp-desc "my experiment" \
+    --realization realiot \
+    --duration 1w \
+    --xdc myxdc
+```
+
+### Cleanup subcommands
+
+```bash
+mrg-iot exp delete         --project neuiot --name myexp
+mrg-iot exp dematerialize  --project neuiot --name myexp --realization realiot
+mrg-iot xdc detach         --project neuiot --name myxdc --experiment myexp --realization realiot
+mrg-iot xdc delete         --project neuiot --name myxdc
+```
+
+Run `mrg-iot --help` for the full flag list.
+
+### Debug logging
+
+```bash
+mrg-iot --debug      # verbose logs to stderr + debug.log
+```
+
+## Input validation
+
+The CLI validates inputs upfront so bad args fail fast rather than
+deep inside a portal call:
+
+- **Names** (`exp-name`, `realization`, `xdc`, network): start with a
+  letter, lowercase letters and digits only, max 32 chars.
+- **Description**: letters, digits, spaces, commas, periods, hyphens;
+  max 256 chars.
+- **Duration**: minimum 4 days. Accepts `1w`, `4d`, `1w2d`,
+  `1 week`, etc.
+
+## macOS SSL note
+
+If portal calls fail with an SSL error on macOS:
+
+```bash
+export SSL_CERT_FILE="$(python -m certifi)"
+export REQUESTS_CA_BUNDLE="$SSL_CERT_FILE"
+```
+
+## Development
+
+```bash
+git clone https://gitlab.com/sphere-neu/mrg-iot.git
+cd mrg-iot
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+mypy .
+pylint *.py
+black *.py
+isort *.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mrg_iot-1.1.8/README.md

@@ -0,0 +1,103 @@
+# mrg-iot
+
+A Python CLI for automating IoT testbed experiments on the
+[Sphere / Merge Testbed](https://sphere-testbed.net) platform.
+
+`mrg-iot` drives the full experiment lifecycle so you don't have to:
+
+- Create an experiment and its network model for the selected devices.
+- Realize and materialize the model.
+- Create an XDC (eXperimental Data Center) and attach it to the
+  materialization.
+- Set up SSH port forwarding for RTSP streams and file downloads.
+- (Optional) De-materialize and clean up resources when you're done.
+
+## Installation
+
+```bash
+pipx install mrg-iot
+```
+
+(Or `pip install mrg-iot` inside a virtualenv.)
+
+`mrg-iot` requires **Python 3.9+** and a working
+[VLC](https://www.videolan.org/vlc/) install on the host for RTSP
+playback — `pip` can't install VLC for you.
+
+## Usage
+
+### Interactive mode
+
+```bash
+mrg-iot login        # save credentials to ~/.mrg-iot/config.json
+mrg-iot              # walk through the experiment flow
+```
+
+### Non-interactive mode
+
+```bash
+mrg-iot --non-interactive \
+    --project neuiot \
+    --devices s-echodot-1 \
+    --exp-name myexp \
+    --exp-desc "my experiment" \
+    --realization realiot \
+    --duration 1w \
+    --xdc myxdc
+```
+
+### Cleanup subcommands
+
+```bash
+mrg-iot exp delete         --project neuiot --name myexp
+mrg-iot exp dematerialize  --project neuiot --name myexp --realization realiot
+mrg-iot xdc detach         --project neuiot --name myxdc --experiment myexp --realization realiot
+mrg-iot xdc delete         --project neuiot --name myxdc
+```
+
+Run `mrg-iot --help` for the full flag list.
+
+### Debug logging
+
+```bash
+mrg-iot --debug      # verbose logs to stderr + debug.log
+```
+
+## Input validation
+
+The CLI validates inputs upfront so bad args fail fast rather than
+deep inside a portal call:
+
+- **Names** (`exp-name`, `realization`, `xdc`, network): start with a
+  letter, lowercase letters and digits only, max 32 chars.
+- **Description**: letters, digits, spaces, commas, periods, hyphens;
+  max 256 chars.
+- **Duration**: minimum 4 days. Accepts `1w`, `4d`, `1w2d`,
+  `1 week`, etc.
+
+## macOS SSL note
+
+If portal calls fail with an SSL error on macOS:
+
+```bash
+export SSL_CERT_FILE="$(python -m certifi)"
+export REQUESTS_CA_BUNDLE="$SSL_CERT_FILE"
+```
+
+## Development
+
+```bash
+git clone https://gitlab.com/sphere-neu/mrg-iot.git
+cd mrg-iot
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+mypy .
+pylint *.py
+black *.py
+isort *.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mrg_iot-1.1.8/grpc_runner.py

@@ -0,0 +1,93 @@
+"""
+Creates an implementation for easily managing a grpc call and accounting for stream terminations
+"""
+
+import socket
+from typing import Any
+import logging
+
+from types import FunctionType
+import betterproto
+from grpclib import GRPCError
+from grpclib.client import Channel
+from grpclib.config import Configuration
+from grpclib.exceptions import StreamTerminatedError
+
+GRPC_HOST = "grpc.sphere-testbed.net"
+GRPC_PORT = 443
+MAX_TERM_RETRIES = 3
+AUTH = "authorization"
+TOKEN_TEMPLATE = "Bearer {}"
+
+
+class GrpcRunner:
+    """
+    Class for running grpc calls and handling stream terminations
+    """
+
+    @staticmethod
+    async def run(
+        grpc_stub: type[betterproto.ServiceStub],
+        target: FunctionType,
+        request: betterproto.Message,
+        token: str = "",
+    ) -> Any:
+        """
+        Runs a grpc method with a given stub and target function
+
+        :param grpc_stub: The stub to call the function from
+        :param target: The target function to call
+        :param request: The request object of the function
+        :param token: User's authentication token, defaults to ""
+        :raises GRPCError: When the grpc call raises an exception back
+        :raises StreamTerminatedError: When the stream terminates due to idle
+        :return: Response from the grpc function
+        """
+
+        i = MAX_TERM_RETRIES
+
+        while i > 0:
+
+            channel = GrpcRunner.create_channel()
+            stub = grpc_stub(channel)
+            meta_data = {AUTH: TOKEN_TEMPLATE.format(token)} if token else None
+
+            try:
+                # pyright: ignore[reportCallIssue]
+                response: betterproto.Message = await target(
+                    stub, request, metadata=meta_data
+                )
+                channel.close()
+                return response
+
+            except GRPCError as e:
+                channel.close()
+                logging.debug("GRPC channel closed after error")
+                raise e
+
+            except (StreamTerminatedError, socket.gaierror) as e:
+                i -= 1
+
+                if i <= 0:
+                    print(
+                        "[mrg-iot] "
+                        + "Communication with Merge Portal interrupted and failed to reconnect. "
+                        "Please wait a few minutes before before attempting communication again. "
+                        f"Received from communication channel: {e}"
+                    )
+                    logging.exception("Max retries exceeded | original_error=%s", e)
+                    raise e
+
+    @staticmethod
+    def create_channel() -> Channel:
+        """
+        Creates a channel for use for grpc communication
+
+        :return: grpc channel connected to
+        """
+
+        config = Configuration(30, 15, True)
+
+        channel = Channel(GRPC_HOST, GRPC_PORT, ssl=True, config=config)
+
+        return channel

mrg_iot-1.1.8/log_manager.py

@@ -0,0 +1,53 @@
+"""
+A module to hold all logging-related classes and methods.
+"""
+
+import logging
+from mrgiot_consts import DEBUG_LOG_PATH
+
+class LogManager:
+    """
+    Singleton class for managing logging configuration.
+    """
+
+    _instance = None
+    _initialized = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+        self._initialized = True
+
+    @staticmethod
+    def get_instance() -> "LogManager":
+        """This function returns the instance of our Log Manager
+
+        Returns:
+            LogManager: The instance of our Log Manager
+        """
+        if LogManager._instance is None:
+            return LogManager()
+        return LogManager._instance
+
+    def configure_logging(self, debug: bool = False):
+        """This function configures logging
+
+        Args:
+            debug (bool, optional): handles debug logging based on the debug flag. Defaults to False.
+        """
+        logging.basicConfig(
+            filename=DEBUG_LOG_PATH,
+            level=logging.DEBUG if debug else logging.INFO,
+            format="%(asctime)s [%(levelname)s] %(message)s",
+            datefmt="%d %B %Y %I:%M:%S %p",
+            filemode="w",
+        )
+        logging.getLogger("paramiko").setLevel(logging.WARNING)
+        logging.getLogger("paramiko.transport").setLevel(logging.WARNING)
+        logging.getLogger("hpack").setLevel(logging.WARNING)
+        logging.getLogger("grpclib").setLevel(logging.WARNING)

mrg_iot-1.1.8/miko_tunnel.py

@@ -0,0 +1,145 @@
+"""
+Implementation for a paramiko based tunnel based on information gotten from the following demo:
+    https://github.com/paramiko/paramiko/blob/main/demos/forward.py
+
+Which creates a substitution for an openSSH tunnel since it is not implementated by paramiko
+"""
+
+from socketserver import ThreadingTCPServer
+
+
+import select
+import socketserver
+import threading
+import paramiko
+from paramiko.ssh_exception import SSHException
+
+
+# pylint: disable=too-few-public-methods
+class MikoTunnel:
+    """
+    Implementation for a paramiko based tunnel
+    """
+
+    __transport: paramiko.Transport
+    __remote_host: str
+    __remote_port: int
+    __local_port: int
+    __forward_server: socketserver.ThreadingTCPServer
+
+    def __init__(
+        self,
+        transport: paramiko.Transport,
+        remote_host: str,
+        remote_port: int,
+        local_port: int = -1,
+    ):
+        """
+        Instantiates a paramiko based forwarding tunnel
+
+        :param transport: paramiko transport to be the source of the tunnel
+        :param remote_host: The remote host to bind to
+        :param remote_port: The remote port to bind to
+        :param local_port: The local port to bind to, defaults to match remote_port
+        """
+
+        self.transport = transport
+        self.remote_host = remote_host
+        self.remote_port = remote_port
+        self.local_port = local_port if local_port > 0 else remote_port
+        self.__forward_server = self.__start()
+
+    def __start(self) -> ThreadingTCPServer:
+        """
+        Starts the tunnel by opening a TCP server that forwards traffic as a daemon thread
+
+        :return: The running traffic forwarding server
+        """
+
+        class _Handler(ForwardHandler):
+            """
+            Local subclass for passing information about the remote host to the server
+            """
+
+            target_host = self.remote_host
+            target_port = self.remote_port
+            ssh_transport = self.transport
+
+        tunnel = socketserver.ThreadingTCPServer(("", self.local_port), _Handler)
+        tunnel.allow_reuse_address = True
+        tunnel.daemon_threads = True
+        thread = threading.Thread(target=tunnel.serve_forever, daemon=True)
+        thread.start()
+
+        return tunnel
+
+    def close(self):
+        """
+        Translates a close call into the server close call to properly close the tunnel
+        """
+        self.__forward_server.server_close()
+
+    def __del__(self):
+        """
+        Automatically closes the tunnel when the instance is deleted to prevent sockets from being occupied
+        """
+        
+        self.close()
+        
+
+
+class ForwardHandler(socketserver.BaseRequestHandler):
+    """
+    Handler for the tunnel that forwards traffic from each end of the tunnel to the other
+    """
+
+    target_host: str
+    target_port: int
+    ssh_transport: paramiko.Transport
+
+    def handle(self) -> None:
+        """
+        Handler function for handling incoming communication from the either end of the tunnel
+        """
+
+        try:
+            channel = self.ssh_transport.open_channel(
+                "direct-tcpip",
+                (self.target_host, self.target_port),
+                self.request.getpeername(),
+            )
+
+        except SSHException as e:
+            print(e)
+            return
+
+        if not channel:
+            return
+
+        # Main tunnel loop
+        try:
+            while not channel.closed:
+                read_list, _, _ = select.select([self.request, channel], [], [], 1.0)
+
+                # Send incoming traffic out
+                if self.request in read_list:
+                    traffic = self.request.recv(1024)
+                    if not traffic:
+                        break
+                    channel.send(traffic)
+
+                # Recieve or redirect inbound traffic
+                if channel in read_list:
+                    traffic = channel.recv(1024)
+                    if not traffic:
+                        break
+                    self.request.send(traffic)
+
+        except (ConnectionResetError, OSError):
+            pass
+
+        finally:
+
+            # Close the socket if needed
+            if self.request.fileno() != -1:
+                self.request.close()