This YEP defines the has-position trait. This is a core trait which applies to all settable hardware. Daemons with this trait have one specific value that describes their current position.

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

Table of Contents


A broad swath of instrumental components have exactly one settable position. Control of these components involves setting their position and getting their current position. These hardware are busy while they are moving, and otherwise not busy. Since so many of the devices yaq communicates with behave in this way, it is crucial that a trait exist to enforce consistency across the ecosystem.

Components with multiple settable positions are not directly covered by this trait. In many cases, such components are best represented by separate yaq interfaces to each axis.


Daemons implementing has-position have two crucial attributes: position and destination. Position should correspond to the current actual position of the hardware. Destination is the location the hardware was most recently set to.

Daemons implementing has-position should remain busy while moving. Certain components allow for external setting of destination, outside of the yaq ecosystem. For example, there may be physical interfaces to set hardware. These external interfaces should update the daemon destination.

has-position implements units, although the units may be None. Daemons expect clients to do conversion: given destinations must be provided in native units.

state: position

type: number

The current position, as read from the hardware. Typically, this position does not change without the hardware being directly set.

state: destination

type: number

The current destination.

message: get_destination

response: float

Get current destination.

message: get_units

response: [null, string]

Get current units.

message: get_position

response: float

Get current position.

message: set_position

parameter: position: float

Give the daemon a new destination. Daemon should immediately begin motion towards that destination.

message: set_relative

parameter: distance: float response: float

Give the daemon a new destination relative to its current position. Daemon will immediately begin motion towards new destination. Returns new destination.



A simple pseudocode implementation of a client which sets a new position, waits for daemon to arrive at destination, and records actual position.

while client.busy():


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


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

built 2020-08-14 17:04:12                                      CC0: no copyright