Client¶

Note

ProcessorClient instances are usually created via YamcsClient.get_processor():

from yamcs.client import YamcsClient

client = YamcsClient('localhost:8090')
processor = client.get_processor(instance='simulator',
                                 processor='realtime')
# ...

class yamcs.client.ProcessorClient(ctx: Context, instance: str, processor: str)¶

Client object that groups operations linked to a specific processor.

acknowledge_alarm(alarm: str, sequence_number: int, comment: Optional[str] = None)¶

Acknowledges a specific alarm.

Parameters:

alarm – Alarm name
sequence_number – Sequence number
comment – Optional comment to associate with the state change.

clear_alarm(alarm: str, sequence_number: int, comment: Optional[str] = None)¶

Clear an alarm.

Note

If the reason that caused the alarm is still present, a new alarm instance will be generated.

Parameters:

alarm – Alarm name
sequence_number – Sequence number
comment – Optional comment to associate with the state change.

clear_alarm_ranges(parameter: str)¶: Removes all alarm limits for the specified parameter.

clear_calibrators(parameter: str)¶: Removes all calibrators for the specified parameter.

create_alarm_subscription(on_data: Optional[Callable[[AlarmUpdate], None]] = None, timeout: float = 60) → AlarmSubscription¶

Create a new alarm subscription.

Parameters:

on_data – Function that gets called with AlarmUpdate updates.
timeout – The amount of seconds to wait for the request to complete.

Returns:

A Future that can be used to manage the background websocket subscription.

create_command_connection(on_data: Optional[Callable[[CommandHistory], None]] = None, timeout: float = 60) → CommandConnection¶

Creates a connection for issuing multiple commands and following up on their acknowledgment progress.

Note

This is a convenience method that merges the functionalities of create_command_history_subscription() with those of issue_command().

Parameters:

on_data – Function that gets called with CommandHistory updates. Only commands issued from this connection are reported.
timeout – The amount of seconds to wait for the request to complete.

Returns:

Future that can be used to manage the background websocket subscription

create_command_history_subscription(on_data: Optional[Callable[[CommandHistory], None]] = None, timeout: float = 60) → CommandHistorySubscription¶

Create a new command history subscription.

Parameters:

on_data – Function that gets called with CommandHistory updates.
timeout – The amount of seconds to wait for the request to complete.

Returns:

Future that can be used to manage the background websocket subscription.

create_container_subscription(containers: Union[str, List[str]], on_data: Optional[Callable[[ContainerData], None]] = None, timeout: float = 60) → ContainerSubscription¶

Create a new container subscription.

Parameters:

containers – Container names.
on_data – Function that gets called with ContainerData updates.
timeout – The amount of seconds to wait for the request to complete.

Returns:

A Future that can be used to manage the background websocket subscription.

create_packet_subscription(on_data: Callable[[Packet], None], stream: Optional[str] = None, timeout: float = 60) → WebSocketSubscriptionFuture¶

Create a new packet subscription.

Parameters:

on_data – Function that gets called with Packet updates.
stream – Stream to subscribe to.
timeout – The amount of seconds to wait for the request to complete.

Returns:

A Future that can be used to manage the background websocket subscription.

create_parameter_subscription(parameters: Union[str, List[str]], on_data: Optional[Callable[[ParameterData], None]] = None, abort_on_invalid: bool = True, update_on_expiration: bool = False, send_from_cache: bool = True, timeout: float = 60) → ParameterSubscription¶

Create a new parameter subscription.

Parameters:

parameters – Parameter names (or aliases).
on_data – Function that gets called with ParameterData updates.
abort_on_invalid – If True an error is generated when invalid parameters are specified.
update_on_expiration – If True an update is received when a parameter value has become expired. This update holds the same value as the last known valid value, but with status set to EXPIRED.
send_from_cache – If True the last processed parameter value is sent from parameter cache. When False only newly processed parameters are received.
timeout – The amount of seconds to wait for the request to complete.

Returns:

A Future that can be used to manage the background websocket subscription.

get_parameter_value(parameter: str, from_cache: bool = True, timeout: float = 10) → Optional[ParameterValue]¶

Retrieve the current value of the specified parameter.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
from_cache – If False this call will block until a fresh value is received on the processor. If True the server returns the latest value instead (which may be None).
timeout – The amount of seconds to wait for a fresh value. (ignored if from_cache=True).

get_parameter_values(parameters: List[str], from_cache: bool = True, timeout: float = 10) → List[Optional[ParameterValue]]¶

Retrieve the current value of the specified parameter.

Parameters:

parameters – List of parameter names. These may be fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
from_cache – If False this call will block until fresh values are received on the processor. If True the server returns the latest value instead (which may be None).
timeout – The amount of seconds to wait for a fresh values (ignored if from_cache=True).

Returns:

A list that matches the length and order of the requested list of parameters. Each entry contains either the returned parameter value, or None.

issue_command(command: str, args: Optional[Mapping[str, Any]] = None, *, dry_run: bool = False, comment: Optional[str] = None, verification: Optional[VerificationConfig] = None, stream: Optional[str] = None, extra: Optional[Mapping[str, Any]] = None, sequence_number: Optional[int] = None) → IssuedCommand¶

Issue the given command

Parameters:

command – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
args – Named arguments (if the command requires any).
dry_run – If True the command is not actually issued. This can be used to test if the server would generate errors when preparing the command (for example because an argument is missing).
comment – Comment attached to the command.
verification – Overrides to the default verification handling of this command.
stream –
Override the stream on which the command should be sent out.

New in version 1.9.6.
extra – Extra command options for interpretation by non-core extensions (custom preprocessor, datalinks, command listeners). Note that Yamcs will refuse command options that it does now know about. Extensions should therefore register available options.
sequence_number –
Sequence number of this command. This is used to determine unicity of commands at the same time and coming from the same origin. If not set Yamcs will automatically assign a sequential number as if every submitted command is unique.

New in version 1.9.0.

Returns:

An object providing access to properties of the newly issued command.

list_alarms(start: Optional[datetime] = None, stop: Optional[datetime] = None) → Iterable[Alarm]¶

Lists the active alarms.

Remark that this does not query the archive. Only active alarms on the current processor are returned.

Parameters:

start – Minimum trigger time of the returned alarms (inclusive)
stop – Maximum trigger time of the returned alarms (exclusive)

reset_alarm_ranges(parameter: str)¶: Reset all alarm limits for the specified parameter to their original MDB value.

reset_algorithm(parameter: str)¶

Reset the algorithm text to its original definition from MDB

Parameters:: parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.

reset_calibrators(parameter: str)¶: Reset all calibrators for the specified parameter to their original MDB value.

run_script(script: str, args: Optional[Union[str, List[str]]] = None)¶

Run a script.

The script has access to the environment variables YAMCS_URL, YAMCS_API_KEY, YAMCS_INSTANCE and YAMCS_PROCESSOR.

Parameters:

script – This should be the relative path to an an executable file in one of the search locations. When unconfigured, the default search location is etc/scripts/ relative to the Yamcs working directory.
args – Optional script arguments, passed verbatim in the command line.

set_alarm_range_sets(parameter: str, sets: List[AlarmRangeSet])¶

Apply an ordered list of alarm range sets for the specified parameter. This replaces existing alarm sets (if any).

Each AlarmRangeSet may have a context, which indicates when its effects may be applied. Only the first matching set is applied.

An AlarmRangeSet with context None represents the default set of alarm ranges. There can be only one such set, and it is always applied at the end when no other set of contextual ranges is applicable.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
sets – List of range sets (either contextual or not)

set_algorithm(parameter: str, text: str)¶

Change an algorithm text. Can only be peformed on JavaScript or Python algorithms.

Parameters:

text – New algorithm text (as it would appear in excel or XTCE)
parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.

set_calibrators(parameter: str, calibrators: List[Calibrator])¶

Apply an ordered set of calibrators for the specified parameter. This replaces existing calibrators (if any).

Each calibrator may have a context, which indicates when it its effects may be applied. Only the first matching calibrator is applied.

A calibrator with context None is the default calibrator. There can be only one such calibrator, and is always applied at the end when no other contextual calibrator was applicable.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
calibrators – List of calibrators (either contextual or not)

set_default_alarm_ranges(parameter: str, watch: Optional[Tuple[Optional[float], Optional[float]]] = None, warning: Optional[Tuple[Optional[float], Optional[float]]] = None, distress: Optional[Tuple[Optional[float], Optional[float]]] = None, critical: Optional[Tuple[Optional[float], Optional[float]]] = None, severe: Optional[Tuple[Optional[float], Optional[float]]] = None, min_violations: int = 1)¶

Generate out-of-limit alarms for a parameter using the specified alarm ranges.

This replaces any previous default alarms on this parameter.

Note

Contextual range sets take precedence over the default alarm ranges. See set_alarm_range_sets() for setting contextual range sets.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
watch – Range expressed as a tuple (lo, hi) where lo and hi are assumed exclusive.
warning – Range expressed as a tuple (lo, hi) where lo and hi are assumed exclusive.
distress – Range expressed as a tuple (lo, hi) where lo and hi are assumed exclusive.
critical – Range expressed as a tuple (lo, hi) where lo and hi are assumed exclusive.
severe – Range expressed as a tuple (lo, hi) where lo and hi are assumed exclusive.
min_violations – Minimum violations before an alarm is generated.

set_default_calibrator(parameter: str, type: Optional[str], data)¶

Apply a calibrator while processing raw values of the specified parameter. If there is already a default calibrator associated to this parameter, that calibrator gets replaced.

Note

Contextual calibrators take precedence over the default calibrator See set_calibrators() for setting contextual calibrators.

Two types of calibrators can be applied:

Polynomial calibrators apply a polynomial expression of the form: y = a + bx + cx^2 + ….

The data argument must be an array of floats [a, b, c, ...].
Spline calibrators interpolate the raw value between a set of points which represent a linear curve.

The data argument must be an array of [x, y] points.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
type – One of polynomial or spline.
data – Calibration definition for the selected type.

set_parameter_value(parameter: str, value: Any, generation_time: Optional[datetime] = None, expires_in: Optional[float] = None)¶

Sets the value of the specified parameter.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
value – The value to set.
generation_time – Generation time of the value. If unset, Yamcs will assign the generation time.
expires_in –
How long before this value expires (in fractional seconds). If unset, the value does not expire.

New in version 1.9.1: Compatible with Yamcs 5.8.8 onwards

set_parameter_values(values: Mapping[str, Any], generation_time: Optional[datetime] = None, expires_in: Optional[float] = None)¶

Sets the value of multiple parameters.

Values are specified with their native Python types. If you need to customize individual value properties, use ValueUpdate instead.

The method arguments generation_time and expires_in can be used to specify a custom generation time for all values at once. This has lower priority than value-specific properties.

If no generation time is specified at all, Yamcs will determine one.

Parameters:

values – Values keyed by parameter name. This name can be either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
generation_time – Generation time of the values.
expires_in –
How long before this value expires (in fractional seconds).

New in version 1.9.1: Compatible with Yamcs 5.8.8 onwards

shelve_alarm(alarm: str, sequence_number: int, comment: Optional[str] = None)¶

Shelve an alarm.

Parameters:

alarm – Alarm name
sequence_number – Sequence number
comment – Optional comment to associate with the state change.

unshelve_alarm(alarm: str, sequence_number: int, comment: Optional[str] = None)¶

Unshelve an alarm.

Parameters:

alarm – Alarm name
sequence_number – Sequence number
comment – Optional comment to associate with the state change.

class yamcs.client.CommandConnection(manager, tmtc_client: ProcessorClient)¶

Bases: WebSocketSubscriptionFuture

Local object providing access to the acknowledgment progress of command updates.

Only commands issued from this object are monitored.

Initializes the future. Should not be called by clients.

issue(command: str, args: Optional[Mapping[str, Any]] = None, *, dry_run: bool = False, comment: Optional[str] = None, verification: Optional[VerificationConfig] = None, stream: Optional[str] = None, extra: Optional[Mapping[str, Any]] = None, sequence_number: Optional[int] = None) → MonitoredCommand¶

Issue the given command

Parameters:

command – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
args – Named arguments (if the command requires these).
dry_run – If True the command is not actually issued. This can be used to test if the server would generate errors when preparing the command (for example because an argument is missing).
comment – Comment attached to the command.
verification – Overrides to the default verification handling of this command.
stream –
Override the stream on which the command should be sent out.

New in version 1.9.6.
extra – Extra command options for interpretation by non-core extensions (custom preprocessor, datalinks, command listeners). Note that Yamcs will refuse command options that it does now know about. Extensions should therefore register available options.
sequence_number –
Sequence number of this command. This is used to determine unicity of commands at the same time and coming from the same origin. If not set Yamcs will automatically assign a sequential number as if every submitted command is unique.

New in version 1.9.0.

Returns:

An object providing access to properties of the newly issued command and updated according to command history updates.

class yamcs.client.AlarmSubscription(manager)¶

Bases: WebSocketSubscriptionFuture

Local object representing an alarm subscription.

A subscription object stores the currently active alarms.

Initializes the future. Should not be called by clients.

get_alarm(name: str) → Alarm¶

Returns the alarm state associated with a specific named alarm from local cache.

Parameters:: name – Fully-qualified name

list_alarms() → List[Alarm]¶: Returns a snapshot of all active alarms.

class yamcs.client.CommandHistorySubscription(manager: WebSocketSubscriptionManager)¶

Bases: WebSocketSubscriptionFuture

Local object providing access to command history updates.

This object buffers all received command history. This is needed to stitch together incremental command history events.

If you expect to receive a lot of command history updates you should periodically clear local cache via clear_cache(). In future work, we may add automated buffer management within configurable watermarks.

Warning

If command history updates are received for commands that are not currently in the local cache, the returned information may be incomplete.

Initializes the future. Should not be called by clients.

clear_cache()¶: Clears local command history cache.

get_command_history(issued_command: IssuedCommand) → Optional[CommandHistory]¶

Gets locally cached CommandHistory for the specified command.

Parameters:: issued_command – object representing a previously issued command.

class yamcs.client.ContainerSubscription(manager: WebSocketSubscriptionManager)¶

Bases: WebSocketSubscriptionFuture

Local object providing access to container updates

Initializes the future. Should not be called by clients.

get_container(name: str) → ContainerData¶

Returns the latest container of a specific name.

Parameters:: name – Container name

list_containers() → List[ContainerData]¶: Returns the latest container for each name.

class yamcs.client.ParameterSubscription(manager: WebSocketSubscriptionManager)¶

Bases: WebSocketSubscriptionFuture

Local object representing a subscription of zero or more parameters.

A subscription object stores the last received value of each subscribed parameter.

Initializes the future. Should not be called by clients.

add(parameters: Union[str, List[str]], abort_on_invalid: bool = True, send_from_cache: bool = True)¶

Add one or more parameters to this subscription.

Parameters:

parameters – Parameter(s) to be added
abort_on_invalid – If True one invalid parameter means any other parameter in the request will also not be added to the subscription.
send_from_cache – If True the last processed parameter value is sent from parameter cache. When False only newly processed parameters are received.

await_first_delivery(timeout: Optional[float] = None)¶

Wait for the first update of parameter values.

Parameters:: timeout – The amount of seconds to wait.

delivery_count: int¶: The number of parameter deliveries.

get_value(parameter: str)¶

Returns the last value of a specific parameter from local cache.

Parameters:: parameter – Parameter name.

remove(parameters: Union[str, List[str]])¶

Remove one or more parameters from this subscription.

Parameters:: parameters – Parameter(s) to be removed

value_cache: Dict[str, ParameterValue]¶: Value cache keyed by parameter name.