Definitions
Medication adherence isn't binary. A dose taken 75 minutes early isn't the same as a dose missed entirely — and treating them the same way creates alert fatigue, mistrust, and missed actual problems. This page lays out exactly how RingoRx classifies every cap-open event, with citations to the clinical literature that shapes our thresholds.
Before we get into how doses get classified, here's the honest architecture: the cap is a dumb sensor and the server is the brain. The cap measures a small number of physical signals very well, and the server is what turns those signals into "you took your dose." Knowing what the cap can and can't actually see helps explain why a few things — like "did you take the right pill" — aren't problems we try to solve with the hardware alone.
A tiny chip that tells the cap which way is up. Reads 20 times per second.
InvenSense MPU-6050 IMU. The Z-axis component of acceleration is interpreted against the local gravity vector to determine whether the cap is right-side-up (≈ +9.8 m/s²) or inverted (≈ −9.8 m/s²). Combined with the X and Y components, total acceleration magnitude is used for motion detection.
Senses rotation. Captured but not actively used yet — reserved for things like detecting a deliberate twist-off versus a knock-over.
Same MPU-6050 part. Sampled at 20 Hz in 500°/s range. Future revisions will use the gyroscope for rotation-based gesture classification (Claim Group M of the RingoRx patent disclosure).
The cap synchronizes its clock with a network time server. Every observation gets a real timestamp.
NTP synchronization via pool.ntp.org with time.nist.gov and time.google.com fallbacks. Local clock drift is tolerated up to 24 hours under offline conditions and reconciled on reconnect.
Worth being explicit. The cap has no camera, no microphone, no weight sensor, no humidity sensor, no GPS, no fingerprint reader. Specifically, none of these are inputs to the system:
This is a deliberate design choice. Fewer sensors means a smaller cap, longer battery life, lower cost, fewer privacy surfaces, and clearer engineering. The trade-off is that some questions — "did the patient actually swallow the pill?" — can't be answered by the cap alone. We address those with workflow design rather than hardware: pill-image verification at notification time, caregiver confirmation flows, and (eventually) optional wearable integrations for medication-adherence-aware activity context.
Everything else is computed by the server from the cap's three input streams. The cap itself has no concept of "dose," "schedule," "compliance," or "tamper" — it only knows orientation, motion, and time. The server combines those raw signals with the patient's prescription schedule and the medication's timing-class rules to produce every classification you see in the app.
We see the cap go upside-down for more than a second. That's "cap off."
A `cap_off` compound event is emitted when the Z-axis acceleration component remains below the inversion threshold (−6.0 m/s²) for at least 1 second of debounce. The inverse condition (≥ +4.0 m/s² for ≥ 1s) emits `cap_on`.
The cap notices the bottle is being handled, even before it gets opened.
A `motion` event is emitted when the deviation of the smoothed acceleration magnitude from its rolling average exceeds 4 m/s², subject to a 400 ms cooldown. Motion events in the 2-second window preceding a `cap_off` provide the "intent" signal that distinguishes a deliberate cap-opening from a knocked-over bottle.
The cap came off, stayed off for a brief moment, then went back on — preceded by someone handling the bottle. That's how we infer "the patient did the thing."
A dose is recorded only when (a) a `cap_off` and `cap_on` pair occur within 30 seconds of each other, and (b) the `cap_off` was preceded by a motion event within the prior 2 seconds. Both conditions must be met. Inversions without prior motion are treated as accidental and do not count toward adherence.
The server looks up your prescription schedule and finds which scheduled time the dose was closest to.
The server-side classifier computes the minute-of-day for the dose event and finds the nearest configured slot. The dose is credited to that slot if the offset is within the medication's configured tolerance — see the Definitions section above for the on-schedule and early/late windows.
Based on how close to the scheduled time you actually took it.
The same `dose_taken` event is emitted regardless, with a `timing` field carrying the classification (`on_schedule`, `early`, or `late`). Downstream consumers (notifier, dashboard) use this field to determine wording, color, and badge placement.
Someone opened the bottle outside any reasonable scheduled-dose window. Could be the patient taking a dose at the wrong time, or someone else accessing the bottle.
A `cap_off` event with no scheduled slot within ±4 hours triggers a `tamper` compound event. Especially relevant for controlled substances (Schedule II–V) where unauthorized access has legal as well as clinical implications.
The cap sends a small heartbeat once a minute. If we don't hear from it for five minutes, we know it's offline.
The cap publishes a `keepalive` event every 60 seconds while it has network connectivity. A server-side watcher thread checks every 30 seconds and flips a cap's `caps_online_state` row to `offline` when more than 300 seconds have elapsed since the last keepalive. The transition triggers a `cap_offline` status event.
When the cap comes back online after being out of range, it uploads everything it recorded while offline. We label those events so they're not mistaken for live activity.
On reconnect, the cap drains its local LittleFS event spool to the `ringorx/<cap>/event_backfill` MQTT topic. The server flags each event with `backfilled=1` in the events table and the cap's online state transitions to `replaying`. After 30 seconds of no further backfill traffic, state transitions to `online` and a single summary email is queued to recipients.
Why this split matters: the cap is just a sensor. The server is the brain. This means we can change the rules without re-flashing every cap in the field, replace a cap without losing the patient's history, and add new medication classifications without firmware changes. Every cap in production runs the same firmware; every account-specific behavior lives on the server.
Every time the cap comes off the bottle, RingoRx classifies it into one of six event types. Each one has a casual name (what we call it in the app) and a clinical definition (what we mean by it, with the source we leaned on).
You took it close enough to when you were supposed to. We count it, we move on, nobody pings the caregiver.
A dose recorded within the medication's configured timing window — by default ±2 hours of the scheduled time for non-time-critical medications, or ±1 hour for time-critical medications. Aligned with ISMP's Timely Administration of Scheduled Medications (TASM) guidelines and MEMS-cap "TIMING" adherence definitions used in pharmacological literature.
Sources: ISMP TASM · MEMS-cap research
You took it earlier than the schedule, but not so early that we think something's wrong. We log it. We don't alert anybody.
A dose recorded between 4 hours before and the start of the on-schedule window. The dose still counts toward Proportion of Days Covered (PDC) calculations. We display the offset on the dashboard (e.g., "Taken 75 minutes early") so caregivers see the pattern without being alarmed by it.
Sources: ISMP TASM · PQA PDC measure
You took it after the window, but still on the same day. We log it. We don't alert anybody.
A dose recorded between the end of the on-schedule window and 4 hours after. Still counts toward PDC. Shown on the dashboard with the offset noted ("Taken 2 hours 15 minutes late").
Sources: ISMP TASM · PQA PDC measure
The window closed and the cap never opened. We alert.
A scheduled dose with no cap-open event recorded by the end of the late-dose window (scheduled time + late window threshold). Missed doses do not count toward PDC and are surfaced to recipients with their notification preferences.
Sources: PQA PDC measure
A dose was already recorded in this slot, but the cap opened again. We alert because it might be a second pill that wasn't supposed to be taken.
A second cap-open event with sufficient inversion + motion signature occurring within an already-credited scheduled slot, where the slot's compliance window has already received a dose_taken record. Surfaced as a possible overdose to the cap's owner and any third-party recipient with notify_overdose enabled.
Sources: RingoRx Patent Claim Group B (idempotent slot-aware state)
The cap opened but there was no scheduled dose within four hours. Could be tampering, could be a household member curious about a controlled medication. We alert.
A cap-open event with no scheduled slot within ±4 hours. Distinguished from "early dose" and "late dose" by the absence of any nearby scheduled window. Especially relevant for controlled substances (Schedule II–V), where unauthorized access has legal as well as clinical consequences.
Sources: RingoRx Patent Claim Group A
Not every medication has the same tolerance for timing variance. We default to the more relaxed ±2-hour window because most chronic prescriptions are non-time-critical, but you can tighten it per medication during onboarding.
Most chronic prescriptions — statins, blood pressure meds, allergy meds, prednisone for inflammation. The default.
ISMP recommends a ±2-hour administration window for non-time-critical scheduled medications to prevent accidental omission while preserving therapeutic intent.
Insulin, antiepileptics, anticoagulants, opioid pain meds, anything with a narrow therapeutic index.
ISMP recommends a ±1-hour window for time-critical medications administered more frequently than once daily but not more frequently than every 4 hours. MEMS-cap pharmacology research defines "TIMING" adherence as the percentage of doses taken within ±1 hour of prescribed intake.
Take it when you need it. No window, no schedule, no alerts.
PRN medications by definition lack a fixed schedule. Adherence is measured by appropriateness of use rather than timing.
On the dashboard, your overall adherence score follows the industry-standard Proportion of Days Covered (PDC). Take 80% or more of your scheduled doses within the late-dose window? You're adherent. That's the threshold Medicare and major insurers use.
Proportion of Days Covered is the Pharmacy Quality Alliance's standardized adherence measure, used by CMS Star Ratings and most commercial health plans. An on-schedule, early, or late dose all contribute equally to PDC. Only missed doses count against it.
Most chronic medications don't care if you take them at 8:45 instead of 10:00. The drug levels in your body at steady-state don't change meaningfully. What matters is whether you take it at all. Strict timing windows produce a lot of false alarms — "off-schedule access" emails to your daughter at 7 AM every Tuesday because Grandma's an early riser — and false alarms train people to ignore real alerts.
Some medications genuinely do need tight timing — insulin matched to meals, antiepileptics that lose efficacy at sub-therapeutic levels, controlled substances where the risk profile is different. For those, you'd switch the medication to "time-critical" at onboarding and the window tightens to ±1 hour.
See ISMP's TASM guidelines and the MEMS-cap pharmacology literature for the empirical basis of these thresholds. Steady-state pharmacokinetics research consistently shows that ±2 hours of dose-timing variability has minimal effect on therapeutic outcomes for non-time-critical regimens at three-or-fewer doses per day.
Institute for Safe Medication Practices. Defines time-critical vs. non-time-critical medications and the ±1 hr / ±2 hr administration windows used widely in US hospital pharmacy practice.
ismp.org — TASM guidelines (PDF)The 80% adherence threshold used in CMS Star Ratings and most commercial health-plan quality measures. PDC is the field's standard outcome measure.
pqaalliance.org — Adherence measuresThe Medication Event Monitoring System pill-cap is the historical gold standard for measuring outpatient adherence. The "timing adherence" definition (within ±1 hour of prescribed intake) used in our time-critical category comes from this literature.
PMC — MEMS scoping reviewThe most cited paper on adherence vocabulary — distinguishing initiation, implementation, and discontinuation, and unifying terminology across the field.
PMC — Vrijens et al. 2012Argues against treating adherence as a single binary cutoff and explores the relationship between drug exposure, missed doses, and clinical outcomes.
Frontiers in PharmacologyPractical overview of how clinicians evaluate adherence with reference to PDC, MPR, and MEMS-based timing measures.
PMC — Lam & Fresco 2015Specific to prednisone/prednisolone — shows that early-morning dosing produces lower peak and trough concentrations but can improve therapeutic alignment with circadian cortisol patterns.
PMC — Czock et al.