From d6954ad4388d375902aaaf05625c76e5f90d9a7c Mon Sep 17 00:00:00 2001 From: Blaise Thompson Date: Thu, 28 Sep 2023 16:04:44 -0500 Subject: [PATCH 1/4] new trait supports-collect-measured --- yeps/yep-314.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 yeps/yep-314.md diff --git a/yeps/yep-314.md b/yeps/yep-314.md new file mode 100644 index 0000000..0412672 --- /dev/null +++ b/yeps/yep-314.md @@ -0,0 +1,48 @@ +--- +yep: 314 +title: supports-collect-measured +author: Blaise Thompson +status: draft +tags: trait +post-history: 2023-09-28 +--- + +# Abstract + +This YEP introduces a message "collect_measured", a way to grab multiple measurements from a sensor simultaniously. + +# Table of Contents + +[TOC] + +# Motivation + +Some experiments incorporate sensors that are very fast or very slow compared to other pieces of hardware being controlled. In such cases it might be natural to let the sensor run asyncronously with other hardware, simply recording each time there is a new sensor reading. Unfortunately, the design of the "get_measured" message defined by is-sensor does not make asyncronus acquistion easy. Clients must ensure that they are polling quickly in order to ensure they don't miss measurements. In extreme cases, sensors are so fast that client polling is simply not practical. + +This trait extends is-sensor with exactly one additional message, "collect_measured". This message allows the client to requiest a whole set of cached measurements from the daemon at once. In this way, clients can take their time and simply "catch up" with all the measurements that a sensor has made all at once. + +# Specification + +This trait requires is-sensor: see [YEP-302](https://yeps.yaq.fyi/302/). + +This trait adds the method `collect_measured`. This method returns an avro array of arrays, where each inner array contains exactly two items: a unix timestamp float and the associated measurement as an avro map. Bluesky users can think of this as a list of readings. + +`collect_measured` accepts one optional argument, `measurement_id`, an integer with default of `null`. If a client provides this argument, the daemon will return only measurements since that id, inclusive. Because each measurement mapping already contains `measurement_id` as specified by the is-sensor trait, there is no ambiguity if clients need to cross-reference to ids. Daemons must account for overflow of `measurement_id`. + +There is no cache size gauarantee. Daemons might have dynamic or hard-coded cache sizes, and they might be smart enough to recognize system constraints in allocating caches. Some peripherals may offer caching outside of memory. Certain daemons might support configuration or messages for configuring caching behavior, but there will be no project-wide convention. Ultimately this trait is not magic---cients still must poll periodically to ensure they don't miss any sensor measurements. + +Just like `get_measured`, `collect_measured` might be empty when a daemon first starts. This trait should be totally orthogonal to has-measure-trigger. + +## message: collect_measured + +parameter: measurement_id: integer default: Null + +response: {type: array, items: {type: array, items=[float, {type: map, values: [float, ndarray]}]}} + +# Rejected Ideas + +It might be more performant to transport this additional data by adding an additional dimension to each channel and making them all numpy arrays. The possible performance improvements would be outweighed by additional complexity for the daemons and clients. + +# Copyright + +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. From e2c173837f18d1a36163ca0578608e28a2ed168e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 28 Sep 2023 21:08:57 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- yeps/yep-314.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/yeps/yep-314.md b/yeps/yep-314.md index 0412672..62d8aca 100644 --- a/yeps/yep-314.md +++ b/yeps/yep-314.md @@ -1,6 +1,6 @@ --- yep: 314 -title: supports-collect-measured +title: supports-collect-measured author: Blaise Thompson status: draft tags: trait From a0c00c47d8dec609343702da8b7d0d4bd8d37371 Mon Sep 17 00:00:00 2001 From: Blaise Thompson Date: Thu, 19 Oct 2023 10:20:55 -0500 Subject: [PATCH 3/4] Update yeps/yep-314.md Co-authored-by: Daniel Kohler <11864045+ddkohler@users.noreply.github.com> --- yeps/yep-314.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/yeps/yep-314.md b/yeps/yep-314.md index 62d8aca..cf3f1da 100644 --- a/yeps/yep-314.md +++ b/yeps/yep-314.md @@ -29,7 +29,7 @@ This trait adds the method `collect_measured`. This method returns an avro array `collect_measured` accepts one optional argument, `measurement_id`, an integer with default of `null`. If a client provides this argument, the daemon will return only measurements since that id, inclusive. Because each measurement mapping already contains `measurement_id` as specified by the is-sensor trait, there is no ambiguity if clients need to cross-reference to ids. Daemons must account for overflow of `measurement_id`. -There is no cache size gauarantee. Daemons might have dynamic or hard-coded cache sizes, and they might be smart enough to recognize system constraints in allocating caches. Some peripherals may offer caching outside of memory. Certain daemons might support configuration or messages for configuring caching behavior, but there will be no project-wide convention. Ultimately this trait is not magic---cients still must poll periodically to ensure they don't miss any sensor measurements. +There is no cache size gauarantee. Daemons might have dynamic or hard-coded cache sizes, and they might be smart enough to recognize system constraints in allocating caches. Some peripherals may offer caching outside of memory. Certain daemons might support configuration or messages for configuring caching behavior, but there will be no project-wide convention. Ultimately this trait is not magic---clients still must poll periodically to ensure they don't miss any sensor measurements. Just like `get_measured`, `collect_measured` might be empty when a daemon first starts. This trait should be totally orthogonal to has-measure-trigger. From 9098e0b576fbf1cca5a5b7b197f7577242f9d7dc Mon Sep 17 00:00:00 2001 From: Blaise Thompson Date: Thu, 19 Oct 2023 10:27:10 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Kyle Sunden --- yeps/yep-314.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/yeps/yep-314.md b/yeps/yep-314.md index cf3f1da..69ead47 100644 --- a/yeps/yep-314.md +++ b/yeps/yep-314.md @@ -19,7 +19,7 @@ This YEP introduces a message "collect_measured", a way to grab multiple measure Some experiments incorporate sensors that are very fast or very slow compared to other pieces of hardware being controlled. In such cases it might be natural to let the sensor run asyncronously with other hardware, simply recording each time there is a new sensor reading. Unfortunately, the design of the "get_measured" message defined by is-sensor does not make asyncronus acquistion easy. Clients must ensure that they are polling quickly in order to ensure they don't miss measurements. In extreme cases, sensors are so fast that client polling is simply not practical. -This trait extends is-sensor with exactly one additional message, "collect_measured". This message allows the client to requiest a whole set of cached measurements from the daemon at once. In this way, clients can take their time and simply "catch up" with all the measurements that a sensor has made all at once. +This trait extends is-sensor with exactly one additional message, "collect_measured". This message allows the client to request a whole set of cached measurements from the daemon at once. In this way, clients can take their time and simply "catch up" with all the measurements that a sensor has made all at once. # Specification