pymoos2 0.1.0__tar.gz

pymoos2-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ray Turrisi
+
+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.

pymoos2-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.1
+Name: pymoos2
+Version: 0.1.0
+Summary: Pure-Python MOOS-IvP application framework
+Author-email: Raymond Turrisi <rturrisi@mit.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/raymondturrisi/pymoos2
+Project-URL: Repository, https://github.com/raymondturrisi/pymoos2
+Keywords: moos,moos-ivp,robotics,auv,marine,middleware
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# pymoos2
+
+Pure-Python MOOS-IvP application framework. Write MOOS apps in Python with full AppCasting, wire protocol, and pAntler integration.
+
+## Install
+
+```bash
+pip install pymoos2
+```
+
+## Quick Start
+
+Generate a new app:
+
+```bash
+cd moos-ivp-myproject/src
+python3 -m pymoos2 --GenAppCastingMOOSApp MyApp p "Your Name"
+```
+
+This creates `pMyApp/` with a ready-to-edit Python MOOS app that:
+- Connects to MOOSDB over the native wire protocol
+- Supports AppCasting (shows up in uMAC/pMarineViewer)
+- Reads ProcessConfig from `.moos` files
+- Installs to `bin/` via CMake alongside C++ apps
+- Responds to `ktm` shutdown signals
+- Handles time warp correctly
+
+## Example Mission
+
+Generate a complete working example with two apps and a mission:
+
+```bash
+cd moos-ivp-myproject
+python3 -m pymoos2 --example
+```
+
+## Writing an App
+
+```python
+from pymoos2 import AppCastingMOOSApp, ACTable
+
+class MyApp(AppCastingMOOSApp):
+
+    def on_startup(self):
+        self.radius = self.config("radius", default=50.0, type=float)
+        self.register("NAV_X")
+        self.register("NAV_Y")
+
+    def on_new_mail(self, mail):
+        for msg in mail:
+            if msg.name == "NAV_X":
+                self.nav_x = msg.double()
+
+    def iterate(self):
+        self.notify("MY_OUTPUT", self.nav_x * 2.0)
+
+    def build_report(self):
+        tab = ACTable(["Variable", "Value"])
+        tab.add("NAV_X", f"{self.nav_x:.2f}")
+        self.report(tab)
+        return True
+```
+
+## Features
+
+- Pure Python — no C++ compilation, no pybind11
+- Full MOOS wire protocol (binary TCP, same as C++ clients)
+- AppCasting and RealmCasting support
+- Time warp support (`MOOSTimeWarp`)
+- `ktm` (kill the moos) UDP multicast listener
+- Mission file parsing (ProcessConfig blocks, global params)
+- Geometry DTOs for all VIEW_* types (XYPoint, XYPolygon, XYCircle, etc.)
+- NodeRecord parsing
+- `py_compile` syntax checking at build time
+- Works with pAntler — shebang'd scripts in `bin/`
+
+## Requirements
+
+- Python >= 3.8
+- MOOSDB running (from moos-ivp)
+- No other dependencies for core functionality
+- `flask` for web-based viewer apps (optional)

pymoos2-0.1.0/README.md

@@ -0,0 +1,82 @@
+# pymoos2
+
+Pure-Python MOOS-IvP application framework. Write MOOS apps in Python with full AppCasting, wire protocol, and pAntler integration.
+
+## Install
+
+```bash
+pip install pymoos2
+```
+
+## Quick Start
+
+Generate a new app:
+
+```bash
+cd moos-ivp-myproject/src
+python3 -m pymoos2 --GenAppCastingMOOSApp MyApp p "Your Name"
+```
+
+This creates `pMyApp/` with a ready-to-edit Python MOOS app that:
+- Connects to MOOSDB over the native wire protocol
+- Supports AppCasting (shows up in uMAC/pMarineViewer)
+- Reads ProcessConfig from `.moos` files
+- Installs to `bin/` via CMake alongside C++ apps
+- Responds to `ktm` shutdown signals
+- Handles time warp correctly
+
+## Example Mission
+
+Generate a complete working example with two apps and a mission:
+
+```bash
+cd moos-ivp-myproject
+python3 -m pymoos2 --example
+```
+
+## Writing an App
+
+```python
+from pymoos2 import AppCastingMOOSApp, ACTable
+
+class MyApp(AppCastingMOOSApp):
+
+    def on_startup(self):
+        self.radius = self.config("radius", default=50.0, type=float)
+        self.register("NAV_X")
+        self.register("NAV_Y")
+
+    def on_new_mail(self, mail):
+        for msg in mail:
+            if msg.name == "NAV_X":
+                self.nav_x = msg.double()
+
+    def iterate(self):
+        self.notify("MY_OUTPUT", self.nav_x * 2.0)
+
+    def build_report(self):
+        tab = ACTable(["Variable", "Value"])
+        tab.add("NAV_X", f"{self.nav_x:.2f}")
+        self.report(tab)
+        return True
+```
+
+## Features
+
+- Pure Python — no C++ compilation, no pybind11
+- Full MOOS wire protocol (binary TCP, same as C++ clients)
+- AppCasting and RealmCasting support
+- Time warp support (`MOOSTimeWarp`)
+- `ktm` (kill the moos) UDP multicast listener
+- Mission file parsing (ProcessConfig blocks, global params)
+- Geometry DTOs for all VIEW_* types (XYPoint, XYPolygon, XYCircle, etc.)
+- NodeRecord parsing
+- `py_compile` syntax checking at build time
+- Works with pAntler — shebang'd scripts in `bin/`
+
+## Requirements
+
+- Python >= 3.8
+- MOOSDB running (from moos-ivp)
+- No other dependencies for core functionality
+- `flask` for web-based viewer apps (optional)

