Constellation Preview Release 0.6#

We are happy to announce the release of Constellation version 0.6, named Triangulum Australe.

Breaking Changes#

Programs using previous versions of Constellation might not compatible with this version due to the breaking changes to our data transmission protocol.

New Data Transmission Protocol#

In this release, we reworked our data transmission protocol (called CDTP) entirely. This rework was necessary due to performance issues in the maximum data rate in particular for small payload sizes. The new protocol improves the data rate about 10x for small payloads compared to previous version on identical setups.

Data rate comparison between CDTP1 and CDTP2

Attention

As part of this rework, the data transmission API has changed both in the C++ and Python version of the framework:

Changes in the Python Interface#

  • The DataSender and DataReceiver classes have been renamed to TransmitterSatellite and ReceiverSatellite respectively. They can be imported as followed:

    from constellation.core.transmitter_satellite import TransmitterSatellite
    from constellation.core.receiver_satellite import ReceiverSatellite
    from constellation.core.transmitter_satellite import TransmitterSatelliteArgumentParser
    
  • The begin- and end-of-run user dictionaries are now in lower-case, i.e. self.bor and self.eor instead of self.BOR and self.EOR.

  • Previously, data could be sent by putting a tuple in a queue:

    self.data_queue.put((payload, meta))
    

    Now, a data record has to be created to which data blocks are be added before it is sent:

    data_record = self.new_data_record(meta)
    data_record.add_block(payload)
    self.send_data_record(data_record)
    

Changes in the C++ Interface#

The interface in C++ has been changed in a similar manner. The new functions names are:

auto data_record = newDataRecord(1);
data_record.addTag("key", value);
data_record.addBlock(std::move(payload));
sendDataRecord(std::move(data_record));

Changed H5 File Format#

Due to changes in the transmission protocol, the file format in the H5DataWriter satellite was changed. The new file formats for the normal and SWMR modes are described in detail in the satellite documentation.

Interrupt and Failure Functions Changed in C++#

The function signature for the interrupting() and failure() Satellite methods in C++ changed. They now also take an std::string_view as argument containing the reason for the interrupt or failure:

void interrupting(protocol::CSCP::State previous_state, std::string_view reason) override;
void failure(protocol::CSCP::State previous_state, std::string_view reason) override;

New Features#

Satellite Templates#

We made it simpler to create new satellites from scratch by providing template projects, which already have all the necessary files for a satellite as well as CI configurations for GitLab and GitHub. The documentation on how to get started creating a new satellite was also extended in the Application Developer Guide.

Docker Images#

Constellation is now available as Docker image, allowing to run satellites in a container. Details on how to use these new images can be found in the Operator Guide.

Improved Logging in Python#

Logging in Python looks significantly prettier thanks to the use of rich. As a bonus feature, logging of external Python logging is now also formatted nicely without any code change required.

Screenshot of logging with Triangulum Australe

New Await Function in the Python Controller#

The Python Controller now has a await_satellites function which takes a list of canonical satellites and waits until all of those satellites are connected.

Previously, waiting for satellites in a script could be done like this:

while len(constellation.satellites) < n_satellites:
    print("Waiting for satellites...")
    time.sleep(0.5)

Now, this process can be made more reliable by directly specifying the satellites:

ctrl.await_satellites(["Sputnik.s1", "Sputnik.s2"])

Detailed Changelog#

The following changes related to protocols are included in this release:

  • MR!659: Switch to CDTP2 for significant performance improvements

  • MR!874: Move optional header tags to satellite implementation guidelines

The following changes related to satellites are included in this release:

  • MR!833: Metrics of the Spuntik satellite are now registered in the constructor

  • MR!863: Write user-tags from BOR and EOR to file in EudaqNativeWriter

The following improvements for the C++ version are included in this release:

  • MR!785: The awaitState() method of the Controller now can take an additional argument to ensure that a satellite actually reconfigured

  • MR!807: Add mimalloc as possible memory allocator in addition to jemalloc

  • MR!825: Add reason to interrupt and failure methods

  • MR!834/MR!850: Allow registering lambdas as CSCP commands

  • MR!841: Fix STAT macro not working with arbitrary types

  • MR!842: Print more information on executable when using --version

  • MR!847: Allow not building any satellites

  • MR!888: More consistent quoting using a new utils::quote function

The following improvements for the Python version are included in this release:

  • MR!845: Fix log level needing to be provided in upper case

  • MR!846: Rename of the Python CHIRP components to better reflect the use of multicast

  • MR!870: Add new await_satellites function to wait for specific satellites

  • MR!871: Fix TypeError: unsupported operand type(s) for +=: 'NoneType' and 'str'

  • MR!872: Improve logging and move to rich

  • MR!877: Implement marking runs as degraded

  • MR!890: Fix race conditions in Controller and network discovery

The following miscellaneous changes are included in this release:

  • MR!646: Satellites in the Constellation GitLab group are now displayed on the website

  • MR!800: Add more sequence diagrams for protocol

  • MR!826: Document and harmonize log topics

  • MR!861: Document satellite templates

  • MR!886: Disable warning when building with build_gui=none

  • MR!887: Add GitHub actions with basic CI pipeline

  • MR!856/MR!891: Add Docker images

  • MR!889: Add how-to for using satellites as systemd services

  • MR!901: Update CI matrix

  • MR!902: Use any address for receiving endpoint in CHIRP

Notes#

The software is publicly available under the EUPL-1.2 from the DESY GitLab repository. In addition, the Python version is available on PyPI and the C++ version is available on Flathub for Linux.

It should be noted that this is a preview release and some interfaces and protocols might change until the first official major release.