Skip to content

Add ambient_light.v1 and proximity.v1 #18

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 separate ambient_light.v1 and proximity.v1 Android collector modules.

These collectors expose bounded raw sensor observations and documented hardware semantics. They must not infer room content, participant presence, attention, pocket state, or behavior.

Requirements

ambient_light.v1

  • Record ambient illuminance in lux, source continuous-monotonic timestamp, and sensor accuracy.
  • Define registry-declared numeric representation, valid range, unavailable/overflow behavior, source-clock basis, maximum encoded size, and event/rate bounds.
  • Allow only bounded sampling and/or change-threshold controls expressed as integer physical units under Finalize a language-neutral Particeps Protocol v1 and conformance corpus #8.
  • Document that sensor placement, dynamic range, calibration, screen effects, and OEM batching vary substantially.

proximity.v1

  • Record raw reported distance, the sensor's declared maximum range, source continuous-monotonic timestamp, and accuracy.
  • Provide a deterministic near/far interpretation only when its rule and uncertainty are explicit in the schema; preserve the raw value.
  • Make clear that many Android proximity sensors expose effectively binary near/far behavior and that numerical values are not comparable precision measurements across devices.
  • Allow only bounded sampling and/or change-threshold controls expressed as integer physical units.
  • Define missing, saturated, maximum-range, unknown-accuracy, and unusual-device behavior without substituting another sensor.

Shared lifecycle and integration

  • Keep the collectors as distinct IDs, modules, disclosures, schemas, and Parquet partitions.
  • Reject enrollment when either is configured as required but the device lacks the corresponding source.
  • Use shared lifecycle, event sink, clock, access, batching, backpressure, and quota contracts.
  • Enforce pause/withdraw barriers and maximum encoded-event/rate bounds.
  • Add Web controls, hardware capability summaries, English/Traditional Chinese disclosure, Python decoders, Parquet fixtures, and data-dictionary entries.
  • Add no network, storage, logging, content capture, presence inference, or activity-inference capability.

Acceptance criteria

  • Both collectors independently round-trip valid events through encrypted storage, export/upload, Python validation, and typed Parquet.
  • Required missing hardware prevents enrollment with a clear participant-facing explanation.
  • Binary-only proximity devices are represented accurately and never reported as precise ranging hardware.
  • Threshold and sampling controls reject negative, unbounded, over-precise, or unsupported values before signing/import.
  • Duplicate/change-driven events remain within registry bounds under noisy sensor callbacks.
  • Pause, resume, reboot, process recovery, sensor removal/failure, queue pressure, and quota have deterministic tests.
  • No post-barrier events are appended after pause/withdraw.
  • UI, logs, docs, and quality reports do not infer room content, presence, attention, or behavior.

Documentation

Update the catalog, collector and researcher/participant guides, consent text, data dictionary, hardware-variance guidance, threat model, 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