cgse 0.16.14__tar.gz → 0.17.0__tar.gz

cgse-0.17.0/.env.example

@@ -0,0 +1,9 @@
+PROJECT='ARIEL'
+SITE_ID='VACUUM_LAB'
+
+# The variable below all start with the project name.
+
+ARIEL_DATA_STORAGE_LOCATION=~/data/ARIEL/VACUUM_LAB
+ARIEL_CONF_DATA_LOCATION=~/data/ARIEL/VACUUM_LAB/conf
+ARIEL_LOCAL_SETTINGS=~/data/ARIEL/VACUUM_LAB/local_settings.yaml
+ARIEL_LOG_FILE_LOCATION=~/data/ARIEL/VACUUM_LAB/log

cgse-0.17.0/CHANGELOG.md

@@ -0,0 +1,135 @@
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [Unreleased](https://github.com/IvS-KULeuven/cgse/compare/v0.17.0...HEAD)
+
+### Added
+- ...
+
+## [v0.17.0](https://github.com/IvS-KULeuven/cgse/compare/v0.16.14...v0.17.0)
+
+### Added
+- Added this CHANGELOG file.
+- Added an initial implementation of the ARIEL Telescope Control Unit (TCU). This is a separate package in this monorepo that is located at `projects/ariel/ariel-tcu`. The package will be added to PyPI as `ariel-tcu`.
+- Added a `read_string()` method to the `DeviceTransport` and `AsyncDeviceTransport` classes.
+### Fixed
+- Fixed the `sm_cs` for the missing `--full` cli argument.
+- Fixed the configuration of the InfluxDB client. The client can now be fully configured with environment variables if needed.
+### Changed
+- Improved initialization of the process environment with `setup_env()`.
+- The configuration manager now also re-registers the obsid table to the storage.
+- The `cgse` subcommand to start the notification hub is changed from `not` to `nh`. Use `cgse nh [start|stop|status]`.
+- The environment variables that contain a path can start with a tilde '`~`' which will be expanded to the user's home directory when used.
+### Docs
+- Documentation updates for the Python version, the CLI `cgse` subcommands,  environment and the introduction of `dotenv`, ...
+- Updated information on the use of `dotenv` in the developer guid.
+- Added information on the environment variables to the user guide.
+
+## [0.16.14](https://github.com/IvS-KULeuven/cgse/compare/v0.16.13...v0.16.14) – 24/10/2025
+
+### Added
+- Added `cmd_string_func` parameter to the `@dynamic_command` interface. Use this parameter if you need to create a fancy command string from the arguments passed into the command function.
+
+## [0.16.13](https://github.com/IvS-KULeuven/cgse/compare/v0.16.12...v0.16.13) – 23/10/2025
+
+### Changed
+- Improved unit tests for the `mixin.py` module.
+
+## [0.16.12](https://github.com/IvS-KULeuven/cgse/compare/v0.16.11...v0.16.12) – 21/10/2025
+
+### Fixed
+- Fixed a bug in starting the puna proxy.
+
+## [0.16.11](https://github.com/IvS-KULeuven/cgse/compare/v0.16.10...v0.16.11) – 21/10/2025
+
+### Fixed
+- Fixed starting the hexapod GUI by specifying a device identifier.
+- Fixed registration and connection of the notification hub.
+### Added
+- Added a dependency for the `dotenv` module.
+### Changed
+- The PUNA GUI script now starts as a Typer app.
+- The `get_port_number()` in `zmq_ser.py` now returns 0 (zero) on error.
+- Improved logging for the Symétrie hexapods.
+- Introduced the `VERBOSE_DEBUG` environment variable that can be used to restrict debug logging messages only when 
+  this environment variable is set. Use this for very verbose debug logging.
+
+## [0.16.10](https://github.com/IvS-KULeuven/cgse/compare/v0.16.9...v0.16.10) – 03/10/2025
+
+### Changed
+- Renamed Settings for external logger from `TEXTUALOG_*` to `EXTERN_LOG_*`.
+- The heartbeat ZeroMQ protocol now uses ROUTER-DEALER instead of REQ-REP. This was needed because too often we got an invalid state for the REQ sockets after one of the services went down.
+
+## [0.16.9](https://github.com/IvS-KULeuven/cgse/compare/v0.16.8...v0.16.9) – 02/10/2025
+
+### Removed
+- Removed caching from the async registry client.
+
+## [0.16.8](https://github.com/IvS-KULeuven/cgse/compare/v0.16.7...v0.16.8) – 02/10/2025
+
+### Fixed
+- Fixed re-registration for the async registry client.
+
+## [0.16.7](https://github.com/IvS-KULeuven/cgse/compare/v0.16.6...v0.16.7) – 01/10/2025
+
+### Fixed
+- Fixed re-registration problem in the service registry.
+### Changed
+- Read the Settings in the `__init__.py` files where possible. Do not spread Settings in all modules of a package.
+
+## [0.16.6](https://github.com/IvS-KULeuven/cgse/compare/v0.16.5...v0.16.6) – 30/09/2025
+
+### Fixed
+- Fixed timeouts for Proxy (sub)classes to seconds instead of milliseconds. We strive to have all timeout in seconds and only convert to milliseconds when needed for a library call.
+
+## [0.16.5](https://github.com/IvS-KULeuven/cgse/compare/v0.16.4...v0.16.5) – 29/09/2025
+
+### Changed
+- The service type for the notification hub is now `NH_CS` instead of `NOTIFY_HUB`.
+- Remove the leading dot '`.`' from all startup log filenames. Startup log files are log files per `cgse` subcommand that are located in the `LOG_FILE_LOCATION`. You will find a log file there for the `start` and the `stop` for each core service or device control server.
+
+## [0.16.4](https://github.com/IvS-KULeuven/cgse/compare/v0.16.3...v0.16.4) – 29/09/2025
+
+### Added
+- Added the `bool_env()` function in `env.py`.
+### Changed
+- The listeners functionality has been transferred to the notification hub and services subscribe to this notification service.
+- Log messages to the `general.log` file now contain the logger name.
+### Removed
+- Remove the listener notification from the configuration manager. 
+- Remove listener registration from the storage manager and the process manager.
+
+## [0.16.3](https://github.com/IvS-KULeuven/cgse/compare/v0.16.2...v0.16.3) – 19/09/2025
+
+### Fixed
+- Fixed a circular import problem in `system.py`.
+
+## [0.16.2](https://github.com/IvS-KULeuven/cgse/compare/v0.16.1...v0.16.2) – 19/09/2025
+
+### Changed
+- The output of startup scripts is now redirected to the log location.
+
+## [0.16.1](https://github.com/IvS-KULeuven/cgse/compare/v0.16.0...v0.16.1) – 19/09/2025
+
+### Changed
+- Use the `get_endpoint()` function in Proxy subclasses.
+- Define constants from settings with proper defaults.
+- Cleanup port numbers for core services in Settings. All core services now have a fixed port number, which can be 
+  overwritten in the local settings file.
+- When `port == 0` use the service registry to get the endpoint.
+
+## [0.16.0](https://github.com/IvS-KULeuven/cgse/compare/v0.15.1...v0.16.0) – 17/09/2025
+
+### Added
+- Added a `deregister` subcommand to the service registry. Usage: `cgse reg deregister <SERVICE_TYPE>`.
+### Fixed
+- Fixed proper sorting of cgse subcommands.
+- Fixed port numbers for core services.
+### Changed
+- Proxies now handle fixed port numbers properly.
+- Renamed `cgse` subcommands `registry` →  `reg`, `notify` →  `not`.

{cgse-0.16.14 → cgse-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgse
-Version: 0.16.14
+Version: 0.17.0
 Summary: Generic Common-EGSE: Commanding and monitoring lab equipment
 Author: IvS KU Leuven
 Maintainer-email: Rik Huygen <rik.huygen@kuleuven.be>, Sara Regibo <sara.regibo@kuleuven.be>
@@ -10,6 +10,7 @@ Requires-Dist: cgse-common
 Requires-Dist: cgse-core
 Requires-Dist: cgse-tools
 Requires-Dist: marimo>=0.17.0
+Requires-Dist: pandas-stubs==2.3.2.250926
 Requires-Dist: rich>=13.9.4
 Requires-Dist: tomlkit>=0.13.2
 Description-Content-Type: text/markdown
@@ -36,12 +37,14 @@ We have the following generic packages:
 - `cgse-tools`: Tools for the `cgse` command.
 - `symetrie-hexapod`: The Symétrie Hexapod drivers. We put this in the generic folder because it is a generic device driver that can be used by different projects.
 - `keithley-tempcontrol`: The DAQ6510 data acquisition and logging multimeter from Keithley.
+- `lakeshore-tempcontrol`: The LakeShore Model 336 Temperature Controller.
 
 We have the following project specific packages:
 
 - `plato-spw`: The PLATO SpaceWire drivers.
 - `plato-fits`: The PLATO FITS plugins.
 - `plato-hdf5`: The PLATO HDF5 plugins.
+- `ariel-tcu`: The Telescope Control Unit for the ARIEL spacecraft
 
 # Installation
 
@@ -56,6 +59,6 @@ $ pip install cgse
 Always install in a virtual environment or use `uv`:
 
 ```shell
-$ uv venv
+$ uv venv --python 3.12
 $ uv pip install cgse
 ```

{cgse-0.16.14 → cgse-0.17.0}/README.md

@@ -20,12 +20,14 @@ We have the following generic packages:
 - `cgse-tools`: Tools for the `cgse` command.
 - `symetrie-hexapod`: The Symétrie Hexapod drivers. We put this in the generic folder because it is a generic device driver that can be used by different projects.
 - `keithley-tempcontrol`: The DAQ6510 data acquisition and logging multimeter from Keithley.
+- `lakeshore-tempcontrol`: The LakeShore Model 336 Temperature Controller.
 
 We have the following project specific packages:
 
 - `plato-spw`: The PLATO SpaceWire drivers.
 - `plato-fits`: The PLATO FITS plugins.
 - `plato-hdf5`: The PLATO HDF5 plugins.
+- `ariel-tcu`: The Telescope Control Unit for the ARIEL spacecraft
 
 # Installation
 
@@ -40,6 +42,6 @@ $ pip install cgse
 Always install in a virtual environment or use `uv`:
 
 ```shell
-$ uv venv
+$ uv venv --python 3.12
 $ uv pip install cgse
 ```

{cgse-0.16.14 → cgse-0.17.0}/docs/dev_guide/coding_style.md

@@ -8,13 +8,14 @@ The following sections will give the most used conventions with a few examples o
 
 ## TL;DR
 
-| Type | Style | Example |
-|------|-------|---------|
-| Classes | CapWords | ProcessManager, ImageViewer, CommandList, Observation, MetaData |
-| Methods & Functions | lowercase with underscores | get_value, set_mask, create_image |
-| Variables | lowercase with underscores | key, last_value, model, index, user_info |
-| Constants | UPPERCASE with underscores | MAX_LINES, BLACK, COMMANDING_PORT |
-| Modules & packages | lowercase **no** underscores | dataset, commanding, multiprocessing |
+| Type                | Style                        | Example                                                                   |
+|---------------------|------------------------------|---------------------------------------------------------------------------|
+| Language            | American Standard English    | Color (~~Colour~~), initialize (~~initialise~~), center (~~centre~~), ... |
+| Classes             | CapWords                     | ProcessManager, ImageViewer, CommandList, Observation, MetaData           |
+| Methods & Functions | lowercase with underscores   | get_value, set_mask, create_image                                         |
+| Variables           | lowercase with underscores   | key, last_value, model, index, user_info                                  |
+| Constants           | UPPERCASE with underscores   | MAX_LINES, BLACK, COMMANDING_PORT                                         |
+| Modules & packages  | lowercase **no** underscores | dataset, commanding, multiprocessing                                      |
 
 ## General
 
@@ -31,6 +32,10 @@ The following sections will give the most used conventions with a few examples o
     you will have to replace that text AND the brackets with your own text. As an example,
     if you see `--prompt <venv name>`, replace this with something like `--prompt cgse-venv`.  
 
+## Language
+
+The code and documentation shall be written in American Standard English for consistency and to avoid confusion when 
+searching for terms like "color" rather than "colour."
 
 ## Classes
 
@@ -83,21 +88,21 @@ Use simple words for modules, preferably just one word like `datasets` or `comma
 * Never use the form `from <module> import *`
 * Always use absolute imports in scripts
 
-Be careful that you do not name any modules the same as a module in the Python standard library. This can result in strange effects and may result in an `AttributeError`. Suppose you have named a module `math` in the `egse` directory and it is imported and used further in the code as follows:
+Be careful that you do not name any modules the same as a module in the Python standard library. This can result in strange effects and may result in an `AttributeError`. Suppose you have named a module `math` in the `egse` directory, and it is imported and used further in the code as follows:
 
 ```python
 from egse import math
 
 # in some expression further down the code you might use
 
-math.exp(a)
+math.exp(2)
 ```
 
 This will result in the following runtime error:
 
 ```text
 File "some_module.py", line 8, in <module>
-  print(math.exp(a))
+  print(math.exp(2))
 AttributeError: module 'egse.math' has no attribute 'exp'
 ```
 

cgse-0.17.0/docs/dev_guide/dotenv.md

@@ -0,0 +1,38 @@
+# Using dotenv
+
+The `cgse` command and subcommands make use of `dotenv`. The package loads environment variables from a `.env` file into
+your application's environment (`os.environ`). The idea is to store sensitive data like API keys, database passwords, or
+configuration settings in the `.env` file. This file stays local on your machine and is ignored by git making your
+project more secure. At the start of an application, call `load_dotenv()` and then access variables using
+`os.getenv('KEY')` throughout your code.
+
+The typical workflow is: create a `.env` file with your environment variables in your project root or in your 
+working directory, add `.env` to the `.gitignore`, commit a `.env.example` template (with dummy values) so other 
+developers know what variables are needed, and call `load_dotenv()` at the top of your main entry point before 
+accessing any environment variables. In production, you usually skip the `.env` file entirely and set real 
+environment variables through your hosting platform.
+
+!!! note 
+    The `load_dotenv()` function will **not overwrite** existing environment variables in `os.environ`. This means
+    environment variables already set in your shell or system take precedence over values in your `.env` file. 
+    To override this behavior and force `.env` values to take priority, use `load_dotenv(override=True)`.
+
+!!! Warning
+    Since the CGSE is a package that is used by and installed by other packages, the CGSE command loads the `.env` from
+    your current working directory instead of the location of the executing script. Otherwise, it would always look 
+    into the folder where the `cgse.py` script is located and that is probably not what you want.
+
+Below, we have summarised some basic know-hows for using dotenv:
+
+- place the `.env` file at the root location of your project or in your current working directory. 
+  When you are developing for the CGSE, use the top-level folder of the monorepo. Please note that 
+  the `load_dotenv()` function searches for a `.env` file in the current folder, the parent folder 
+  up until it hits your home directory.
+- the format to use for the environment variables is `KEY=VALUE`.
+- do not use quotes, unless the VALUE contains spaces.
+- do not use the _`export`_ statement (the `.env` files are not shell scripts).
+- add a comment after a hash character: '`#`'
+- call the `load_dotenv()` function at the top of your entry point file or app, right after the imports.
+- Call the `load_dotenv()` function only once at application startup, not in every module.
+- You might want to consider calling `load_dotenv(find_dotenv(usecwd=True))` instead
+- Do not call the function in library code.

{cgse-0.16.14 → cgse-0.17.0}/docs/getting_started.md

@@ -2,7 +2,8 @@ All you need to get started using and building the CGSE.
 
 ## Requirements
 
-- Python 3.10.x (we do not yet support higher versions, but are working to extend the list)
+- Python 3.10.x (although we know at least the `cgse-common` works with Python versions up to 3.13, we do not yet 
+  fully support higher versions, but are working to extend the list)
 - macOS or Linux
 
 ## Virtual environment

{cgse-0.16.14 → cgse-0.17.0}/docs/user_guide/cli.md

@@ -18,6 +18,7 @@ The _Commands_ section lists the `cgse` commands that are not linked to a core s
 
 The _Core Command_ section lists the sub-command for each of the core services, use `core` when you want to 
 start/stop all core services in one go. The core services are:
+
 - **reg** the service registry for all core services and control servers
 - **not** the notification server that collects and published all events
 - **log** the log server that collects and stores all log messages
@@ -27,6 +28,7 @@ start/stop all core services in one go. The core services are:
 
 The _Device Command_ section lists the sub-commands for all device packages that have been installed and have a 
 plugin for the `cgse` command. In the `cgse` package, the following devices are available:
+
 - **DAQ6510** the Keithley Data Acquisition and Logging Multimeter
 - **LakeShore336** the LakeShore Temperature Controller
 - **puna**, **joran**, **zonda** the Symétrie positioning Hexapods

cgse-0.17.0/docs/user_guide/env.md

@@ -0,0 +1,69 @@
+# The Environment
+
+The CGSE uses a number of environment variables that you will need to set in order to properly run services. There 
+are currently two mandatory environment variables:
+
+- **PROJECT**: which is the name of your project, use ALL_CAPS to set its value. The value of this environment 
+  variable is used as a prefix for other known environment variable specific for your project. For instance, when 
+  your PROJECT=ARIEL, you will have a number of environment variables starting with `ARIEL_`, e.g. 
+  `ARIEL_DATA_STORAGE_LOCATION`.
+- **SITE_ID**: this is the name of the site or lab where the CGSE is running. The site id makes your tests and 
+  environment unique. Suppose you have a laboratory with three test setupt, you can distinct site ids for each of 
+  these setups. The `SITE_ID` will be used to assemble the path location of your storage, database, configurations 
+  files, etc.
+
+Besides the mandatory environment variables, the CGSE also maintains a number of _known_ environment variables. When 
+these variables are not set, they will be determined from defaults.
+
+**`{PROJECT}_DATA_STORAGE_LOCATION`**
+
+:   This directory contains all the data files that are generated and filled by 
+    the control servers and other components. The folder is the root folder for all 
+    data from your test equipment, the SUT (system under test) and
+    all site ids.
+
+**`{PROJECT}_CONF_DATA_LOCATION`**: 
+
+:   This directory is the root folder for all the Setups of the site, the site is part
+    of the name. By default, this directory is located in the overall data storage folder.
+
+**`{PROJECT}_LOG_FILE_LOCATION`**: 
+
+:   This directory contains the log files with all messages that were sent to the
+    logger control server. The log files are rotated on a daily basis at midnight UTC.
+    By default, this directory is also located in the overall data storage folder, such
+    that log files are kept per project and site id.
+
+**`{PROJECT}_LOCAL_SETTINGS`**: 
+
+:   This file is used for local site-specific settings. When the environment
+    variable is not set, no local settings will be loaded. By default, the name 
+    of this file is assumed to be 'local_settings.yaml'.
+
+You can inspect your current environment with the command given below. The example is for 
+a project called ARIEL and a test setup in the vacuum lab.
+
+```shell
+➜ cgse show env
+Environment variables:
+    PROJECT = ARIEL
+    SITE_ID = VACUUM_LAB
+    ARIEL_DATA_STORAGE_LOCATION = ~/data/ARIEL/VACUUM_LAB
+    ARIEL_CONF_DATA_LOCATION = ~/data/ARIEL/VACUUM_LAB/conf
+    ARIEL_CONF_REPO_LOCATION = not set
+    ARIEL_LOG_FILE_LOCATION = ~/data/ARIEL/VACUUM_LAB/log
+    ARIEL_LOCAL_SETTINGS = ~/data/ARIEL/VACUUM_LAB/local_settings.yaml
+
+Generated locations and filenames
+    get_data_storage_location() = '~/data/ARIEL/VACUUM_LAB'
+    get_conf_data_location() = '~/data/ARIEL/VACUUM_LAB/conf'
+    get_conf_repo_location() = None  ⟶ ERROR: The configuration repository location doesn't exist!
+    get_log_file_location() = '~/data/ARIEL/VACUUM_LAB/log'
+    get_local_settings_path() = '~/data/ARIEL/VACUUM_LAB/local_settings.yaml'
+
+use the '--full' flag to get a more detailed report, '--doc' for help on the variables.
+```
+!!! note
+
+    Note that the environment variables can start with the tilde `~` character which will be expanded into the 
+    user's home folder when used.

{cgse-0.16.14 → cgse-0.17.0}/libs/cgse-common/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cgse-common"
-version = "0.16.14"
+version = "0.17.0"
 description = "Software framework to support hardware testing"
 authors = [
     {name = "IvS KU Leuven"}
@@ -48,7 +48,6 @@ dependencies = [
 
 [project.scripts]
 cgse = 'cgse_common.cgse:app'
-monitor = "egse.monitoring:app"
 
 [project.entry-points."cgse.version"]
 cgse-common = 'egse.version:get_version_installed'
@@ -61,7 +60,7 @@ pythonpath = "src"
 testpaths = ["tests"]
 addopts = "-ra --cov --cov-branch --cov-report html"
 log_cli = true
-log_cli_level = "INFO"
+log_cli_level = "DEBUG"
 filterwarnings = [
     "ignore::DeprecationWarning"
 ]

{cgse-0.16.14 → cgse-0.17.0}/libs/cgse-common/src/cgse_common/cgse.py

@@ -72,7 +72,7 @@ class SortedCommandGroup(TyperGroup):
         commands = super().list_commands(ctx)
 
         # Define priority commands in specific order
-        priority_commands = ["init", "version", "show", "top", "core", "reg", "not", "log", "cm", "sm", "pm"]
+        priority_commands = ["init", "version", "show", "top", "core", "reg", "log", "nh", "cm", "sm", "pm"]
 
         # Custom sort:
         # First the priority commands in the given order (their index)
@@ -175,6 +175,10 @@ def main(ctx: typer.Context, verbose: bool = False):
     - inspect, configure, monitor the core services and device control servers.
     """
 
+    from egse.env import setup_env
+
+    setup_env()
+
     # This is more of a show-case for using application wide optional arguments and how to pass
     # them into (sub-)commands.
 

{cgse-0.16.14 → cgse-0.17.0}/libs/cgse-common/src/egse/decorators.py

@@ -15,7 +15,6 @@ from typing import Optional
 
 import rich
 
-from egse.settings import Settings
 from egse.system import get_caller_info
 from egse.log import logger
 
@@ -390,6 +389,8 @@ def profile(func):
     if not hasattr(profile, "counter"):
         profile.counter = 0
 
+    from egse.settings import Settings
+
     @functools.wraps(func)
     def wrapper_profile(*args, **kwargs):
         if Settings.profiling():

{cgse-0.16.14 → cgse-0.17.0}/libs/cgse-common/src/egse/device.py

@@ -199,7 +199,7 @@ class DeviceConnectionInterface(DeviceConnectionObservable):
 
 
 class DeviceInterface(DeviceConnectionInterface):
-    """Generic interface for all device classes."""
+    """A generic interface for all device classes."""
 
     @dynamic_interface
     def is_simulator(self) -> bool:
@@ -237,6 +237,7 @@ class DeviceTransport:
         raise NotImplementedError
 
     def read_string(self, encoding="utf-8") -> str:
+        """Reads a bytes object from the instrument and returns it converted into a stripped UTF-8 string."""
         return self.read().decode(encoding).strip()
 
     def trans(self, command: str) -> bytes:
@@ -297,6 +298,11 @@ class AsyncDeviceTransport:
 
         raise NotImplementedError
 
+    async def read_string(self, encoding="utf-8") -> str:
+        """Reads a bytes object from the instrument and returns it converted into a stripped UTF-8 string."""
+        b = await self.read()
+        return b.decode(encoding).strip()
+
     async def trans(self, command: str) -> bytes:
         """
         Send a single command to the device controller and block until a response from the
@@ -389,7 +395,7 @@ class AsyncDeviceConnectionInterface(DeviceConnectionObservable):
 
 
 class AsyncDeviceInterface(AsyncDeviceConnectionInterface):
-    """Generic interface for all device classes."""
+    """A generic interface for all device classes."""
 
     def is_simulator(self) -> bool:
         """Checks whether the device is a simulator rather than a real hardware controller.