jaraco / jaraco/pluslife-analyzer

Resilience: operate the analyzer without virus.sucks (capture protocol / offline mode)

Open
#3 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.