marilib-pkg 0.6.0__tar.gz

marilib_pkg-0.6.0/.gitignore

@@ -0,0 +1,46 @@
+# Segger Studio specific files
+
+*.emSession
+*.jlink
+
+# Python compiled files
+*.pyc
+
+# Git conflict files
+*.orig
+
+# Visual Studio specific files
+.vscode/
+
+# Segger Studio output directory
+Output/
+
+# Python package dist
+dist/
+
+# Virtual env folder
+.venv/
+
+# Tox
+.tox/
+
+# Venv files
+.venv*
+venv
+
+# Python cache files
+__pycache__/
+
+# Build files
+build/
+
+# Distribution files
+dist/
+
+# Coverage reports
+.coverage
+coverage.*
+
+# do not commit logs
+logs_metrics
+logs

marilib_pkg-0.6.0/AUTHORS

@@ -0,0 +1,2 @@
+Geovane Fedrecheski <geovane.fedrecheski@inria.fr>
+Alexandre Abadie <alexandre.abadie@inria.fr>

marilib_pkg-0.6.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Inria
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

marilib_pkg-0.6.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: marilib-pkg
+Version: 0.6.0
+Summary: MariLib is a Python library for interacting with the Mari network.
+Project-URL: Homepage, https://github.com/DotBots/marilib
+Project-URL: Bug Tracker, https://github.com/DotBots/marilib/issues
+Author-email: Geovane Fedrecheski <geovane.fedrecheski@inria.fr>
+License: BSD
+License-File: AUTHORS
+License-File: LICENSE
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: click==8.1.7
+Requires-Dist: paho-mqtt==2.1.0
+Requires-Dist: pyserial==3.5
+Requires-Dist: rich==14.0.0
+Requires-Dist: structlog==24.4.0
+Requires-Dist: tqdm==4.66.5
+Description-Content-Type: text/markdown
+
+# MariLib 💫 👀 🐍
+
+MariLib is a Python library to interact with a local [Mari](https://github.com/DotBots/mari) network.
+It connects to a Mari gateway via UART.
+
+## Example with TUI
+MariLib provides a stateful class with gateway and node information, network statistics, and a rich real-time TUI:
+
+[mari-edge-2.webm](https://github.com/user-attachments/assets/fe50f2ba-8e67-4522-8700-69730f8e3aee)
+
+See the how it works in `examples/basic.py`.
+
+## Minimal example
+Here is a minimal example showcasing how to use MariLib:
+
+```python
+import time
+from marilib.marilib import MarilibEdge
+from marilib.serial_uart import get_default_port
+
+def main():
+    mari = MarilibEdge(lambda event, data: print(event.name, data), get_default_port())
+    while True:
+        for node in mari.gateway.nodes:
+            mari.send_frame(dst=node.address, payload=b"A" * 3)
+        statistics = [(f"{node.address:016X}", node.stats.received_rssi_dbm()) for node in mari.gateway.nodes]
+        print(f"Network statistics: {statistics}")
+        time.sleep(0.25)
+
+if __name__ == "__main__":
+    main()
+```
+See it in action in `examples/minimal.py`.

marilib_pkg-0.6.0/README.md

@@ -0,0 +1,33 @@
+# MariLib 💫 👀 🐍
+
+MariLib is a Python library to interact with a local [Mari](https://github.com/DotBots/mari) network.
+It connects to a Mari gateway via UART.
+
+## Example with TUI
+MariLib provides a stateful class with gateway and node information, network statistics, and a rich real-time TUI:
+
+[mari-edge-2.webm](https://github.com/user-attachments/assets/fe50f2ba-8e67-4522-8700-69730f8e3aee)
+
+See the how it works in `examples/basic.py`.
+
+## Minimal example
+Here is a minimal example showcasing how to use MariLib:
+
+```python
+import time
+from marilib.marilib import MarilibEdge
+from marilib.serial_uart import get_default_port
+
+def main():
+    mari = MarilibEdge(lambda event, data: print(event.name, data), get_default_port())
+    while True:
+        for node in mari.gateway.nodes:
+            mari.send_frame(dst=node.address, payload=b"A" * 3)
+        statistics = [(f"{node.address:016X}", node.stats.received_rssi_dbm()) for node in mari.gateway.nodes]
+        print(f"Network statistics: {statistics}")
+        time.sleep(0.25)
+
+if __name__ == "__main__":
+    main()
+```
+See it in action in `examples/minimal.py`.

marilib_pkg-0.6.0/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())

marilib_pkg-0.6.0/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()

marilib_pkg-0.6.0/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()

marilib_pkg-0.6.0/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()

marilib_pkg-0.6.0/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()

marilib_pkg-0.6.0/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()

marilib_pkg-0.6.0/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_pkg-0.6.0/marilib/__init__.py

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