Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Overhaul frequency management in the specification #468

Merged
merged 4 commits into from
Aug 8, 2023

Conversation

rakuco
Copy link
Member

@rakuco rakuco commented Aug 2, 2023

This commit addresses a few issues with the way frequency management was
handled in the specification:

  1. "Sampling frequency" was interchangeably used as a number as well as an
    interval ("sampling frequency bounds"), and the latter was not even
    properly defined.
  2. The actual bounds were not properly defined, and neither was the clamping
    process that used them.
  3. There were too many frequency-related terms in use.

Let us start with the changes in the concepts and definitions:

  • A platform sensor has a sampling frequency, a positive number or null.
    It represents the frequency at which the platform sensor attempts to
    retrieve data from the device sensor and it is calculated in an
    implementation-defined manner based on the [[frequency]] of the
    associated Sensor objects. It is therefore a mixture of the previous
    "sampling frequency" and "requested sampling frequency" definitions.
    • How the sampling process works is implementation-defined: it could be
      polling, or requesting updates at this interval, or something else
      entirely.
  • A device sensor has a sampling frequency. It is similar to the above, but
    operating system or hardware dependent and opaque to this specification.
    • As such, the device sensor may choose a sampling frequency that differs
      from the platform sensor's sampling frequency and we have no control
      over it.
  • A device sensor MAY report lower and/or upper sampling frequency bounds.

With the above, the actual sampling bounds are defined and checked:

  • A sensor type MUST have lower and upper sampling frequency bounds. The
    lower bound is "max(implementation-defined value, optional spec-defined
    value)", and the upper bound is "min(implementation-defined value,
    optional spec-defined value)".
  • A new algorithm returns a platform sensor's lower and upper sampling
    bounds as a tuple "(max(optional device sensor lower bound, sensor type
    lower bound), min(optional device sensor upper bound, sensor type upper
    bound))".
  • A Sensor's [[frequency]] is always set to a value within a platform
    sensor's sampling bounds in "Connect to a sensor" (before that it might
    not have an associated platform sensor and should be in the "activated"
    state).
  • "Set sensor settings" requires that the platform sensor sampling value
    calculated based on its associated sensors' [[frequency]] values lies
    within its sampling bounds.

The "optimal sampling frequency" and "requested sampling frequency" s
have been removed, and so has the "Find the reporting frequency of a sensor
object" algorithm, which addresses point (3).

The "Automation" section has only received enough changes to avoid Bikeshed
errors and warnings, as the entire section is being rewritten.

Related to #463.


Preview | Diff

@rakuco rakuco requested a review from reillyeon August 2, 2023 21:15
This commit addresses a few issues with the way frequency management was
handled in the specification:
1. "Sampling frequency" was interchangeably used as a number as well as an
   interval ("sampling frequency bounds"), and the latter was not even
   properly defined.
2. The actual bounds were not properly defined, and neither was the clamping
   process that used them.
3. There were too many frequency-related terms in use.

Let us start with the changes in the concepts and definitions:
- A platform sensor has a sampling frequency, a positive number or null.
  It represents the frequency at which the platform sensor attempts to
  retrieve data from the device sensor and it is calculated in an
  implementation-defined manner based on the `[[frequency]]` of the
  associated Sensor objects. It is therefore a mixture of the previous
  "sampling frequency" and "requested sampling frequency" definitions.
  . How the sampling process works is implementation-defined: it could be
    polling, or requesting updates at this interval, or something else
    entirely.
- A device sensor has a sampling frequency. It is similar to the above, but
  operating system or hardware dependent and opaque to this specification.
  . As such, the device sensor may choose a sampling frequency that differs
    from the platform sensor's sampling frequency and we have no control
    over it.
- A device sensor MAY report lower and/or upper sampling frequency bounds.

With the above, the actual sampling bounds are defined and checked:
- A sensor type MUST have lower and upper sampling frequency bounds. The
  lower bound is "max(implementation-defined value, optional spec-defined
  value)", and the upper bound is "min(implementation-defined value,
  optional spec-defined value)".
- A new algorithm returns a platform sensor's lower and upper sampling
  bounds as a tuple "(max(optional device sensor lower bound, sensor type
  lower bound), min(optional device sensor upper bound, sensor type upper
  bound))".
- A Sensor's `[[frequency]]` is always set to a value within a platform
  sensor's sampling bounds in "Connect to a sensor" (before that it might
  not have an associated platform sensor and should be in the "activated"
  state).
- "Set sensor settings" requires that the platform sensor sampling value
  calculated based on its associated sensors' `[[frequency]]` values lies
  within its sampling bounds.

The "optimal sampling frequency" and "requested sampling frequency" <dfn>s
have been removed, and so has the "Find the reporting frequency of a sensor
object" algorithm, which addresses point (3).

The "Automation" section has only received enough changes to avoid Bikeshed
errors and warnings, as the entire section is being rewritten.

Related to #463.
@rakuco rakuco force-pushed the overhaul-frequency-management branch from 7414cd8 to ab2e54f Compare August 2, 2023 21:18
@rakuco rakuco changed the title overhaul frequency management Overhaul frequency management in the specification Aug 2, 2023
index.bs Outdated Show resolved Hide resolved
Compared to the original suggestion:
- The note was moved after we say that a device sensor's sampling rate is
  opaque.
- The note has been word-wrapped at 100 characters.
- I've added some `[=references=]` to terms from the spec.
Copy link
Member

@reillyeon reillyeon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with nits

index.bs Outdated Show resolved Hide resolved
index.bs Outdated Show resolved Hide resolved
Raphael Kubo da Costa and others added 2 commits August 9, 2023 00:15
@rakuco rakuco merged commit f0dca6f into main Aug 8, 2023
@rakuco rakuco deleted the overhaul-frequency-management branch August 8, 2023 22:17
@rakuco rakuco restored the overhaul-frequency-management branch August 8, 2023 22:18
github-actions bot added a commit that referenced this pull request Aug 8, 2023
SHA: f0dca6f
Reason: push, by rakuco

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@rakuco rakuco deleted the overhaul-frequency-management branch August 8, 2023 22:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants