py-multitrack 0.0.1__py3-none-any.whl

multitrack/MultitrackAPI.py

@@ -0,0 +1,169 @@
+from .UDPListener import UDPListener
+from .models import PluginInfo, MultitrackConfig, AdoptModel
+from .Elements import RemoteElements, LocalElements
+from .SerialBridge import SerialBridge
+from .SerialDriver import SerialDriver
+from fastapi import FastAPI, APIRouter, Response
+from contextlib import asynccontextmanager
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed
+import uvicorn
+import asyncio
+import logging
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s:     %(asctime)s - %(name)s: %(message)s")
+log = logging.getLogger("MultitrackAPI")
+
+class MultitrackAPI():
+    """
+    Manages the communication between your plugin and the **Multitrack Core**\n
+    Exposes the *API endpoints*, runs the *UDPBroadcast listener*, connects to the Core's *WebSocket Server*, manages *plugin configuration*... 
+    """
+    def __init__(self, http_port: int, discovery_port: int, discovery_msg: str, driver: SerialDriver, multicast_group = "239.255.42.69", listening_interface = "0.0.0.0", config_file = "/home/mbn/projects/multitrack/src/plugin_demo/config.ini"):
+        # Misc. props
+        self.http_port = http_port
+        self.discovery_port = discovery_port
+        self.discovery_msg = discovery_msg
+        self.multicast_group = multicast_group
+        self.listening_interface = listening_interface
+        # Websocket
+        self.ws_task: asyncio.Task | None = None
+        # Config
+        self.config = MultitrackConfig.read(config_file)
+        # Initialize MultitrackBridge
+        self.bridge = SerialBridge(driver)
+        # UIElements
+        self.local = LocalElements()
+        self.remote = RemoteElements()
+
+        # Other inits
+        self.bridge.driver.set_plugin_id(self.config.api.id)
+
+    def run(self):
+        log.info("Running application.")
+        # Gather plugin info
+        self.info = PluginInfo(
+            id = self.config.api.id,
+            port = self.http_port,
+            elements = self.remote.list_elements() + self.local.list_elements(),
+            bound = self.config.api.bound
+        )
+
+        # Initialize UDPListener
+        self.udp_listener = UDPListener(
+            self.discovery_port, 
+            self.discovery_msg,
+            self.info,
+            self.multicast_group,
+            self.listening_interface
+        )
+
+        # Initialize lifespan events (on_startup/on_shutdown)
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            await self._on_startup()
+            yield
+            await self._on_shutdown()
+
+        # Initialize FastAPI
+        self.app = FastAPI(lifespan=lifespan)
+        self._init_routes()
+
+        # Runs FastAPI (with lifespan handlers)
+        try:
+            uvicorn.run(self.app, host="0.0.0.0", port=self.http_port)
+        except OSError:
+            print("error")
+
+    async def _on_startup(self):
+        # Runs the SerialBridge thread
+        self.bridge.bind_loop(asyncio.get_running_loop())
+        self.bridge.thread.start()
+        for action in self.bridge.driver.on_startup():
+            await self.bridge.send_command(action)
+        # Runs UDP Listener
+        await self.udp_listener.start()
+        # Runs the WebSocket connection with the Core
+        if self.config.api.bound:
+            try:
+                self.ws_task = asyncio.create_task(self._connect_to_core())
+            except ConnectionError as e:
+                log.error(e)
+
+    async def _on_shutdown(self):
+        # Stops SerialBridge thread
+        self.bridge.stop_sig.set()
+        await asyncio.to_thread(self.bridge.thread.join)
+        # Stops UDP Listener
+        self.udp_listener.stop()
+        # Stops the WebSocket connection
+        if self.ws_task:
+            self.ws_task.cancel()
+            log.info("Disconnected from the Core")
+
+    async def _connect_to_core(self):
+        if not self.config.api.token: raise ConnectionError("API Token not loaded")
+        async for ws in connect(f"ws://{self.config.api.core_host}/plugins?id={self.config.api.id}", additional_headers={"bearer-token": self.config.api.token}):
+            try:
+                log.info(f"Connected to Core on {self.config.api.core_host}")
+                self.ws = ws
+                async for data in self._fetch_cmds_from_bridge():
+                    await ws.send(data)
+            except ConnectionClosed:
+                continue
+
+    async def _fetch_cmds_from_bridge(self):
+        try:
+            while True:
+                yield await self.bridge.events.get()
+        except:
+            pass
+
+    def _init_routes(self):
+        @self.app.get("/")
+        async def home():
+            return self.info
+
+        @self.app.get("/restart")
+        async def restart():
+            raise KeyboardInterrupt
+
+        @self.app.post("/adopt")
+        async def adopt(payload: AdoptModel):
+            if(self.config.api.bound): return Response(status_code=403, content="Plugin already bound.")
+
+            self.config.api.core_host = payload.host
+            self.config.api.token = payload.token
+            self.config.api.bound = True
+            self.config.write()
+
+            self.ws_task = asyncio.create_task(self._connect_to_core())
+
+            return Response(status_code=200, content="Successfully bound plugin.")
+
+        remote_router = APIRouter(
+            prefix="/remote"
+        )
+
+        local_router = APIRouter(
+            prefix="/local"
+        )
+
+        for (path, element) in self.remote.elements.items():
+            remote_router.add_api_route(
+                path=f"/{path}",
+                endpoint=element.make_endpoint(self.bridge.send_command),
+                methods=[element.metadata.method],
+                name=path
+            )
+
+        for (path, element) in self.local.elements.items():
+            local_router.add_api_route(
+                path=f"/{path}",
+                endpoint=element.make_endpoint(self.bridge.send_command),
+                methods=[element.metadata.method],
+                name=path
+            )
+
+        self.app.include_router(remote_router)
+        self.app.include_router(local_router)

