Skip to content

Add gyroscope.v1 #17

Description

@JacobLinCool

Scope narrowed. The Android field-matrix and real-device evidence regime has been
removed from this issue. What remains is the work that a build, a test, or a checked-in
artifact can settle.

Summary

Add a dedicated gyroscope.v1 Android collector for raw angular-velocity observations.

The collector records sensor observations only. It must not calculate orientation, activity, gestures, or behavioral inferences.

Requirements

Schema and configuration

  • Define a registry entry and compiled collector module for Android's calibrated gyroscope source.
  • Record:
    • raw x/y/z angular velocity in radians per second;
    • the hardware/source continuous-monotonic timestamp;
    • sensor accuracy using a strict enum;
    • any source metadata required to interpret timestamp/accuracy without identifying the physical device.
  • Preserve the sensor's coordinate-system semantics in the catalog and documentation.
  • Use the same bounded sampling-period and maximum-report-latency model as the accelerometer collector, expressed as integer physical-unit configuration values under Protocol v1.
  • Define absolute minimum/maximum sampling, batch latency, encoded-event-size, rate, daily-volume, and quota bounds.
  • Reject unsupported or unavailable required hardware before enrollment; do not substitute another motion sensor.

Runtime behavior

  • Use the shared collector lifecycle, access, clock, event-sink, backpressure, and quota contracts.
  • Register/unregister the sensor listener idempotently across start, pause, resume, process recovery, finish, and withdraw.
  • Enforce the pause/withdraw barrier so no callback accepted after the barrier can be appended.
  • Preserve source timestamps rather than replacing them with callback wall time; attach the standard wall/boot context required by Protocol v1.
  • Bound callback queues and batching. On overflow, quota, unavailable sensor, or OS failure, emit only bounded fixed-code collector state/audit events.
  • Do not add filesystem, database, network, arbitrary logging, inference, or export logic.

Integration and assurance

  • Add Web configuration controls, required-hardware validation, researcher/participant disclosure, data-dictionary entries, Python decoder, Parquet schema/fixtures, and demo/test configuration.
  • Document device-dependent range, resolution, calibration, batching, and achieved-rate differences without claiming cross-device equivalence.

Acceptance criteria

  • Valid x/y/z, timestamp, and accuracy events round-trip through storage, manual export, automatic upload, Python verification, and typed Parquet.
  • Requested sampling period and report latency are strictly bounded and map deterministically to Android sensor registration.
  • Hardware timestamps remain ordered only within their documented boot-session/source-clock domain.
  • Missing required hardware blocks enrollment; an optional unavailable collector follows the explicit Protocol v1 behavior without substitution.
  • Pause, resume, rapid lifecycle changes, process death, reboot, listener errors, queue pressure, and quota have deterministic tests.
  • No event is appended after the pause/withdraw barrier.
  • Maximum encoded event size and configured rate bounds are enforced before append.
  • No production code or documentation performs or claims orientation/activity inference.

Documentation

Update the catalog, collector guide, researcher/participant guides, consent copy, data dictionary, coordinate/time semantics, threat model, device-variance guidance, and analysis examples.

Dependencies

Blocked by #10 and #11.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Battery, temporal, gyroscope, ambient light, proximity, randomized windowsarea: collectorcollector/ modules and their assurance

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions