@cutos/core 3.2.2 → 3.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -34,29 +34,31 @@ The CUTOS Core API provides a comprehensive set of classes for interacting with
34
34
 
35
35
  # Table of Contents
36
36
 
37
- 1.Quick Start
37
+ 1.[Quick Start](#quick-start)
38
38
 
39
39
  - Installation
40
40
  - Initialization
41
41
 
42
- 2.PlatformAPI
42
+ 2.[PlatformAPI](#platform-api)
43
43
 
44
44
  - Version
45
45
  - Platform Information
46
46
  - Configuration
47
47
  - Box Information
48
+ - Device Information
48
49
  - Shell Command Execution
50
+ - Http Proxy
49
51
  - Volume Control
50
52
 
51
53
  3.IPC (Inter-Process Communication)
52
54
 
53
55
  4.Database
54
56
 
55
- 5.Device & Driver
57
+ 5.[Device & Driver](#device-driver-development)
56
58
 
57
- 6.Notification
59
+ 6.[Notification](#notification-api)
58
60
 
59
- 7.Logger
61
+ 7.[Logger](#logger-api)
60
62
 
61
63
 
62
64
  # Quick Start
@@ -64,7 +66,7 @@ The CUTOS Core API provides a comprehensive set of classes for interacting with
64
66
  ##### Install
65
67
 
66
68
  `
67
- npm install @cutos/core
69
+ npm install @cutos/core
68
70
  `
69
71
 
70
72
  ##### Initialize
@@ -84,8 +86,8 @@ CoreAPI.getVersion();
84
86
  ```
85
87
  - Return result example:
86
88
 
87
- ```
88
- 3.0.3
89
+ ```json
90
+ "3.2.4"
89
91
  ```
90
92
 
91
93
  ### CoreAPI.getPlatform
@@ -95,12 +97,12 @@ CoreAPI.getVersion();
95
97
  CoreAPI.getPlatform(callback);
96
98
  ```
97
99
  - callback: callback function
98
-
100
+
99
101
  ##### Example:
100
102
 
101
103
  ```js
102
104
  CoreAPI.getPlatform(result => {
103
- console.log(result)
105
+ console.log(result)
104
106
  });
105
107
  ```
106
108
 
@@ -108,8 +110,10 @@ CoreAPI.getPlatform(result => {
108
110
 
109
111
  ```json
110
112
  {
111
- "arch": "x64",
112
- "type": "Windows_NT"
113
+ "arch": "x64",
114
+ "platform": "win32",
115
+ "type": "Windows_NT",
116
+ "release": "10.0.19045"
113
117
  }
114
118
  ```
115
119
 
@@ -140,51 +144,85 @@ CoreAPI.getConfig(result => {
140
144
  "debug": false
141
145
  }
142
146
  ```
143
- ### CoreAPI.getSignInfo
144
- ##### Get device information
147
+
148
+ ### CoreAPI.getBoxInfo
149
+ ##### Get host information
145
150
 
146
151
  ```js
147
- CoreAPI.getSignInfo(callback);
152
+ CoreAPI.getBoxInfo(callback);
148
153
  ```
149
154
  - callback: callback function
150
155
 
151
156
  ##### Example:
152
157
 
153
158
  ```js
154
- CoreAPI.getSignInfo(result => {
159
+ CoreAPI.getBoxInfo(result => {
155
160
  console.log(result)
156
161
  })
157
162
  ```
158
- ### CoreAPI.getBoxInfo
159
- ##### Get host information
163
+ - Return result example:
164
+
165
+ ```json
166
+ {
167
+ "id": 1016,
168
+ "macAddress": "00-F1-F5-2A-8E-8C",
169
+ "ipAddress": "192.168.1.127",
170
+ "masterIpAddress": "",
171
+ "osVersion": "3.2.0"
172
+ }
173
+ ````
174
+ - Return results:
175
+ - `macAddress`: Host MAC address
176
+ - `ipAddress`: host IP address
177
+ - `masterIpAddress`: Master IP address, used when multiple hosts form a host group
178
+ - `osVersion`: CUTOS Player Version
179
+
180
+ ### CoreAPI.getDeviceInfo
181
+ ##### Get device information
160
182
 
161
183
  ```js
162
- CoreAPI.getBoxInfo(callback);
184
+ CoreAPI.getDeviceInfo(callback);
163
185
  ```
164
186
  - callback: callback function
165
187
 
166
188
  ##### Example:
167
189
 
168
190
  ```js
169
- CoreAPI.getBoxInfo(result => {
170
- console.log(result)
191
+ CoreAPI.getDeviceInfo(result => {
192
+ console.log(result)
171
193
  })
172
194
  ```
195
+
173
196
  - Return result example:
174
197
 
175
198
  ```json
176
199
  {
177
- "id": 1004,
178
- "macAddress": "54-48-10-D9-BB-27",
179
- "ipAddress": "192.168.1.136",
180
- "masterIpAddress": ""
200
+ "id": 1234,
201
+ "name": "sipTimes office",
202
+ "shortName": "",
203
+ "groupId": 0,
204
+ "groupName": null,
205
+ "department": null,
206
+ "description": null,
207
+ "gwi": "9E1E3B67-...101B",
208
+ "gwUrl": "ws://127.0.0.1:61614",
209
+ "ext": null,
210
+ "token": "D+yIxq1d3...BTgjK....."
181
211
  }
212
+
182
213
  ```
183
- -Return results:
184
- - `macAddress`: Host MAC address
185
- - `ipAddress`: host IP address
186
- - `masterIpAddress`: Master IP address, used when multiple hosts form a host group
187
- - `status`: 1 means online, 0 means offline
214
+ - Return result:
215
+ - `id`: device ID
216
+ - `name`: device name
217
+ - `shortName`: device short name
218
+ - `groupId`: device group ID
219
+ - `groupName`: device group name
220
+ - `department`: department
221
+ - `description`: description
222
+ - `gwi`: gateway ID
223
+ - `gwUrl`: gateway address
224
+ - `ext`: extended information
225
+ - `token`: token
188
226
 
189
227
  ### CoreAPI.getVolume
190
228
  ##### Get the volume
@@ -204,7 +242,7 @@ CoreAPI.getVolume(result => {
204
242
  - Return result example:
205
243
 
206
244
  ```js
207
- 10
245
+ "10"
208
246
  ```
209
247
 
210
248
  ### CoreAPI.setVolume
@@ -219,16 +257,58 @@ CoreAPI.setVolume(value,callback)
219
257
  ##### Example:
220
258
 
221
259
  ```js
222
- CoreAPI.setVolume(70, result => {
260
+ CoreAPI.setVolume(70,result => {
223
261
  console.log(result)
224
262
  })
225
263
  ```
226
264
 
227
265
  - Return result example:
228
266
 
267
+ ```json
268
+ {
269
+ "result":70
270
+ }
271
+ ```
272
+ ### CoreAPI.setHttpProxy
273
+ ##### Set proxy to solve LWA cross-domain problem
274
+
275
+ ```js
276
+ CoreAPI.setHttpProxy(api, target, callback)
277
+ ```
278
+
279
+ - api: interface name
280
+ - target: target address
281
+ - callback: callback function. The callback function returns result if successful and error if failed.
282
+
283
+ ##### Example:
284
+
285
+ ```js
286
+ CoreAPI.setHttpProxy('api', 'https://www.cut-os.com', (result, error) => {
287
+ if (!error) {
288
+ console.log(result)
289
+ }
290
+ })
291
+ ```
292
+
293
+ - Return result example:
294
+
295
+ ```json
296
+ {
297
+ "result": {
298
+ "path": "proxy/api",
299
+ "target": "https://www.cut-os.com"
300
+ }
301
+ }
302
+ ```
303
+ ##### Actual interface call example
229
304
  ```js
230
- success
305
+ fetch(`http://localhost:3000/proxy/api/rest/sv/system/runtime/ping`)
231
306
  ```
307
+ ##### The actual request address
308
+ ```js
309
+ fetch(`https://www.cut-os.com/rest/sv/system/runtime/ping`)
310
+ ```
311
+
232
312
  ### CoreAPI.shell
233
313
  ##### Shell command execution
234
314
 
@@ -241,5 +321,491 @@ CoreAPI.shell(command, callback)
241
321
  ##### Example:
242
322
 
243
323
  ```js
244
- CoreAPI.shell('sudo reboot', null) //Restart the system
324
+ CoreAPI.shell('cd', null) //Display the current directory(windows)
325
+ ```
326
+
327
+ # Device Driver Development
328
+
329
+ ## Driver Usage
330
+
331
+ ### Constructor
332
+
333
+ ```js
334
+ const driver = new Driver(name, type, counter)
335
+ ```
336
+ * name: driver name, default is 'default-driver-name'
337
+ * type: device type, default is cutosAPI.DEVICE.DEFAULT
338
+ * counter: heartbeat interval, default is 10s
339
+
340
+ ### driver.sendData
341
+ ##### Driver sends data to the device
342
+
343
+ ```js
344
+ driver.sendData(data)
345
+ ```
346
+ - data: transmission data
347
+
348
+ ### driver.onCommand
349
+ ##### Driver receives device commands
350
+
351
+ ```js
352
+ driver.onCommand(listener)
353
+ ```
354
+ - listener: listener callback function
355
+ ```js
356
+ listener(messageBody, callback);
357
+ ```
358
+ - messageBody: message body
359
+ - callback: callback function
360
+
361
+
362
+ ## Device SDK usage
363
+
364
+ ### Constructor
365
+
366
+ ```js
367
+ const device = new Device(name, type)
368
+ ```
369
+ * name: device name, default is 'default-device-name'
370
+ * type: device type, default is cutosAPI.DEVICE.DEFAULT
371
+
372
+ ### device.init
373
+ ##### Device initialization
374
+
375
+ ```js
376
+ device.init([opts], callback)
377
+ ```
378
+ * opts: optional parameter; if opts is not needed, this parameter can be omitted.
379
+ * callback: callback function
380
+
381
+ ### device.sendCommand
382
+ ##### Device sends command to driver
383
+
384
+ ```js
385
+ device.sendCommand(command, callback)
386
+ ```
387
+ - command: command, example: command = {cmd: "connect", args: ""}
388
+ - callback: callback function, you can pass a listener callback function to listen to device status
389
+
390
+ ##### Example:
391
+ ```js
392
+ device.sendCommand( {cmd: "connect", args: ""},Listener(msg))
393
+ ```
394
+
395
+ ### device.onData
396
+ ##### Device receiving driver return data
397
+
398
+ ```js
399
+ device.onData(listener)
400
+ ```
401
+ - listener: listener callback function
402
+ ```js
403
+ listener(data);
404
+ ```
405
+ - data: return data
406
+
407
+ ## Device driver relationship
408
+ ##### 1. onData and sendData
409
+ ![ddr1.png](https://oss.cut-os.com/resources/developer/images/ddr1.png)
410
+ ##### 2. sendCommand (without callback function) and onCommand
411
+ ![ddr2.png](https://oss.cut-os.com/resources/developer/images/ddr2.png)
412
+ ##### 3. sendCommand (with callback function) and onCommand
413
+ ![ddr3.png](https://oss.cut-os.com/resources/developer/images/ddr3.png)
414
+ ## Device driver management template
415
+
416
+ ### Download project template
417
+
418
+ | <span style="white-space:nowrap;">Name </span> | Description | Download |
419
+ |:---------------------------------------------|:------:|:-----------------------------------------------------------------------------:|
420
+ | driver-template | Device driver template | [Download](https://oss.cut-os.com/resources/developer/template/driver-template.zip) |
421
+
422
+ ##### Project structure
423
+ ```
424
+ ├── driver/ # Driver
425
+ │ ├── src/ # Driver source directory
426
+ │ ├── config.json # Configuration file, configure related parameters
427
+ │ ├── driver-template.js # Driver template
428
+ │ ├── driver-template-def.js # Device driver data definition (same as in SDK)
429
+ │ ├── index.js # Driver loading file
430
+ │ ├── test/ # Test directory
431
+ │ ├── main.js # Test entry file, simulate cutos, create a driver service
432
+ │ ├── package.json # Configuration information for this project
433
+ │ ├── gulpfile.js # Packaging file
434
+ │ ├── readme.txt # Instructions
435
+ ├── sdk/ # Interface SDK
436
+ │ ├── src/ # Source code directory
437
+ │ ├── device-template.js # Device template
438
+ │ ├── device-template-def.js # Device driver data definition (same as in driver)
439
+ │ ├── test/     # Test directory
440
+ │ ├── main.js # Test entry file
441
+ │ ├── package.json # Configuration information for this project
442
+ │ ├── gulpfile.mjs # Packaging file
443
+ │ ├── readme.txt # Instructions
444
+ ```
445
+
446
+ ### Installation dependencies
447
+
448
+ > Note: node version >= 16
449
+
450
+ ```
451
+ cd driver-template/driver
452
+ npm install
453
+ ```
454
+ ```
455
+ cd driver-template/sdk
456
+ npm install
457
+ ```
458
+
459
+ [//]: # (### Template-based development)
460
+
461
+ ### Project startup
462
+
463
+ You need to start the driver first, then start the SDK.
464
+ ```
465
+ npm start
466
+ ```
467
+ If the startup is successful, the console will return the following content
468
+
469
+ * driver
470
+
471
+ ```
472
+ CUTOS CORE connected.
473
+ CUTOS Simulator started and listening on port 1883
474
+ drvDefault onCommand
475
+ {
476
+ "cmd":"init",
477
+ "args":{"name":"device-template","type":"device-template","development":true},
478
+ "topicResponse":"device-channel-device-template-response"
479
+ }
480
+ connect: received.
481
+ cmd: custom-cmd received.
482
+ cmd: unknown is unsupported.
483
+ ```
484
+ * SDK
485
+
486
+ ```
487
+ CUTOS CORE connected.
488
+ device template init true
489
+ connect: { msg: 'return success.', status: true }
490
+ ```
491
+ ### Packaging and Release
492
+
493
+ ```
494
+ cd driver-template/driver
495
+ npm run build
496
+ ```
497
+ ```
498
+ cd driver-template/sdk
499
+ npm run build
500
+ ```
501
+ ##### Packaging Driver
502
+ ```
503
+ ├── driver/
504
+ │ ├── dist/ # Packaging directory
505
+ │ ├── driver-template-v1.0.1.drv # Packaging file
506
+ ```
507
+ ##### Release the driver
508
+ Upload the package file to https://www.cut-os.com/ and publish
509
+ Hardware/Driver--Add
510
+
511
+ ##### Packaged Device SDK
512
+ ```
513
+ ├── sdk/
514
+ │ ├── dist/ # Packaging directory
515
+ │ ├── device-template-sdk-v1.0.2.zip # Packaging files
516
+ ```
517
+
518
+ #####
519
+ > Note:
520
+ >
521
+ > 1.The template device-template.js references TYPE, CMD exported in device-template-def.js
522
+ >
523
+ > `import {CMD, TYPE} from './device-template-def.js';`
524
+ > * Device type (TYPE):
525
+ > - Type constant: key "TEMPLATE", value "Device template".
526
+ > - Indicates the template type, identifying the category of the device.
527
+ >* Command type (CMD):
528
+ > - CMD constant with two pairs:
529
+ > - CONNECT: 'connect' represents the connection command.
530
+ > - CUSTOM_CMD: "custom-cmd" represents a custom command for a specific device.
531
+
532
+ > 2.Configuration requirements: Keep the TYPE parameter 3 in the template consistent so that the driver matches the corresponding SDK.
533
+ >
534
+ > ```let device = new DeviceTemplate('device-template')``` //device-template.js
535
+ >
536
+ > ``` const TYPE = 'device-template';```//device-template-def.js
537
+ >
538
+ > ```{"name": "device-template",...}```//config.json
539
+
540
+ ## Review
541
+
542
+ The complete code is as follows:
543
+
544
+ ##### driver
545
+ ```js
546
+ // driver/src/driver-template.js
547
+ const {CoreDefine, CoreClass} = require('@cutos/core');
548
+ const {TYPE, CMD} = require('./device-template-def.js');
549
+ const config = require('./config.json');
550
+
551
+ class DriverTemplate extends CoreClass.Driver {
552
+ constructor(args) {
553
+ // check
554
+ if (TYPE !== config.type) {
555
+ throw "Error: the 'type' value in config.js and *-def.js MUST be identical.";
556
+ }
557
+ super(args.name, TYPE);
558
+
559
+ this.startBeat();
560
+ this.updateStatusInfo(CoreDefine.HEARTBEAT_STATUS.ALIVE, "alive");
561
+
562
+ this.onCommand(({cmd, args}, callback) => {
563
+ //Listen to the messages sent by the device SDK, process the different commands in the message body,
564
+ // and respond back to the device SDK through the callback function.
565
+ switch (cmd) {
566
+ case CMD.CONNECT:
567
+ this.connect(args, callback);
568
+ break;
569
+ case CMD.CUSTOM_CMD:
570
+ this.customCmd(cmd, args);
571
+ break;
572
+ default:
573
+ this.unsupported(cmd, args, callback);
574
+ break;
575
+ }
576
+ });
577
+ }
578
+
579
+ unsupported(cmd, args, callback) {
580
+ let result = {};
581
+ result.msg = "cmd: " + cmd + " is unsupported.";
582
+ result.status = false;
583
+ console.log(result.msg);
584
+ callback(result);
585
+ }
586
+
587
+ connect(args, callback) {
588
+ console.log("connect: received.");
589
+ let result = {};
590
+ result.msg = "return success.";
591
+ result.status = true;
592
+ callback(result);
593
+ }
594
+
595
+ // no response
596
+ customCmd(cmd, args) {
597
+ console.log("cmd: " + cmd + args, " received.");
598
+ // process cmd below
599
+ }
600
+
601
+ sendCustomData() {
602
+ let data = {};
603
+ data.type = "custom-type"; // custom defined data type
604
+ data.values = {}; // values from template driver
605
+ data.values.val = "any value";
606
+ data.values.timeStamp = Date.now();
607
+ this.sendData(data);
608
+ }
609
+ }
610
+
611
+ module.exports = DriverTemplate;
612
+ ```
613
+
614
+ ##### SDK
615
+
616
+ ```js
617
+ // sdk/src/device-template.js
618
+ import {CoreClass} from '@cutos/core';
619
+ import {CMD, TYPE} from './device-template-def.js';
620
+
621
+ class DeviceTemplate extends CoreClass.Device {
622
+ constructor(name) {
623
+ super(name, TYPE);
624
+
625
+ this.onData((data) => {
626
+ console.log("on data", data)
627
+ });
628
+ }
629
+
630
+ /**
631
+ *
632
+ * @param callback(result)
633
+ */
634
+ connect(callback) {
635
+ let cmdMessage = {cmd: CMD.CONNECT};
636
+ this.sendCommand(cmdMessage, callback);
637
+ }
638
+
639
+ customCmd() {
640
+ let cmdMessage = {cmd: CMD.CUSTOM_CMD, args: ""};
641
+ this.sendCommand(cmdMessage);
642
+ }
643
+ }
644
+
645
+ export {DeviceTemplate};
646
+ ```
647
+ ```js
648
+ // sdk/test/main.js
649
+ import {CoreAPI} from '@cutos/core';
650
+ import {DeviceTemplate} from '../src/device-template.js';
651
+
652
+
653
+ CoreAPI.init(null, (result, error) => {
654
+ if (error) {
655
+ console.log(error)
656
+ return;
657
+ }
658
+ console.log(result)
659
+
660
+ let device = new DeviceTemplate('device-template');
661
+ device.init((result, error) => {
662
+ if (error) {
663
+ console.log(error)
664
+ return;
665
+ }
666
+ console.log(result)
667
+
668
+ device.connect((result) => {
669
+ console.log("connect:", result)
670
+ });
671
+ device.customCmd();
672
+ device.sendCommand({cmd: "unknown", args: ""}, (result) => {
673
+ console.log('unknown:', result)
674
+ });
675
+ });
676
+ });
677
+ ```
678
+
679
+ # NOTIFICATION API
680
+
681
+ ### CoreAPI.getNotification
682
+ ##### Get notification information instance object
683
+ ```js
684
+ let notification = CoreAPI.getNotification();
685
+ ```
686
+
687
+ ### notification.register
688
+ ##### Example:
689
+
690
+ ```js
691
+ notification.register((args) => {
692
+ console.log(args);
693
+ })
694
+ ```
695
+ - Return result example:
696
+
697
+ ```json
698
+ {
699
+ "event": "networkConnection",
700
+ "msg": true
701
+ }
702
+ ```
703
+ - Return result:
704
+ * event:Event Name
705
+ * msg:true, the host is online; false, the host is offline
706
+
707
+ # LOGGER API
708
+
709
+ ### CoreAPI.getLogger
710
+ ##### Get the log instance object
711
+
712
+ ```js
713
+ let logger = CoreAPI.getLogger();
714
+ ```
715
+
716
+ ### logger.info
717
+ ##### Information
718
+
719
+ ```js
720
+ logger.info(remark, content, type = "LWA")
721
+ ```
722
+ * remark: logo;
723
+ * content: content;
724
+ * type: type, default is LWA if not passed.
725
+
726
+ ##### Example:
727
+
728
+ ```js
729
+ logger.info('call-face','success')
730
+ ```
731
+
732
+ * Return result log file example:
733
+
734
+ ```json
735
+ {"dateTime":1709891709950,"status":"The server is alive!"}
736
+ ```
737
+
738
+ ### logger.warning
739
+ ##### Warning
740
+
741
+ ```js
742
+ logger.warning(remark, content, type = "LWA")
743
+ ```
744
+ * remark: logo;
745
+ * content: content;
746
+ * type: type, default is LWA if not passed.
747
+
748
+ ##### Example:
749
+
750
+ ```js
751
+ logger.warning('call-face','warning-content')
752
+ ```
753
+
754
+ * Return result log file example:
755
+
756
+ ```json
757
+ {
758
+ "type": "LWA",
759
+ "level": "warning",
760
+ "remark": "call-face",
761
+ "content": "warning-content"
762
+ }
763
+ ```
764
+
765
+ ### logger.error
766
+ ##### Error
767
+
768
+ ```js
769
+ logger.error(remark, content, type = "LWA")
770
+ ```
771
+ * remark: logo;
772
+ * content: content;
773
+ * type: type, default is LWA if not passed.
774
+
775
+ ##### Example:
776
+
777
+ ```js
778
+ logger.error('call-face','fatal-content')
779
+ ```
780
+
781
+ * Example of returned result log file:
782
+
783
+ ```
784
+ AxiosError: Network Error
785
+ ```
786
+
787
+ ### logger.debug
788
+ ##### Debug
789
+
790
+ ```js
791
+ logger.debug(remark, content, type = "LWA")
792
+ ```
793
+ * remark: logo;
794
+ * content: content;
795
+ * type: type, default is LWA if not passed.
796
+
797
+ ##### Example:
798
+
799
+ ```js
800
+ logger.debug('call-face','debug-content')
801
+ ```
802
+ * Example of returned result log file:
803
+
804
+ ```json
805
+ {
806
+ "type": "LWA",
807
+ "level": "debug",
808
+ "remark": "call-face",
809
+ "content": "debug-content"
810
+ }
245
811
  ```