openc3 7.4.1 → 7.5.0

data/templates/plugin/README.md

@@ -8,6 +8,96 @@ Update this comment with your own description.
 
 1. Edit the .gemspec file fields: name, summary, description, authors, email, and homepage
 1. Update the LICENSE.md file with your company name
+<% if @@language == 'py' -%>
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage the plugin's Python dependencies
+
+## Python dependencies with uv
+
+The plugin's Python dependencies are declared in `pyproject.toml` and locked in `uv.lock`.
+Both files are packaged into the gem automatically, and COSMOS reads them when the plugin is installed.
+
+### Adding dependencies
+
+```sh
+uv add requests                 # runtime dependency, installed into COSMOS with the plugin
+uv add --group dev pytest-mock  # development only, never installed into COSMOS
+```
+
+`uv add` updates both `pyproject.toml` and `uv.lock`. Commit both files.
+
+`uv lock` resolves `pyproject.toml` and writes `uv.lock` without installing anything. `uv sync` does the
+same when the lock is stale, then installs into `.venv`. Either works after editing `pyproject.toml` by hand;
+commit the updated `uv.lock`.
+
+COSMOS installs a locked plugin with `uv sync --frozen`, which installs exactly what `uv.lock` records and never
+relocks, so a stale lock ships stale dependencies. `uv lock --check` fails if the lock is out of date.
+
+### How COSMOS installs them
+
+- **With `uv.lock`** (recommended): COSMOS runs `uv sync --frozen --no-dev`. Every install gets the same
+  versions, downloaded from the URLs recorded in the lock.
+- **Without `uv.lock`**: COSMOS resolves the dependencies at install time against the PyPI URL set in
+  Admin Console -> Settings, so versions can change from one install to the next.
+
+The `dev` dependency group is never installed into COSMOS.
+
+### Developing locally
+
+```sh
+uv sync --group dev           # create .venv with runtime and dev dependencies
+uv run --group dev pytest     # run tests; lib/ is on the import path
+uv run --group dev ruff check # lint
+uv run --group dev ruff format
+uv run --group dev ty check   # type check
+```
+
+A plain `uv sync` installs only the runtime dependencies, matching what COSMOS installs.
+
+The plugin itself is not installed into `.venv`: COSMOS puts `lib/` on the Python path instead, and pytest and ty
+are configured to do the same. Anything else needs `lib/` on the path to import `<%= package_name %>`:
+
+```
+PYTHONPATH=lib uv run python my_script.py
+```
+
+`cli generate` writes a `.python-version` file pinning the Python version of the COSMOS image it ran in, so
+uv develops against the same Python COSMOS runs. If you upgrade to a COSMOS release with a newer Python, update
+it with `uv python pin <version>`. Without that file uv picks any installed Python that satisfies
+`requires-python`.
+
+The `openc3` dev dependency provides the COSMOS Python API for your editor, tests and `ty`. Pin it to the
+COSMOS version you deploy to so they see the same API, e.g. `uv add --group dev "openc3==X.Y.Z"`.
+
+### Where to put Python code
+
+Put Python code shared across the plugin in `lib/<%= package_name %>/`, never directly in `lib/`.
+
+COSMOS adds the `lib/` directory of every installed plugin to the Python path. If two plugins both ship
+`lib/helpers.py`, `import helpers` loads whichever one Python finds first, and the other can't be imported
+at all. A module directly in `lib/` can also hide an installed package of the same name, such as `requests`.
+The `<%= package_name %>` package is named after this plugin, so its modules can't collide.
+
+Import from the package:
+
+```python
+from <%= package_name %>.helpers import Helper
+```
+
+Reference its files by path in plugin configuration, e.g. `INTERFACE MY_INT <%= package_name %>/my_interface.py`.
+
+### Updating dependencies
+
+```
+uv lock --upgrade-package requests  # upgrade one package
+uv lock --upgrade                   # upgrade everything
+```
+
+### Private package indexes
+
+See the comments in the `[tool.uv]` section of `pyproject.toml`. If the COSMOS PyPI URL setting points at
+anything other than public PyPI, COSMOS ignores the plugin's own index settings when it resolves, so a
+package published only to your private index must also be served by that index, or be locked in `uv.lock`.
+<% end -%>
 
 ## Building non-tool / widget plugins
 
@@ -26,19 +116,41 @@ If you don’t have a local node environment, you can use our openc3-node contai
 
 Mac / Linux:
 
