marilib-pkg 0.6.0__py3-none-any.whl

marilib/tui_edge.py

@@ -0,0 +1,185 @@
+from datetime import datetime, timedelta
+
+from rich.columns import Columns
+from rich.console import Console, Group
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from marilib import MarilibEdge
+from marilib.model import MariNode, TestState
+from marilib.tui import MarilibTUI
+
+
+class MarilibTUIEdge(MarilibTUI):
+    """A Text-based User Interface for MarilibEdge."""
+
+    def __init__(
+        self,
+        max_tables=3,
+        re_render_max_freq=0.2,
+        test_state: TestState | None = None,
+    ):
+        self.console = Console()
+        self.live = Live(console=self.console, auto_refresh=False, transient=True)
+        self.live.start()
+        self.max_tables = max_tables
+        self.re_render_max_freq = re_render_max_freq
+        self.last_render_time = datetime.now()
+        self.test_state = test_state
+
+    def get_max_rows(self) -> int:
+        """Calculate maximum rows based on terminal height."""
+        terminal_height = self.console.height
+        available_height = terminal_height - 10 - 2 - 2 - 1 - 2
+        return max(2, available_height)
+
+    def render(self, mari: MarilibEdge):
+        """Render the TUI layout."""
+        with mari.lock:
+            if datetime.now() - self.last_render_time < timedelta(seconds=self.re_render_max_freq):
+                return
+            self.last_render_time = datetime.now()
+            layout = Layout()
+            layout.split(
+                Layout(self.create_header_panel(mari), size=12),
+                Layout(self.create_nodes_panel(mari)),
+            )
+            self.live.update(layout, refresh=True)
+
+    def create_header_panel(self, mari: MarilibEdge) -> Panel:
+        """Create the header panel with gateway and network stats."""
+        status = Text()
+        status.append("MarilibEdge is ", style="bold")
+        status.append(
+            "connected" if mari.serial_connected else "disconnected",
+            style="bold green" if mari.serial_connected else "bold red",
+        )
+        status.append(
+            f" via {mari.serial_interface.port} at {mari.serial_interface.baudrate} baud "
+            f"since {mari.started_ts.strftime('%Y-%m-%d %H:%M:%S')}"
+        )
+        status.append("  |  ")
+        secs = int((datetime.now() - mari.last_received_serial_data_ts).total_seconds())
+        status.append(
+            f"last received: {secs}s ago",
+            style="bold green" if secs <= 1 else "bold red",
+        )
+
+        status.append("\n\nGateway:  ", style="bold cyan")
+        status.append(f"0x{mari.gateway.info.address:016X}  |  ")
+        status.append("Network ID: ", style="bold cyan")
+        status.append(f"0x{mari.gateway.info.network_id:04X}  |  ")
+
+        status.append("\n\n")
+        status.append("Schedule: ", style="bold cyan")
+        status.append(f"#{mari.gateway.info.schedule_id} ({mari.gateway.info.schedule_name})  |  ")
+        status.append(mari.gateway.info.repr_schedule_cells_with_colors())
+        status.append("\n\n")
+
+        if mari.gateway.latency_stats.last_ms > 0:
+            status.append("Latency:  ", style="bold cyan")
+            lat = mari.gateway.latency_stats
+            status.append(
+                f"Last: {lat.last_ms:.1f}ms | Avg: {lat.avg_ms:.1f}ms | "
+                f"Min: {lat.min_ms:.1f}ms | Max: {lat.max_ms:.1f}ms"
+            )
+
+        status.append("\n\nStats:    ", style="bold yellow")
+        if self.test_state and self.test_state.load > 0 and self.test_state.rate > 0:
+            status.append(
+                "Test load: ",
+                # style="bold yellow",
+            )
+            status.append(f"{self.test_state.load}% of {self.test_state.rate} pps")
+            status.append("  |  ")
+
+        stats = mari.gateway.stats
+        status.append(f"Nodes: {len(mari.gateway.nodes)}  |  ")
+        status.append(f"Frames TX: {stats.sent_count(include_test_packets=False)}  |  ")
+        status.append(f"Frames RX: {stats.received_count(include_test_packets=False)} |  ")
+        status.append(f"TX/s: {stats.sent_count(1, include_test_packets=False)}  |  ")
+        status.append(f"RX/s: {stats.received_count(1, include_test_packets=False)}")
+
+        return Panel(status, title="[bold]MarilibEdge Status", border_style="blue")
+
+    def create_nodes_table(self, nodes: list[MariNode], title="") -> Table:
+        """Create a table displaying information about connected nodes."""
+        table = Table(
+            show_header=True,
+            header_style="bold cyan",
+            border_style="blue",
+            padding=(0, 1),
+            title=title,
+        )
+        table.add_column("Node Address", style="cyan")
+        table.add_column("TX", justify="right")
+        table.add_column("TX/s", justify="right")
+        table.add_column("RX", justify="right")
+        table.add_column("RX/s", justify="right")
+        table.add_column("SR(total)", justify="right")
+        table.add_column("PDR Down", justify="right")
+        table.add_column("PDR Up", justify="right")
+        table.add_column("RSSI", justify="right")
+        table.add_column("Latency (ms)", justify="right")
+        for node in nodes:
+            lat_str = (
+                f"{node.latency_stats.avg_ms:.1f}" if node.latency_stats.last_ms > 0 else "..."
+            )
+            table.add_row(
+                f"0x{node.address:016X}",
+                str(node.stats.sent_count(include_test_packets=False)),
+                str(node.stats.sent_count(1, include_test_packets=False)),
+                str(node.stats.received_count(include_test_packets=False)),
+                str(node.stats.received_count(1, include_test_packets=False)),
+                f"{node.stats.success_rate():>4.0%}",
+                f"{node.pdr_downlink:>4.0%}",
+                f"{node.pdr_uplink:>4.0%}",
+                f"{node.stats.received_rssi_dbm(5)}",
+                lat_str,
+            )
+        return table
+
+    def create_nodes_panel(self, mari: MarilibEdge) -> Panel:
+        """Create the panel that contains the nodes table."""
+        nodes = mari.gateway.nodes
+        max_rows = self.get_max_rows()
+        max_displayable_nodes = self.max_tables * max_rows
+        nodes_to_display = nodes[:max_displayable_nodes]
+        remaining_nodes = max(0, len(nodes) - max_displayable_nodes)
+        tables = []
+        current_table_nodes = []
+        for i, node in enumerate(nodes_to_display):
+            current_table_nodes.append(node)
+            if len(current_table_nodes) == max_rows or i == len(nodes_to_display) - 1:
+                title = f"Nodes {i - len(current_table_nodes) + 2}-{i + 1}"
+                tables.append(self.create_nodes_table(current_table_nodes, title))
+                current_table_nodes = []
+                if len(tables) >= self.max_tables:
+                    break
+        if len(tables) > 1:
+            content = Columns(tables, equal=True, expand=True)
+        else:
+            content = tables[0] if tables else Table()
+        if remaining_nodes > 0:
+            panel_content = Group(
+                content,
+                Text(
+                    f"\n(...and {remaining_nodes} more nodes)",
+                    style="bold yellow",
+                ),
+            )
+        else:
+            panel_content = content
+        return Panel(
+            panel_content,
+            title="[bold]Connected Nodes",
+            border_style="blue",
+        )
+
+    def close(self):
+        """Clean up the live display."""
+        self.live.stop()
+        print("")