pymoos2-0.1.0/pymoos2/__init__.py

@@ -0,0 +1,48 @@
+"""
+pymoos2 — Pure-Python MOOS-IvP application framework.
+"""
+
+from pymoos2.core.AppCastingMOOSApp import AppCastingMOOSApp
+from pymoos2.core.MOOSApp import MOOSApp
+from pymoos2.core.MOOSMsg import MOOSMsg
+from pymoos2.core.MOOSCommClient import MOOSCommClient
+from pymoos2.core.MissionReader import MissionReader
+from pymoos2.core.ACTable import ACTable
+from pymoos2.core.time import moos_time, moos_local_time, moos_pause
+
+import sys
+import signal
+
+
+def run(app_class, app_name, mission_file):
+    """
+    Launch a pymoos2 application.
+    """
+    app = app_class()
+    app._initialize(app_name, mission_file)
+
+    def shutdown(sig, frame):
+        app._shutdown()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, shutdown)
+    signal.signal(signal.SIGTERM, shutdown)
+
+    try:
+        app._run()
+    except KeyboardInterrupt:
+        app._shutdown()
+
+
+__all__ = [
+    "AppCastingMOOSApp",
+    "MOOSApp",
+    "MOOSMsg",
+    "MOOSCommClient",
+    "MissionReader",
+    "ACTable",
+    "moos_time",
+    "moos_local_time",
+    "moos_pause",
+    "run",
+]

pymoos2-0.1.0/pymoos2/__main__.py