-```
+```sh
 docker run -it -v `pwd`:/openc3/local:z -w /openc3/local docker.io/openc3inc/openc3-node sh
 ```
 
 Windows:
 
-```
+```sh
 docker run -it -v %cd%:/openc3/local -w /openc3/local docker.io/openc3inc/openc3-node sh
 ```
 
 1. pnpm install --frozen-lockfile --ignore-scripts
 1. rake build VERSION=1.0.0
 
+## Continuous integration
+
+`.github/workflows/` ships three GitHub Actions workflows that work as soon as
+you push this plugin to GitHub. They call shared workflows from `OpenC3/.github`,
+so the steps stay current without you updating anything here.
+
+- **Unit Tests** - on every push and pull request. Runs Python tests in `tests/`
+  or `test/` and Ruby specs in `spec/` or `specs/`. Whichever you don't have is
+  skipped, so just add a test file.
+- **Playwright** - on every push and pull request, plus weekly. Builds the gem,
+  starts the latest COSMOS release in Docker, and installs the plugin through the
+  Admin tool, which catches a `plugin.txt` that doesn't parse, a target that
+  doesn't build, or a microservice that won't start. The weekly run is what tells
+  you a new COSMOS release broke this plugin. Once you add targets, list them in
+  `expected_targets` so the install is verified against them.
+- **Release** - manual, from the Actions tab. Builds the gem, tags the commit and
+  creates a GitHub release. Publishing to the OpenC3 App Store and to RubyGems is
+  off until you add the matching secret and tick the box.
+
+Adding a tool or a widget needs no change to any of these. All three build a
+frontend with pnpm as soon as the plugin has a `package.json`.
+
 ## Installing into OpenC3 COSMOS
 
 1. Go to the OpenC3 Admin Tool, Plugins Tab

data/templates/plugin/lib/PACKAGE/__init__.py

@@ -0,0 +1,4 @@
+# Python code shared across this plugin lives in this package. COSMOS puts
+# every installed plugin's lib/ on sys.path, so a module placed directly in
+# lib/ can collide with another plugin's module of the same name. Keeping it
+# under this uniquely named package avoids that. See README.md.

data/templates/plugin/plugin.gemspec

@@ -20,7 +20,16 @@ Gem::Specification.new do |s|
     time = Time.now.strftime("%Y%m%d%H%M%S")
     s.version = '0.0.0' + ".#{time}"
   end
