@shimmerresearch/shimmer-web-sdk

Web Bluetooth and Web Serial SDK for Shimmer sensor devices.

Supported Devices

Device	Class	Transport
Shimmer3R	Shimmer3RClient	Web Bluetooth
Verisense (IMU, Pulse+)	VerisenseBleDevice	Web Bluetooth, Web Serial

Quick Start

Shimmer3R

<script type="module">
  import { Shimmer3RClient, SensorBitmapShimmer3 } from './dist/shimmer-web-sdk.esm.js';

  const client = new Shimmer3RClient({ timestampFmt: 'u24', debug: true });

  client.onStatus = (msg) => console.log('[status]', msg);
  client.onStreamFrame = (oc) => {
    const gz = oc.get('GYRO_Z', 'raw')?.value;
    console.log('GYRO_Z =', gz);
  };

  document.getElementById('btnConnect').addEventListener('click', async () => {
    await client.connect();
    await client.setSamplingRate(51.2);
    await client.setSensors(SensorBitmapShimmer3.SENSOR_GYRO | SensorBitmapShimmer3.SENSOR_A_ACCEL);
    await client.startStreaming();
  });
</script>

Verisense

<script type="module">
  import { VerisenseBleDevice } from './dist/shimmer-web-sdk.esm.js';

  const v = new VerisenseBleDevice({ hardwareIdentifier: 'VERISENSE_PULSE_PLUS' });
  v.on('streamPacket', (pkt) => console.log(pkt.sensorId, pkt.decoded));

  document.getElementById('btnConnect').addEventListener('click', async () => {
    await v.connect();
    await v.startStreaming();
  });
</script>

Building

npm install
npm run build    # produces dist/shimmer-web-sdk.esm.js, .umd.js, .d.ts

Build Helper Script (for consumer repos)

Consumer repos can call this SDK-owned helper to keep build logic centralized:

powershell -ExecutionPolicy Bypass -File .\build-local-sdk.ps1

First run only (installs dependencies):

powershell -ExecutionPolicy Bypass -File .\build-local-sdk.ps1 -InstallDeps

Build from a specific tag version (for example v0.1.7) without switching your current checkout:

powershell -ExecutionPolicy Bypass -File .\build-local-sdk.ps1 -Version 0.1.7

Build from the latest v* tag:

powershell -ExecutionPolicy Bypass -File .\build-local-sdk.ps1 -Latest

Testing

npm test         # Vitest — runs without a browser

Publishing to GitHub Packages

This package is configured for GitHub Packages (@shimmerresearch scope).
Release, tag, and package publishing are automated by .github/workflows/cut-release.yml.

To cut a new release using npm-standard versioning:

1. Run .github/workflows/cut-release.yml.
2. Choose major, minor, or patch.
3. The workflow bumps package.json/package-lock.json, publishes to GitHub Packages, pushes the vX.Y.Z tag, and creates a GitHub Release.

Automatic Formatting

Formatting is automated on each push by .github/workflows/format-on-commit.yml using Prettier.

• Run locally: npm run format
• Check formatting only: npm run format:check

Package Layout

src/
  index.ts                     ← barrel: re-exports all public API
  core/
    types.ts                   ← shared interfaces (IShimmerClient, SensorField…)
    ObjectCluster.ts            ← sensor data frame container
    BaseShimmerClient.ts        ← abstract base class
  devices/
    shimmer3r/
      Shimmer3RClient.ts        ← main BLE client class
      constants.ts              ← opcodes, UUIDs, defaults
      channelFormats.ts         ← channel ID → format map
      SensorBitmap.ts           ← sensor enable bitmasks
      calibration.ts            ← GSR / ExG / ADC calibration math
      protocol.ts               ← byte-level helpers (u16le, sign24…)
    verisense/
      VerisenseClient.ts        ← main BLE + Serial client class
      constants.ts              ← NUS UUIDs, opcodes, OP_IDX offsets
      protocol.ts               ← CRC-16, packet framing, config helpers
      sensors/
        SensorBase.ts           ← timestamp unwrap + extrapolation
        SensorADC.ts            ← ADC/GSR + battery decoder (id=1)
        SensorLIS2DW12.ts       ← LIS2DW12 accelerometer (id=2)
        SensorLSM6DS3.ts        ← LSM6DS3 gyro+accel (id=3)
        SensorPPG.ts            ← PPG decoder (id=4)

tests/
  shimmer3r/
    calibration.test.ts
    protocol.test.ts
  verisense/
    crc.test.ts
    sensors.test.ts

License

BSD-3-Clause (see LICENSE).