yaq-yeps/310

has-measure-trigger

Abstract ¶

This YEP defines the has-measure-trigger trait. Daemons implementing this trait allow measurement to be software triggered over the yaq interface.

Table of Contents ¶

Motivation ¶

In many cases, it's relevant to tell a sensor "begin measurement now". For example, you might wish to wait for a motor to arrive at its position before telling a sensor to make a measurement. This trait standardizes this common sensor interface pattern within the yaq ecosystem.

Note that this trait builds on the is-sensor trait defined in YEP-302. That trait defines a standard way of accessing the sensor data and metadata. The scope of this trait is only the software triggering feature.

Proposal ¶

This trait requires is-sensor: see YEP-302.

The principle feature of the has-measure-trigger is the addition of the measure method. This method can be called to initiate a measurement. Because measurements might take some time to complete, the measure method does not wait to return the results of the measurement. Instead, it merely returns the measurement_id of the measurement that was initiated (the "next" measurement). Clients will use the messages defined by YEP-302 to access the data once the measurement is complete. Clients will be assured of measurement order by comparing the measurement_id returned by get_measured to tme measurement_id that was returned by measure previously.

has-measure-trigger does not change the fundamental nature of measurement_id as described by YEP-302: measurement_id increments when the channel values are changed. That is, when a measurement completes. The measurement_id returned by measure can be thought of as the id of the NEXT measurement. The value returned by measure will never be the same as returned by get_measurement_id.

The fact that a measurement can be initiated implies that daemons implementing has-measure-trigger can, at some times, be not measuring. We tie the state of busy to the act of measurement. A daemon will remain busy as long as it is actively measuring and will release busy once it becomes idle again. This is natural in many orchestration situations where software will want to wait for all sensors to finish measuring before proceeding.

It's very important that the behavior of the measure method is consistent, especially with respect to order. One crucial detail: what happens when measure is called during a measurement? In this case daemons implementing has-measure-trigger MUST return the measurement_id corresponding to the currently ongoing measurement. They MUST NOT halt the ongoing measurement. If a measure command is recieved during an ongoing measurement, that DOES NOT imply that the daemon should "remember" to initiate a new measurement once the ongoing measurement finishes. measure will only initiate a measurement if the sensor is idle at that time.

As an auxillary feature to measure, this trait defines the concept of "looping". A looping sensor will "self-trigger" as quickly as it can. This implies that the sensor will always remain busy. Looping state is set by the argument loop to measure, default false. A configuration option loop_at_startup and a message stop_looping must also be implemented. Conveniently, a looping sensor behaves exactly like the generic sensor described in YEP-302. Clients that aren't interested in micromanaging order of measurement with respect to acquisition flow will find this convinient.

config: loop_at_startup ¶

type: boolean

default: false

If set to true, the daemon will begin to loop measure as soon as it starts. By using this config, users may ignore software triggering and treat this sensor as a pure asyncronus measurement device.

message: measure ¶

parameter: loop: boolean parameter: loop: default: false

Initiate a measurement. Returns integer, measurement ID.

message: stop_looping ¶

Stop looping measurement.

Copyright ¶

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