multitrack/SerialBridge.py

@@ -0,0 +1,61 @@
+from .SerialDriver import SerialDriver
+from typing import Callable
+import logging
+import asyncio, threading, queue, time
+
+log = logging.getLogger("SerialBridge")
+
+class SerialBridge():
+    """
+    Bridges the MultitrackAPI and the SerialDriver.
+    """
+    def __init__(self, driver: SerialDriver):
+        self.loop: asyncio.AbstractEventLoop
+        self.stop_sig = threading.Event()
+        self.commands: queue.Queue[tuple[str, Callable[[str], bool] | None, asyncio.Future]] = queue.Queue()
+        self.events = asyncio.Queue()
+        self.thread = threading.Thread(target=self._run)
+        self.driver = driver
+
+    def _run(self):
+        line = b''
+        busy: float | None = None
+        predicate: Callable[[str], bool] | None = None
+        while not self.stop_sig.is_set():
+            # Read a byte from the Serial object init. in the driver
+            byte_read = self.driver.serial.read(1)
+
+            # Resets the line when a 'bol' is found
+            if byte_read == self.driver.bol:
+                line = b''
+            else:
+                if byte_read == self.driver.eol:
+                    # Checks for the ACK, sets the busy flag to None if the condition is fullfilled
+                    if predicate and predicate(line.decode()):
+                        busy = None
+
+                    self.loop.call_soon_threadsafe(log.info, f"Received {line.decode()}")
+                else:
+                    # Add the byte read to the line
+                    line += byte_read
+
+            # Manages the writing of serial commands
+            while not self.commands.empty() and not busy:
+                cmd, ack, fut = self.commands.get_nowait()
+
+                # If the commands has to wait for a provided ACK, set the ok flag to False
+                if ack:
+                    predicate = ack
+                    busy = time.time()
+
+                # Write the command on the serial port and returns the result via the Future object
+                self.driver.serial.write(self.driver.encode_wrap(cmd))
+                self.loop.call_soon_threadsafe(fut.set_result, f"Sent {cmd}")
+
+    async def send_command(self, cmd: str, ack: Callable[[str], bool] | None = None):
+        fut = self.loop.create_future()
+        self.commands.put((cmd, ack, fut))
+        log.info(await fut)
+
+    def bind_loop(self, loop: asyncio.AbstractEventLoop):
+        self.loop = loop

multitrack/SerialDriver.py

@@ -0,0 +1,65 @@
+from serial import Serial
+from .models import CoreData
+import logging
+from datetime import datetime
+
+log = logging.getLogger("SerialDriver")
+
+class SerialDriver():
+    """
+    Abstract class that serves as a template for **Serial communication**.\n
+    Here's how you write your driver :
+    - Create a new class **inheriting** from this one
+    - Overwrite the **parser()** method with your own
+    - Provide a **Serial object** and specific **bol/eol** when initializing the class
+    - Bind it to the **MultitrackAPI**
+    """
+    def __init__(self, serial: Serial, bol: bytes, eol: bytes, MSGCH: int = -1, DEFCH: int = -1, blocking_timeout: int = 5, verbose: bool = False):
+        # Misc. properties
+        self.verbose = verbose
+        # Serial obj. and properties
+        self.serial = serial
+        self.bol = bol
+        self.eol = eol
+        self.MSGCH = MSGCH
+        self.DEFCH = DEFCH
+        self.blocking_timeout = blocking_timeout
+
+    def on_startup(self) -> list[str]:
+        """
+        Actions executed when connecting to the serial port.
+        """
+        return []
+    
+    def set_plugin_id(self, id: str):
+        self.plugin_id = id
+    
+    def parser(self, cmd: str) -> CoreData:
+        """
+        Place here every **command** your radio may receive.\n
+        Returns sanitized **PluginData** for the *Core*
+        """
+        return CoreData(
+            plugin_id=self.plugin_id,
+            entity_id=None,
+            timestamp=datetime.now().timestamp(),
+            type="err",
+            success=False,
+            data=None
+        )
+
+    def nmea_to_decimal(self, value: str, hemisphere: str):
+        """
+        Small utility to convert **NMEA** coordinates to **decimal**.
+        """
+        dot = value.index(".")
+        degrees = int(value[:dot - 2])
+        minutes = float(value[dot - 2:])
+        dec = degrees + minutes / 60
+        return -dec if hemisphere in ("S", "W") else dec
+
+    def encode_wrap(self, cmd: str):
+        """
+        Encode the command in utf-8, then wraps it with *bol* and *eol* characters.
+        """
+        return self.bol + cmd.encode() + self.eol

multitrack/StateStore.py

@@ -0,0 +1,35 @@
+from pydantic import BaseModel
+from typing import Any, Literal
+
+class State(BaseModel):
+    scope: Literal["local", "remote"]
+    label: str
+
+class SimpleState(State):
+    type: Literal["str", "int", "float", "bool"]
+    default: str | int | float | bool | None
+
+class ChatboxState(State):
+    direction: bool
+    msg: str
+
+class GPSState(State):
+    lat: float
+    long: float
+
+class StateStore():
+    def __init__(self):
+        self.states: dict[str, dict[str, Any]] = {}
+
+    def register(self, state: State):
+        self.states[state.label] = state.model_dump()
+
+    def get_ref(self, label: str):
+        return self.states[label]
+
+test = []
+props = ChatboxState.model_json_schema()['properties']
+for p in props:
+    test.append((p, props[p]["type"]))
+    
+print(test)

multitrack/UDPListener.py

@@ -0,0 +1,64 @@
+from .models import PluginInfo
+import asyncio
+import logging
+import struct
+import socket
+
+log = logging.getLogger("UDPListener")
+
+class UDPListener():
+    def __init__(self, discovery_port: int, discovery_msg: str, plugin_info: PluginInfo, multicast_group: str, listening_interface: str):
+        self.discovery_port = discovery_port
+        self.discovery_msg = discovery_msg
+        self.multicast_group = multicast_group
+        self.listening_interface = listening_interface
+        self.plugin_info = plugin_info
+        self.transport = None
+
+    async def start(self):
+        # Get the Asyncio running loop
+        loop = asyncio.get_running_loop()
+        # Creates the socket
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            if hasattr(socket, "SO_REUSEPORT"):
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+            sock.bind(("", self.discovery_port))
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, struct.pack("4s4s", socket.inet_aton(self.multicast_group), socket.inet_aton(self.listening_interface)))
+            sock.setblocking(False)
+            # Opens the socket for transport, and listens asynchronously
+            self.transport, _ = await loop.create_datagram_endpoint(
+                lambda: _DiscoveryProtocol(self.discovery_msg, self.plugin_info),
+                sock=sock
+            )
+        except OSError as e:
+            log.error(f"Error while binding socket: {e}")
+            sock.close()
+            raise e
+
+    def stop(self):
+        if self.transport:
+            self.transport.close()
+            self.transport = None
+
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    def __init__(self, discovery_msg: str, plugin_info: PluginInfo):
+        self.discovery_msg = discovery_msg
+        self.plugin_info = plugin_info
+
+    def connection_made(self, transport):
+        log.info("Listening for Discovery")
+        self.transport = transport
+
+    def connection_lost(self, exc):
+        log.info("No longer listening for Discovery")
+
+    def datagram_received(self, data, addr):
+        log.info(f"received {str(data)}")
+        if data != self.discovery_msg.encode():
+            return
+
+        reply = self.plugin_info.model_dump_json(indent=4).encode()
+        self.transport.sendto(reply, addr)
+        log.info(f"Discovery request from {addr}, replied.")