marilib_pkg-0.6.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,30 @@
+examples/frames.py,sha256=SSC36A66kFwL-U5HtFgAuK6_BI1ik_84EFJ7DoG0oBo,780
+examples/mari_cloud.py,sha256=EQmQb6AiZt49j6bI4h9kAe8nfy6Zg5PfY0WTYKc8Kes,1860
+examples/mari_cloud_minimal.py,sha256=zaLnd61gkqht5AclJC6Hfc1CPS_8BzTmGE-tItbWlao,1125
+examples/mari_edge.py,sha256=VI5iv46f5ejbNn7H6A7pQjSDrdWsj3pDM6DrLos5SuI,1936
+examples/mari_edge_minimal.py,sha256=9vOsIdW9WnS_GQg9fBw_G1wkvGFokwsiM83Q8etoUpA,1090
+examples/mari_edge_stats.py,sha256=LQx4gtfFCp1rP0uBo1UCLg5e5eusDKsH_beoKj5_CAI,4340
+examples/uart.py,sha256=pUvkpVf64T94XFLzgyHSzMOZISMrm0wqyurjNyS3JhY,823
+marilib/__init__.py,sha256=PCxfi_8iZpMbc5DscErorPXqdO7qghp6t1MFU0NnYfk,130
+marilib/communication_adapter.py,sha256=IEcSLm5lbtFMtFCZ784QdvZZ5zcqL1IZQ90CSSp-XvM,6998
+marilib/latency.py,sha256=jz-7Yvgmk-BO40FHW_pltHbRV2OL1QD-dCkV9iSJiiY,2729
+marilib/logger.py,sha256=IgkC1JM9sf3JxiSBYUcHeuYpiRrwcODVR2Y54GA2LPA,7867
+marilib/mari_protocol.py,sha256=b1hQdSJX8CjPtKgosO7F-vt8ZHsnZ9QqMI2oKNL4r0E,2516
+marilib/marilib.py,sha256=m7drdxhAMnjTrqYjUvwqunreYpffz7-AKgaOkuXHukg,939
+marilib/marilib_cloud.py,sha256=0yPTea0J2h4EkWwTcU4QAr001srd9_P6LOPtmJmhH24,7346
+marilib/marilib_edge.py,sha256=tzjeNtI_SpvghYxgV_y8j27d6xXX-1HIQc2TGKuNOg0,9743
+marilib/model.py,sha256=0WAEtMxqnqziSG0epZfLXlXVAzVRNfou4n6suhtdB1k,12831
+marilib/protocol.py,sha256=wOsG_oIk2Ls6gnbDYa5_g1sbHGuYgsj6liiax_yTn34,3786
+marilib/serial_hdlc.py,sha256=6EDbjkJ5RU_1Gv3OhHaIhLAXscce_2-yCv-602sw2-8,8119
+marilib/serial_uart.py,sha256=7sv8Ouj-y7k2Yry6cINil9WgVYvy1cRPPpIbW4JLVQo,2764
+marilib/tui.py,sha256=doTpHnZqyHEglSck_a1cl9DU1uTCZavVOlcZjA8aTV4,231
+marilib/tui_cloud.py,sha256=LZQVYLSwdLBubUcbUy7Eoahma_98b690ndCVgXSm_EA,5672
+marilib/tui_edge.py,sha256=N2i0aUZ2zeaC0oPcCamNd5FY0wTDtmp2KWFF1yL6ABA,7573
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_hdlc.py,sha256=SSgDpdTa2ga-P5tlXZtGvjliame4Ug9FwyreSw_nT9k,2450
+tests/test_protocol.py,sha256=JJRtzCV2BygogSFFmss4FwYLb7x3Zy8sIEWxzopfxNE,1167
+marilib_pkg-0.6.0.dist-info/METADATA,sha256=FuhL1nVncSyrIJ1mpqqReAajGZSCQcCJW-gEsQbE0h4,1992
+marilib_pkg-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+marilib_pkg-0.6.0.dist-info/licenses/AUTHORS,sha256=gGgRHmEH6klwG7KQd4rYVy0AT8MkA9mMimfiN1NvOHU,96
+marilib_pkg-0.6.0.dist-info/licenses/LICENSE,sha256=j97C1uBc5chpQWi4bv_2SrqExuvKaJK2Ch6L2LFkoc4,1492
+marilib_pkg-0.6.0.dist-info/RECORD,,

marilib_pkg-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

marilib_pkg-0.6.0.dist-info/licenses/AUTHORS

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

marilib_pkg-0.6.0.dist-info/licenses/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.

tests/test_hdlc.py

@@ -0,0 +1,76 @@
+"""Test module for HDLC handler class."""
+
+import pytest
+
+from marilib.serial_hdlc import HDLCDecodeException, HDLCHandler, HDLCState
+
+
+def test_hdlc_handler_states():
+    handler = HDLCHandler()
+    assert handler.state == HDLCState.IDLE
+    handler.handle_byte(b"A")
+    assert handler.state == HDLCState.IDLE
+    handler.handle_byte(b"~")
+    assert handler.state == HDLCState.RECEIVING
+    handler.handle_byte(b"A")
+    assert handler.state == HDLCState.RECEIVING
+    handler.handle_byte(b"~")
+    assert handler.state == HDLCState.READY
+    handler.handle_byte(b"~")
+    assert handler.state == HDLCState.RECEIVING
+    handler.handle_byte(b"A")
+    handler.handle_byte(b"\xf5")
+    handler.handle_byte(b"\xa3")
+    assert handler.state == HDLCState.RECEIVING
+    handler.handle_byte(b"~")
+    assert handler.state == HDLCState.READY
+    handler.handle_byte(b"~")
+    assert handler.state == HDLCState.RECEIVING
+    handler.handle_byte(b"~")
+    assert handler.output == bytearray()
+    assert handler.state == HDLCState.RECEIVING
+    handler.handle_byte(b"~")
+    assert handler.output == bytearray()
+    assert handler.state == HDLCState.RECEIVING
+
+
+def test_hdlc_handler_decode():
+    handler = HDLCHandler()
+    for byte in b"~test\x88\x07~":
+        handler.handle_byte(int(byte).to_bytes(1, "little"))
+    assert handler.payload == b"test"
+    assert handler.state == HDLCState.IDLE
+
+
+def test_hdlc_handler_decode_with_flags():
+    handler = HDLCHandler()
+    for byte in b"~}^test}]\x06\x94~":
+        handler.handle_byte(int(byte).to_bytes(1, "little"))
+    assert handler.state == HDLCState.READY
+    assert handler.payload == bytearray(b"~test}")
+    assert handler.state == HDLCState.IDLE
+
+
+def test_hdlc_handler_invalid_state():
+    handler = HDLCHandler()
+    for byte in b"~test\x42\x42":
+        handler.handle_byte(int(byte).to_bytes(1, "little"))
+    with pytest.raises(HDLCDecodeException) as exc:
+        _ = handler.payload
+    assert str(exc.value) == "Incomplete HDLC frame"
+
+
+def test_hdlc_handler_invalid_fcs():
+    handler = HDLCHandler()
+    for byte in b"~test\x42\x42~":
+        handler.handle_byte(int(byte).to_bytes(1, "little"))
+    payload = handler.payload
+    assert payload == bytearray()
+
+
+def test_hdlc_handler_payload_too_short():
+    handler = HDLCHandler()
+    for byte in b"~a~":
+        handler.handle_byte(int(byte).to_bytes(1, "little"))
+    payload = handler.payload
+    assert payload == bytearray()

