| YEP: | 309 |
|---|---|
| Title: | is-discrete |
| Authors: | Blaise Thompson |
| Status: | accepted |
| Tags: | trait |
| Post-History: | 2020-06-16, 2021-03-23 |
This YEP defines the is-discrete trait. This trait requires and is closely related to has-position (YEP-301). While has-position considers the case of any device with a single settable position, is-discrete considers the subset of devices that have just a few available positions.
This trait has been accepted. See built documentation at at yaq.fyi.
Devices with just a few available positions are typically interacted with in slightly different ways than devices with many positions. These "discrete" devices typically have a unique name for each position, and setting them using the position names is easier than index. For example, a simple digital output pin might have two positions named "high" and "low". In contrast, an optical filter wheel might have three filters named "red", "blue", and "orange".
The is-discrete trait implements a consistent interface for such devices.
The is-discrete trait implements a very simple "identifier" system that lives on top of the position attribute defined by has-position. Conceptually, this system can be thought of as a hashtable that has unique strings as keys (the identifiers) and unique numbers as values (the positions). Clients may use these identifier strings to directly set the device to the mapped position. Furthmore, clients may as the daemon for the current active identifier.
Since this trait requires has-position, the daemon must also implement all of the features of the has-position trait.
For example, clients can use the set_position and get_position methods directly.
Daemons may choose to respond to such methods in device-appropriate ways.
Certain devices actually can take on intermediate positions, even though certain postions are special and commonly accessed.
Other devices really do only have the options present in the identifier map, and should likely simply go to the nearest valid position.
Because certain devices may be able to take on intermediate positions that do not correspond to a valid identifier, clients should be aware that current identifier may be None.
type: map with double values
This provides an in-house way of specifying discrete positions. Note that all devices must have a numeric value that the positions map onto. If a particular device does not innately have numeric positions, it is recommended to use something like natural numbers. Some devices will have native position identifiers. In that case, this config should be ignored and the more standard to that device identifiers should be preferred. Daemons must add an addendum saying as much when this is the case.
type: string
Current position identifier.
returns: dictionary of {string: number}
Get position identifiers. Identifiers may not change at runtime.
arguments: identifier: string
Set using an identifier.
returns: string
Get current identifier string. Current identifier may be None.
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
built 2023-10-10 23:52:42 CC0: no copyright