Timeline¶

Conceptual Model¶

• View: A top-level container used to group multiple bands together for a specific purpose (e.g., “Daily Operations”).

• Band: A horizontal lane within a view. Bands can be of different types and act as filters or containers for items.

• Item: The actual data points on the timeline. These are often activities (like those defined in Activities) or simple events with a start time and duration.

Timeline Items¶

Within the Yamcs timeline, Items are the fundamental building blocks of a schedule. While they all share common properties like tags, durations, and start conditions, they differ in how they are executed and their intended purpose.

Here is a breakdown of the different kinds of items:

• A TimelineActivity is an executable item that carries a specific payload (an Activity definition). It represents a concrete action that Yamcs can perform automatically, such as sending a Telecommand, running a Python script, or triggering a Stack. When the start condition is met and auto_start is enabled, Yamcs handles the execution logic internally.

• A TimelineTask represents a manual or user-driven action. Unlike activities, tasks are usually “placeholders” for work to be performed by an operator.

  • Manual Lifecycle: They have auto_start disabled by default, meaning an operator must manually signal when the task has started and finished via the Web UI or API.

  • Planning: They are primarily used for coordination and ensuring that human-in-the-loop procedures are accounted for within the mission timeline.

• A TimelineEvent is typically a passive marker. It is used to denote a point in time or a span of time that is significant for the mission—such as an “Orbital Sunset” or a “Communication Window”, but does not involve the execution of any activities.

Create some items (any of subclasses TimelineEvent, TimelineTask or TimelineActivity). Bands of type ItemBand will display items with matching tags:

from datetime import datetime, timedelta, timezone

from yamcs.client import TimelineEvent

now = datetime.now(tz=timezone.utc)

for i in range(10):
    item = TimelineEvent(
        name=f"A {i + 1}",
        start=now + timedelta(seconds=i * 7200),
        duration=timedelta(seconds=3600),
        tags=["group-a"],
    )
    timeline.save_item(item)

    item = TimelineEvent(
        name=f"B {i + 1}",
        start=now + timedelta(seconds=3600 + (i * 7200)),
        duration=timedelta(seconds=3600),
        tags=["group-b"],
    )
    timeline.save_item(item)

Chaining Activities¶

Yamcs supports relative scheduling through Predecessors. This allows you to chain items together so that an activity only begins once its predecessor has met a specific condition (e.g., successful completion).

When creating a TimelineActivity or TimelineTask, the start argument can accept a Trigger instead of a fixed datetime. There are four primary trigger types:

• OnSuccess: Starts the item only if the predecessor completes successfully.

• OnFailure: Starts the item only if the predecessor fails.

• OnCompletion: Starts the item regardless of whether the predecessor succeeded or failed.

• OnStart: Starts the item as soon as the predecessor begins (parallel execution).

from yamcs.client import (
    CommandActivity,
    OnSuccess,
    ScriptActivity,
    TimelineActivity,
)

# Define the first activity (The Predecessor)
item_a = TimelineActivity(
    name="Data Dump",
    start=datetime.now(),
    activity=CommandActivity(command="/SPACECRAFT/DUMP_DATA"),
)

# Define the second activity, triggered by the success of the first
item_b = TimelineActivity(
    name="Cleanup",
    start=OnSuccess(item_a),
    activity=ScriptActivity(script="cleanup.sh"),
)

# Save both to the timeline
timeline.save_item(item_a)
timeline.save_item(item_b)

Auto-Start¶

• If auto_start=True, Yamcs will automatically trigger the execution logic the moment the relationship conditions are satisfied. This is enabled by default for TimelineActivity instances.

• If auto_start=False, Yamcs will wait for a user to manually “Start” the item in the Web UI, unless specifically configured otherwise. This is the default for TimelineTask.

TimelineEvent classes do not have such a configuration option: they always start on time.

Bands¶

A Band is a horizontal lane on the timeline. It defines what data is displayed and how that data is visualized. Bands do not “own” items; instead, they act as filters or data providers.

The timeline supports several specialized band types:

• TimeRuler: Displays absolute time, formatted in a timezone of choice.

• ItemBand: The most common band. It displays Item resources (Activities, Tasks, Events) based on matching tags.

• CommandBand: Automatically displays telecommands that have been issued to the system, providing a historical record of commanding.

• ParameterPlot: Plots the values of a numeric parameter.

• ParameterStateBand: Visualizes the state of a specific telemetry parameter over time (e.g., “On/Off” or “Nominal/Warning”).

• Spacer: Insert vertical gap between surrounding bands.

Create a few Band objects, matching the tags of the previously created timeline events.

from yamcs.client import ItemBand, TimeRuler

utc_time = TimeRuler()
utc_time.name = "UTC"
timeline.save_band(utc_time)

local_time = TimeRuler()
local_time.name = "Local"
local_time.timezone = "Europe/Brussels"
timeline.save_band(local_time)

group_a = ItemBand()
group_a.name = "Group A"
group_a.tags = ["group-a"]
timeline.save_band(group_a)

group_b = ItemBand()
group_b.name = "Group B"
group_b.tags = ["group-b"]
group_b.item_border_color = "#ff4500"
group_b.item_background_color = "#ffa500"
timeline.save_band(group_b)

Views¶

A View is a top-level organizational container. It represents a specific layout that a user opens in the Yamcs Web UI. A View consists of an ordered list of Bands:

Create a View showing all bands:

from yamcs.client import View

view = View()
view.name = "Two groups"
view.bands = [utc_time, local_time, group_a, group_b]
timeline.save_view(view)

Create a view with ParameterStateBand and ParameterPlot bands:

from yamcs.client import (
    ParameterPlot,
    ParameterStateBand,
    RangeMapping,
    Trace,
    ValueMapping,
    View,
)

states = ParameterStateBand()
states.name = "State example"
states.parameter = "/YSS/SIMULATOR/BatteryVoltage2"
states.mappings.append(RangeMapping(40, 56, label="LOW", color="#ff0000"))
states.mappings.append(ValueMapping(57, label="OK", color="#00ff00"))
states.mappings.append(RangeMapping(58, 70, label="HIGH", color="#ff0000"))
timeline.save_band(states)

plot = ParameterPlot()
plot.name = "Plot example"
plot.maximum = 65
trace = Trace(
    parameter="/YSS/SIMULATOR/BatteryVoltage2",
    line_color="#ffff00",
    fill=True,
)
plot.traces.append(trace)
timeline.save_band(plot)

view = View()
view.name = "Parameter examples"
view.bands = [states, plot]
timeline.save_view(view)

Reference¶