tests/test_protocol.py

@@ -0,0 +1,35 @@
+from marilib.mari_protocol import Frame, Header
+
+
+def test_header_size():
+    assert Header().size == 20
+
+
+def test_header_from_bytes():
+    header = Header().from_bytes(
+        bytes.fromhex("0210170059291ba8fdcecef531eb7f2526ef0399f0f0f0f0f0")[0:20]
+    )
+    assert header.version == 2
+    assert header.type_ == 16
+    assert header.network_id == 23
+    assert header.destination == int.from_bytes(
+        bytes.fromhex("59291ba8fdcecef5"), byteorder="little"
+    )
+    assert header.source == int.from_bytes(bytes.fromhex("31eb7f2526ef0399"), byteorder="little")
+
+
+def test_frame_from_bytes():
+    frame = Frame().from_bytes(
+        bytes.fromhex("0210170059291ba8fdcecef531eb7f2526ef0399dcf0f0f0f0f0")
+    )
+    assert frame.header.version == 2
+    assert frame.header.type_ == 16
+    assert frame.header.network_id == 23
+    assert frame.header.destination == int.from_bytes(
+        bytes.fromhex("59291ba8fdcecef5"), byteorder="little"
+    )
+    assert frame.header.source == int.from_bytes(
+        bytes.fromhex("31eb7f2526ef0399"), byteorder="little"
+    )
+    assert frame.stats.rssi_dbm == -35
+    assert frame.payload == bytes.fromhex("f0f0f0f0f0")