Commit 819d67e3 authored by Kyle Sunden's avatar Kyle Sunden

Merge branch '111' into 'master'

fields

See merge request !47
parents 0360b3b9 98f022fa
Pipeline #209415732 passed with stage
in 46 seconds
---
yep: 111
title: Hints
title: Fields
author: Blaise Thompson <blaise@untzag.com>
status: draft
tags: standard
......@@ -9,10 +9,10 @@ post-history: 2020-09-27
# Abstract
This YEP describes a hints system for the yaq ecosystem.
Using hints, yaq daemons provide suggestions for how clients might best display the daemon protocol.
Hints are especially useful when automatically building graphical user interfaces.
Hints are inspired in-part by the [hinting system within bluesky](http://nsls-ii.github.io/bluesky/callbacks.html#hints).
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](http://nsls-ii.github.io/bluesky/metadata.html) and [hints](http://nsls-ii.github.io/bluesky/callbacks.html#hints).
# Table of Contents
......@@ -20,10 +20,16 @@ Hints are inspired in-part by the [hinting system within bluesky](http://nsls-ii
# Motivation
When interacting with hardware via "rich" graphical clients, users typically expect to be presented with a set of [fields](https://en.wikipedia.org/wiki/Field_(computer_science)).
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](https://yeps.yaq.fyi/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 that clients can use when they expect certain basic behaviors.
Still, it can be difficult to automatically construct "rich" clients, especially graphical user interfaces, for a given yaq daemon.
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:
......@@ -31,17 +37,20 @@ A typical graphical client needs to know the following:
- which fields can be set, and which are read-only?
- what messages are used to read and write a given field?
- which read-only fields are dynamic?
- which fields are primary and which are secondary?
Here "field" is a single piece of information about a daemon, things like "current position", "integration time", and "averaging method".
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.
The hints system allows daemons to help connected clients by specifing relevant fields.
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.
Hints exist on-top-of and do not modify or define the Avro-RPC protocol which each daemon defines.
Clients may ignore hints without penalty.
Fields exist on-top-of and do not modify or define the Avro-RPC protocol itself.
Clients may ignore fields without penalty.
# Specification
Hints appear under the `hints` key of every schema provided by yaq daemons.
## 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:
```
......@@ -52,30 +61,97 @@ This key maps to a `string: record` mapping where the string key is the field na
{"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 hint must have a `getter`.
Every field must have a `getter`.
The `setter` message must accept exactly one required argument of the type specified.
If a hint does not have a `setter` it is assumed read-only.
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 non read-only hint is assumed to be dynamic.
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](https://yaqc-cmds.wright.tools/en/latest/), [typhos](https://pcdshub.github.io/typhos/v1.1.1/)).
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](https://nsls-ii.github.io/ophyd/signals.html#kind).
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.
Hints may be specified by traits.
Individual daemons may overload trait-specified hints, but only in the following cases:
## Fields and Traits
Fields may be specified by traits.
Individual daemons may overload trait-specified fields, but only in the following cases:
- to change `dyanmic` from `true` to `false`
- to change `dynamic` from `true` to `false`
- to narrow the scope of a union type
Of course, daemons may add additional fields as needed.
For demonstration, the fields of three exisiting traits are shown below:
has-position ([YEP-301](https://yeps.yaq.fyi/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](https://yeps.yaq.fyi/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](https://yeps.yaq.fyi/303/))
```
{
"limits": {
"getter": "get_limits",
"dynamic": true,
"kind": "normal",
"type": {"type": "array", "items": "double"}
}
}
```
# Discussion
Discussion can be found on the [gitlab issue](https://gitlab.com/yaq/yeps/-/issues/23) for this YEP.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment