marilib-pkg 0.6.0__py3-none-any.whl

examples/frames.py

@@ -0,0 +1,23 @@
+"""
+This script is used to generate a frame to send to a node.
+
+Usage:
+python frames.py [destination]
+
+If no destination is provided, the frame will be sent to the broadcast address.
+
+Example usage sending to broadcast address via mosquitto_pub:
+
+while [ 1 ]; do  python examples/frames.py | xxd -r -p | base64 | mosquitto_pub -h localhost -p 1883 -t /mari/00A0/to_edge -l; done
+"""
+
+from marilib.mari_protocol import Frame, Header, MARI_BROADCAST_ADDRESS
+from marilib.model import EdgeEvent
+import sys
+
+destination = sys.argv[1] if len(sys.argv) > 1 else MARI_BROADCAST_ADDRESS
+
+header = Header(destination=destination)
+frame = Frame(header=header, payload=b"NORMAL_APP_DATA")
+frame_to_send = EdgeEvent.to_bytes(EdgeEvent.NODE_DATA) + frame.to_bytes()
+print(frame_to_send.hex())

examples/mari_cloud.py

@@ -0,0 +1,72 @@
+import time
+
+import click
+from marilib.mari_protocol import MARI_BROADCAST_ADDRESS, MARI_NET_ID_DEFAULT, Frame
+from marilib.marilib_cloud import MarilibCloud
+from marilib.model import EdgeEvent, GatewayInfo, MariNode
+from marilib.communication_adapter import MQTTAdapter
+from marilib.tui_cloud import MarilibTUICloud
+from marilib.logger import MetricsLogger
+
+NORMAL_DATA_PAYLOAD = b"NORMAL_APP_DATA"
+
+
+def on_event(event: EdgeEvent, event_data: MariNode | Frame | GatewayInfo):
+    """An event handler for the application."""
+    pass
+
+
+@click.command()
+@click.option(
+    "--mqtt-url",
+    "-m",
+    type=str,
+    default="mqtt://localhost:1883",
+    show_default=True,
+    help="MQTT broker to use",
+)
+@click.option(
+    "--network-id",
+    "-n",
+    type=lambda x: int(x, 16),
+    default=MARI_NET_ID_DEFAULT,
+    help=f"Network ID to use [default: 0x{MARI_NET_ID_DEFAULT:04X}]",
+)
+@click.option(
+    "--log-dir",
+    default="logs",
+    show_default=True,
+    help="Directory to save metric log files.",
+    type=click.Path(),
+)
+def main(mqtt_url: str, network_id: int, log_dir: str):
+    """A basic example of using the MariLibCloud library."""
+
+    mari = MarilibCloud(
+        on_event,
+        mqtt_interface=MQTTAdapter.from_url(mqtt_url, is_edge=False),
+        logger=MetricsLogger(
+            log_dir_base=log_dir, rotation_interval_minutes=1440, log_interval_seconds=1.0
+        ),
+        network_id=network_id,
+        tui=MarilibTUICloud(),
+        main_file=__file__,
+    )
+
+    try:
+        while True:
+            mari.update()
+            if mari.nodes:
+                mari.send_frame(MARI_BROADCAST_ADDRESS, NORMAL_DATA_PAYLOAD)
+            mari.render_tui()
+            time.sleep(0.5)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        mari.close_tui()
+        mari.logger.close()
+
+
+if __name__ == "__main__":
+    main()

examples/mari_cloud_minimal.py

@@ -0,0 +1,38 @@
+import time
+import sys
+
+from marilib.mari_protocol import MARI_NET_ID_DEFAULT
+from marilib.marilib_cloud import MarilibCloud
+from marilib.communication_adapter import MQTTAdapter
+from marilib.model import EdgeEvent
+
+
+def on_event(event, event_data):
+    """An event handler for the application."""
+    if event == EdgeEvent.GATEWAY_INFO:
+        return
+    print(".", end="", flush=True)
+
+
+def main():
+    mari_cloud = MarilibCloud(
+        on_event,
+        mqtt_interface=MQTTAdapter("localhost", 1883, is_edge=False),
+        network_id=int(sys.argv[1], 16) if len(sys.argv) > 1 else MARI_NET_ID_DEFAULT,
+    )
+
+    while True:
+        mari_cloud.update()
+        for node in mari_cloud.nodes:
+            # print(f"Sending frame to {node.address:016X}")
+            mari_cloud.send_frame(dst=node.address, payload=b"NORMAL_APP_DATA")
+            print(",", end="", flush=True)
+        statistics = [
+            (f"{node.address:016X}", node.stats.received_rssi_dbm()) for node in mari_cloud.nodes
+        ]
+        print(f"Network statistics: {statistics}")
+        time.sleep(1)
+
+
+if __name__ == "__main__":
+    main()

