yaq-yeps/309


is-discrete

YEP:309
Title:is-discrete
Authors:Blaise Thompson
Status:accepted
Tags:trait
Post-History:2020-06-16

Abstract

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 avaliable positions.

This trait has been accepted. See built documentation at at yaq.fyi.

Table of Contents

Motivation

Devices with just a few avaliable 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.

Proposal

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.

state: postion_identifier

type: string

Current position identifier.

method: get_position_identifiers

returns: dictionary of {string: number}

Get position identifiers. Identifiers may not change at runtime.

method: set_identifier

arguments: identifier: string

Set using an identifier.

method: get_identifier

returns: string

Get current identifier string. Current identifier may be None.

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