Merge branch 'yamcs:master' into pixxel/master

Author: nikhil-pixxel

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "maven"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # Don't notify for regular version updates, only security ones
+    open-pull-requests-limit: 0
+
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # Don't generate version update PRs for webapp (too noisy)
+    exclude-paths:
+      - "yamcs-web/src/main/webapp/**"

docs/server-manual/activities/_images/activities-page.png

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2025-09-10T14:07:45.144Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.3.0 Chrome/104.0.5112.114 Electron/20.1.3 Safari/537.36" etag="ZAMGO0btfpaQRaqPCaTz" version="20.3.0" type="device"><diagram id="bG7BKePdNWSyEMryDBXW" name="Page-1">5Vddb9owFP01PK4iMYT2sUC3Vmu1SVTq9jSZ+JJ4dXIjx4Fkv37XxCGEjK6VKrF2T/iee/11jn2IB2yWlJ80z+I7FKAG/lCUAzYf+L438gP6sUhVIxcTvwYiLYUraoGF/AUOHDq0kALyTqFBVEZmXTDENIXQdDCuNW66ZStU3VkzHkEPWIRc9dEHKUxco+f+pMWvQUZxM7MXXNSZhDfFbid5zAVu9iB2NWAzjWjqVlLOQFnyGl7qfh+PZHcL05Ca53S4m13fYDZ+WHuPX7LH9Y/P9zfLD26UNVeF2/C9TEDJFNyiTdUwobFIBdjBvAGbbmJpYJHx0GY3pD1hsUmUS6+kUjNUqLd92Wq18sOQ8NxofIS9jAiWwTigjFsIaAPl0R16O97owAEmYHRFJa6DzxzV7qyxoYs3rXJeI0e8p1rgMO4OS7QbuuWTGo7SF9Dr9+i9DI1cS2NXvQC9luFbJHo07hLtTU5N9KhHtABj/YCufGEKTSwHihYxXWpqRbbFayUkucuhAiDIA1yI2sQYYcrVVYtOW42GFLU1t4iZU+YnGFM5Q+OFwa5u9Zx2oqc1oHVhoUN4Yu/M2SLXEZi/3fW+phoUJya663h1gcY9gaCEsDDHhan+E1n8U8rCnjSoMAZRKNDvwKJO/18w6VGdKZ7+a75E9Orqm+u/Db7b4GzchPNyPzmvXPSKFyd4C352ftzPhjJJQEj+jr3tuRKd1NuCnkQ91rEw9lt3tns8WGoFz+Mdz9aEJD0HbvkS1FfM6WJiSrklGoPJXsGlkpFNGKvGlLsoJGrJPzs60EMgs/MnZWTfTGd8k7OzIt+WHXjl3J+zOSOcKoWksZpciim8jlF6h99y532jZH/wydHLfZLC9rmzze09GtnVbw==</diagram></mxfile>

docs/server-manual/activities/_images/planned-activities.drawio

@@ -0,0 +1,73 @@
+Command Activities
+==================
+
+Yamcs is capable of executing a single command as a background activity.
+
+.. note::
+   Yamcs does not enforce all commands to be activities, rather it has an API to send commands directly. The capability to wrap a command in an activity is primarily intended for use with planned activities.
+
+
+Activity Options
+----------------
+
+command (string)
+    **Required.** Fully-qualified command name.
+
+args (map)
+    Command arguments mapped from name to value.
+
+processor (string)
+    Choose the processor that will handle the command instruction.
+
+    This defaults to the first defined processor with commanding capabilities, which by convention is usually called ``realtime``.
+
+extra (map)
+    Additional command options mapped from name to value (implementation-specific).
+
+stream (string)
+    Specify the low-level Yamcs stream where the command is emitted.
+
+    If undefined, Yamcs will automatically select the target stream (first matching ``tc`` stream under the ``streamConfig`` configuration block. See :doc:`../data-management/streams`.
+
+
+Execution
+---------
+
+The activity finishes successfully when the command could be encoded and submitted to a link. It does not currently track any acknowledgments or command completion.
+
+
+Yamcs UI
+--------
+
+The Yamcs UI does not support **immediate** execution of command activities, because you can send commands directly without the notion of an activity.
+
+To execute a command **at a later time**, go to :menuselection:`Commanding --> Send a command`. Enter the command form, then choose the option :guilabel:`Send later...`. You will be asked to enter the desired execution time. This will create an activity *item* in the :doc:`../timeline/index`.
+
+
+Python Yamcs Client
+-------------------
+
+Run a command activity one minute from now:
+
+.. code-block:: python
+
+    from datetime import datetime, timedelta, timezone
+
+    from yamcs.client import CommandActivity, YamcsClient, TimelineActivity
+
+    client = YamcsClient("http://localhost:8090")
+    timeline = client.get_timeline_client("simulator")
+
+    now = datetime.now(tz=timezone.utc)
+
+    item = TimelineActivity(
+        name="Switch on battery 1 voltage",
+        start=now + timedelta(minutes=1),
+        duration=timedelta(seconds=1),  # Planned duration
+        activity=CommandActivity(
+            command="/YSS/SIMULATOR/SWITCH_VOLTAGE_ON",
+            args={"voltage_num": 1},
+        ),
+    )
+
+    timeline.save_item(item)

docs/server-manual/activities/_images/planned-activities.png

@@ -0,0 +1,42 @@
+Activities
+==========
+
+Yamcs can run background activities whose execution state are tracked in the UI.
+
+.. image:: _images/activities-page.png
+    :alt: Activities Page
+    :align: center
+
+Yamcs includes a core set of activity types that cover command execution, stack execution and script execution. Yamcs plugins may add additional types.
+
+.. note::
+    Prior to Yamcs 5.13.0, activities were only available by enabling the :doc:`Timeline Service <../services/instance/timeline-service>`. Since then, activities were upgraded to a core Yamcs functionality, and so no longer require presence of the Timeline Service.
+
+
+.. rubric:: Status
+
+An activity can assume one of these statuses:
+
+* **RUNNING:** The activity is ongoing
+* **CANCELLED:** The activity was cancelled
+* **SUCCESSFUL:** The activity completed successfully
+* **FAILED:** An error occurred while running the activity
+
+
+.. rubric:: Relation to Timeline
+
+When combining with the :doc:`../timeline/index`, you can plan activities for future execution:
+
+.. image:: _images/planned-activities.png
+    :alt: Planned Activities
+    :align: center
+
+Planned activities are submitted via the UI or API to the Timeline (saved as activity *items*). An activity scheduler monitors all activity items in the Timeline, and submits them to the activity service when due, for immediate execution.
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Table of Contents
+
+    commands
+    stacks
+    scripts

docs/server-manual/activities/commands.rst

@@ -0,0 +1,211 @@
+Script Activities
+=================
+
+Yamcs can run arbitrary scripts or programs as a background activity.
+
+Scripts are predefined and stored under :file:`etc/scripts`.
+
+Script files may be directly executable, or be associated to another program based on its file extension.
+
+
+Configuration
+-------------
+
+Script activity options are configured in the instance configuration file :file:`etc/yamcs.{instance}.yaml`.
+
+.. code-block:: yaml
+    :caption: :file:`etc/yamcs.{instance}.yaml`
+
+    activities:
+      scriptExecution:
+        searchPath: etc/scripts
+        impersonateCaller: false
+        fileAssociations:
+          py: python3 -u
+
+
+Configuration Options
+---------------------
+
+searchPath (string or string[])
+  Directory where to locate scripts or executables.
+
+  Default: :file:`etc/scripts`
+
+fileAssociations (map)
+  Extend or override the default file associations. Each entry maps a file extension (case-insensitive) to a program that should be used to execute this file.
+
+  The default file associations are:
+
+  .. code-block:: yaml
+
+      fileAssociations:
+        java: java
+        js: node
+        mjs: node
+        pl: perl
+        py: python -u
+        rb: ruby
+
+  Any file that does not have an association, is executed directly.
+
+  .. note::
+     Some Linux distributions no longer have a ``python`` command. In this case you can adapt the file association to ``python3 -u``. Alternatively, on Debian-based distributions you may want to install the ``python-is-python3`` package:
+
+     .. code-block:: shell
+
+        sudo apt install python-is-python3
+   
+     This package creates a symlink so that ``python`` invokes ``python3``.
+
+  .. note::
+      The ``-u`` flag added to the ``python`` command forces Python to run in **unbuffered mode**. This affects how Python handles output streams, allowing Yamcs to capture output in realtime instead of needing to wait until the buffer is full.
+
+impersonateCaller (boolean)
+  Scripts receive a transient API key via an environment variable. By default this API key uses the built-in ``System`` user, which provides unrestricted access.
+
+  When this property is enabled, the script receives instead an API key of the user that started the activity.
+
+  Default: ``false``
+
+
+Activity Options
+----------------
+
+script (string)
+    **Required.** Script path relative to the :file:`etc/scripts` directory.
+
+args (string, or list of strings)
+    Command line arguments.
+
+processor (string)
+    If provided this information is passed to the called script as a ``YAMCS_PROCESSOR`` environment variable.
+
+
+Execution
+---------
+
+The script's ``stdout`` and ``stderr`` output streams are captured in the Yamcs activity log. The activity tracks the lifecycle of the subprocess. The exit code of this process determines whether the activity is considered successful or not. A non-zero exit code indicates failure.
+
+
+Environment Variables
+---------------------
+
+Scripts are executed with the following environment variables:
+
+``YAMCS``
+    Always set to ``1``.
+
+``YAMCS_INSTANCE``
+    Set to the applicable Yamcs instance.
+
+``YAMCS_PROCESSOR``
+    Set to the applicable Yamcs processor.
+
+``YAMCS_URL``
+    URL that the script can use to reach Yamcs.
+
+    For example: ``http://localhost:8090``
+
+If Yamcs requires authentication, another environment variable is set:
+
+``YAMCS_API_KEY``
+    A randomly generated API key that the script may use to authenticate against Yamcs. Keys are invalidated when the script terminates.
+
+    Clients can use an API key by setting the ``x-api-key`` HTTP header on each request. Yamcs will know how to link this back to the appropriate user, which (depending on configuration) could be the script caller, or a generic ``System`` user.
+
+
+Python Scripts
+--------------
+
+Python scripts may use the `Python Yamcs Client <https://docs.yamcs.org/python-yamcs-client/>`_ to access the Yamcs API. This includes a static utility function ``YamcsClient.from_environment()`` that reads aforementioned environment variables, and authenticates when needed.
+
+.. code-block:: python
+
+   from yamcs.client import YamcsClient
+   import sys
+
+   # Create a client instance
+   client = YamcsClient.from_environment()
+
+   # Print all command-line arguments 
+   print(sys.argv)
+
+   # ...
+
+The Python Yamcs Client is something that would need to be installed separate from Yamcs.
+
+
+Shell Scripts
+-------------
+
+Below is an example of a shell script that generates a Yamcs event. Remember to make the file executable.
+
+.. code-block:: shell
+
+   #!/bin/sh
+   
+   echo "Creating event"
+   
+   MSG="$(whoami) says hi"
+   JSON_STRING=$(printf '{"message": "%s"}' "$MSG")
+   
+   curl -XPOST $YAMCS_URL/api/archive/$YAMCS_INSTANCE/events \
+        --silent -d "$JSON_STRING" --fail-with-body
+
+For authenticated servers, you can specify an additional HTTP header on the curl command:
+
+.. code-block:: shell
+
+   -H "x-api-key: $YAMCS_API_KEY"
+
+
+Yamcs UI
+--------
+
+In the Yamcs UI, choose :menuselection:`Procedures --> Run a script`. A list of the available scripts is displayed, and you can choose to run one **immediately**, providing any script arguments.
+
+To execute a script **at a later time**, choose the option :guilabel:`Run later...`. You will be asked to enter the desired execution time. This will create an activity *item* in the :doc:`../timeline/index`.
+
+
+Python Yamcs Client
+-------------------
+
+Run a script activity immediately (does not use Yamcs Timeline):
+
+.. code-block:: python
+
+    from yamcs.client import YamcsClient
+
+    client = YamcsClient("localhost:8090")
+    processor = client.get_processor("simulator", "realtime")
+
+    # Simulate LOS for 5 seconds
+    # (the run_script call does not block)
+    processor.run_script("simulate_los.py", "--duration 5")
+
+
+Run a script activity one minute from now:
+
+.. code-block:: python
+
+    from datetime import datetime, timedelta, timezone
+
+    from yamcs.client import ScriptActivity, YamcsClient, TimelineActivity
+
+    client = YamcsClient("http://localhost:8090")
+    timeline = client.get_timeline_client("simulator")
+
+    now = datetime.now(tz=timezone.utc)
+
+    item = TimelineActivity(
+        name="Simulate LOS",
+        start=now + timedelta(minutes=1),
+        duration=timedelta(seconds=5),  # Planned duration
+        activity=ScriptActivity(
+            script="simulate_los.py",
+            args="--duration 5",
+            processor="realtime",
+        ),
+    )
+    timeline.save_item(item)