motion-master-client 0.0.76 → 0.0.85

package/README.md

@@ -1,138 +1,227 @@
-# Motion Master Client
-
-Motion Master Client is a library and CLI program written in [TypeScript](https://www.typescriptlang.org). It is used for communicating with Motion Master process over [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) connections by exchanging [Protocol Buffers](https://developers.google.com/protocol-buffers) serialized messages.
-
-## Installation
-
-```sh
-npm install motion-master-client
-```
-
-## Usage
-
-```ts
-const reqResSocket = new MotionMasterReqResWebSocket();
-const pubSubSocket = new MotionMasterPubSubWebSocket();
-
-const client = new MotionMasterClient(reqResSocket, pubSubSocket);
-
-const clientId = v4();
-reqResSocket.open(`ws://oblac-drives-7dc95497.local:63524?clientId=${clientId}`);
-pubSubSocket.open(`ws://oblac-drives-7dc95497.local:63525?clientId=${clientId}`);
-
-client.request.getDeviceInfo().subscribe(console.log);
-```
-
-## Class Diagrams
-
-```mermaid
----
-title: Client & socket classes
----
-classDiagram
-  class MotionMasterClient {
-    +MotionMasterReqResClient request
-    +MotionMasterPubSubClient monitor
-    +startMonitoring()
-    +stopMonitoring()
-  }
-  
-  class MotionMasterReqResClient {
-    +MotionMasterReqResSocket socket
-    note "Has all the request methods\ncorresponding to the proto file."
-  }
-
-  class MotionMasterReqResSocket
-  <<interface>> MotionMasterReqResSocket
-  MotionMasterReqResSocket: +BehaviorSubject~boolean~ opened\$
-  MotionMasterReqResSocket: +BehaviorSubject~boolean~ alive\$
-  MotionMasterReqResSocket: +Observable~MotionMasterMessage~ message\$
-  MotionMasterReqResSocket: +open(string url, number pingSystemInterval?, number systemAliveTimeout?)
-  MotionMasterReqResSocket: +close()
-  MotionMasterReqResSocket: +send(MotionMasterMessage message)
-  
-  class MotionMasterReqResWebSocket {
-    note "Keeps the connection alive by\nsending the ping system messages\nin regular intervals."
-  }
-  
-  class MotionMasterReqResWorkerSocket {
-    +Worker worker
-    note "Passes messages between\nthe UI and worker thread."
-  }
-
-  class MotionMasterPubSubClient {
-    +MotionMasterPubSubSocket socket
-    +Subject<[string, MotionMasterMessage[]]> data\$
-    +Observable~MotionMasterMessage~ notification\$
-    +Observable~MotionMasterMessage~ systemEvent\$
-    +Observable~MotionMasterMessage~ deviceEvent\$
-    +subscribe(MonitoringConfig config)
-    +unsubscribe(string messageId)
-    +unsubscribeAll()
-  }
-
-  class MotionMasterPubSubSocket
-  <<interface>> MotionMasterPubSubSocket
-  MotionMasterPubSubSocket: +BehaviorSubject~boolean~ opened\$
-  MotionMasterPubSubSocket: +Observable<[string, MotionMasterMessage]> data\$
-  MotionMasterPubSubSocket: +open(string url)
-  MotionMasterPubSubSocket: +close()
-
-  class MotionMasterPubSubWebSocket {
-    note "Deserializes incoming data into\na tuple of topic and message."
-  }
-  
-  class MotionMasterPubSubWorkerSocket {
-    +Worker worker
-    note "Passes messages between\nthe UI and worker thread."
-  }
-
-  MotionMasterClient *-- MotionMasterReqResClient
-  MotionMasterClient *-- MotionMasterPubSubClient
-
-  MotionMasterReqResClient *-- MotionMasterReqResSocket
-  MotionMasterReqResWebSocket <|-- MotionMasterReqResSocket
-  MotionMasterReqResWorkerSocket <|-- MotionMasterReqResSocket
-  
-  MotionMasterPubSubClient *-- MotionMasterPubSubSocket
-  MotionMasterPubSubWebSocket <|-- MotionMasterPubSubSocket
-  MotionMasterPubSubWorkerSocket <|-- MotionMasterPubSubSocket
-```
-
-## Communication
-
-### Protocols
-
-### Message Exchange
-
-## Running unit tests
-
-## Features
-
-## Goals
-
-Run `nx test motion-master-client` to execute the unit tests via [Jest](https://jestjs.io).
-
-https://github.com/protocolbuffers/protobuf/issues/2497#issuecomment-267422550
-
-explain status progress completed error
-request timeout
-ping mechanism
-reactive and async api
-two sockets
-matching request id (message id with response)
-
-## Build & Publish
-
-Update the `motion-master-client` version in `libs/motion-master-client/package.json`. Then, from the repository root, build the library by running:
-
-```sh
-npm run build motion-master-client
-```
-
-and publish the built library:
-
-```sh
-cd dist/libs/motion-master-client
-npm publish
-```
+# Motion Master Client
+
+Motion Master Client is a library and CLI program written in [TypeScript](https://www.typescriptlang.org). It is used for communicating with Motion Master process over [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) connections by exchanging [Protocol Buffers](https://developers.google.com/protocol-buffers) serialized messages.
+
+## Usage
+
+The Motion Master Client library can be equally used on a server with Node.js or in browsers.
+
+### Server usage
+
+Initialize a project:
+
+```sh
+mkdir hello-somanet
+cd hello-somanet
+npm init --yes
+```
+
+Install the required dependencies:
+
+```sh
+npm install --save motion-master-client rxjs ws
+npm install --save-dev ts-node typescript
+```
+
+Create a TypeScript configuration:
+
+```sh
+npx tsc --init
+```
+
+Create a main program file:
+
+```sh
+touch main.ts
+```
+
+Add the following content to the _main.ts_ file:
+
+```ts
+import { createMotionMasterClient } from 'motion-master-client';
+import { lastValueFrom } from 'rxjs';
+
+// Ensure that Node.js has the global WebSocket object available.
+Object.assign(globalThis, { WebSocket: require('ws') });
+
+const client = createMotionMasterClient('192.168.200.253');
+
+client.whenReady().then(async () => {
+  const devices = await lastValueFrom(client.request.getDevices());
+  const message = JSON.stringify(devices, null, 2);
+  console.log(message);
+  client.closeSockets();
+});
+```
+
+Run the program:
+
+```sh
+npx ts-node main.ts
+```
+
+The program will:
+
+1. Create an instance of the client and connect to a Motion Master process running at 192.168.200.253.
+2. The client needs some time to connect, so it must be ready before making requests. Most of the requests are implemented and documented in the [MotionMasterReqResClient](https://synapticon.github.io/oblac/motion-master-client/classes/MotionMasterReqResClient.html) class.
+3. The client requests a list of devices, which are then printed to the console.
+4. The client closes opened sockets.
+
+Here's another example that demonstrates how to get and set device parameter values:
+
+```ts
+import { createMotionMasterClient } from 'motion-master-client';
+
+// Ensure that Node.js has the global WebSocket object available.
+Object.assign(globalThis, { WebSocket: require('ws') });
+
+const client = createMotionMasterClient('192.168.200.253');
+
+client.whenReady().then(async () => {
+  // Device is referenced by a position (0).
+  const motorRatedCurrent = await client.request.upload(0, 0x6075, 0);
+  console.log(`Motor rated current: ${motorRatedCurrent}`);
+
+  // The device parameter is referenced by an ID, which consists of
+  // the index (0x6076), subindex (0x00), and the device serial number (8504-03-0002369-2329).
+  const motorRatedTorque = await client.request.upload('0x6076:00.8504-03-0002369-2329');
+  console.log(`Motor rated current: ${motorRatedTorque}`);
+
+  // Update the Max current parameter value to 2000.
+  await client.request.download(0, 0x6073, 0, 2000);
+
+  client.closeSockets();
+});
+```
+
+## Understanding requests
+
+When the client is instantiated, it connects to the Motion Master process using the WebSocket protocol. As it is a bi-directional, full-duplex communication protocol, there needs to be a mechanism that couples requests with responses. This is solved by having a message ID that is a mandatory attribute of each request; responses produced by that request will include the same message ID.
+
+For some requests, such as firmware installation, Motion Master will send progress messages until the firmware installation is complete. Therefore, when making a request with the client library, functions will return an Observable of request statuses. This means that you can subscribe to an Observable and receive status messages over time. These observables are asynchronous, meaning your program can continue to do other things while the request executes. For the purpose of utilizing Observables and implementing reactive programming, the client library uses [RxJs](https://rxjs.dev/).
+
+To demonstrate the use of reactive programming, let's create a program that monitors the drive and core temperatures:
+
+```ts
+import { createMotionMasterClient } from 'motion-master-client';
+import { map, mergeMap } from 'rxjs';
+
+// Ensure that Node.js has the global WebSocket object available.
+Object.assign(globalThis, { WebSocket: require('ws') });
+
+const client = createMotionMasterClient('192.168.200.253');
+
+const subscription = client.onceReady$
+  .pipe(
+    mergeMap(() =>
+      client.startMonitoring(
+        [
+          [0, 0x2030, 1], // Core temperature
+          [0, 0x2031, 1], // Drive temperature
+        ],
+        1000000, // microseconds
+        { topic: 'temperatures-monitoring', distinct: true }
+      )
+    ),
+    map((values) => `core=${values[0]} drive=${values[1]}`)
+  )
+  .subscribe(console.log);
+
+process.on('SIGINT', function () {
+  console.log('\nGracefully shutting down from SIGINT (Ctrl-C).\nStopping monitoring and closing sockets.');
+  subscription?.unsubscribe();
+  client.closeSockets();
+  process.exit(0);
+});
+```
+
+## Class Diagrams
+
+```mermaid
+---
+title: Client & socket classes
+---
+classDiagram
+  class MotionMasterClient {
+    +MotionMasterReqResClient request
+    +MotionMasterPubSubClient monitor
+    +startMonitoring()
+    +stopMonitoring()
+  }
+
+  class MotionMasterReqResClient {
+    +MotionMasterReqResSocket socket
+    note "Has all the request methods\ncorresponding to the proto file."
+  }
+
+  class MotionMasterReqResSocket
+  <<interface>> MotionMasterReqResSocket
+  MotionMasterReqResSocket: +BehaviorSubject~boolean~ opened\$
+  MotionMasterReqResSocket: +BehaviorSubject~boolean~ alive\$
+  MotionMasterReqResSocket: +Observable~MotionMasterMessage~ message\$
+  MotionMasterReqResSocket: +open(string url, number pingSystemInterval?, number systemAliveTimeout?)
+  MotionMasterReqResSocket: +close()
+  MotionMasterReqResSocket: +send(MotionMasterMessage message)
+
+  class MotionMasterReqResWebSocket {
+    note "Keeps the connection alive by\nsending the ping system messages\nin regular intervals."
+  }
+
+  class MotionMasterReqResWorkerSocket {
+    +Worker worker
+    note "Passes messages between\nthe UI and worker thread."
+  }
+
+  class MotionMasterPubSubClient {
+    +MotionMasterPubSubSocket socket
+    +Subject<[string, MotionMasterMessage[]]> data\$
+    +Observable~MotionMasterMessage~ notification\$
+    +Observable~MotionMasterMessage~ systemEvent\$
+    +Observable~MotionMasterMessage~ deviceEvent\$
+    +subscribe(MonitoringConfig config)
+    +unsubscribe(string messageId)
+    +unsubscribeAll()
+  }
+
+  class MotionMasterPubSubSocket
+  <<interface>> MotionMasterPubSubSocket
+  MotionMasterPubSubSocket: +BehaviorSubject~boolean~ opened\$
+  MotionMasterPubSubSocket: +Observable<[string, MotionMasterMessage]> data\$
+  MotionMasterPubSubSocket: +open(string url)
+  MotionMasterPubSubSocket: +close()
+
+  class MotionMasterPubSubWebSocket {
+    note "Deserializes incoming data into\na tuple of topic and message."
+  }
+
+  class MotionMasterPubSubWorkerSocket {
+    +Worker worker
+    note "Passes messages between\nthe UI and worker thread."
+  }
+
+  MotionMasterClient *-- MotionMasterReqResClient
+  MotionMasterClient *-- MotionMasterPubSubClient
+
+  MotionMasterReqResClient *-- MotionMasterReqResSocket
+  MotionMasterReqResWebSocket <|-- MotionMasterReqResSocket
+  MotionMasterReqResWorkerSocket <|-- MotionMasterReqResSocket
+
+  MotionMasterPubSubClient *-- MotionMasterPubSubSocket
+  MotionMasterPubSubWebSocket <|-- MotionMasterPubSubSocket
+  MotionMasterPubSubWorkerSocket <|-- MotionMasterPubSubSocket
+```
+
+## Build & Publish
+
+To update the `motion-master-client` version, first modify the version in `libs/motion-master-client/package.json`. Then, from the repository root, build the library by executing the following command:
+
+```sh
+npm run build motion-master-client
+```
+
+After building the library, proceed to publish it by following these steps:
+
+```sh
+cd dist/libs/motion-master-client
+npm publish
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motion-master-client",
-  "version": "0.0.76",
+  "version": "0.0.85",
   "type": "commonjs",
   "description": "A library and CLI program used for communicating with Motion Master.",
   "dependencies": {

package/src/cli.d.ts

@@ -1 +1 @@
-export {};
+export {};