@medwand/mwsdk-javascript 0.0.0-stage → 3.2.2

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# MedWand JavaScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use the SDK to connect a MedWand device to a browser app and work with thermometer, pulse oximeter, ECG, stethoscope, and camera readings. The package includes TypeScript declarations.
+
+## Install
+
+```sh
+npm install @medwand/mwsdk-javascript
+```
+
+Run your app in a Chromium-based browser with Web Serial support, over HTTPS or localhost. The user must grant access to the MedWand serial port. Camera and stethoscope preview can also require browser media permissions.
+
+## Connect and take a reading
+
+Use the license and public key provided for your application. Call this function from a button click so the browser can open its device chooser.
+
+```typescript
+import { MedWandController } from "@medwand/mwsdk-javascript";
+
+export async function startThermometer(license: string, publicKey: string) {
+    const controller = new MedWandController();
+
+    try {
+        controller.Construct(license, publicKey);
+        if (!controller.IsLicenseValid) throw new Error("Invalid MedWand license.");
+
+        await controller.Connect();
+        if (!controller.IsConnected) throw new Error("MedWand connection failed.");
+
+        await controller.CheckFirmwareVersion();
+        controller.Configure();
+        await controller.Initialize();
+        if (!controller.IsInitialized) throw new Error("MedWand initialization failed.");
+
+        controller.on("OnReadingReceived", reading => console.log(reading));
+        if (!await controller.StartThermometer()) {
+            throw new Error("Could not start the thermometer.");
+        }
+
+        return controller;
+    } catch (error) {
+        await controller.Dispose();
+        throw error;
+    }
+}
+```
+
+Call `StopSensor()` to end the active reading and `Dispose()` when your app is done with the device. Calling `on()` returns an unsubscribe function. Subscribe to `OnDeviceStateChanged` and `OnDeviceError` to show connection status and device errors in your app.
+
+## Use other sensors
+
+| Sensor | Start or configure | Capture |
+| --- | --- | --- |
+| Pulse oximeter | Call `StartPulseOximeter()`. | Read values through `OnReadingReceived`. |
+| ECG | Pass a canvas to `Configure(canvas)` before initialization, then call `StartEcg()`. | Use `StartRecording()` and `StopRecording()`. Listen for `controller.Ecg`'s `RecordedStripReady` event and pass its bytes to `EcgBmpFromCapture()`. |
+| Stethoscope | Call `SetStethoscopeMode(MicrophoneModes.Heart, null)` for SDK-managed preview on the default speaker. Omit the second argument if your app manages audio input itself. Use `MicrophoneModes.Off` when finished. | For SDK-managed audio, use `StartRecording()` and `StopRecording()`. Listen for `controller.Stethoscope`'s `RecordedFramesReady` event and pass its bytes to `StethoscopeWavFromCapture()`. |
+| Camera | Pass a video or canvas element and a mode to `SetCameraMode(preview, CameraModes.Otoscope)`. Use `CameraModes.Off` when finished. | Call `StartRecording()` to capture one frame. Listen for `controller.Camera`'s `RecordedFrameReady` event and pass its bytes to `CameraBmpFromCapture()`. |
+
+## Handle firmware updates
+
+`Connect()` or `CheckFirmwareVersion()` can throw `MedWandFirmwareUpdateRequiredException`. Use its `CurrentVersion` and `RequiredVersion` fields to inform the user. Dispose the device controller, then call the firmware updater from a separate button click. Keep the MedWand connected until the update completes.
+
+```typescript
+import { FirmwareController } from "@medwand/mwsdk-javascript";
+
+export async function updateFirmware() {
+    const updater = new FirmwareController();
+    updater.on("FirmwareStateChanged", state => console.log(state));
+    updater.on("FirmwareProgressChanged", percent => console.log(percent));
+    updater.on("FirmwareError", error => console.error(error));
+
+    try {
+        return await updater.StartAsync();
+    } finally {
+        await updater.DisposeAsync();
+    }
+}
+```
+
+`StartAsync()` returns whether the update completed successfully. After success, reconnect and initialize a new `MedWandController` before starting a sensor.