examples/mari_edge.py

@@ -0,0 +1,73 @@
+import time
+
+import click
+from marilib.logger import MetricsLogger
+from marilib.mari_protocol import Frame, MARI_BROADCAST_ADDRESS
+from marilib.model import EdgeEvent, MariNode
+from marilib.communication_adapter import SerialAdapter, MQTTAdapter
+from marilib.serial_uart import get_default_port
+from marilib.tui_edge import MarilibTUIEdge
+from marilib.marilib_edge import MarilibEdge
+
+NORMAL_DATA_PAYLOAD = b"NORMAL_APP_DATA"
+
+
+def on_event(event: EdgeEvent, event_data: MariNode | Frame):
+    """An event handler for the application."""
+    pass
+
+
+@click.command()
+@click.option(
+    "--port",
+    "-p",
+    type=str,
+    default=get_default_port(),
+    show_default=True,
+    help="Serial port to use (e.g., /dev/ttyACM0)",
+)
+@click.option(
+    "--mqtt-url",
+    "-m",
+    type=str,
+    default="mqtt://localhost:1883",
+    show_default=True,
+    help="MQTT broker to use (default: empty, no cloud)",
+)
+@click.option(
+    "--log-dir",
+    default="logs",
+    show_default=True,
+    help="Directory to save metric log files.",
+    type=click.Path(),
+)
+def main(port: str | None, mqtt_url: str, log_dir: str):
+    """A basic example of using the MarilibEdge library."""
+
+    mari = MarilibEdge(
+        on_event,
+        serial_interface=SerialAdapter(port),
+        mqtt_interface=MQTTAdapter.from_url(mqtt_url, is_edge=True) if mqtt_url else None,
+        logger=MetricsLogger(
+            log_dir_base=log_dir, rotation_interval_minutes=1440, log_interval_seconds=1.0
+        ),
+        tui=MarilibTUIEdge(),
+        main_file=__file__,
+    )
+
+    try:
+        while True:
+            mari.update()
+            if not mari.uses_mqtt and mari.nodes:
+                mari.send_frame(MARI_BROADCAST_ADDRESS, NORMAL_DATA_PAYLOAD)
+            mari.render_tui()
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        mari.close_tui()
+        mari.logger.close()
+
+
+if __name__ == "__main__":
+    main()

examples/mari_edge_minimal.py

@@ -0,0 +1,37 @@
+import time
+
+from marilib.marilib_edge import MarilibEdge, EdgeEvent
+from marilib.communication_adapter import MQTTAdapter, SerialAdapter
+from marilib.serial_uart import get_default_port
+
+
+def on_event(event, event_data):
+    """An event handler for the application."""
+    if event == EdgeEvent.GATEWAY_INFO:
+        return
+    print(".", end="", flush=True)
+
+
+def main():
+    mari_edge = MarilibEdge(
+        on_event,
+        serial_interface=SerialAdapter(get_default_port()),
+        mqtt_interface=MQTTAdapter("localhost", 1883, is_edge=True),
+    )
+
+    while True:
+        mari_edge.update()
+        if not mari_edge.uses_mqtt:
+            # only generate frames if not using MQTT
+            for node in mari_edge.nodes:
+                mari_edge.send_frame(dst=node.address, payload=b"NORMAL_APP_DATA")
+                print(",", end="", flush=True)
+        statistics = [
+            (f"{node.address:016X}", node.stats.received_rssi_dbm()) for node in mari_edge.nodes
+        ]
+        print(f"Stats: {statistics}")
+        time.sleep(3)
+
+
+if __name__ == "__main__":
+    main()

examples/mari_edge_stats.py

