Getting Started

Purpose

This guide shows you how to get Yamcs up and running with Maven. Maven is a popular Java build tool available in most package repositories.

The base features of Yamcs do not require Java knowledge, however as soon as you dive into custom data links and other extensions, you will need a build tool anyway.

Prerequisites

  • Java 11
  • Maven
  • Linux x64 or macOS

Project Setup

Clone the quickstart repository to kickstart a minimal Yamcs project:

git clone https://github.com/yamcs/quickstart.git myproject

This will generate a project structure in the following way:

myproject/
|-- README.md
|-- pom.xml
|-- simulator.py
|-- src
|   `-- main
|       |-- java
|       |   `-- com
|       |       `-- example
|       |           `-- myproject
|       |               `-- MyPacketPreprocessor.java
|       `-- yamcs
|           |-- etc
|           |   |-- processor.yaml
|           |   |-- yamcs.myproject.yaml
|           |   `-- yamcs.yaml
|           `-- mdb
|               `-- xtce.xml
`-- testdata.ccsds
  • Custom Java classes (if any) go into ${project.basedir}/src/main/java/.
  • Yamcs configuration goes into ${project.basedir}/src/main/yamcs/ in subfolders etc/ and mdb/.

The file pom.xml is the entrypoint for subsequent Maven builds. It adds dependencies to the desired Yamcs modules. At least a dependency to yamcs-core is required. yamcs-web is another common dependency that makes Yamcs host a prebuilt copy of the Yamcs web interface.

<dependencies>
  <dependency>
    <groupId>org.yamcs</groupId>
    <artifactId>yamcs-core</artifactId>
    <version>${yamcsVersion}</version>
  </dependency>
  <dependency>
    <groupId>org.yamcs</groupId>
    <artifactId>yamcs-web</artifactId>
    <version>${yamcsVersion}</version>
  </dependency>
  ...
</dependencies>

Running Yamcs

To now run your Yamcs application:

cd myproject/
mvn yamcs:run

By default, Yamcs will run from the target/yamcs/ directory.

View the Yamcs web interface by visiting http://localhost:8090

The homepage shows you the available instances. Each instance corresponds to a separate database with custom Yamcs configuration. In this example we have just a single instance called myproject. In more advanced scenarios, you could use instances to group data by simulation session, mission environment or any other criteria.

If we now navigate to the main page for our myproject instance, we see not much going on.

So let's liven things up a bit by pushing telemetry packets to Yamcs. In another terminal:

python simulator.py

This Python script simulates a space system that emits packets at 1 Hz. Each packets is put in a UDP frame and sent to the port 10015 on localhost. This port is bound to by the udp-in link of Yamcs. You can monitor this link from the Links menu item of the myproject instance. The counter increases with each incoming packet.

Navigate to Telemetry > Parameters to see the individual parameters that are being extracted from the received packets.

Yamcs knows how to decode packets into parameters by applying the definitions contained in a Mission Database (MDB). We can explore the applicable definitions of our example project by navigating to the pages under the MDB menu item:

Configuring Yamcs

Yamcs is configured through a set of Yaml configuration files. Yaml is a popular format, which despite the name similarity, is otherwise unrelated to Yamcs.

The main entrypoint is the file src/main/yamcs/etc/yamcs.yaml

...
dataDir: yamcs-data
instances:
  - myproject
...

The dataDir property specifies the folder where Yamcs will persist data such as received telemetry. In this example we use a relative directory which resolves to target/yamcs/yamcs-data. This means that when we do mvn clean, all of our data will be removed. That may be acceptable for development purposes, but if you want to preserve received data, it's better to use an absolute path somewhere on your file system.

The instances property contains a list of predefined instances that are started by Yamcs. In this example we only require one instance.

For each instance there must be a matching file yamcs.[instance].yaml that contains instance-level configuration instructions. In our example project we have a file yamcs.myproject.yaml

services:
  - class: org.yamcs.archive.XtceTmRecorder
  - class: org.yamcs.archive.ParameterRecorder
  ...

dataLinks:
  - name: udp-in
    class: org.yamcs.tctm.UdpTmDataLink
    args:
      stream: tm_realtime
      port: 10015
  - name: udp-out
    class: org.yamcs.tctm.UdpTcDataLink
    args:
      stream: tc_realtime
      host: localhost
      port: 10025

mdb:
  - type: xtce
    args:
      file: mdb/xtce.xml

...

The services property contains a list of services that activate optional functionalities on this instance. In the example, there are services for recording. If they would not have been specified, Yamcs would only serve realtime data and not archive telemetry.

The dataLinks property contains a list of available data links. Here we use two UDP-based link types that are included in yamcs-core. The link org.yamcs.tctm.UdpTmDataLink listens to TM on the configured port. The link org.yamcs.tctm.UdpTcDataLink sends TC to the configured address.

The mdb property describes how the Mission Database is constructed. The word database is a bit of a misnomer, since Yamcs will build an in-memory instance-level MDB on startup based on the configured components. In this example Yamcs will read all definitions from an XML file in XTCE format. XTCE is a CCSDS Recommended Standard that defines an XSD Schema for validating telemetry and commanding definitions written in XML.

Yamcs supports a few other MDB types as well, and it is even possible to write your own MDB Loader. This is however an advanced topic requiring familiarity with Java. The same goes for many other features of Yamcs. For example, it is possible to extend the default services or data links with your own implementations. The class attribute in the Yaml configuration files indicates a Java-level class, which must be available on the classpath.

Packaging Yamcs

Running through Maven is useful for development and for creating prototypes, but it is not recommended for production environments. Instead bundle Yamcs together with your extensions and configurations in one integrated distribution:

mvn clean package
This uses the bundle goal of the yamcs-maven-plugin as configured in pom.xml
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.yamcs</groupId>
        <artifactId>yamcs-maven-plugin</artifactId>
        <version>1.2.3</version>
        <executions>
          <execution>
            <id>bundle-yamcs</id>
            <phase>package</phase>
            <goals>
              <goal>bundle</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Next Steps

The typical next steps would be to:
  • Replace the simulator.py script with your own data source
  • Configure the appropriate data link(s) for your data source
  • Configure the Mission Database so that it matches your packet structure

For an example of advanced customizations, refer to our development testcase on GitHub.

For scripted access, have a look at the Python API.