jaraco / jaraco/pluslife-analyzer
Resilience: operate the analyzer without virus.sucks (capture protocol / offline mode)
- Dominant language
- JavaScript
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
Today the app loads its UI and — critically — its **device protocol and amplification-curve/result analysis** from `virus.sucks`. If that site goes down or changes, this app and the dock become far less useful. We should capture what's needed to operate the analyzer independently, and offer an offline mode.
Two tiers, increasing effort:
## Tier 1 — Offline mirror of the web app (cheap insurance)
Vendor a pinned local copy of the two upstream bundles (`_js/main.js`, `_js/pluslife_app.js`) and the page, and load them from disk (`PLUSLIFE_URL` already allows overriding the source). Pros: preserves the exact, validated protocol + result math with little work. Cons: no updates; redistribution/licensing of a community project — coordinate with the maintainer (`hi@virus.sucks`), who may welcome it or prefer we host a fork.
## Tier 2 — Native reimplementation of the BLE protocol
Reimplement the transport + framing + result interpretation so no web app is needed. What has already been observed from the client source (starting point, verify against hardware):
**Transports**
- BLE: custom service `50a337e2-3a36-474f-81e3-ecaeb6f92eb3`; 16-bit chars `0xC304` / `0xC305` (write / notify) and `0xA002`. Device name pattern like `Pluslife-PM001`.
- USB-C: Web Serial, `115200` 8N1 (CDC).
**Framing / messages**
- Parsed fields: `sequenceNumber`, `conversationId`, `target`, `length`, `type`, `payload` (DataView), `payloadLength`.
- Start-test command builds a hex string `"ff01a60700" + kitConfig.payload`, zero-padded to length 194, then wrapped by a framing fn (adds header/CRC — confirm).
**Kits / assays** (`Jo`, derived from an `m5` table)
- Each kit: `{ ProjName -> name, CarrierType -> carrier (1=human, 2=veterinary), Version, EncryptKey, ProjConf, ... }`.
- `EncryptKey` is MD5'd and `ProjConf` is Base64 — there is crypto (likely AES) around config/among device messages. Needs decoding.
- Kit carries `channels` and `groups` used for result interpretation (`subGroupResults`, `detectionResult`, per-endpoint results, IC/internal-control handling).
- Option value encoding: `zs(kit) = name.toLowerCase().replaceAll(' ','-')`.
**Result interpretation**
- Isothermal amplification: temperature + fluorescence `samples` over time; `testData = {temperatureSamples, samples}`; final `testResult` / `detectionResult`; kit `groups` map channels → targets; IC (internal control) validity rules.
**Work**
- Capture live BLE traffic during a real run (macOS PacketLogger / `blueutil` + a BLE sniffer, or Chrome `chrome://bluetooth-internals`) to confirm framing, notifications, and the config/crypto handshake.
- Document the protocol in `docs/protocol.md`.
- Prototype a native client (`@abandonware/noble` for BLE, or Web Serial for USB) that can start a test and stream results.
- Port result interpretation (kit groups → result), preserving the disclaimers — this is the medically sensitive part.
## Acceptance
- `docs/protocol.md` capturing transports, framing, kit/assay model, and result logic.
- Tier 1 offline mode selectable and documented.
- (Stretch) a native path that starts a test and reports a result without virus.sucks.
Note: keep the same non-diagnostic disclaimers as upstream; this is for resilience/research, not clinical use.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing PLUSLIFE_URL and the upstream bundles `_js/main.js` and `_js/pluslife_app.js`, then capture a real BLE run to verify the protocol details. Document transports, framing, kit and assay data, and result logic in `docs/protocol.md`; Tier 1 is complete when the local mirror can be selected and documented, with native support as stretch work.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, macos, node.js
- Domain
- desktop, documentation, embedded-iot, reverse-engineering
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100