@@ -0,0 +1,156 @@
+import sys
+import threading
+import time
+
+import click
+from marilib.logger import MetricsLogger
+from marilib.mari_protocol import MARI_BROADCAST_ADDRESS, Frame
+from marilib.marilib_edge import MarilibEdge
+from marilib.model import EdgeEvent, GatewayInfo, MariNode, TestState
+from marilib.serial_uart import get_default_port
+from marilib.tui_edge import MarilibTUIEdge
+from marilib.communication_adapter import SerialAdapter, MQTTAdapter
+
+LOAD_PACKET_PAYLOAD = b"L"
+NORMAL_DATA_PAYLOAD = b"NORMAL_APP_DATA"
+
+
+class LoadTester(threading.Thread):
+    def __init__(
+        self,
+        mari: MarilibEdge,
+        test_state: TestState,
+        stop_event: threading.Event,
+    ):
+        super().__init__(daemon=True)
+        self.mari = mari
+        self.test_state = test_state
+        self._stop_event = stop_event
+        self.has_rate = False
+        self.delay = None
+
+    def run(self):
+        while not self._stop_event.is_set():
+            # wait for gateway schedule to be available and try to compute rate
+            if not self.has_rate:
+                self.set_rate()
+            if self.delay is None:
+                self._stop_event.wait(0.1)  # fixed, waiting for gateway schedule to be available
+                continue
+
+            # once we have rate, send packets at that rate
+            with self.mari.lock:
+                nodes_exist = bool(self.mari.gateway.nodes)
+
+            if nodes_exist:
+                self.mari.send_frame(MARI_BROADCAST_ADDRESS, LOAD_PACKET_PAYLOAD)
+            self._stop_event.wait(self.delay)
+
+    def set_rate(self):
+        if self.test_state.load == 0:
+            return
+        max_rate = self.mari.get_max_downlink_rate()
+        if max_rate == 0:
+            sys.stderr.write("Error computing max rate")
+            return
+        self.test_state.rate = int(max_rate)
+        packets_per_second = max_rate * (self.test_state.load / 100.0)
+        self.delay = 1.0 / packets_per_second if packets_per_second > 0 else float("inf")
+        self.has_rate = True
+
+
+def on_event(event: EdgeEvent, event_data: MariNode | Frame | GatewayInfo):
+    """An event handler for the application."""
+    pass
+
+
+@click.command()
+@click.option(
+    "--port",
+    "-p",
+    type=str,
+    default=get_default_port(),
+    show_default=True,
+    help="Serial port to use (e.g., /dev/ttyACM0)",
+)
+@click.option(
+    "--mqtt-host",
+    "-m",
+    type=str,
+    default="",
+    show_default=True,
+    help="MQTT broker to use (default: empty, no cloud)",
+)
+@click.option(
+    "--load",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Load percentage to apply (0–100)",
+)
+@click.option(
+    "--log-dir",
+    default="logs",
+    show_default=True,
+    help="Directory to save metric log files.",
+    type=click.Path(),
+)
+def main(port: str | None, mqtt_host: str, load: int, log_dir: str):
+    if not (0 <= load <= 100):
+        sys.stderr.write("Error: --load must be between 0 and 100.\n")
+        return
+
+    test_state = TestState(
+        load=load,
+    )
+
+    logger = MetricsLogger(log_dir_base=log_dir, rotation_interval_minutes=1440)
+
+    mari = MarilibEdge(
+        on_event,
+        serial_interface=SerialAdapter(port),
+        mqtt_interface=MQTTAdapter.from_host_port(mqtt_host, is_edge=True) if mqtt_host else None,
+        logger=logger,
+        main_file=__file__,
+        tui=MarilibTUIEdge(test_state=test_state),
+    )
+
+    stop_event = threading.Event()
+
+    mari.latency_test_enable()
+
+    load_tester = LoadTester(mari, test_state, stop_event)
+    if load > 0:
+        load_tester.start()
+
+    try:
+        normal_traffic_interval = 0.5
+        last_normal_send_time = 0
+
+        while not stop_event.is_set():
+            current_time = time.monotonic()
+
+            mari.update()
+
+            mari.render_tui()
+
+            if current_time - last_normal_send_time >= normal_traffic_interval:
+                if mari.nodes:
+                    mari.send_frame(MARI_BROADCAST_ADDRESS, NORMAL_DATA_PAYLOAD)
+                last_normal_send_time = current_time
+
+            time.sleep(0.1)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        stop_event.set()
+        mari.latency_test_disable()
+        if load_tester.is_alive():
+            load_tester.join()
+        mari.close_tui()
+        mari.logger.close()
+
+
+if __name__ == "__main__":
+    main()

