forked from Blendman974/faceclaw
72 lines
4.5 KiB
Markdown
72 lines
4.5 KiB
Markdown
# R1 health export
|
||
|
||
Android Settings → Health export uses the existing toggle and text/password
|
||
editors. Export defaults off; URL and API key default empty. Only the API key
|
||
uses AES-GCM with Android Keystore and an AtomicFile in noBackupFilesDir. Keys
|
||
are masked on both glasses and phone. The URL/cursor use shared settings.
|
||
|
||
The API/image pipeline lives in the dedicated Infrastructure/FaceclawHealth Git
|
||
repository. Kubernetes manifests live in the Infrastructure repository under
|
||
FaceclawHealth, and SQL dashboards in GrafanaDashboards/Health. Protocol v1 sends normalized HealthSample/SleepSession
|
||
fields with original millisecond timestamps. Batches contain at most 200 records
|
||
and 240 KB. HTTPS is mandatory, redirects are refused, and only HTTP 200 with
|
||
accepted:true advances the cursor. No health content or keys are logged.
|
||
|
||
The exporter reads existing append journals, including revisions to old months,
|
||
without extra BLE pulls. Partial trailing lines are retried. Unresolved sleep
|
||
sessions and sample fixtures are excluded. Replayed data is upserted server-side.
|
||
A new URL/key resets delivery history safely. One batch runs per minute while
|
||
the Android process is alive; this adds no background service or wake lock and
|
||
does not promise synchronization while the app is stopped. Disable preserves
|
||
local history and existing server data. Watch/iOS export is outside this change.
|
||
|
||
Software validation: exporter tests for replay, revisions, failed/malformed
|
||
acknowledgements, redirects, destination/credential edits, fixtures, partial
|
||
records and overlapping requests; full JS suite, TypeScript and Android release
|
||
compilation. API tests additionally cover PostgreSQL rollback and deduplication.
|
||
|
||
Hardware/end-to-end validation remains pending: enable ring health sync, configure
|
||
the deployed URL/key, then compare measured timestamps/values and sleep durations
|
||
with Grafana. Test offline/reconnect, app restart, disable/re-enable and rotated
|
||
keys. Check key masking, log redaction and preservation of other preferences.
|
||
No firmware modification is needed.
|
||
|
||
## Latest heart-rate observations
|
||
|
||
Live HR pages also carry a last-measured timestamp and value. These are now
|
||
stored as `heartRate` with `spanMs: 1`, at the exact measurement timestamp:
|
||
this denotes a point observation, **not** a ten-minute average. Existing hourly
|
||
records retain `spanMs: 3600000`. The existing local and PostgreSQL keys include
|
||
span, so readings and summaries coexist without collisions. Equal BPM at a new
|
||
timestamp is a new measurement; repeated timestamps are deduplicated across
|
||
restarts and corrected values update the same observation. Local bucket charts
|
||
and daily rollups exclude points, including when the cache is rebuilt.
|
||
|
||
The existing aligned ring pull changes from :01/:31 to :01/:11/:21/:31/:41/:51.
|
||
This is a collection cadence, not a sensor setting or a guarantee of six readings
|
||
per hour. It uses the same ring worker, connection windows and anti-spam guards;
|
||
it makes more collection attempts than before. Offline gaps remain gaps and
|
||
there is no new background service. The exporter still sends at most one batch
|
||
per minute while the Android process runs.
|
||
|
||
Timestamp handling deliberately retains the current handshake's legacy clock
|
||
convention, inverting its existing phone-timezone offset once. Only a live point
|
||
within 20 minutes of page reception and no more than two minutes in the future
|
||
is accepted; invalid/missing timestamps and BPM outside 1–300 are skipped.
|
||
Reception time is never substituted for measurement time. Old frame-journal
|
||
replay continues restoring hourly history but does not reconstruct point readings:
|
||
old pages may mix clock domains. No firmware/time-sync migration is attempted.
|
||
A timezone change around measurement or an older value can therefore leave a gap;
|
||
correct placement across such transitions still requires hardware validation.
|
||
|
||
The deployed v1 API already accepts span 1 and upserts on device/metric/time/span.
|
||
No API image, schema migration, Infrastructure change or key rotation is needed.
|
||
The Grafana overview shows separate hourly-average and latest-reading series,
|
||
with point markers for readings, not interpolated ten-minute averages.
|
||
|
||
Software checks cover latest-page conversion, invalid/stale/future readings,
|
||
timezone offsets, restart/deduplication, unchanged hourly rollups, export and
|
||
all six scheduling slots. Hardware checks remain pending: record raw/current
|
||
measurement times across several pulls, compare BPM/time with the stock app,
|
||
and check reconnect, timezone/DST transitions and collection battery impact.
|