incyclist-devices 2.0.0-beta.1 → 2.0.0

package/README.MD

@@ -0,0 +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)

package/lib/adapters.d.ts

@@ -2,5 +2,6 @@ import { IncyclistDeviceAdapter } from "./types/adapter";
 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

@@ -1,11 +1,24 @@
 "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;
@@ -19,6 +32,12 @@ class AdapterFactory {
             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);
+                break;
         }
         if (adapter) {
             adapters.push(adapter);

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

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

package/lib/antv2/adapter-factory.js

@@ -32,10 +32,12 @@ class AntAdapterFactory {
         let info;
         const { profile, protocol } = settings;
         if (protocol) {
-            info = this.getAdapter({ incyclistProfile: profile });
+            const incyclistProfile = profile;
+            info = this.getAdapter({ incyclistProfile });
         }
         else {
-            info = this.getAdapter({ antProfile: profile });
+            const antProfile = profile;
+            info = this.getAdapter({ antProfile });
         }
         if (info && info.Adapter)
             return new info.Adapter(settings, props);

package/lib/antv2/adapter.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { IChannel, ISensor } from 'incyclist-ant-plus';
+import { IChannel, ISensor, Profile } from 'incyclist-ant-plus';
 import AntInterface from './ant-interface';
 import IncyclistDevice from '../base/adpater';
 import { AntDeviceProperties, AntDeviceSettings } from './types';
@@ -41,7 +41,7 @@ export default class AntAdapter extends IncyclistDevice {
     getID(): string;
     getName(): string;
     getInterface(): string;
-    getProfile(): string;
+    getProfile(): Profile;
     startDataTimeoutCheck(): void;
     stopDataTimeoutCheck(): void;
     check(): Promise<boolean>;
@@ -54,6 +54,7 @@ export declare class ControllableAntAdapter extends AntAdapter implements Bike {
     cyclingMode: CyclingMode;
     user?: User;
     constructor(settings: AntDeviceSettings, props?: AntDeviceProperties);
+    isControllable(): boolean;
     setUser(user: User): void;
     setBikeProps(props: DeviceProperties): void;
     getWeight(): number;

package/lib/antv2/adapter.js

@@ -38,6 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ControllableAntAdapter = exports.DEFAULT_UPDATE_FREQUENCY = void 0;
 const ant_interface_1 = __importDefault(require("./ant-interface"));
 const adpater_1 = __importStar(require("../base/adpater"));
+const types_1 = require("./types");
 const utils_1 = require("../utils/utils");
 const capabilities_1 = require("../types/capabilities");
 const adpater_2 = require("../base/adpater");
@@ -49,6 +50,9 @@ class AntAdapter extends adpater_1.default {
     constructor(settings, props) {
         super(settings, props);
         this.startupRetryPause = 1000;
+        const antSettings = this.settings;
+        if ((0, types_1.isLegacyProfile)(antSettings.profile))
+            antSettings.profile = (0, utils_2.mapLegacyProfile)(antSettings.profile);
         if (this.settings.interface !== 'ant')
             throw new Error('Incorrect interface');
         this.sensor = this.createSensor(settings);
@@ -66,7 +70,7 @@ class AntAdapter extends adpater_1.default {
         const as = this.settings;
         if (as.interface !== settings.interface)
             return false;
-        if (as.deviceID != settings.deviceID || as.profile !== settings.profile)
+        if (as.deviceID !== settings.deviceID || as.profile !== settings.profile)
             return false;
         return true;
     }
@@ -100,7 +104,7 @@ class AntAdapter extends adpater_1.default {
         const { ManId } = this.deviceData;
         this.deviceData = Object.assign({}, deviceData);
         if (!ManId && deviceData.ManId) {
-            this.emit('device-info', { manufacturer: (0, utils_2.getBrand)(deviceData.ManId) });
+            this.emit('device-info', { device: this.getSettings(), manufacturer: (0, utils_2.getBrand)(deviceData.ManId) });
         }
     }
     waitForData(timeout) {
@@ -142,7 +146,11 @@ class AntAdapter extends adpater_1.default {
     }
     getProfile() {
         const settings = this.settings;
-        return settings.profile;
+        if (settings.protocol === undefined)
+            return settings.profile;
+        else {
+            return (0, utils_2.mapLegacyProfile)(settings.profile);
+        }
     }
     startDataTimeoutCheck() {
         if (this.ivDataTimeout)
@@ -245,13 +253,16 @@ class ControllableAntAdapter extends AntAdapter {
         this.cyclingMode = this.getDefaultCyclingMode();
         this.user = {};
     }
+    isControllable() {
+        return true;
+    }
     setUser(user) {
         this.user = user;
         if (!user.weight)
             this.user.weight = adpater_2.DEFAULT_USER_WEIGHT;
     }
     setBikeProps(props) {
-        const { user, userWeight, bikeWeight } = props || {};
+        const { user, userWeight } = props || {};
         if (user)
             this.setUser(user);
         if (userWeight)

package/lib/antv2/ant-interface.d.ts

@@ -9,6 +9,10 @@ import { AntDeviceSettings, AntScanProps } from "./types";
 export interface AntInterfaceProps extends InterfaceProps {
     startupTimeout?: number;
 }
+export interface ConnectState {
+    connected: boolean;
+    connecting: boolean;
+}
 export default class AntInterface extends EventEmitter implements IncyclistInterface {
     static _instance: AntInterface;
     static INTERFACE_NAME: string;
@@ -17,8 +21,7 @@ export default class AntInterface extends EventEmitter implements IncyclistInter
     protected logger: EventLogger;
     protected device: IAntDevice;
     protected Binding: typeof AntDeviceBinding;
-    protected isConnected: boolean;
-    protected isConnecting: boolean;
+    protected connectState: ConnectState;
     protected props: AntInterfaceProps;
     protected activeScan: IChannel;
     constructor(props: AntInterfaceProps);
@@ -27,6 +30,7 @@ export default class AntInterface extends EventEmitter implements IncyclistInter
     setBinding(binding: typeof AntDeviceBinding): void;
     setLogger(logger: EventLogger): void;
     logEvent(event: any): void;
+    isConnected(): boolean;
     connect(): Promise<boolean>;
     disconnect(): Promise<boolean>;
     onError(profile: any, error: any): void;

package/lib/antv2/ant-interface.js

@@ -28,8 +28,10 @@ class AntInterface extends events_1.default {
         super();
         this.props = props;
         this.device = undefined;
-        this.isConnected = false;
-        this.isConnecting = false;
+        this.connectState = {
+            connected: false,
+            connecting: false
+        };
         const { binding, logger } = props;
         if (logger)
             this.logger = logger;
@@ -56,38 +58,42 @@ class AntInterface extends events_1.default {
         if (this.logger)
             this.logger.logEvent(event);
     }
+    isConnected() {
+        return this.connectState.connected;
+    }
     connect() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.isConnected)
+            if (this.isConnected())
                 return true;
-            if (!this.isConnecting) {
-                this.isConnecting = true;
+            if (!this.connectState.connecting) {
+                this.connectState.connecting = true;
                 this.logEvent({ message: 'ANT+ connecting ...' });
                 try {
                     const device = new this.Binding(Object.assign(Object.assign({}, this.props), { logger: this.logger }));
                     const opened = yield device.open();
                     if (!opened) {
                         this.logEvent({ message: 'ANT+ not connected' });
-                        this.isConnecting = false;
+                        this.connectState.connecting = false;
                         return false;
                     }
                     this.device = device;
-                    this.isConnected = true;
-                    this.isConnecting = false;
+                    this.connectState.connected = true;
+                    this.connectState.connecting = false;
                     this.logEvent({ message: 'ANT+ connected' });
                     return true;
                 }
                 catch (err) {
-                    this.isConnected = false;
-                    this.isConnecting = false;
+                    this.logEvent({ message: 'error', fn: 'connect', error: err.message, stack: err.stack });
+                    this.connectState.connected = false;
+                    this.connectState.connecting = false;
                     return false;
                 }
             }
             else {
                 return new Promise(resolve => {
                     setInterval(() => {
-                        if (!this.isConnecting)
-                            resolve(this.isConnected);
+                        if (!this.connectState.connecting)
+                            resolve(this.connectState.connected);
                     }, 500);
                 });
             }
@@ -99,7 +105,7 @@ class AntInterface extends events_1.default {
                 return true;
             this.logEvent({ message: 'ANT+ disconnecting ...' });
             const closed = yield this.device.close();
-            this.isConnected = !closed;
+            this.connectState.connected = !closed;
             this.logEvent({ message: 'ANT+ disconnected' });
             return closed;
         });
@@ -114,16 +120,11 @@ class AntInterface extends events_1.default {
         return __awaiter(this, void 0, void 0, function* () {
             this.logEvent({ message: 'starting scan ..' });
             const detected = [];
-            if (!this.isConnected) {
-                const connected = yield this.connect();
-                if (!connected)
-                    return [];
-            }
             const onDetected = (profile, deviceID) => {
                 if (deviceID && detected.find(s => s.deviceID === deviceID && s.profile === profile) === undefined) {
                     try {
                         detected.push({ interface: this.getName(), profile, deviceID });
-                        this.emit('device', profile, deviceID);
+                        this.emit('device', { interface: 'ant', profile, deviceID });
                     }
                     catch (err) {
                         this.logEvent({ message: 'error', fn: 'onDerected', error: err.message, stack: err.stack });
@@ -132,6 +133,11 @@ class AntInterface extends events_1.default {
             };
             let channel;
             if (!this.activeScan) {
+                while (!this.isConnected()) {
+                    const connected = yield this.connect();
+                    if (!connected)
+                        return [];
+                }
                 channel = this.device.getChannel();
                 channel.setProps({ logger: this.logger });
                 if (!channel)
@@ -204,7 +210,7 @@ class AntInterface extends events_1.default {
     }
     startSensor(sensor, onDeviceData) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!this.isConnected) {
+            if (!this.isConnected()) {
                 const connected = yield this.connect();
                 if (!connected)
                     return false;
@@ -235,7 +241,7 @@ class AntInterface extends events_1.default {
     }
     stopSensor(sensor) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!this.isConnected || !this.device)
+            if (!this.isConnected() || !this.device)
                 return true;
             const channel = sensor.getChannel();
             if (channel) {

package/lib/antv2/binding.d.ts

@@ -2,7 +2,7 @@
 import { IAntDevice, IChannel } from 'incyclist-ant-plus';
 import { AntInterfaceProps } from './ant-interface';
 export default class AntDeviceBinding implements IAntDevice {
-    constructor(props: AntInterfaceProps);
+    constructor(_props: AntInterfaceProps);
     open(): Promise<boolean>;
     close(): Promise<boolean>;
     getMaxChannels(): number;

package/lib/antv2/binding.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 class AntDeviceBinding {
-    constructor(props) { }
+    constructor(_props) { }
     open() {
         throw new Error('Method not implemented.');
     }

package/lib/antv2/fe/adapter.d.ts

@@ -1,25 +1,28 @@
-import { ISensor } from "incyclist-ant-plus";
+import { FitnessEquipmentSensorState, ISensor, Profile } from "incyclist-ant-plus";
 import { ControllableAntAdapter } from "../adapter";
-import CyclingMode, { IncyclistBikeData } from '../../modes/cycling-mode';
-import { AntDeviceProperties, AntDeviceSettings } from "../types";
+import CyclingMode, { IncyclistBikeData, UpdateRequest } from '../../modes/cycling-mode';
+import { AntDeviceProperties, AntDeviceSettings, LegacyProfile } from "../types";
 export default class AntFEAdapter extends ControllableAntAdapter {
-    static INCYCLIST_PROFILE_NAME: string;
-    static ANT_PROFILE_NAME: string;
+    static INCYCLIST_PROFILE_NAME: LegacyProfile;
+    static ANT_PROFILE_NAME: Profile;
     protected distanceInternal?: number;
     protected startProps: AntDeviceProperties;
     protected isReconnecting: boolean;
     constructor(settings: AntDeviceSettings, props?: AntDeviceProperties);
     createSensor(settings: AntDeviceSettings): ISensor;
     getName(): string;
+    getUniqueName(): string;
     getDisplayName(): string;
     getSupportedCyclingModes(): Array<any>;
     getDefaultCyclingMode(): CyclingMode;
     getLogData(data: any, excludeList: any): any;
-    sendUpdate(request: any): Promise<void>;
-    onDeviceData(deviceData: any): void;
-    mapData(deviceData: any): IncyclistBikeData;
-    transformData(bikeData: any): any;
+    sendUpdate(request: UpdateRequest, forced?: boolean): Promise<void>;
+    onDeviceData(deviceData: FitnessEquipmentSensorState): void;
+    canSendUpdate(): boolean;
+    mapToCycleModeData(deviceData: FitnessEquipmentSensorState): IncyclistBikeData;
+    transformData(bikeData: IncyclistBikeData): any;
     start(props?: any): Promise<any>;
     setFEDefaultTimeout(): void;
     reconnect(): Promise<boolean>;
+    setCyclingMode(mode: string | CyclingMode, settings?: any): void;
 }