JacobLinCool / JacobLinCool/particeps
Add gyroscope.v1
- Dominant language
- Kotlin
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
> **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.
Contributor guide
Research direction
Start with the existing accelerometer collector and the shared Protocol v1 lifecycle, access, clock, event-sink, backpressure, and quota contracts. Trace the Web configuration, Python decoder, Parquet schema and fixtures, catalog, and demo/test configuration mentioned in the issue. Done means bounded gyroscope events round-trip through storage and export, required hardware and lifecycle behavior are tested, and the listed documentation is updated without inference logic.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, kotlin, python
- Domain
- data, documentation, mobile
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100