yaq-yeps/111


Fields

YEP:111
Title:Fields
Authors:Blaise Thompson
Status:draft
Tags:standard
Post-History:2020-09-27

Abstract

This YEP describes a "fields" system for the yaq ecosystem. Using fields, yaq daemons provide suggestions for how clients might best display the daemon's state to users. Fields are especially useful when automatically building graphical user interfaces. Fields are inspired by Bluesky, which has a system of fields and hints.

Table of Contents

Motivation

When interacting with hardware via "rich" graphical clients, users typically expect to be presented with a set of fields. For example, a simple motor might have the field "position" and the field "velocity". Users might expect a graphical client to display the current value of each of these fields and allow setting their value, where possible.

Using Avro-RPC (see YEP-107), yaq daemons completely specify their client interface. A client knows the exact signature of every message that the daemon supports. In addition, yaq has a traits system which defines prefered message syntax for common behaviors. Client developers may use the traits system to safely build user interfaces. Despite these tools, the releationship between message protocols and logical "fields" of the daemon is often not obvious. Because individual daemons are allowed to specify arbitrary messages beyond those implied by traits, it can be a challenge to automatically discover the relevant fields for an arbitrary daemon.

A typical graphical client needs to know the following:

Here "field" is a single piece of information about a daemon, things like "current position", "integration time", and "averaging method". This YEP allows daemons to help connected clients by specifing relevant fields in a standardized way. While the primary purpose of fields is automatic user-interface generation, fields may also be useful when choosing what (meta)data to record from each daemon in the context of an experiment.

Fields exist on-top-of and do not modify or define the Avro-RPC protocol itself. Clients may ignore fields without penalty.

Specification

The Field Record

Fields appear under the fields key of every protocol provided by yaq daemons. This key maps to a string: record mapping where the string key is the field name and the record matches the following:

{
  "type": "record",
  "name": "field",
  "fields": [
    {"name": "getter", "type": "string"},
    {"name": "setter", "type": ["null", "string"], "default": "null"},
    {"name": "dynamic", "type": "boolean", "default": true},
    {"name": "kind", "type": "enum", "symbols": ["normal", "hinted"]},
    {"name": "type", "type": "string"}
}

The strings getter and setter are the message names used to get and set that field. The getter message must accept no required arguments and must return exactly the type specified. Every field must have a getter. The setter message must accept exactly one required argument of the type specified. If a field does not have a setter it is assumed read-only.

dyanamic indicates whether a read-only field's value can change while the daemon is running. Any field with a setter is assumed to be dynamic. dynamic is default true, so any field that does not provide the dyanmic key will be assumed to be dynamic. A client that encounters a field with dynamic equal to false may call the getter only once, caching the response. In cases where a daemon kicks a client and reconnects, the client should refresh all fields.

kind further informs clients of best behavior for presenting daemons to users. A common design pattern for graphical user interfaces is to have two "levels" of interface for each piece of hardware---one small simplified interface and one complete "advanced menu" or "engineering screen" (examples: yaqc-cmds, typhos). A kind of normal tells the client that the field should only be shown on the "advanced menu". A kind of hinted tells the client that the field is of principle importance and should be shown on the "simplified interface". In an effort to increase compatability between ecosystems, yaq has copied these keys directly from ophyd. Every field must define kind---there is no default value.

type is a valid Avro type. It is encouraged to use simple types here, as most graphical clients may not be able to display arbitrarily complex types.

Fields and Traits

Fields may be specified by traits. Individual daemons may overload trait-specified fields, but only in the following cases:

Of course, daemons may add additional fields as needed. For demonstration, the fields of three exisiting traits are shown below:

has-position (YEP-301)

{
  "position": {
    "getter": "get_position",
    "setter": "set_position",
    "dyanamic": true,
    "kind": "hinted",
    "type": "double"
  }
  "destination": {
    "getter": "get_destination",
    "dyanamic": true,
    "kind": "normal",
    "type": "double"
  }
}

is-discrete (YEP-309)

{
  "position_identifier": {
    "getter": "get_identifier",
    "setter": "set_identifier",
    "dynamic": true,
    "kind": "hinted",
    "type": "string"
  }
  "position_identifiers": {
    "getter": "get_position_identifiers",
    "dynamic": false,
    "kind": "normal",
    "type": {"type": "map", "values": "double"}
  }
}

has-limits (YEP-303)

{
  "limits": {
    "getter": "get_limits",
    "dynamic": true,
    "kind": "normal",
    "type": {"type": "array", "items": "double"}
  }
}

Discussion

Discussion can be found on the gitlab issue for this YEP.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.


built 2020-10-30 18:08:48                                      CC0: no copyright