@@ -0,0 +1,201 @@
+"""
+pymoos2 CLI — application generator and example scaffolding.
+
+Usage:
+    python3 -m pymoos2 --GenAppCastingMOOSApp AppName [prefix] [author]
+    python3 -m pymoos2 --example
+"""
+
+import os
+import sys
+import stat
+import shutil
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print_usage()
+        sys.exit(1)
+
+    if args[0] == "--GenAppCastingMOOSApp":
+        gen_app(args[1:])
+    elif args[0] == "--example":
+        gen_example()
+    else:
+        print_usage()
+        sys.exit(1)
+
+
+def print_usage():
+    print("pymoos2 — Pure-Python MOOS-IvP application framework")
+    print()
+    print("Usage:")
+    print("  python3 -m pymoos2 --GenAppCastingMOOSApp AppName [prefix] [author]")
+    print("  python3 -m pymoos2 --example")
+    print()
+    print("Options:")
+    print("  --GenAppCastingMOOSApp  Generate a new MOOS app with AppCasting support")
+    print("  --example               Generate a complete example mission with two pymoos2 apps")
+
+
+def gen_app(remaining):
+    if not remaining:
+        print("Error: AppName is required.")
+        sys.exit(1)
+
+    app_name = remaining[0]
+    prefix = remaining[1] if len(remaining) > 1 else "p"
+    author = remaining[2] if len(remaining) > 2 else ""
+
+    full_name = f"{prefix}{app_name}"
+    out_dir = os.path.join(os.getcwd(), full_name)
+
+    if os.path.exists(out_dir):
+        print(f"Error: directory {full_name}/ already exists.")
+        sys.exit(1)
+
+    tmpl_dir = os.path.join(os.path.dirname(__file__), "templates")
+    replacements = {
+        "{{APP_NAME}}": app_name,
+        "{{PREFIX}}": prefix,
+        "{{AUTHOR}}": author,
+    }
+
+    def render(template_name):
+        with open(os.path.join(tmpl_dir, template_name), "r") as f:
+            content = f.read()
+        for k, v in replacements.items():
+            content = content.replace(k, v)
+        return content
+
+    os.makedirs(out_dir)
+
+    main_path = os.path.join(out_dir, f"{full_name}.py")
+    with open(main_path, "w") as f:
+        f.write(render("Main.py.tmpl"))
+    _make_executable(main_path)
+
+    with open(os.path.join(out_dir, f"{app_name}.py"), "w") as f:
+        f.write(render("App.py.tmpl"))
+
+    with open(os.path.join(out_dir, "CMakeLists.txt"), "w") as f:
+        f.write(render("CMakeLists.txt.tmpl"))
+
+    print(f"Generated {full_name}/")
+    print(f"  {full_name}/{full_name}.py      — entry point (executable)")
+    print(f"  {full_name}/{app_name}.py        — app class (edit this)")
+    print(f"  {full_name}/CMakeLists.txt       — CMake install rule")
+    print()
+    print(f"Next steps:")
+    print(f"  1. Edit {app_name}.py — implement on_startup, on_new_mail, iterate, build_report")
+    print(f"  2. Add to src/CMakeLists.txt:  ADD_SUBDIRECTORY({full_name})")
+    print(f"  3. Build:  cd build && cmake .. && make")
+
+
+def gen_example():
+    cwd = os.getcwd()
+    src_dir = os.path.join(cwd, "src")
+    missions_dir = os.path.join(cwd, "missions")
+
+    # --- Pre-flight checks ---
+    print("pymoos2 --example")
+    print("=" * 50)
+    print()
+    print("You should be in moos-ivp-{your-extend-tree}/ with src/ and missions/")
+    print("below your current directory.")
+    print()
+    print(f"  Current directory: {cwd}")
+    print()
+    print("This will generate:")
+    print()
+    print("  Apps (in src/):")
+    print("    pWptPulse/     — vehicle app: publishes VIEW_RANGE_PULSE on waypoint changes")
+    print("    pNodeWatch/    — shoreside app: web page showing scrolling NODE_REPORT log")
+    print()
+    print("  Mission (in missions/):")
+    print("    alpha_pymoos2/ — ufld_alpha-based mission with both pymoos2 apps wired in")
+    print()
+
+    if not os.path.isdir(src_dir):
+        print(f"Error: no src/ directory found in {cwd}")
+        print("  Run this from the root of a moos-ivp-extend tree.")
+        sys.exit(1)
+    if not os.path.isdir(missions_dir):
+        print(f"Error: no missions/ directory found in {cwd}")
+        print("  Run this from the root of a moos-ivp-extend tree.")
+        sys.exit(1)
+
+    # Check for conflicts
+    conflicts = []
+    for d in ["src/pWptPulse", "src/pNodeWatch", "missions/alpha_pymoos2"]:
+        if os.path.exists(os.path.join(cwd, d)):
+            conflicts.append(d)
+    if conflicts:
+        print("Error: the following already exist:")
+        for c in conflicts:
+            print(f"  {c}/")
+        sys.exit(1)
+
+    # Confirm
+    resp = input("Proceed? [y/N] ").strip().lower()
+    if resp not in ("y", "yes"):
+        print("Aborted.")
+        sys.exit(0)
+
+    # Check for flask dependency
+    try:
+        import flask
+    except ImportError:
+        print("  pNodeWatch requires flask. Installing...")
+        import subprocess
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "flask"],
+                             stdout=subprocess.DEVNULL)
+        print("  flask installed.")
+
+    print()
+    example_dir = os.path.join(os.path.dirname(__file__), "templates", "example")
+
+    # --- Copy pWptPulse ---
+    _copytree(os.path.join(example_dir, "pWptPulse"), os.path.join(src_dir, "pWptPulse"))
+    _make_executable(os.path.join(src_dir, "pWptPulse", "pWptPulse.py"))
+    print("  Created src/pWptPulse/")
+
+    # --- Copy pNodeWatch ---
+    _copytree(os.path.join(example_dir, "pNodeWatch"), os.path.join(src_dir, "pNodeWatch"))
+    _make_executable(os.path.join(src_dir, "pNodeWatch", "pNodeWatch.py"))
+    print("  Created src/pNodeWatch/")
+
+    # --- Copy mission ---
+    _copytree(os.path.join(example_dir, "alpha_pymoos2"), os.path.join(missions_dir, "alpha_pymoos2"))
+    for sh in ["launch.sh", "launch_vehicle.sh", "launch_shoreside.sh", "clean.sh"]:
+        _make_executable(os.path.join(missions_dir, "alpha_pymoos2", sh))
+    print("  Created missions/alpha_pymoos2/")
+
+    print()
+    print("To complete setup, add the following to src/CMakeLists.txt:")
+    print()
+    print("  ADD_SUBDIRECTORY(pWptPulse)")
+    print("  ADD_SUBDIRECTORY(pNodeWatch)")
+    print()
+    print("Then:")
+    print("  1. ./build.sh")
+    print("  2. cd missions/alpha_pymoos2")
+    print("  3. ./launch.sh 10     (launches at 10x time warp)")
+    print("  4. Open http://localhost:8081 to see pNodeWatch")
+    print("  5. Hit DEPLOY in pMarineViewer — watch for yellow range pulses at waypoints")
+
+
+def _copytree(src, dst):
+    """Copy a directory tree."""
+    shutil.copytree(src, dst)
+
+
+def _make_executable(path):
+    st = os.stat(path)
+    os.chmod(path, st.st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+
+if __name__ == "__main__":
+    main()

pymoos2-0.1.0/pymoos2/core/ACTable.py

@@ -0,0 +1,45 @@
+"""
+Column-aligned ASCII tables for AppCast reports.
+"""
+
+
+class ACTable:
+    """Build formatted column-aligned tables for buildReport()."""
+
+    def __init__(self, columns, pad=2):
+        """
+        columns: list of column header strings, e.g. ["Variable", "Value"]
+        pad:     spaces between columns
+        """
+        self.headers = list(columns)
+        self.ncols = len(columns)
+        self.pad = pad
+        self.rows = []
+        self.widths = [len(h) for h in self.headers]
+
+    def add(self, *values):
+        """Add a row of values. Number of values should match number of columns."""
+        row = [str(v) for v in values]
+        # Pad or truncate to match column count
+        while len(row) < self.ncols:
+            row.append("")
+        row = row[:self.ncols]
+        self.rows.append(row)
+        for i, v in enumerate(row):
+            if len(v) > self.widths[i]:
+                self.widths[i] = len(v)
+
+    def _fmt_row(self, values):
+        parts = []
+        for i, v in enumerate(values):
+            parts.append(v.ljust(self.widths[i]))
+        sep = " " * self.pad
+        return sep.join(parts)
+
+    def __str__(self):
+        lines = []
+        lines.append(self._fmt_row(self.headers))
+        lines.append(self._fmt_row(["-" * self.widths[i] for i in range(self.ncols)]))
+        for row in self.rows:
+            lines.append(self._fmt_row(row))
+        return "\n".join(lines)

pymoos2-0.1.0/pymoos2/core/AppCastingMOOSApp.py

@@ -0,0 +1,177 @@
+"""
+AppCastingMOOSApp — MOOSApp with AppCasting support.
+
+Registers for APPCAST_REQ, posts APPCAST reports via build_report(),
+and tracks events/warnings.
+"""
+
+from pymoos2.core.time import moos_time
+from pymoos2.core.MOOSApp import MOOSApp
+
+# Separators used by the C++ AppCast serialization
+OSEP = "!@#"  # outer: between fields
+ISEP = "!@"   # inner: between items within a field
+
+
+class AppCastingMOOSApp(MOOSApp):
+    """
+    MOOS application with AppCasting support.
+    Override: on_startup(), on_new_mail(), iterate(), build_report().
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._report_lines = []
+        self._events = []
+        self._run_warnings = {}    # warning_text -> count
+        self._config_warnings = []
+        self._max_events = 20
+        self._last_report_time = 0.0
+
+        # APPCAST_REQ tracking: key -> expiry_time
+        self._appcast_requests = {}
+
+    # --- Report building ---
+
+    def report(self, text):
+        """Append a line (or multi-line string, or ACTable) to the current report."""
+        self._report_lines.append(str(text))
+
+    def report_event(self, event):
+        """Add a timestamped event to the appcast."""
+        ts = moos_time() - self.m_start_time
+        self._events.append(f"[{ts:8.1f}] {event}")
+        if len(self._events) > self._max_events:
+            self._events = self._events[-self._max_events:]
+
+    def report_run_warning(self, warning):
+        """Add a runtime warning (tracked with count)."""
+        self._run_warnings[warning] = self._run_warnings.get(warning, 0) + 1
+
+    def retract_run_warning(self, warning):
+        """Remove a runtime warning."""
+        self._run_warnings.pop(warning, None)
+
+    def report_config_warning(self, warning):
+        """Add a configuration warning."""
+        if warning not in self._config_warnings:
+            self._config_warnings.append(warning)
+
+    # --- Lifecycle callback (override this) ---
+
+    def build_report(self):
+        """
+        Build the AppCast report. Override this.
+        Use self.report("text") and self.report(actable) to add content.
+        Return True to post the report.
+        """
+        return True
+
+    # --- Internal ---
+
+    def on_startup(self):
+        """Override in subclass. Base registers for APPCAST_REQ."""
+        pass
+
+    def _run(self):
+        """Extend parent _run to register for APPCAST_REQ after startup."""
+        super_on_startup = self.on_startup
+        super_on_new_mail = self.on_new_mail
+
+        def wrapped_on_startup():
+            self.register("APPCAST_REQ", 0.0)
+            super_on_startup()
+
+        def wrapped_on_new_mail(mail):
+            user_mail = []
+            for msg in mail:
+                if msg.name == "APPCAST_REQ":
+                    self._handle_appcast_req(msg.string())
+                else:
+                    user_mail.append(msg)
+            if user_mail:
+                super_on_new_mail(user_mail)
+
+        self.on_startup = wrapped_on_startup
+        self.on_new_mail = wrapped_on_new_mail
+        super()._run()
+
+    def _handle_appcast_req(self, req_str):
+        """Parse APPCAST_REQ and track if it targets this app."""
+        params = {}
+        for token in req_str.split(","):
+            if "=" in token:
+                k, v = token.split("=", 1)
+                params[k.strip().lower()] = v.strip()
+
+        req_node = params.get("node", "")
+        req_app = params.get("app", "")
+        duration = min(float(params.get("duration", "3")), 30.0)
+        key = params.get("key", "unknown")
+
+        if req_node and req_node != "all" and req_node != self.m_community:
+            return
+        if req_app and req_app != "all" and req_app != self.m_app_name:
+            return
+
+        self._appcast_requests[key] = moos_time() + duration
+
+    def _appcast_requested(self):
+        """Returns True if any non-expired appcast request exists."""
+        now = moos_time()
+        self._appcast_requests = {
+            k: v for k, v in self._appcast_requests.items() if v > now
+        }
+        return len(self._appcast_requests) > 0
+
+    def _post_iterate(self):
+        """Build and post the AppCast report after each iteration."""
+        if not self._appcast_requested():
+            return
+
+        self._report_lines = []
+        should_post = self.build_report()
+
+        if should_post:
+            self._post_appcast()
+            self._last_report_time = moos_time()
+
+    def _post_appcast(self):
+        """
+        Format and Notify the APPCAST string in the wire format
+        expected by uMAC / pMarineViewer.
+        """
+        parts = []
+
+        # Required fields
+        parts.append(f"proc={self.m_app_name}")
+        parts.append(f"iter={self.m_iteration}")
+        parts.append(f"node={self.m_community}")
+
+        # Messages (the user's report content)
+        if self._report_lines:
+            msg_body = ISEP.join(self._report_lines)
+            parts.append(f"messages={msg_body}")
+
+        # Config warnings
+        if self._config_warnings:
+            parts.append("config_warnings=" + ISEP.join(self._config_warnings))
+
+        # Events
+        if self._events:
+            parts.append(f"events_total={len(self._events)}")
+            parts.append("events=" + ISEP.join(self._events))
+
+        # Run warnings (format: count:warning_text)
+        if self._run_warnings:
+            total = sum(self._run_warnings.values())
+            parts.append(f"run_warning_total={total}")
+            warnings_strs = [f"{count}:{text}" for text, count in self._run_warnings.items()]
+            parts.append("run_warnings=" + ISEP.join(warnings_strs))
+
+        appcast_str = OSEP.join(parts)
+        self.notify("APPCAST", appcast_str)
+
+    def _report_iterate_error(self, err_msg):
+        """Surface iterate/on_new_mail exceptions as run warnings in AppCast."""
+        self.report_run_warning(err_msg)