multitrack/__init__.py

@@ -0,0 +1,10 @@
+"""
+Framework to write MultitrackCore plugins.\n
+Documentation can be found here : **insert_doc_link**.
+"""
+
+from .MultitrackAPI import MultitrackAPI
+from .SerialBridge import SerialBridge
+from .SerialDriver import SerialDriver
+from .UDPListener import UDPListener
+from .models import EntityInfo, PluginInfo, TextMessage, GPSPosition, StatusUpdate, CoreData

multitrack/models.py

@@ -0,0 +1,184 @@
+from pydantic import BaseModel
+from typing import Literal, Callable, Any
+from types import CoroutineType
+from configparser import ConfigParser
+from uuid import uuid4
+
+# Metadata
+
+class GeneralMetadata(BaseModel):
+    path: str
+    element: Literal["button", "text", "number", "chatbox", "toggle", "dropdown"]
+    blocking: bool
+    scope: Literal["local", "remote"] = "remote"
+    role: Literal["operator", "admin"] = "operator"
+    method: Literal["GET", "POST"] = "POST"
+    group: str | None = None
+    sensible: bool = False
+    display_text: str | None = None
+    tooltip: str | None = None
+
+class ToggleMetadata(GeneralMetadata):
+    ref: str
+    colors: tuple[str, str] | None = None
+
+class ChatboxMetadata(GeneralMetadata):
+    ref: str
+
+class NumberMetadata(GeneralMetadata):
+    ref: str
+    vartype: Literal["int", "float"]
+    min_max: tuple[int | float, int | float] | None = None
+
+class DropdownMetadata(GeneralMetadata):
+    ref: str
+    values: list[str]
+
+class Element(BaseModel):
+    handler: Callable[..., str]
+    check_ack: Callable[[str], bool] | None = None
+    metadata: GeneralMetadata | type[GeneralMetadata]
+
+    def make_endpoint(self, send_command: Callable[[str, Callable[[str], bool] | None], CoroutineType[Any, Any, None]]):
+        if self.metadata.scope == "remote":
+            match self.metadata.element:
+                case "button":
+                    async def remote_button(e: EntityInfo):
+                        await send_command(self.handler(e), self.check_ack)
+                    return remote_button
+                case "chatbox":
+                    async def remote_chatbox(e: EntityInfo, msg: str):
+                        await send_command(self.handler(e, msg), self.check_ack)
+                    return remote_chatbox
+                case "dropdown":
+                    async def remote_dropdown(e: EntityInfo, value: str):
+                        await send_command(self.handler(e, value), self.check_ack)
+                    return remote_dropdown
+                case "number":
+                    async def remote_number(e: EntityInfo, value: int | float):
+                        await send_command(self.handler(e, value), self.check_ack)
+                    return remote_number
+                case "text":
+                    async def remote_text(e: EntityInfo, msg: str):
+                        await send_command(self.handler(e, msg), self.check_ack)
+                    return remote_text
+                case "toggle":
+                    async def remote_toggle(e: EntityInfo, state: bool):
+                        await send_command(self.handler(e, state), self.check_ack)
+                    return remote_toggle
+        else:
+            match self.metadata.element:
+                case "button":
+                    async def local_button():
+                        await send_command(self.handler(), self.check_ack)
+                    return local_button
+                case "chatbox":
+                    async def local_chatbox(msg: str):
+                        await send_command(self.handler(msg), self.check_ack)
+                    return local_chatbox
+                case "dropdown":
+                    async def local_dropdown(value: str):
+                        await send_command(self.handler(value), self.check_ack)
+                    return local_dropdown
+                case "number":
+                    async def local_number(value: int | float):
+                        await send_command(self.handler(value), self.check_ack)
+                    return local_number
+                case "text":
+                    async def local_text(msg: str):
+                        await send_command(self.handler(msg), self.check_ack)
+                    return local_text
+                case "toggle":
+                    async def local_toggle(state: bool):
+                        await send_command(self.handler(state), self.check_ack)
+                    return local_toggle
+
+# Infos
+
+class EntityInfo(BaseModel):
+    serial: int
+
+class PluginInfo(BaseModel):
+    id: str
+    port: int
+    elements: list[GeneralMetadata | type[GeneralMetadata]]
+    bound: bool
+
+# Data
+
+class TextMessage(BaseModel):
+    msg: str
+
+class GPSPosition(BaseModel):
+    latitude: float
+    longitude: float
+
+class StatusUpdate(BaseModel):
+    status: str
+
+class CoreData(BaseModel):
+    plugin_id: str
+    entity_id: str | None
+    timestamp: float
+    type: Literal["text", "gps", "status", "err"]
+    success: bool
+    data: TextMessage | GPSPosition | StatusUpdate | None
+
+class AdoptModel(BaseModel):
+    host: str
+    token: str
+
+class APIConfig(BaseModel):
+    id: str
+    core_host: str | None
+    token: str | None
+    bound: bool
+
+class MultitrackConfig(BaseModel):
+    filepath: str
+    api: APIConfig
+
+    @classmethod
+    def read(cls, filepath: str):
+        config = ConfigParser()
+        config.read(filepath)
+        try:
+            api = APIConfig(
+                id = config["API"]["id"],
+                core_host = None if config["API"]["core_host"] == "None" else config["API"]["core_host"],
+                token = None if config["API"]["token"] == "None" else config["API"]["token"],
+                bound = config["API"]["bound"] == "True"
+            )
+            print("Config loaded.")
+            return cls(
+                filepath = filepath,
+                api = api
+            )
+        except:
+            print("Couldn't parse config, generating defaults.")
+            config = cls.default(filepath)
+            config.write()
+            return config
+
+    @classmethod
+    def default(cls, filepath: str):
+        return cls(
+            filepath = filepath,
+            api = APIConfig(
+                id = str(uuid4()),
+                core_host = None,
+                token = None,
+                bound = False
+            )
+        )
+
+    def write(self):
+        config = ConfigParser()
+        config["API"] = {}
+        config["API"]["id"] = self.api.id
+        config["API"]["core_host"] = str(self.api.core_host)
+        config["API"]["token"] = str(self.api.token)
+        config["API"]["bound"] = str(self.api.bound)
+
+        with open(self.filepath, "w") as f:
+            config.write(f)