examples/uart.py

@@ -0,0 +1,35 @@
+import time
+
+from marilib.serial_hdlc import (
+    HDLCDecodeException,
+    HDLCHandler,
+    HDLCState,
+    hdlc_encode,
+)
+from marilib.serial_uart import SerialInterface
+
+BAUDRATE = 1000000
+# BAUDRATE = 115200
+
+hdlc_handler = HDLCHandler()
+
+
+def on_byte_received(byte):
+    # print(f"Received byte: {byte}")
+    hdlc_handler.handle_byte(byte)
+    if hdlc_handler.state == HDLCState.READY:
+        try:
+            payload = hdlc_handler.payload
+            print(f"Received payload: {payload.hex()}")
+        except HDLCDecodeException as e:
+            print(f"Error decoding payload: {e}")
+
+
+serial_interface = SerialInterface("/dev/ttyACM0", BAUDRATE, on_byte_received)
+
+
+while True:
+    time.sleep(1)
+    payload = b"AAA"
+    print(f"Sending payload: {payload.hex()}")
+    serial_interface.write(hdlc_encode(payload))

marilib/__init__.py

@@ -0,0 +1,10 @@
+__version__ = "0.6.0"
+
+
+# declare these just to avoid circular imports
+class MarilibEdge:
+    pass
+
+
+class MarilibCloud:
+    pass

marilib/communication_adapter.py