-  s.files = Dir.glob("{targets,lib,public,tools,microservices}/**/*") + %w(Rakefile README.md LICENSE.md plugin.txt)
+<% if @@language == 'py' -%>
+  # pyproject.toml and uv.lock must be in the gem for COSMOS to install the
+  # plugin's python dependencies: install only sees files the gem contains.
+  # Globbed rather than listed so the gem still builds before `uv lock` is run.
+<% end -%>
+  s.files = Dir.glob("{targets,lib,public,tools,microservices}/**/*") + %w(Rakefile README.md LICENSE.md plugin.txt)<% if @@language == 'py' %> + Dir.glob("{pyproject.toml,uv.lock}")<% end %>
+<% if @@language == 'py' -%>
+  # Running tests or scripts locally writes bytecode next to the source; keep it out of the gem.
+  s.files = s.files.reject { |file| file.include?('__pycache__') }
+<% end -%>
 
   s.metadata = {
     # These fields are used when you submit your plugin to the OpenC3 Store at store.openc3.com

data/templates/plugin/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "<%= plugin_name %>"
+version = "0.0.0"
+description = "OpenC3 <%= plugin_name %> plugin Python dependencies"
+readme = "README.md"
+requires-python = ">=3.11"
+# Add your plugin's Python dependencies here, then run `uv lock` and commit the
+# resulting uv.lock so COSMOS installs the same versions every time.
+dependencies = []
+
+[dependency-groups]
+# Development and test only. COSMOS installs plugin dependencies with --no-dev,
+# so nothing here reaches a deployed plugin. Left unpinned on purpose: a bound
+# written into this template would still be here whenever you generated this
+# plugin, holding you on stale tooling. Commit the uv.lock for reproducible
+# versions, and add a pin here only if you need a specific one.
+dev = [
+    "openc3",
+    "pytest",
+    "ruff",
+    "ty",
+]
+
+[tool.uv]
+# This file declares dependencies only — it is not a buildable package. COSMOS
+# loads plugin code from lib/ at runtime and installs with `uv sync --frozen`,
+# so nothing here is ever built and no [build-system] is needed.
+package = false
+
+# Keep the dev group out of a plain `uv sync` so a local install matches what
+# COSMOS installs (it passes --no-dev). Use `uv sync --group dev` while
+# developing, or `uv run --group dev pytest`.
+default-groups = []
+
+# Uncomment to install dependencies from a private PyPI repository.
+# See: https://docs.astral.sh/uv/configuration/indexes/
+#
+# These settings are used whenever uv resolves: when you run `uv lock` yourself,
+# and at install time when no uv.lock is committed alongside this file.
+#
+# They do not always survive installation into COSMOS. When the PyPI URL in
+# Admin Console -> Settings names anything other than public PyPI, the operator
+# has designated an index and COSMOS makes it authoritative: the install passes
+# uv `--no-config --no-sources`, so everything below is ignored and every
+# package is resolved from the operator's index. A dependency published only to
+# your private index then fails to install there, rather than being fetched
+# from it — coordinate with the operator so their index serves it too.
+#
+# A committed uv.lock sidesteps this entirely: COSMOS installs with
+# `uv sync --frozen`, which fetches the exact registry and wheel URLs recorded
+# in the lock and consults no index at all.
+#
+# Indexes are searched in the order listed, before the default index. Mark one
+# `default = true` to replace public PyPI entirely, or list your private repo
+# first and leave PyPI as the default to fall back to it.
+#
+# index = [
+#     { name = "private", url = "https://private-pypi.example.com/simple" },
+#     { name = "pypi", url = "https://pypi.org/simple", default = true },
+# ]
+#
+# Pin internal packages to a specific index. A pin keeps a same-named package on
+# public PyPI from being substituted. Add `explicit = true` to an index to keep
+# it from serving anything other than packages pinned to it.
+#
+# sources = { my-internal-pkg = { index = "private" } }
+#
+# Uncomment for self-signed certificates.
+#
+# allow-insecure-host = ["private-pypi.example.com"]
+
+[tool.ty.environment]
+# COSMOS puts the plugin's lib/ on sys.path at runtime rather than installing it,
+# so ty needs it here to resolve imports between the plugin's own modules.
+extra-paths = ["lib"]
+
+[tool.pytest.ini_options]
+# Same reason as ty's extra-paths: lib/ is on sys.path at runtime, not installed,
+# so tests need it on the path to import the plugin's own modules.
+pythonpath = ["lib"]
+
+[tool.ty.rules]
+# These are artifacts of how COSMOS ships its Python API, not mistakes in your
+# plugin, so they are off rather than "warn": ty exits non-zero on a warning, so
+# "warn" would fail the check just as an error does. Delete a line to opt back
+# in, or silence a single case with `# ty: ignore[rule-name]`.
+#
+# openc3.script re-exports its API through star imports (from .telemetry import *,
+# etc.) with no __all__, so ty cannot see tlm, cmd, send_raw and friends even
+# though they resolve at runtime. unresolved-reference covers using such a name,
+# unresolved-import covers importing one by name. Ruff's F405 flags the same
+# thing if you want it reported.
+unresolved-reference = "ignore"
+unresolved-import = "ignore"
+# Script Runner replaces openc3.script.start() at runtime with its own
+# implementation, which accepts bind_variables. The pip package only ships the
+# stub signature start(procedure_name).
+unknown-argument = "ignore"
+
+[tool.ruff]
+line-length = 120
+# target-version is intentionally absent: ruff infers it from the project's
+# requires-python above, so there is one place to bump the minimum. ty does the
+# same, which is why [tool.ty.environment] sets no python-version either.
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "W", "C4", "SIM"]
+ignore = [
+    "E402",   # Module level import not at top of file
+    "E501",   # Line too long (handled by the formatter)
+    "F402",   # Import shadowed by loop var
+    "F403",   # Star imports used - the documented way to import the COSMOS API
+    "F405",   # Name may be undefined due to star import
+    "N815",   # Mixed case variable in class scope
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["openc3"]
+lines-after-imports = 2

data/templates/tool_angular/package.json

@@ -1,6 +1,6 @@
 {
   "name": "<%= tool_name %>",
-  "version": "7.4.1",
+  "version": "7.5.0",
   "scripts": {
     "ng": "ng",
     "start": "ng serve",
@@ -23,7 +23,7 @@
     "@angular/platform-browser-dynamic": "^18.2.6",
     "@angular/router": "^18.2.6",
     "@astrouxds/astro-web-components": "^7.24.0",
-    "@openc3/js-common": "7.4.1",
+    "@openc3/js-common": "7.5.0",
     "rxjs": "~7.8.0",
     "single-spa": "^5.9.5",
     "single-spa-angular": "^9.2.0",

data/templates/tool_angular/pnpm-workspace.yaml

@@ -0,0 +1,16 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+minimumReleaseAge: 1440 # 1 day
+minimumReleaseAgeExclude:
+  # we control these packages, so we don't need to wait to consume them
+  - '@openc3/js-common'
+  - '@openc3/vue-common'

data/templates/tool_react/package.json

@@ -16,7 +16,7 @@
     "@emotion/react": "^11.13.3",
     "@emotion/styled": "^11.11.0",
     "@mui/material": "^6.1.1",
-    "@openc3/js-common": "7.4.1",
+    "@openc3/js-common": "7.5.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "single-spa-react": "^5.1.4"

data/templates/tool_react/pnpm-workspace.yaml

@@ -0,0 +1,16 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+minimumReleaseAge: 1440 # 1 day
+minimumReleaseAgeExclude:
+  # we control these packages, so we don't need to wait to consume them
+  - '@openc3/js-common'
+  - '@openc3/vue-common'

data/templates/tool_svelte/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@astrouxds/astro-web-components": "^7.24.0",
-    "@openc3/js-common": "7.4.1",
+    "@openc3/js-common": "7.5.0",
     "@smui/button": "^7.0.0",
     "@smui/common": "^7.0.0",
     "@smui/card": "^7.0.0",
@@ -26,6 +26,7 @@
   "devDependencies": {
     "@babel/core": "^7.25.2",
     "@babel/preset-env": "^7.25.4",
+    "@material/theme": "^14.0.0",
     "@rollup/plugin-commonjs": "^28.0.0",
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@testing-library/jest-dom": "^6.5.0",

data/templates/tool_svelte/pnpm-workspace.yaml

@@ -0,0 +1,20 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+# smui-theme builds its sass load path from require.resolve('@material/dom'),
+# which only finds the sibling @material/* packages in a flat node_modules.
+nodeLinker: hoisted
+
+minimumReleaseAge: 1440 # 1 day
+minimumReleaseAgeExclude:
+  # we control these packages, so we don't need to wait to consume them
+  - '@openc3/js-common'
+  - '@openc3/vue-common'

data/templates/tool_vue/package.json

@@ -1,6 +1,6 @@
 {
   "name": "<%= tool_name %>",
-  "version": "7.4.1",
+  "version": "7.5.0",
   "private": true,
   "type": "module",
   "scripts": {
@@ -11,8 +11,8 @@
   },
   "dependencies": {
     "@astrouxds/astro-web-components": "^7.24.0",
-    "@openc3/js-common": "7.4.1",
-    "@openc3/vue-common": "7.4.1",
+    "@openc3/js-common": "7.5.0",
+    "@openc3/vue-common": "7.5.0",
     "axios": "^1.7.7",
     "date-fns": "^4.1.0",
     "lodash": "^4.17.21",

data/templates/tool_vue/pnpm-workspace.yaml

@@ -0,0 +1,16 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+minimumReleaseAge: 1440 # 1 day
+minimumReleaseAgeExclude:
+  # we control these packages, so we don't need to wait to consume them
+  - '@openc3/js-common'
+  - '@openc3/vue-common'

data/templates/widget/package.json

@@ -1,6 +1,6 @@
 {
   "name": "<%= widget_name %>",
-  "version": "7.4.1",
+  "version": "7.5.0",
   "private": true,
   "type": "module",
   "scripts": {
@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@astrouxds/astro-web-components": "^7.24.0",
-    "@openc3/vue-common": "7.4.1",
+    "@openc3/vue-common": "7.5.0",
     "vuetify": "^3.7.1"
   },
   "devDependencies": {

data/templates/widget/pnpm-workspace.yaml

@@ -0,0 +1,16 @@
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+minimumReleaseAge: 1440 # 1 day
+minimumReleaseAgeExclude:
+  # we control these packages, so we don't need to wait to consume them
+  - '@openc3/js-common'
+  - '@openc3/vue-common'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openc3
 version: !ruby/object:Gem::Version
-  version: 7.4.1
+  version: 7.5.0
 platform: ruby
 authors:
 - Ryan Melton
@@ -953,6 +953,7 @@ files:
 - data/config/command_modifiers.yaml
 - data/config/command_telemetry.yaml
 - data/config/conversions.yaml
+- data/config/default_plugins.yaml
 - data/config/graph_settings.yaml
 - data/config/interface_modifiers.yaml
 - data/config/item_modifiers.yaml
@@ -1094,6 +1095,7 @@ files:
 - lib/openc3/interfaces/protocols/slip_protocol.rb
 - lib/openc3/interfaces/protocols/template_protocol.rb
 - lib/openc3/interfaces/protocols/terminated_protocol.rb
+- lib/openc3/interfaces/read_queue_interface.rb
 - lib/openc3/interfaces/serial_interface.rb
 - lib/openc3/interfaces/simulated_target_interface.rb
 - lib/openc3/interfaces/stream_interface.rb
@@ -1300,6 +1302,7 @@ files:
 - lib/openc3/utilities/crc.rb
 - lib/openc3/utilities/csv.rb
 - lib/openc3/utilities/ctrf.rb
+- lib/openc3/utilities/default_plugins.rb
 - lib/openc3/utilities/env_helper.rb
 - lib/openc3/utilities/local_bucket.rb
 - lib/openc3/utilities/local_mode.rb
@@ -1309,6 +1312,7 @@ files:
 - lib/openc3/utilities/migration.rb
 - lib/openc3/utilities/open_telemetry.rb
 - lib/openc3/utilities/process_manager.rb
+- lib/openc3/utilities/process_stats.rb
 - lib/openc3/utilities/pypi_url.rb
 - lib/openc3/utilities/python_proxy.rb
 - lib/openc3/utilities/python_venv.rb
@@ -1330,6 +1334,7 @@ files:
 - lib/openc3/utilities/target_file.rb
 - lib/openc3/utilities/thread_manager.rb
 - lib/openc3/utilities/throttle.rb
+- lib/openc3/utilities/topic_lag_monitor.rb
 - lib/openc3/utilities/zip.rb
 - lib/openc3/version.rb
 - lib/openc3/win32/excel.rb
@@ -1345,12 +1350,17 @@ files:
 - templates/limits_response/response.rb
 - templates/microservice/microservices/TEMPLATE/microservice.py
 - templates/microservice/microservices/TEMPLATE/microservice.rb
+- templates/plugin/.github/workflows/playwright.yml
+- templates/plugin/.github/workflows/release.yml
+- templates/plugin/.github/workflows/unit-tests.yml
 - templates/plugin/.gitignore
 - templates/plugin/LICENSE.md
 - templates/plugin/README.md
 - templates/plugin/Rakefile
+- templates/plugin/lib/PACKAGE/__init__.py
 - templates/plugin/plugin.gemspec
 - templates/plugin/plugin.txt
+- templates/plugin/pyproject.toml
 - templates/processor/processor.py
 - templates/processor/processor.rb
 - templates/target/targets/TARGET/cmd_tlm/cmd.txt
@@ -1370,6 +1380,7 @@ files:
 - templates/tool_angular/angular.json
 - templates/tool_angular/extra-webpack.config.js
 - templates/tool_angular/package.json
+- templates/tool_angular/pnpm-workspace.yaml
 - templates/tool_angular/src/app/app-routing.module.ts
 - templates/tool_angular/src/app/app.component.html
 - templates/tool_angular/src/app/app.component.scss
@@ -1397,6 +1408,7 @@ files:
 - templates/tool_react/babel.config.json
 - templates/tool_react/jest.config.js
 - templates/tool_react/package.json
+- templates/tool_react/pnpm-workspace.yaml
 - templates/tool_react/src/openc3-tool_name.js
 - templates/tool_react/src/root.component.js
 - templates/tool_react/src/root.component.test.js
@@ -1408,6 +1420,7 @@ files:
 - templates/tool_svelte/build/smui.css
 - templates/tool_svelte/jest.config.js
 - templates/tool_svelte/package.json
+- templates/tool_svelte/pnpm-workspace.yaml
 - templates/tool_svelte/rollup.config.js
 - templates/tool_svelte/src/App.svelte
 - templates/tool_svelte/src/App.test.js
@@ -1419,6 +1432,7 @@ files:
 - templates/tool_vue/eslint.config.mjs
 - templates/tool_vue/jsconfig.json
 - templates/tool_vue/package.json
+- templates/tool_vue/pnpm-workspace.yaml
 - templates/tool_vue/src/App.vue
 - templates/tool_vue/src/main.js
 - templates/tool_vue/src/router.js
@@ -1428,6 +1442,7 @@ files:
 - templates/widget/LICENSE.md
 - templates/widget/Rakefile
 - templates/widget/package.json
+- templates/widget/pnpm-workspace.yaml
 - templates/widget/src/Widget.vue
 - templates/widget/vite.config.js
 homepage: https://github.com/OpenC3/cosmos