py_multitrack-0.0.1.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: py-multitrack
+Version: 0.0.1
+Summary: Multitrack Framework to bridge serial radios to the Multitrack Core tracking system
+Author: Maxime Brison
+License-Expression: GPL-3.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# py_multitrack
+Python framework to bridge serial radios to the Multitrack Core tracking system.

py_multitrack-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+multitrack/Elements.py,sha256=7JIbiCteMEeoY4q2J3AIbjSK1fGGZJ5INFAmCj3vkW8,37211
+multitrack/MultitrackAPI.py,sha256=_YwT1bQFFewK2XS2TVZiesGBTE39EiaQwwdA3_6ska4,6142
+multitrack/SerialBridge.py,sha256=EsP29zwXfMU-TJ14Z0RpxGZOEXQDQxkTd5-fBzNFn_k,2397
+multitrack/SerialDriver.py,sha256=hkWXSrJsBrht1xUc4UAjdsq9SU1Idi9bzRjt86Ei7dc,2136
+multitrack/StateStore.py,sha256=z7-T_RTr75luI65SnFmxG0uKMhJ3zeqKuukcUwuz41s,809
+multitrack/UDPListener.py,sha256=xfzUzxWraWx1q_yPxuhIsyLML498lbZLshqMDiOAI90,2477
+multitrack/__init__.py,sha256=eWpgoByXRzVnQnS3rFpng9gMgEF24jch6drmMWGFWYY,357
+multitrack/models.py,sha256=QsgdIBUGjkwYa2Nafz6bL9Npklx8lB2Q_CNTRdWThYw,6226
+py_multitrack-0.0.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+py_multitrack-0.0.1.dist-info/METADATA,sha256=hhFiz2NddzcDjU4JMYrNOpYSMw7C5nsbvl5uIYvnh8g,406
+py_multitrack-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+py_multitrack-0.0.1.dist-info/top_level.txt,sha256=JqCSP17N5fwlcmf-XmXMT3zYXUSCykULjKHmsOO7ox0,11
+py_multitrack-0.0.1.dist-info/RECORD,,

py_multitrack-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+