# eChip WebUSB Library

# Overview

This development documentation outlines the use of the Keiser eChip as a means of collecting workout information from Keiser Strength and Functional equipment. The library is written in TypeScript and supports modern browsers with WebUSB support.

# Requirements

In order to use the eChip, equipment must have the Power Display with the eChip slot in the bottom right corner. Data that exists on the eChip that pre-dates the current time by at least 2 hours will be displayed on the display as "target" data.

Required Hardware: USB to 1-Wire/iButton Adapter (DS9490)

Required Drivers: 1-Wire/iButton Drivers for Windows

# Installation

Install with npm: npm install @keiser/echip-webusb

# Initialization

Import singleton instance from module using preferred module loading technique.

import ChipReaderWatcher from '@keiser/echip-webusb'

if (ChipReaderWatcher.isConnected) {
  console.log('Chip Reader Connected 😄')
}

The ChipReaderWatcher handles permissions and USB connection events. On first load, the browser will not have provided a grant to the site to access the USB device, so the ChipReaderWatcher.start() method must be called by an event that originates from a user action. This may only be required once on the first visit to the site, or it may be required each time the site is loaded based on browser vendors preferred implementation.

connectButton.addEventListener('click', async () => {
  try {
    await ChipReaderWatcher.start()
  } catch (error) {
    console.error(error.message)
  }
})

Once the ChipReaderWatcher.start() method has been called the class will prompt the browser for permission and begin watching for devices matching the Chip Readers device signature. To be alerted when a device is found, pass a function to the ChipReaderWatcher.onConnect() method.

ChipReaderWatcher.onConnect((chipReader) => {
  console.log('Chip Reader Connected 😄')
})

The ChipReaderWatcher.onConnect() will pass in a ChipReader object which is the object bound to the physical device connected. This library is capable of handling multiple Chip Reader devices simultaneously, so the onConnect() method has potential for returning multiple ChipReader devices over the course of the application's life.

chipReader.onDisconnect(() => {
  console.log('Chip Reader Disconnected 😞')
})

The ChipReader object has an onDisconnect() method which will alert when the Chip Reader has been disconnected for some reason. Once a ChipReader object has been disconnected, it is disposed and cannot be used again. The next time the device is connected, a new ChipReader object will be returned.

chipReader.onChipDetect(async (chip) => {
  console.log('Chip Connected: ' + chip.id)
  if (chip instanceof DataChip) {
    chip.onData(data => console.log(data))
  }
})

The ChipReader object also has an onChipDetect() method which will alert when a valid chip has been placed into the reader. The event passes in a Chip object that can be used to interact with the chip data directly. Just like the ChipReaderWatcher.onConnect() method, the ChipReader.onChipDetect() method can be called multiple times for multiple chips all being handled concurrently. Once a chip is disconnected, the Chip object is disposed and cannot be reused.

# Example

import ChipReaderWatcher, { DataChip } from '@keiser/echip-webusb'

document.addEventListener('DOMContentLoaded', event => {
  const connectButton = document.querySelector('#connect') as HTMLInputElement

  if (connectButton) {
    connectButton.addEventListener('click', async () => {
      try {
        await ChipReaderWatcher.start()
      } catch (error) {
        console.error(error.message)
      }
    })
  }

  ChipReaderWatcher.onConnect((chipReader) => {
    console.log('Chip Reader Connected 😄')

    chipReader.onChipDetect(async (chip) => {
      console.log('Chip Connected: ' + chip.id)
      if (chip instanceof DataChip) {
        chip.onData(data => console.log(data))
      }
    })

    chipReader.onDisconnect(() => {
      console.log('Chip Reader Disconnected 😞')
    })
  })
})

# eChip Capabilities

A single eChip is capable of holding 200 workout sets worth of data from 24 distinct machines. If the eChip is full, machines will replace the oldest workout record on the eChip with new data. It is recommended to completely clear the eChip between uses and to only write the data required for targeting during the current workout session.

# API

# ChipReaderWatcher

The ChipReaderWatcher is a singleton class which handles the USB device monitoring and permissions handling. There can be only one ChipReaderWatcher instance created within a window scope, so the library instantiates the class during import and preserves a single instance for all imports.

# Properties

# Methods

# ChipReader

The ChipReader instance is passed into the onConnect callback function and is the interface to the connected Chip Reader device.

# Properties

# Methods

# BaseChip

The BaseChip instance is passed into the onChipDetect callback function and is the interface to the connected chip device. There are several different extensions to the base BaseChip object that can identified by doing a instanceOf check or looking at the type property.

# Properties

# Methods

# TZChip and RTCChip

The TZChip and RTCChip are class extensions on the BaseChip class. They add no additional properties or methods, but allow the identification of chip type and will perform chip set operations automatically when detected. An event issued on the onData event indicates that the chips data has been successfully updated.

# DataChip

The DataChip class extension on the BaseChip class adds additional properties and methods specific to the data chip.

# Methods

# Data Structures

# ChipObject

interface ChipObject {
  type: ChipType
}

# DataChipObject

interface DataChipObject {
  type: ChipType
  machineData: {[index: string]: MachineObject}
  rawData: Uint8Array[]
  validStructure: boolean
}

# MachineObject

interface MachineObject {
  position: MachinePosition
  sets: MachineSet[]
}

# MachinePosition

interface MachinePosition {
  chest: number | null
  rom2: number | null
  rom1: number | null
  seat: number | null
}

# MachineSet

interface MachineSet {
  version: string
  serial: string
  time: string
  resistance: number
  precision: Precision
  units: ForceUnit
  repetitions: number
  peak: number | null
  work: number | null
  distance: number | null
  chest: number | null
  rom2: number | null
  rom1: number | null
  seat: number | null
  test: MachineTest | null
}

# MachineTest

interface MachineTest {
  type: TestType
  high: MachineTestResult | null
  low: MachineTestResult | null
}

# MachineTestResult

interface MachineTestResult {
  power: number
  velocity: number
  force: number
  position: number
}

# Constants

enum Precision {
  dec = 'dec',
  int = 'int'
 }

enum ForceUnit {
  lb = 'lb',
  kg = 'kg',
  ne = 'ne',
  er = 'er'
}

enum TestType {
  power6r = 'power6r',
  a4206r = 'a4206r',
  a42010r = 'a42010r'
}

enum ChipType {
  dataChip = 12,
  rtcChip = 36,
  tzChip = 45,
  unknown = 0
}

# Development Tools

# Keiser Air Documentation

# Agreements and Guidelines

The Keiser eChip WebUSB Library source code and library package are made available through the MIT license.

Using any of this library in connection with any Keiser eChip enabled equipment make you subject to the following agreements. Please read all documents in their entirety as they govern your use of the APIs.

• API Agreement
• Brand Guidelines for Developers