incyclist-devices 2.1.14 → 2.1.16

package/README.MD

@@ -1,238 +1,238 @@
-# incyclist-devices
-
-Library used by the [Incyclist](https://incyclist.com) Indoor Cycling App to communicate with devices (Smart Trainers,  Sensors)
-
-It currently support the following Interfaces/Devices
-
-__ANT__
-- Smart Trainers (ANT+ FE)
-- Power Meters (ANT+PWR)
-- Heartrate Monitors (ANT+HR)
-
-__BLE__
-- Smart Trainers (BLE FTMS)
-- Power Meters (BLE CP)
-- Heartrate Monitors (BLE HR)
-- Wahoo Smart Trainers (Wahoo specific service)
-- Tacx FE-C over BLE
-
-__Serial__
-- Daum Classic Ergo Bikes
-- Daum Premium Ergo Bikes  (also over TCP/IP)
-- Kettler Ergo Racer Ergo Bikes
-
-
-## Install
-
-```sh
-npm install incyclist-devices
-```
-
-## Usage
-
-### Setup Interfaces and Bindings
-
-`Interface` classes are used to enable basic communication (transport layer).
-
-As this library supports various OS( Linux, Windows, Mac) and Incyclist is based on Electron, which requires to clearly separate between rendering and main process, Bindings need to be provided for each of the Interfaces. The specifications of these bindings are specific to the interface: 
-- Ant: specified by the [incyclist-ant-plus](https://github.com/incyclist/ant-plus) library
-- Serial: specified by the [serialport](https://serialport.io/) library
-- BLE: specified by the [noble](https://github.com/noble/noble) library
-
-__Ant Example__
-
-```
-const {EventLogger,ConsoleAdapter} = require( 'gd-eventlog');
-const {AntDevice} = require('incyclist-ant-plus/lib/bindings');
-
-const logger = new EventLogger('AntSample')
-const ant = InterfaceFactory.create('ant',{logger, log:true, binding:AntDevice})
-```
-
-__Serial Example__
-
-```
-const {EventLogger,ConsoleAdapter} = require( 'gd-eventlog');
-const { autoDetect } = require('@serialport/bindings-cpp')
-
-
-const logger = new EventLogger('SerialSample')
-const serial = InterfaceFactory.create('serial',{logger, log:true, binding:autodetect()})
-```
-
-__BLE Example__
-
-```
-const {EventLogger,ConsoleAdapter} = require( 'gd-eventlog');
-const {WinrtBindings} = require('./bindings')
-const Noble = require('noble/lib/noble');
-
-
-const noble = new Noble(new WinrtBindings())
-const logger = new EventLogger('BLESample')
-const ble = InterfaceFactory.create('ble',{logger, log:true, binding:noble})
-```
-
-### Check availability of interface
-
-For some interfaces (ANT and BLE) it cannot be guaranteed that the underlying hardware supports the interface ( e.g. a USB stick might be required). Therefore this library offers a `connect` method, that allows to check if the interface is availabe
-
-__Ant Example__
-```
-    const connected = await ant.connect() // tries to establish communication and blocks USB stick for usage with other apps
-    if (connect) {
-        .... 
-        await ant.disconnect() // closes communication and unblocks USB stick
-    }
-    else {
-        ... 
-    }
-```
-
-### Scan for devices
-
-Every interface offers a method `scan` that allows to scan for devices. The timeout for the scan can be specified in the properties. If those are not provided, a default will apply.
-
-The scan method returns a `Promise<DeviceSettings[]>` containing the settings of all detected devices. 
-
-In addition to that, all devices that are detected, will be emitted as `device` event during the scan.
-
-The method `stopScan`can be used to stop an ongoing scan.
-
-__Examples__
-
-- Example 1: wait for teh result of the scan
-
-    ```
-    _interface.on('device',(deviceSettings:DeviceSettings)=>{console.log('Device found', DeviceSettings)})
-    const devices = await _interface_.scan({timeout:20000})
-    console.log(devices)
-    ```
-- Example 2: stop scan as soon as one device was found
-
-    ```
-    _interface.on('device',async (deviceSettings:DeviceSettings)=>{
-        console.log('Device found', DeviceSettings)
-        await _interface.stopScan()
-    })
-    _interface_.scan({timeout:20000})    
-    ```
-
-
-
-### Create a device 
-
-The Devices library provides and `AdapterFactory`, which allows you to create a device adapters, based on the specifications provided in a `DeviceSettings` object. 
-
-The exact content if this object varies between the interfaces:
-
-- __Ant__: interface ('ant'), profile( one of 'HR','PWR', 'FE'), deviceID
-
-- __BLE__: interface ('ble'), protocol( one of 'fm','cp,'hr', 'tacx', 'wahoo'), name, id or address
-
-- __Serial__: interface('serial' or 'tcpip'), protocol( one of 'Daum Premium', 'Daum Classic', 'Kettler Racer'), name, port, host (only for TCP/IP)
-
-These device adapters are used by Incyclist to communicate with the devices. The AdapterFactory will ensure that for a given device only one instance of a device adapter will be provided, to avoid that two classes will concurrently communicate with the same physical device.
-
-At the point where a device adapter is created, the constructor will _not_ try to communicate with the device. I.e. the adapter can be created even if no such device is available/connected.
-
-__Example__
-
-```
-const {AdapterFactory} = require('incyclist-devices')
-
-const device = AdapterFactory.create({interface:'ble, protocol:'fm', name:'KICKR BIKE 1234'})
-```
-
-
-
-### Communicate with a device
-
-In order to commuicate with the device, the device firstly has to be started
-
-
-#### __start( props?: DeviceProperties):Promise\<boolean\>__
-
-
-you then should register for events:
-
-- __data__ (device:DeviceSettings, data: DeviceData): is emitted whenever a device/sensor has sent data 
-    - device: describes the device that has sent data
-    - data: provides the data that the device/sensor has provided (power, speed, cadence,slope, heartrate, timestamp,... )
-
-- __disconnected__ (device:DeviceSettings): is emitted when the library has not recieved any udate for a configurable time or the underlying interface has recognized a connection loss
-    - device: describes the device that has sent data
-
-- __device-info__- (device:DeviceSettings, info:): signals that additional information about the device was received ( e.g. manufacturer, additional features/capabilities)
-    - device: describes the device that has sent data
-
-
-```
-try {
-    await device.start({timeout:5000, userWeight:90,bikeWeight:10})
-    device.on('data',(deviceInfo,data)=> { console.log('device data', deviceInfo,data) })
-    device.on('disconnected',(deviceInfo)=> { 
-        console.log('device disconnected', deviceInfo) 
-        // check if reconnect makes sense
-        device.disconnect()
-    })
-}
-catch(err) {
-    console.log('device could not be started, reason', err.message)
-}
-```
-
-#### __setMaxUpdateFrequency(ms:number):void__
-#### __getMaxUpdateFrequency():number__
-
-BLE and ANT devices might send data more frequently than you mihgt want to process in your app. Therefore you can control how often you want to receive updates from a device. 
-
-Default value is 1s
-
-A value of -1 indicates that the app wants to receive any data without delays
-
-```
-device.setMaxUpdateFrequency(1000) // send update every 1000ms
-const updateFrequency = device.getMaxUpdateFrequency()
-```
-
-
-#### __setPullFrequency(ms:number):void__
-#### __getPullFrequency():number__
-
-Serial Devices are typically not automatically sending data, but the app has to actively pull. Therefore the Serial device adapters also offer the capability to control how often the library will pull data from the device
-
-Default value is 1s
-
-_Warning_: Setting this value to low might overload the serial port and you might not receive any data
-
-#### __stop():Promise\<boolean\>__
-
-Once the commeunication is not required anymore, you can call stop() to close the connection. This will also automatically unregister the event listeners. 
-
-
-#### __pause():Promise\<boolean\>__
-#### __resume():Promise\<boolean\>__
-
-In some cases it might sense to not further receive any update from the device, but still keep the communication open. In thise case, pause() and resume() can be called. 
-
-During a paused state, no event will be emitted
-
-#### __sendUpdate(request:UpdateRequest):Promise\<boolean\>__
-
-Allows to send data to the device, typically one of the following data will be sent
-
-__slope__: (SIM Mode) sets the slope/incline. The smart trainer then will adjust power accordingly
-
-__targetPower__: (ERG Mode) sets the power that the smart trainer should 
-
-__reset__: returns to the default settings at the start of the training
-
-__resfresh__: repeats the previous update
-
-This method should only be called for SmartTrainers or PowerMeters
-
-
-## Examples
-
-Please have a look at the [example code](./samples)
+# incyclist-devices
+
+Library used by the [Incyclist](https://incyclist.com) Indoor Cycling App to communicate with devices (Smart Trainers,  Sensors)
+
+It currently support the following Interfaces/Devices
+
+__ANT__
+- Smart Trainers (ANT+ FE)
+- Power Meters (ANT+PWR)
+- Heartrate Monitors (ANT+HR)
+
+__BLE__
+- Smart Trainers (BLE FTMS)
+- Power Meters (BLE CP)
+- Heartrate Monitors (BLE HR)
+- Wahoo Smart Trainers (Wahoo specific service)
+- Tacx FE-C over BLE
+
+__Serial__
+- Daum Classic Ergo Bikes
+- Daum Premium Ergo Bikes  (also over TCP/IP)
+- Kettler Ergo Racer Ergo Bikes
+
+
+## Install
+
+```sh
+npm install incyclist-devices
+```
+
+## Usage
+
+### Setup Interfaces and Bindings
+
+`Interface` classes are used to enable basic communication (transport layer).
+
+As this library supports various OS( Linux, Windows, Mac) and Incyclist is based on Electron, which requires to clearly separate between rendering and main process, Bindings need to be provided for each of the Interfaces. The specifications of these bindings are specific to the interface: 
+- Ant: specified by the [incyclist-ant-plus](https://github.com/incyclist/ant-plus) library
+- Serial: specified by the [serialport](https://serialport.io/) library
+- BLE: specified by the [noble](https://github.com/noble/noble) library
+
+__Ant Example__
+
+```
+const {EventLogger,ConsoleAdapter} = require( 'gd-eventlog');
+const {AntDevice} = require('incyclist-ant-plus/lib/bindings');
+
+const logger = new EventLogger('AntSample')
+const ant = InterfaceFactory.create('ant',{logger, log:true, binding:AntDevice})
+```
+
+__Serial Example__
+
+```
+const {EventLogger,ConsoleAdapter} = require( 'gd-eventlog');
+const { autoDetect } = require('@serialport/bindings-cpp')
+
+
+const logger = new EventLogger('SerialSample')
+const serial = InterfaceFactory.create('serial',{logger, log:true, binding:autodetect()})
+```
+
+__BLE Example__
+
+```
+const {EventLogger,ConsoleAdapter} = require( 'gd-eventlog');
+const {WinrtBindings} = require('./bindings')
+const Noble = require('noble/lib/noble');
+
+
+const noble = new Noble(new WinrtBindings())
+const logger = new EventLogger('BLESample')
+const ble = InterfaceFactory.create('ble',{logger, log:true, binding:noble})
+```
+
+### Check availability of interface
+
+For some interfaces (ANT and BLE) it cannot be guaranteed that the underlying hardware supports the interface ( e.g. a USB stick might be required). Therefore this library offers a `connect` method, that allows to check if the interface is availabe
+
+__Ant Example__
+```
+    const connected = await ant.connect() // tries to establish communication and blocks USB stick for usage with other apps
+    if (connect) {
+        .... 
+        await ant.disconnect() // closes communication and unblocks USB stick
+    }
+    else {
+        ... 
+    }
+```
+
+### Scan for devices
+
+Every interface offers a method `scan` that allows to scan for devices. The timeout for the scan can be specified in the properties. If those are not provided, a default will apply.
+
+The scan method returns a `Promise<DeviceSettings[]>` containing the settings of all detected devices. 
+
+In addition to that, all devices that are detected, will be emitted as `device` event during the scan.
+
+The method `stopScan`can be used to stop an ongoing scan.
+
+__Examples__
+
+- Example 1: wait for teh result of the scan
+
+    ```
+    _interface.on('device',(deviceSettings:DeviceSettings)=>{console.log('Device found', DeviceSettings)})
+    const devices = await _interface_.scan({timeout:20000})
+    console.log(devices)
+    ```
+- Example 2: stop scan as soon as one device was found
+
+    ```
+    _interface.on('device',async (deviceSettings:DeviceSettings)=>{
+        console.log('Device found', DeviceSettings)
+        await _interface.stopScan()
+    })
+    _interface_.scan({timeout:20000})    
+    ```
+
+
+
+### Create a device 
+
+The Devices library provides and `AdapterFactory`, which allows you to create a device adapters, based on the specifications provided in a `DeviceSettings` object. 
+
+The exact content if this object varies between the interfaces:
+
+- __Ant__: interface ('ant'), profile( one of 'HR','PWR', 'FE'), deviceID
+
+- __BLE__: interface ('ble'), protocol( one of 'fm','cp,'hr', 'tacx', 'wahoo'), name, id or address
+
+- __Serial__: interface('serial' or 'tcpip'), protocol( one of 'Daum Premium', 'Daum Classic', 'Kettler Racer'), name, port, host (only for TCP/IP)
+
+These device adapters are used by Incyclist to communicate with the devices. The AdapterFactory will ensure that for a given device only one instance of a device adapter will be provided, to avoid that two classes will concurrently communicate with the same physical device.
+
+At the point where a device adapter is created, the constructor will _not_ try to communicate with the device. I.e. the adapter can be created even if no such device is available/connected.
+
+__Example__
+
+```
+const {AdapterFactory} = require('incyclist-devices')
+
+const device = AdapterFactory.create({interface:'ble, protocol:'fm', name:'KICKR BIKE 1234'})
+```
+
+
+
+### Communicate with a device
+
+In order to commuicate with the device, the device firstly has to be started
+
+
+#### __start( props?: DeviceProperties):Promise\<boolean\>__
+
+
+you then should register for events:
+
+- __data__ (device:DeviceSettings, data: DeviceData): is emitted whenever a device/sensor has sent data 
+    - device: describes the device that has sent data
+    - data: provides the data that the device/sensor has provided (power, speed, cadence,slope, heartrate, timestamp,... )
+
+- __disconnected__ (device:DeviceSettings): is emitted when the library has not recieved any udate for a configurable time or the underlying interface has recognized a connection loss
+    - device: describes the device that has sent data
+
+- __device-info__- (device:DeviceSettings, info:): signals that additional information about the device was received ( e.g. manufacturer, additional features/capabilities)
+    - device: describes the device that has sent data
+
+
+```
+try {
+    await device.start({timeout:5000, userWeight:90,bikeWeight:10})
+    device.on('data',(deviceInfo,data)=> { console.log('device data', deviceInfo,data) })
+    device.on('disconnected',(deviceInfo)=> { 
+        console.log('device disconnected', deviceInfo) 
+        // check if reconnect makes sense
+        device.disconnect()
+    })
+}
+catch(err) {
+    console.log('device could not be started, reason', err.message)
+}
+```
+
+#### __setMaxUpdateFrequency(ms:number):void__
+#### __getMaxUpdateFrequency():number__
+
+BLE and ANT devices might send data more frequently than you mihgt want to process in your app. Therefore you can control how often you want to receive updates from a device. 
+
+Default value is 1s
+
+A value of -1 indicates that the app wants to receive any data without delays
+
+```
+device.setMaxUpdateFrequency(1000) // send update every 1000ms
+const updateFrequency = device.getMaxUpdateFrequency()
+```
+
+
+#### __setPullFrequency(ms:number):void__
+#### __getPullFrequency():number__
+
+Serial Devices are typically not automatically sending data, but the app has to actively pull. Therefore the Serial device adapters also offer the capability to control how often the library will pull data from the device
+
+Default value is 1s
+
+_Warning_: Setting this value to low might overload the serial port and you might not receive any data
+
+#### __stop():Promise\<boolean\>__
+
+Once the commeunication is not required anymore, you can call stop() to close the connection. This will also automatically unregister the event listeners. 
+
+
+#### __pause():Promise\<boolean\>__
+#### __resume():Promise\<boolean\>__
+
+In some cases it might sense to not further receive any update from the device, but still keep the communication open. In thise case, pause() and resume() can be called. 
+
+During a paused state, no event will be emitted
+
+#### __sendUpdate(request:UpdateRequest):Promise\<boolean\>__
+
+Allows to send data to the device, typically one of the following data will be sent
+
+__slope__: (SIM Mode) sets the slope/incline. The smart trainer then will adjust power accordingly
+
+__targetPower__: (ERG Mode) sets the power that the smart trainer should 
+
+__reset__: returns to the default settings at the start of the training
+
+__resfresh__: repeats the previous update
+
+This method should only be called for SmartTrainers or PowerMeters
+
+
+## Examples
+
+Please have a look at the [example code](./samples)

package/lib/adapters.d.ts

@@ -0,0 +1,7 @@
+import { IncyclistDeviceAdapter } from "./base/adpater";
+import { DeviceProperties, DeviceSettings } from "./types/device";
+export default class AdapterFactory {
+    static adapters: IncyclistDeviceAdapter[];
+    static reset(): void;
+    static create(settings: DeviceSettings, props?: DeviceProperties): any;
+}

package/lib/adapters.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const antv2_1 = require("./antv2");
+const ble_1 = require("./ble");
+const serial_1 = require("./serial");
+const Simulator_1 = require("./simulator/Simulator");
+const device_1 = require("./types/device");
+class AdapterFactory {
+    static reset() {
+        AdapterFactory.adapters = [];
+        ble_1.BleAdapterFactory.getInstance().instances = [];
+    }
+    static create(settings, props) {
+        const adapters = AdapterFactory.adapters;
+        if (!settings.interface && settings.protocol === 'Simulator') {
+            const adapter = new Simulator_1.Simulator(settings);
+            if (adapter) {
+                adapters.push(adapter);
+            }
+            return adapter;
+        }
+        const existing = adapters.find(a => a.isEqual(settings));
+        if (existing)
+            return existing;
+        const ifaceName = typeof settings.interface === 'string' ? settings.interface : settings.interface.getName();
+        let adapter;
+        switch (ifaceName) {
+            case device_1.INTERFACE.SERIAL:
+            case device_1.INTERFACE.TCPIP:
+                adapter = serial_1.SerialAdapterFactory.getInstance().createInstance(settings, props);
+                break;
+            case device_1.INTERFACE.ANT:
+                adapter = antv2_1.AntAdapterFactory.getInstance().createInstance(settings, props);
+                break;
+            case device_1.INTERFACE.BLE:
+                adapter = ble_1.BleAdapterFactory.getInstance().createInstance(settings, props);
+                break;
+            case device_1.INTERFACE.SIMULATOR:
+                adapter = new Simulator_1.Simulator(settings, props);
+                break;
+        }
+        if (adapter) {
+            adapters.push(adapter);
+        }
+        return adapter;
+    }
+}
+AdapterFactory.adapters = [];
+exports.default = AdapterFactory;

package/lib/antv2/adapter-factory.d.ts

@@ -0,0 +1,14 @@
+import { Profile } from "incyclist-ant-plus";
+import AntAdapter from "./base/adapter";
+import { AntDeviceProperties, AntDeviceSettings, LegacyProfile, BaseDeviceData } from "./types";
+import { AntAdapterInfo, AdapterQuery } from "./types";
+export default class AntAdapterFactory {
+    static _instance: AntAdapterFactory;
+    adapters: AntAdapterInfo[];
+    static getInstance(): AntAdapterFactory;
+    constructor();
+    register<TDeviceData extends BaseDeviceData>(antProfile: Profile, incyclistProfile: LegacyProfile, Adapter: typeof AntAdapter<TDeviceData>): void;
+    getAdapter(query?: AdapterQuery): any;
+    createInstance(settings: AntDeviceSettings, props?: AntDeviceProperties): any;
+    createFromDetected(profile: Profile, deviceID: number, props?: AntDeviceProperties): any;
+}

package/lib/antv2/adapter-factory.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class AntAdapterFactory {
+    static getInstance() {
+        if (!AntAdapterFactory._instance)
+            AntAdapterFactory._instance = new AntAdapterFactory();
+        return AntAdapterFactory._instance;
+    }
+    constructor() {
+        this.adapters = [];
+    }
+    register(antProfile, incyclistProfile, Adapter) {
+        const info = Object.assign({}, { antProfile, incyclistProfile, Adapter });
+        const existing = this.adapters.findIndex(a => a.antProfile === antProfile);
+        if (existing !== -1)
+            this.adapters[existing] = info;
+        else
+            this.adapters.push(info);
+    }
+    getAdapter(query) {
+        const { antProfile, incyclistProfile } = query;
+        if (!antProfile && !incyclistProfile)
+            throw new Error('Illegal arguments: either "antProfile" or "incyclistProfile" must be set');
+        let found;
+        if (antProfile)
+            found = this.adapters.find(a => a.antProfile === antProfile);
+        if (incyclistProfile)
+            found = this.adapters.find(a => a.incyclistProfile === incyclistProfile);
+        return found;
+    }
+    createInstance(settings, props) {
+        let info;
+        const { profile, protocol } = settings;
+        let isLegacy = false;
+        if (protocol) {
+            try {
+                const incyclistProfile = profile;
+                info = this.getAdapter({ incyclistProfile });
+                isLegacy = true;
+            }
+            catch (_a) {
+                isLegacy = false;
+            }
+        }
+        if (!isLegacy) {
+            const antProfile = profile;
+            info = this.getAdapter({ antProfile });
+        }
+        if (info && info.Adapter)
+            return new info.Adapter(settings, props);
+    }
+    createFromDetected(profile, deviceID, props) {
+        const info = this.getAdapter({ antProfile: profile });
+        if (!info || !info.Adapter)
+            return;
+        const settings = Object.assign({}, {
+            profile: info.incyclistProfile,
+            deviceID: deviceID.toString(),
+            interface: 'ant',
+            protocol: 'Ant'
+        });
+        return new info.Adapter(settings, props);
+    }
+}
+exports.default = AntAdapterFactory;

package/lib/antv2/adapter.d.ts

@@ -0,0 +1,54 @@
+/// <reference types="node" />
+import { IChannel, ISensor, Profile } from 'incyclist-ant-plus';
+import AntInterface from './ant-interface';
+import IncyclistDevice from '../base/adpater';
+import { AntDeviceProperties, AntDeviceSettings, BaseDeviceData } from './types';
+import { IAdapter, IncyclistAdapterData, IncyclistBikeData } from '../types';
+export default class AntAdapter<TDeviceData extends BaseDeviceData> extends IncyclistDevice<AntDeviceProperties> {
+    sensor: ISensor;
+    data: IncyclistAdapterData;
+    deviceData: TDeviceData;
+    updateFrequency: number;
+    channel: IChannel;
+    ant: AntInterface;
+    userSettings: {
+        weight?: number;
+    };
+    bikeSettings: {
+        weight?: number;
+    };
+    onDataFn: (data: IncyclistAdapterData) => void;
+    startupRetryPause: number;
+    protected ivDataTimeout: NodeJS.Timeout;
+    protected lastDataTS: number;
+    protected dataMsgCount: number;
+    protected ivWaitForData: NodeJS.Timeout;
+    constructor(settings: AntDeviceSettings, props?: AntDeviceProperties);
+    createSensor(settings: AntDeviceSettings): ISensor;
+    isEqual(settings: AntDeviceSettings): boolean;
+    connect(): Promise<boolean>;
+    close(): Promise<boolean>;
+    resetData(): void;
+    isSame(device: IAdapter): boolean;
+    hasData(): boolean;
+    mapData(deviceData: TDeviceData): IncyclistBikeData;
+    transformData(data: IncyclistBikeData): void;
+    mapToAdapterData(deviceData: any): void;
+    onDeviceData(deviceData: TDeviceData): void;
+    isWaitingForData(): boolean;
+    waitForData(timeout: number): Promise<boolean>;
+    getID(): string;
+    getName(): string;
+    getInterface(): string;
+    getProfile(): Profile;
+    getLogData(data: any, excludeList: any): any;
+    triggerTimeoutCheck(): void;
+    startDataTimeoutCheck(): void;
+    stopDataTimeoutCheck(): void;
+    check(): Promise<boolean>;
+    checkCapabilities(): Promise<void>;
+    initControl(): Promise<void>;
+    sendUpdate(request: any): void;
+    start(props?: AntDeviceProperties): Promise<boolean>;
+    stop(): Promise<boolean>;
+}