@@ -0,0 +1,212 @@
+import base64
+from urllib.parse import urlparse
+import paho.mqtt.client as mqtt
+
+from abc import ABC, abstractmethod
+from rich import print
+
+from marilib.serial_hdlc import (
+    HDLCDecodeException,
+    HDLCHandler,
+    HDLCState,
+    hdlc_encode,
+)
+from marilib.serial_uart import SerialInterface, SERIAL_DEFAULT_BAUDRATE
+
+
+class CommunicationAdapterBase(ABC):
+    """Base class for interface adapters."""
+
+    @abstractmethod
+    def init(self, on_data_received: callable):
+        """Initialize the interface."""
+
+    @abstractmethod
+    def close(self):
+        """Close the interface."""
+
+
+class SerialAdapter(CommunicationAdapterBase):
+    """Class used to interface with the serial port."""
+
+    def __init__(self, port, baudrate=SERIAL_DEFAULT_BAUDRATE):
+        self.port = port
+        self.baudrate = baudrate
+        self.hdlc_handler = HDLCHandler()
+
+    def on_byte_received(self, byte):
+        self.hdlc_handler.handle_byte(byte)
+        if self.hdlc_handler.state == HDLCState.READY:
+            try:
+                payload = self.hdlc_handler.payload
+                # print(f"Received payload: {payload.hex()}")
+                self.on_data_received(payload)
+            except HDLCDecodeException as e:
+                print(f"Error decoding payload: {e}")
+
+    def init(self, on_data_received: callable):
+        self.on_data_received = on_data_received
+        self.serial = SerialInterface(self.port, self.baudrate, self.on_byte_received)
+        print(f"[yellow]Connected to serial port {self.port} at {self.baudrate} baud[/]")
+
+    def close(self):
+        print("[yellow]Disconnect from gateway...[/]")
+
+    def send_data(self, data):
+        self.serial.serial.flush()
+        encoded = hdlc_encode(data)
+        self.serial.write(encoded)
+
+
+class MQTTAdapter(CommunicationAdapterBase):
+    """Class used to interface with MQTT."""
+
+    def __init__(self, host, port, is_edge: bool, use_tls: bool = False):
+        self.host = host
+        self.port = port
+        self.is_edge = is_edge
+        self.network_id = None
+        self.client = None
+        self.on_data_received = None
+        self.use_tls = use_tls
+        # optimize qos for throughput
+        # 0 = no delivery guarantee, 1 = at least once, 2 = exactly once
+        self.qos = 0
+
+    @classmethod
+    def from_url(cls, url: str, is_edge: bool):
+        url = urlparse(url)
+        host, port = url.netloc.split(":")
+        if url.scheme == "mqtt":
+            return cls(host, int(port), is_edge, use_tls=False)
+        elif url.scheme == "mqtts":
+            return cls(host, int(port), is_edge, use_tls=True)
+        else:
+            raise ValueError(f"Invalid MQTT URL: {url} (must start with mqtt:// or mqtts://)")
+
+    # ==== public methods ====
+
+    def is_ready(self) -> bool:
+        return self.client is not None and self.client.is_connected()
+
+    def set_network_id(self, network_id: str):
+        self.network_id = network_id
+
+    def set_on_data_received(self, on_data_received: callable):
+        self.on_data_received = on_data_received
+
+    def update(self, network_id: str, on_data_received: callable):
+        if self.network_id is None:
+            # might have been set by set_network_id
+            self.network_id = network_id
+        else:
+            # TODO: handle the case when the network_id changes
+            pass
+        if self.network_id is None:
+            # wait a bit, network_id not set yet
+            return
+        if self.on_data_received is None:
+            self.set_on_data_received(on_data_received)
+        if not self.is_ready():
+            self.init()
+
+    def init(self):
+        if self.client:
+            # already initialized, do nothing
+            return
+        if self.network_id is None:
+            # network_id not set yet
+            return
+
+        self.client = mqtt.Client(
+            mqtt.CallbackAPIVersion.VERSION2,
+            protocol=mqtt.MQTTProtocolVersion.MQTTv5,
+        )
+        if self.use_tls:
+            self.client.tls_set_context(context=None)
+        self.client.on_log = self._on_log
+        self.client.on_connect = self._on_connect_edge if self.is_edge else self._on_connect_cloud
+        self.client.on_message = self._on_message_edge if self.is_edge else self._on_message_cloud
+        self.client.connect(self.host, self.port, 60)
+        print(f"[yellow]Connected to MQTT broker on {self.host}:{self.port}[/]")
+        self.client.loop_start()
+
+    def close(self):
+        self.client.disconnect()
+        self.client.loop_stop()
+
+    def send_data_to_edge(self, data):
+        if not self.is_ready():
+            return
+        self.client.publish(
+            f"/mari/{self.network_id}/to_edge",
+            base64.b64encode(data).decode(),
+            qos=self.qos,
+        )
+
+    def send_data_to_cloud(self, data):
+        if not self.is_ready():
+            return
+        self.client.publish(
+            f"/mari/{self.network_id}/to_cloud",
+            base64.b64encode(data).decode(),
+            qos=self.qos,
+        )
+
+    # ==== private methods ====
+
+    # TODO: de-duplicate the _on_message_* functions? decide as the integration evolves
+    def _on_message_edge(self, client, userdata, message):
+        try:
+            data = base64.b64decode(message.payload)
+        except Exception as e:
+            # print the error and a stacktrace
+            print(f"[red]Error decoding MQTT message: {e}[/]")
+            print(f"[red]Message: {message.payload}[/]")
+            return
+        self.on_data_received(data)
+
+    def _on_message_cloud(self, client, userdata, message):
+        try:
+            data = base64.b64decode(message.payload)
+        except Exception as e:
+            # print the error and a stacktrace
+            print(f"[red]Error decoding MQTT message: {e}[/]")
+            print(f"[red]Message: {message.payload}[/]")
+            return
+        self.on_data_received(data)
+
+    def _on_log(self, client, userdata, paho_log_level, messages):
+        # print(messages)
+        pass
+
+    def _on_connect_edge(self, client, userdata, flags, reason_code, properties):
+        self.client.subscribe(f"/mari/{self.network_id}/to_edge", qos=self.qos)
+        print(f"[yellow]Subscribed to /mari/{self.network_id}/to_edge[/]")
+
+    def _on_connect_cloud(self, client, userdata, flags, reason_code, properties):
+        self.client.subscribe(f"/mari/{self.network_id}/to_cloud", qos=self.qos)
+        print(f"[yellow]Subscribed to /mari/{self.network_id}/to_cloud[/]")
+
+
+class MQTTAdapterDummy(MQTTAdapter):
+    """Dummy MQTT adapter, does nothing, for when edge runs only locally, without a cloud."""
+
+    def __init__(self, host="", port=0, is_edge=True):
+        super().__init__(host, port, is_edge)
+
+    def is_ready(self) -> bool:
+        """Dummy adapter is never ready."""
+        return False
+
+    def init(self):
+        pass
+
+    def close(self):
+        pass
+
+    def send_data_to_edge(self, data):
+        pass
+
+    def send_data_to_cloud(self, data):
+        pass