@cutos/core 3.2.3 → 3.2.5

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,73 +34,102 @@ 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
- - Installation
40
- - Initialization
41
-
42
- 2.PlatformAPI
39
+ 2.[PlatformAPI](#platform-api)
43
40
 
44
41
  - Version
45
42
  - Platform Information
46
43
  - Configuration
47
44
  - Box Information
48
- - Shell Command Execution
45
+ - Device Information
46
+ - Http Proxy
49
47
  - Volume Control
48
+ - Shell Command Execution
50
49
 
51
- 3.IPC (Inter-Process Communication)
50
+ 3.[IPC](#ipc-api)
52
51
 
53
- 4.Database
52
+ 4.[Database](#database-api)
54
53
 
55
- 5.Device & Driver
54
+ 5.[Device & Driver](#devicediver-api)
56
55
 
57
- 6.Notification
56
+ 6.[Notification](#notification-api)
58
57
 
59
- 7.Logger
58
+ 7.[Logger](#logger-api)
60
59
 
61
60
 
62
61
  # Quick Start
63
62
 
64
- ##### Install
63
+ ### Install
65
64
 
66
65
  `
67
- npm install @cutos/core
66
+ npm install @cutos/core
68
67
  `
69
68
 
70
- ##### Initialize
69
+ ### Initialize
70
+
71
+ ```js
72
+ CoreAPI.init(host, callback);
73
+ ```
74
+
75
+ * host: CUTOS address. When host is equal to null, it takes the value 'localhost'. During development, it can be changed
76
+ to the target address (the device address where CUTOS is installed), such as: '192.168.1.11'
77
+ * callback: callback function. The callback function will receive two parameters: result (String) and error (Object).
78
+ Among them, error.name is the error name, and error.message is the specific error message.
79
+
80
+ ##### Example:
71
81
 
72
82
  ```js
73
- // Initialize the CUTOS Core module
74
83
  import { CoreAPI } from '@cutos/core';
75
- CoreAPI.init();
84
+ CoreAPI.init('192.168.1.11', (result, error) => {
85
+ if (!error) {
86
+ console.log(result)
87
+ } else {
88
+ console.error('init failed' + error.message)
89
+ }
90
+ })
91
+ ```
92
+
93
+ - Return result example:
94
+
95
+ ```json
96
+ {
97
+ "result": "CUTOS CORE connected."
98
+ }
76
99
  ```
77
100
 
78
- # Platform API
101
+
102
+ # Platform API
79
103
 
80
104
  ### CoreAPI.getVersion
81
- ##### Get platform version information
105
+
106
+ Get platform version information
107
+
82
108
  ```js
83
109
  CoreAPI.getVersion();
84
110
  ```
111
+
85
112
  - Return result example:
86
113
 
87
114
  ```
88
- 3.0.3
115
+ "3.2.5"
89
116
  ```
90
117
 
91
118
  ### CoreAPI.getPlatform
92
- ##### Get platform information
119
+
120
+ Get platform information
93
121
 
94
122
  ```js
95
123
  CoreAPI.getPlatform(callback);
96
124
  ```
125
+
97
126
  - callback: callback function
98
-
127
+
99
128
  ##### Example:
100
129
 
101
130
  ```js
102
131
  CoreAPI.getPlatform(result => {
103
- console.log(result)
132
+ console.log(result)
104
133
  });
105
134
  ```
106
135
 
@@ -108,23 +137,28 @@ CoreAPI.getPlatform(result => {
108
137
 
109
138
  ```json
110
139
  {
111
- "arch": "x64",
112
- "type": "Windows_NT"
140
+ "arch": "x64",
141
+ "platform": "win32",
142
+ "type": "Windows_NT",
143
+ "release": "10.0.19045"
113
144
  }
114
145
  ```
115
146
 
116
147
  ### CoreAPI.getConfig
117
- ##### Get configuration information
148
+
149
+ Get configuration information
150
+
118
151
  ```js
119
152
  CoreAPI.getConfig(callback);
120
153
  ```
154
+
121
155
  - callback: callback function
122
156
 
123
157
  ##### Example:
124
158
 
125
159
  ```js
126
160
  CoreAPI.getConfig(result => {
127
- console.log(result)
161
+ console.log(result)
128
162
  });
129
163
  ```
130
164
 
@@ -132,114 +166,1344 @@ CoreAPI.getConfig(result => {
132
166
 
133
167
  ```json
134
168
  {
135
- "srvAddress": "www.cut-os.com",
136
- "srvRestProtocol": "https",
137
- "enableTimeSync": true,
138
- "playReport": false,
139
- "language": "Chinese",
140
- "debug": false
169
+ "srvAddress": "www.cut-os.com",
170
+ "srvRestProtocol": "https",
171
+ "enableTimeSync": true,
172
+ "playReport": false,
173
+ "language": "Chinese",
174
+ "debug": false
141
175
  }
142
176
  ```
143
- ### CoreAPI.getSignInfo
144
- ##### Get device information
177
+
178
+ ### CoreAPI.getBoxInfo
179
+
180
+ Get host information
145
181
 
146
182
  ```js
147
- CoreAPI.getSignInfo(callback);
183
+ CoreAPI.getBoxInfo(callback);
148
184
  ```
185
+
149
186
  - callback: callback function
150
187
 
151
188
  ##### Example:
152
189
 
153
190
  ```js
154
- CoreAPI.getSignInfo(result => {
155
- console.log(result)
191
+ CoreAPI.getBoxInfo(result => {
192
+ console.log(result)
156
193
  })
157
194
  ```
158
- ### CoreAPI.getBoxInfo
159
- ##### Get host information
195
+
196
+ - Return result example:
197
+
198
+ ```json
199
+ {
200
+ "id": 1016,
201
+ "macAddress": "00-F1-F5-2A-8E-8C",
202
+ "ipAddress": "192.168.1.127",
203
+ "masterIpAddress": "",
204
+ "osVersion": "3.2.0"
205
+ }
206
+ ````
207
+
208
+ - `id`: Host ID
209
+ - `macAddress`: Host MAC address
210
+ - `ipAddress`: host IP address
211
+ - `masterIpAddress`: Master IP address, used when multiple hosts form a host group
212
+ - `osVersion`: CUTOS Player Version
213
+
214
+ ### CoreAPI.getDeviceInfo
215
+
216
+ Get device information
160
217
 
161
218
  ```js
162
- CoreAPI.getBoxInfo(callback);
219
+ CoreAPI.getDeviceInfo(callback);
163
220
  ```
221
+
164
222
  - callback: callback function
165
223
 
166
224
  ##### Example:
167
225
 
168
226
  ```js
169
- CoreAPI.getBoxInfo(result => {
170
- console.log(result)
227
+ CoreAPI.getDeviceInfo(result => {
228
+ console.log(result)
171
229
  })
172
230
  ```
231
+
173
232
  - Return result example:
174
233
 
175
234
  ```json
176
235
  {
177
- "id": 1004,
178
- "macAddress": "54-48-10-D9-BB-27",
179
- "ipAddress": "192.168.1.136",
180
- "masterIpAddress": ""
236
+ "id": 1234,
237
+ "name": "sipTimes office",
238
+ "shortName": "",
239
+ "groupId": 0,
240
+ "groupName": null,
241
+ "department": null,
242
+ "description": null,
243
+ "gwi": "9E1E3B67-...101B",
244
+ "gwUrl": "ws://127.0.0.1:61614",
245
+ "ext": null,
246
+ "token": "D+yIxq1d3...BTgjK....."
181
247
  }
182
248
  ```
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
249
+
250
+ - `id`: device ID
251
+ - `name`: device name
252
+ - `shortName`: device short name
253
+ - `groupId`: device group ID
254
+ - `groupName`: device group name
255
+ - `department`: department
256
+ - `description`: description
257
+ - `gwi`: gateway ID
258
+ - `gwUrl`: gateway address
259
+ - `ext`: extended information
260
+ - `token`: token
188
261
 
189
262
  ### CoreAPI.getVolume
190
- ##### Get the volume
263
+
264
+ Get the volume
191
265
 
192
266
  ```js
193
267
  CoreAPI.getVolume(callback);
194
268
  ```
269
+
195
270
  - callback: callback function
196
271
 
197
272
  ##### Example:
198
273
 
199
274
  ```js
200
275
  CoreAPI.getVolume(result => {
201
- console.log(result)
276
+ console.log(result)
202
277
  })
203
278
  ```
279
+
204
280
  - Return result example:
205
281
 
206
282
  ```js
207
- 10
283
+ "10"
208
284
  ```
209
285
 
210
286
  ### CoreAPI.setVolume
211
- ##### Set the volume
287
+
288
+ Set the volume
212
289
 
213
290
  ```js
214
- CoreAPI.setVolume(value,callback)
291
+ CoreAPI.setVolume(value, callback)
215
292
  ```
293
+
216
294
  - value: volume (0-100)
217
295
  - callback: callback function
218
296
 
219
297
  ##### Example:
220
298
 
221
299
  ```js
222
- CoreAPI.setVolume(70, result => {
223
- console.log(result)
300
+ CoreAPI.setVolume(70, (result, error) => {
301
+ if (!error) {
302
+ console.log(result)
303
+ }
304
+ })
305
+ ```
306
+
307
+ - Return result example:
308
+
309
+ ```json
310
+ {
311
+ "result": 70
312
+ }
313
+ ```
314
+
315
+ ### CoreAPI.setHttpProxy
316
+
317
+ Set proxy to solve LWA cross-domain problem
318
+
319
+ ```js
320
+ CoreAPI.setHttpProxy(api, target, callback)
321
+ ```
322
+
323
+ - api: interface name
324
+ - target: target address
325
+ - callback: callback function. The callback function returns result if successful and error if failed.
326
+
327
+ ##### Example:
328
+
329
+ ```js
330
+ CoreAPI.setHttpProxy('api', 'https://www.cut-os.com', (result, error) => {
331
+ if (!error) {
332
+ console.log(result)
333
+ }
224
334
  })
225
335
  ```
226
336
 
227
337
  - Return result example:
228
338
 
339
+ ```json
340
+ {
341
+ "path": "proxy/api",
342
+ "target": "https://www.cut-os.com"
343
+ }
344
+ ```
345
+
346
+ * path: Request address prefix
347
+ * target: target address
348
+
349
+ ##### Actual interface call example
350
+
351
+ ```js
352
+ fetch(`http://localhost:3000/proxy/api/rest/sv/system/runtime/ping`)
353
+ ```
354
+
355
+ ##### The actual request address
356
+
229
357
  ```js
230
- success
358
+ fetch(`https://www.cut-os.com/rest/sv/system/runtime/ping`)
231
359
  ```
360
+
232
361
  ### CoreAPI.shell
233
- ##### Shell command execution
362
+
363
+ Shell command execution
234
364
 
235
365
  ```js
236
366
  CoreAPI.shell(command, callback)
237
367
  ```
368
+
238
369
  - command: command
239
370
  - callback: callback function
240
371
 
241
372
  ##### Example:
242
373
 
243
374
  ```js
244
- CoreAPI.shell('sudo reboot', null) //Restart the system
375
+ CoreAPI.shell('pwd', (result, error) => {
376
+ if (!error) {
377
+ console.log(result)
378
+ }
379
+ })
380
+ ```
381
+
382
+ - Return result example:
383
+
384
+ ```
385
+ "/home/linaro"
386
+ ```
387
+
388
+
389
+ # IPC API
390
+
391
+ ### CoreAPI.getIPC
392
+
393
+ Get IPC instance object
394
+
395
+ ```js
396
+ let ipc = CoreAPI.getIPC([destAddress]);
397
+ ```
398
+
399
+ * destAddress: optional parameter, target IP address, used for inter-device process communication
400
+
401
+ ![PNG](/img/IPC.png)
402
+
403
+ ### ipc.on
404
+
405
+ Listen IPC
406
+
407
+ ```js
408
+ ipc.on(channel, listener);
409
+ ```
410
+
411
+ * channel: channel name
412
+ * listener: listener function (data)
413
+
414
+ ### ipc.sendTo
415
+
416
+ Send IPC information
417
+
418
+ ```js
419
+ ipc.sendTo(channel, data);
420
+ ```
421
+
422
+ * channel: channel name
423
+ * data: sent information
424
+
425
+ ##### Local device communication example:
426
+
427
+ ```js
428
+ import {CoreAPI} from '@cutos/core';
429
+
430
+ CoreAPI.init();
431
+
432
+ let ipc = CoreAPI.getIPC();
433
+ //Listen for IPC information
434
+ let ipcListener = function (data) {
435
+ console.log(data);
436
+ };
437
+ ipc.on("channel-1", ipcListener);
438
+ //Send IPC information
439
+ ipc.sendTo("channel-1", {event: "event-1", msg: "msg-1"});
440
+ ```
441
+
442
+ - Return result example:
443
+
444
+ ```json
445
+ {
446
+ "event": "event-1",
447
+ "msg": "msg-1"
448
+ }
449
+ ```
450
+
451
+ ##### Example of inter-device process communication:
452
+
453
+ ```js
454
+ import {CoreAPI} from '@cutos/core';
455
+
456
+ CoreAPI.init();
457
+
458
+ let ipc = CoreAPI.getIPC("192.168.1.149");
459
+ //Listen for IPC information
460
+ let ipcListener = function (data) {
461
+ console.log(data);
462
+ }
463
+ ipc.on("channel-2", ipcListener);
464
+ //Send IPC information
465
+ ipc.sendTo("channel-2", {event: "event-2", msg: "msg-2"});
466
+ ```
467
+
468
+ - Return result example:
469
+
470
+ ```json
471
+ {
472
+ "event": "event-2",
473
+ "msg": "msg-2"
474
+ }
475
+ ```
476
+
477
+
478
+ # Database API
479
+
480
+ The basic table structure of CUTOS database is in Key-Value format, and Value can be any json object. The advantage of
481
+ this design is that the database does not need to be upgraded to modify the Value field, but the disadvantage is that it
482
+ cannot be accessed as flexibly as traditional databases. If you need more flexible database access functions, you can
483
+ use the SQL fully compatible interface provided by CUTOS.
484
+
485
+ CUTOS basic table structure (default primary key name is `id`, data type is `INTEGER`):
486
+
487
+ | **Field** | **Data type** | **Description** |
488
+ |:---------:|:-------------:|:------------------------------------------------------:|
489
+ | id | INTEGER | Primary key |
490
+ | value | TEXT | Data |
491
+ | tid | TEXT | Foreign key, transaction id |
492
+ | sync | INTEGER | Synchronization flag: 0-unsynchronized, 1-synchronized |
493
+ | timestamp | INTEGER | Last modified timestamp |
494
+
495
+ ### Database
496
+
497
+ Constructor
498
+
499
+ ```js
500
+ let database = new Database(db);
501
+ ```
502
+
503
+ - db: database name, default is lwa.db if name is not passed
504
+
505
+ ### Database.connect
506
+
507
+ Connect to database
508
+
509
+ ```js
510
+ database.connect(callback)
511
+ ```
512
+
513
+ - callback: callback function
514
+
515
+ ##### Example:
516
+
517
+ ```js
518
+ let database = database.connect((result, error) => {
519
+ if (!error) {
520
+ console.log(result)
521
+ }
522
+ })
523
+ ```
524
+
525
+ - Return result example:
526
+
527
+ ```json
528
+ {
529
+ "dbPath": "/home/linaro/.config/dios/data/lwa.db"
530
+ }
531
+ ```
532
+
533
+ ### Database.run
534
+
535
+ Run sql
536
+
537
+ ```js
538
+ database.run(sql, callback)
539
+ ```
540
+
541
+ - sql: execute sql statement
542
+ - callback: callback function
543
+
544
+ ##### Example:
545
+
546
+ ```js
547
+ database.run('select * from device', (result, error) => {
548
+ if (!error) {
549
+ console.log(result)
550
+ }
551
+ })
552
+ ```
553
+
554
+ - Return result example:
555
+
556
+ ```json
557
+ [
558
+ {
559
+ "id": 1,
560
+ "value": "{\"type\":\"printer\",\"name\":\"HP-1\"}",
561
+ "tid": "tra-001",
562
+ "sync": 0,
563
+ "timestamp": 1691401911678
564
+ },
565
+ {
566
+ "id": 2,
567
+ "value": "{\"type\":\"printer\",\"name\":\"HP-2\"}",
568
+ "tid": "tra-002",
569
+ "sync": 0,
570
+ "timestamp": 1691401911681
571
+ }
572
+ ]
573
+ ```
574
+
575
+ ### Database.Table
576
+
577
+ Constructor
578
+
579
+ ```js
580
+ let table = new Database.Table(name, db);
581
+ ```
582
+
583
+ - name: table name
584
+ - db: database instance
585
+
586
+ ##### Example:
587
+
588
+ ```js
589
+ let table = new Database.Table('device', database);
590
+ ```
591
+
592
+ ### Table.create
593
+
594
+ Create a database table
595
+
596
+ ```js
597
+ table.create([opts], callback)
598
+ ```
599
+
600
+ - opts: optional parameters, including 3 attributes:
601
+ * retentionTime: retention time, in hours; if not passed, it will be retained forever by default
602
+ * keyName: name, if not passed, it will be 'id' by default
603
+ * keyType: type, including 2 types 'TEXT' and 'INTEGER', if not passed, it will be 'INTEGER' by default
604
+ - callback: callback function
605
+
606
+ ##### Example:
607
+
608
+ ```js
609
+ table.create((result, error) => {
610
+ if (!error) {
611
+ console.log(result)
612
+ }
613
+ });
614
+ ```
615
+
616
+ - Return result example:
617
+
618
+ ```json
619
+ []
620
+ ```
621
+
622
+ ### Table.insert
623
+
624
+ Insert data
625
+
626
+ ```js
627
+ table.insert(value, [opts], callback);
628
+ ```
629
+
630
+ - value: Insert data
631
+ - opts: optional parameters
632
+ * tid: foreign key id, used to establish relationships between multiple records
633
+ - callback: callback function
634
+
635
+ ##### Example:
636
+
637
+ ```js
638
+ let tid = "tra-001";
639
+ table.insert({type: "printer", name: "NEC"}, {tid: tid}, (result, error) => {
640
+ if (!error) {
641
+ console.log(result)
642
+ }
643
+ });
644
+ ```
645
+
646
+ - Return result example:
647
+
648
+ ```json
649
+ {
650
+ "status": true,
651
+ "row": 1
652
+ }
653
+ ```
654
+
655
+ ### table.insertById
656
+
657
+ Insert data by id
658
+
659
+ ```js
660
+ table.insertById(id, value, [opts], callback)
661
+ ```
662
+
663
+ - id: data id
664
+ - value: insert data
665
+ - opts: optional parameters
666
+ * tid: Foreign key id, used to establish relationships between multiple records
667
+ - callback: callback function
668
+
669
+ ##### Example:
670
+
671
+ ```js
672
+ let tid = "tra-001";
673
+ table.insertById(1, {type: "printer", name: "NEC"}, {tid: tid}, (result, error) => {
674
+ if (!error) {
675
+ console.log(result)
676
+ }
677
+ });
678
+ ```
679
+
680
+ - Return result example:
681
+
682
+ ```json
683
+ {
684
+ "status": true,
685
+ "row": 1
686
+ }
687
+ ```
688
+
689
+ ### Table.update
690
+
691
+ Update data
692
+
693
+ ```js
694
+ table.update(id, value, callback);
695
+ ```
696
+
697
+ - id: data id
698
+ - value: update data
699
+ - callback: callback function
700
+
701
+ ##### Example:
702
+
703
+ ```js
704
+ table.update(row, {type: "printer", name: "HP-2"}, (result, error) => {
705
+ if (!error) {
706
+ console.log(result)
707
+ }
708
+ });
709
+ ```
710
+
711
+ - Return result example:
712
+
713
+ ```json
714
+ {
715
+ "status": true,
716
+ "msg": 0
717
+ }
718
+ ```
719
+
720
+ ### table.delete
721
+
722
+ Delete data
723
+
724
+ ```js
725
+ table.delete(id, callback)
726
+ ```
727
+
728
+ - id: data id
729
+ - callback: callback function
730
+
731
+ ### Table.query
732
+
733
+ Query data
734
+
735
+ ```js
736
+ table.query(id, callback);
737
+ ```
738
+
739
+ - id: data id
740
+ - callback: callback function
741
+
742
+ ##### Example:
743
+
744
+ ```js
745
+ deviceTable.query(row, (result, error) => {
746
+ if (!error) {
747
+ console.log(result)
748
+ }
749
+ });
750
+ ```
751
+
752
+ - Return result example:
753
+
754
+ ```json
755
+ [
756
+ {
757
+ "id": 2,
758
+ "value": "{\"type\":\"printer\",\"name\":\"HP-2\"}",
759
+ "tid": "tra-001",
760
+ "sync": 0,
761
+ "timestamp": 1691401911681
762
+ }
763
+ ]
764
+ ```
765
+
766
+ ### Table.sync
767
+
768
+ Synchronize data
769
+
770
+ ```js
771
+ table.sync(id, callback);
772
+ ```
773
+
774
+ - id: data id
775
+ - callback: callback function
776
+
777
+ ##### Example:
778
+
779
+ ```js
780
+ deviceTable.sync(row, (result, error) => {
781
+ if (!error) {
782
+ console.log(result)
783
+ }
784
+ });
785
+ ```
786
+
787
+ - Return result example:
788
+
789
+ ```json
790
+ {
791
+ "status": true,
792
+ "msg": 0
793
+ }
794
+ ```
795
+
796
+ ### Table.queryUnsynced
797
+
798
+ Query unsynchronized data
799
+
800
+ ```js
801
+ table.queryUnsynced([opts], callback);
802
+ ```
803
+
804
+ - opts: optional parameters
805
+ - callback: callback function
806
+
807
+ ##### Example:
808
+
809
+ ```js
810
+ deviceTable.queryUnsynced((result, error) => {
811
+ if (!error) {
812
+ console.log(result)
813
+ }
814
+ });
815
+ ```
816
+
817
+ - Return result example:
818
+
819
+ ```json
820
+ [
821
+ {
822
+ "id": 1,
823
+ "value": "{\"type\":\"printer\",\"name\":\"NEC\"}",
824
+ "tid": "tra-001",
825
+ "sync": 0,
826
+ "timestamp": 1691402230172
827
+ }
828
+ ]
829
+ ```
830
+
831
+ ### Table.queryByTid
832
+
833
+ Query data by foreign key
834
+
835
+ ```js
836
+ table.queryByTid(tid, callback);
837
+ ```
838
+
839
+ - tid: foreign key id
840
+ - callback: callback function
841
+
842
+ ##### Example:
843
+
844
+ ```js
845
+ deviceTable.queryByTid("tra-001", (result, error) => {
846
+ if (!error) {
847
+ console.log(result)
848
+ }
849
+ });
850
+ ```
851
+
852
+ - Return result example:
853
+
854
+ ```json
855
+ [
856
+ {
857
+ "id": 2,
858
+ "value": "{\"type\":\"printer\",\"name\":\"HP-2\"}",
859
+ "tid": "tra-001",
860
+ "sync": 0,
861
+ "timestamp": 1691401911681
862
+ }
863
+ ]
864
+ ```
865
+
866
+ ### Table.queryAll
867
+
868
+ Query all data
869
+
870
+ ```js
871
+ table.queryAll(callback);
872
+ ```
873
+
874
+ - callback: callback function
875
+
876
+ ##### Example:
877
+
878
+ ```js
879
+ deviceTable.queryAll((result, error) => {
880
+ if (!error) {
881
+ console.log(result)
882
+ }
883
+ });
884
+ ```
885
+
886
+ - Return result example:
887
+
888
+ ```json
889
+ [
890
+ {
891
+ "id": 1,
892
+ "value": "{\"type\":\"printer\",\"name\":\"HP-1\"}",
893
+ "tid": "tra-001",
894
+ "sync": 0,
895
+ "timestamp": 1691401911678
896
+ },
897
+ {
898
+ "id": 2,
899
+ "value": "{\"type\":\"printer\",\"name\":\"HP-2\"}",
900
+ "tid": "tra-002",
901
+ "sync": 0,
902
+ "timestamp": 1691401911681
903
+ }
904
+ ]
905
+ ```
906
+
907
+
908
+ # Device&Diver API
909
+
910
+ ## Driver
911
+
912
+ ### Driver
913
+
914
+ Constructor
915
+
916
+ ```js
917
+ const driver = new Driver(name = 'default-driver-name', type = cutosAPI.DEVICE.DEFAULT, counter = 10)
918
+ ```
919
+
920
+ - name: driver name, default is 'default-driver-name'
921
+ - type: device type, default is cutosAPI.DEVICE.DEFAULT
922
+ - counter: heartbeat interval, default is 10s
923
+
924
+ ### Driver.sendData
925
+
926
+ Send data to the device
927
+
928
+ ```js
929
+ driver.sendData(data)
930
+ ```
931
+
932
+ - data: data
933
+
934
+ ### Driver.onCommand
935
+
936
+ Receive device commands
937
+
938
+ ```js
939
+ driver.onCommand(listener)
940
+ ```
941
+
942
+ - listener: listen callback function (command, [callback]), call callback after processing command
943
+ - command: command, example: {cmd: "connect", args: ""}
944
+ - callback: callback function (result)
945
+
946
+ ## SDK
947
+
948
+ ### Device
949
+
950
+ Constructor
951
+
952
+ ```js
953
+ const device = new (name = 'default-device-name', type = cutosAPI.DEVICE.DEFAULT)
954
+ ```
955
+
956
+ * name: device name, default is 'default-device-name'
957
+ * type: device type, default is cutosAPI.DEVICE.DEFAULT
958
+
959
+ ### Device.init
960
+
961
+ Device initialization
962
+
963
+ ```js
964
+ device.init([opts], callback)
965
+ ```
966
+
967
+ * opts: optional parameters, passed to the driver loading process, refer
968
+ to [Driver Template](#download-project-template)
969
+ * callback: callback function
970
+
971
+ ##### Example:
972
+
973
+ ```js
974
+ device.init((result, error) => {
975
+ if (error) {
976
+ console.log(error)
977
+ return;
978
+ }
979
+ console.log(result)
980
+ });
981
+ ```
982
+
983
+ ### Device.sendCommand
984
+
985
+ Send a command to the driver
986
+
987
+ ```js
988
+ device.sendCommand(command, callback)
989
+ ```
990
+
991
+ - command: command, example: command = {cmd: "connect", args: ""}
992
+ - callback: callback function, you can pass a listening callback function to listen to the device status
993
+
994
+ ##### Example:
995
+
996
+ ```js
997
+ device.sendCommand({cmd: "connect", args: ""}, Listener(msg))
998
+ ```
999
+
1000
+ ### Device.onData
1001
+
1002
+ Receive data sent by the driver
1003
+
1004
+ ```js
1005
+ device.onData(listener)
1006
+ ```
1007
+
1008
+ - listener: listener callback function (data)
1009
+ - data: data
1010
+
1011
+ ## Device driver relationship
1012
+
1013
+ ##### 1. onData and sendData
1014
+
1015
+ ![ddr1.png](..%2Fimg%2Fddr1.png)
1016
+
1017
+ ##### 2. sendCommand (without callback function) and onCommand
1018
+
1019
+ ![ddr2.png](..%2Fimg%2Fddr2.png)
1020
+
1021
+ ##### 3. sendCommand (with callback function) and onCommand
1022
+
1023
+ ![ddr3.png](..%2Fimg%2Fddr3.png)
1024
+
1025
+ ## Device driver management template
1026
+
1027
+ ### Download project template
1028
+
1029
+ | <span style="white-space:nowrap;">Name </span> | Description | Download |
1030
+ |:-----------------------------------------------|:----------------------:|:-----------------------------------------------------------------------------------:|
1031
+ | driver-template | Device driver template | [Download](https://oss.cut-os.com/resources/developer/template/driver-template.zip) |
1032
+
1033
+ ##### Project structure
1034
+
1035
+ ```
1036
+ ├── driver/ # Driver
1037
+ │ ├── src/ # Driver source directory
1038
+ │ ├── config.json # Configuration file, configure related parameters
1039
+ │ ├── driver-template.js # Driver template
1040
+ │ ├── driver-template-def.js # Device driver data definition (same as in SDK)
1041
+ │ ├── index.js # Driver loading file
1042
+ │ ├── test/ # Test directory
1043
+ │ ├── main.js # Test entry file, simulate cutos, create a driver service
1044
+ │ ├── package.json # Configuration information for this project
1045
+ │ ├── gulpfile.js # Packaging file
1046
+ │ ├── readme.txt # Instructions
1047
+ ├── sdk/ # Interface SDK
1048
+ │ ├── src/ # Source code directory
1049
+ │ ├── driver-template.js # Device template
1050
+ │ ├── driver-template-def.js # Device driver data definition (same as in driver)
1051
+ │ ├── test/     # Test directory
1052
+ │ ├── main.js # Test entry file
1053
+ │ ├── package.json # Configuration information for this project
1054
+ │ ├── gulpfile.mjs # Packaging file
1055
+ │ ├── readme.txt # Instructions
1056
+ ```
1057
+
1058
+ ### Installation dependencies
1059
+
1060
+ > Note: node version >= 16
1061
+
1062
+ ```
1063
+ cd driver-template/driver
1064
+ npm install
1065
+ ```
1066
+
1067
+ ```
1068
+ cd driver-template/sdk
1069
+ npm install
1070
+ ```
1071
+
1072
+ [//]: # (### Template-based development)
1073
+
1074
+ ### Project startup
1075
+
1076
+ You need to start the driver first, then start the SDK.
1077
+
1078
+ ```
1079
+ npm start
1080
+ ```
1081
+
1082
+ If the startup is successful, the console will return the following content
1083
+
1084
+ * driver
1085
+
1086
+ ```
1087
+ CUTOS CORE connected.
1088
+ CUTOS Simulator started and listening on port 1883
1089
+ drvDefault onCommand
1090
+ {
1091
+ "cmd":"init",
1092
+ "args":{"name":"driver-template","type":"driver-template","development":true},
1093
+ "topicResponse":"device-channel-driver-template-response"
1094
+ }
1095
+ connect: received.
1096
+ cmd: custom-cmd received.
1097
+ cmd: unknown is unsupported.
1098
+ ```
1099
+
1100
+ * SDK
1101
+
1102
+ ```
1103
+ CUTOS CORE connected.
1104
+ driver template init true
1105
+ connect: { msg: 'return success.', status: true }
1106
+ ```
1107
+
1108
+ ### Packaging and Release
1109
+
1110
+ ##### Packaging Driver
1111
+
1112
+ ```
1113
+ cd driver-template/driver
1114
+ npm run build
1115
+ ```
1116
+
1117
+ ```
1118
+ ├── driver/
1119
+ │ ├── dist/ # Packaging directory
1120
+ │ ├── driver-template-v1.0.1.drv # Packaging file
1121
+ ```
1122
+
1123
+ ##### Release the driver
1124
+
1125
+ Upload the package file to https://www.cut-os.com/ and publish
1126
+ Hardware/Driver--Add
1127
+
1128
+ ##### Packaged Device SDK
1129
+
1130
+ ```
1131
+ cd driver-template/sdk
1132
+ npm run build
1133
+ ```
1134
+
1135
+ ```
1136
+ ├── sdk/
1137
+ │ ├── dist/ # Packaging directory
1138
+ │ ├── driver-template-sdk-v1.0.2.zip # Packaging files
1139
+ ```
1140
+
1141
+ ##### Note:
1142
+
1143
+ > 1.The template device-template.js references TYPE, CMD exported in device-template-def.js
1144
+ >
1145
+ > `import {CMD, TYPE} from './device-template-def.js';`
1146
+ > * Device type (TYPE):
1147
+ >
1148
+ - Type constant: key "TEMPLATE", value "Device template".
1149
+ > - Indicates the template type, identifying the category of the device.
1150
+ >* Command type (CMD):
1151
+ >
1152
+ - CMD constant with two pairs:
1153
+ >
1154
+ - CONNECT: 'connect' represents the connection command.
1155
+ > - CUSTOM_CMD: "custom-cmd" represents a custom command for a specific device.
1156
+
1157
+ > 2.Configuration requirements: Keep the TYPE parameter 3 in the template consistent so that the driver matches the
1158
+ > corresponding SDK.
1159
+ >
1160
+ > ```let device = new DeviceTemplate('device-template',callback)``` //device-template.js
1161
+ >
1162
+ > ``` const TYPE = 'device-template';```//device-template-def.js
1163
+ >
1164
+ > ```{"name": "device-template",...}```//config.json
1165
+
1166
+ ## Review
1167
+
1168
+ The complete code is as follows:
1169
+
1170
+ ### driver
1171
+
1172
+ ```js
1173
+ // driver/src/driver-template.js
1174
+ const {CoreDefine, CoreClass} = require('@cutos/core');
1175
+ const {TYPE, CMD} = require('./driver-template-def.js');
1176
+ const config = require('./config.json');
1177
+
1178
+ class DriverTemplate extends CoreClass.Driver {
1179
+ constructor(args) {
1180
+ // check
1181
+ if (TYPE !== config.type) {
1182
+ throw "Error: the 'type' value in config.js and *-def.js MUST be identical.";
1183
+ }
1184
+ super(args.name, TYPE);
1185
+
1186
+ this.startBeat();
1187
+ this.updateStatusInfo(CoreDefine.HEARTBEAT_STATUS.ALIVE, "alive");
1188
+
1189
+ this.onCommand(({cmd, args}, callback) => {
1190
+ // Listen to the messages sent by the device SDK, process the different commands in the message body,
1191
+ // and respond back to the device SDK through the callback function.
1192
+ switch (cmd) {
1193
+ case CMD.CONNECT:
1194
+ this.connect(args, callback);
1195
+ break;
1196
+ case CMD.CUSTOM_CMD:
1197
+ this.customCmd(cmd, args);
1198
+ break;
1199
+ default:
1200
+ this.unsupported(cmd, args, callback);
1201
+ break;
1202
+ }
1203
+ });
1204
+ }
1205
+
1206
+ unsupported(cmd, args, callback) {
1207
+ let result = {};
1208
+ result.msg = "cmd: " + cmd + " is unsupported.";
1209
+ result.status = false;
1210
+ console.log(result.msg);
1211
+ callback(result);
1212
+ }
1213
+
1214
+ connect(args, callback) {
1215
+ console.log("connect: received.");
1216
+ let result = {};
1217
+ result.msg = "return success.";
1218
+ result.status = true;
1219
+ callback(result);
1220
+ }
1221
+
1222
+ // no response
1223
+ customCmd(cmd, args) {
1224
+ console.log("cmd: " + cmd + args, " received.");
1225
+ // process cmd below
1226
+ }
1227
+
1228
+ sendCustomData() {
1229
+ let data = {};
1230
+ data.type = "custom-type"; // custom defined data type
1231
+ data.values = {}; // values from template driver
1232
+ data.values.val = "any value";
1233
+ data.values.timeStamp = Date.now();
1234
+ this.sendData(data);
1235
+ }
1236
+ }
1237
+
1238
+ module.exports = DriverTemplate;
1239
+ ```
1240
+
1241
+ ### SDK
1242
+
1243
+ ```js
1244
+ // sdk/src/driver-template.js
1245
+
1246
+ import {CoreClass} from '@cutos/core';
1247
+ import {CMD, TYPE} from './driver-template-def.js';
1248
+
1249
+ class DriverTemplate extends CoreClass.Device {
1250
+ constructor(name, callback, opts = {development: true}) {
1251
+ super(name, TYPE, callback, opts);
1252
+
1253
+ this.onData((data) => {
1254
+ console.log("on data", data)
1255
+ });
1256
+ }
1257
+
1258
+ connect(callback) {
1259
+ let cmdMessage = {cmd: CMD.CONNECT};
1260
+ this.sendCommand(cmdMessage, callback);
1261
+ }
1262
+
1263
+ customCmd() {
1264
+ let cmdMessage = {cmd: CMD.CUSTOM_CMD, args: ""};
1265
+ this.sendCommand(cmdMessage);
1266
+ }
1267
+ }
1268
+
1269
+ export {DriverTemplate};
1270
+ ```
1271
+
1272
+ ```js
1273
+ // sdk/test/main.js
1274
+ import {CoreAPI} from '@cutos/core';
1275
+ import {DriverTemplate} from '../src/driver-template.js';
1276
+
1277
+ CoreAPI.init(null, () => {
1278
+ //
1279
+ let device = new DriverTemplate('driver-template', ({result, msg}) => {
1280
+ console.log("driver template init", result, msg ? " error:" + msg : "");
1281
+
1282
+ device.onData((data) => {
1283
+ console.log("on data", data)
1284
+ });
1285
+
1286
+ device.connect((result) => {
1287
+ console.log("connect: ", result)
1288
+ });
1289
+ device.customCmd();
1290
+ device.sendCommand({cmd: "unknown", args: ""});
1291
+ });
1292
+ });
1293
+ ```
1294
+
1295
+
1296
+ # Notification API
1297
+
1298
+ ### CoreAPI.getNotification
1299
+
1300
+ Get notification information instance object
1301
+
1302
+ ```js
1303
+ let notification = CoreAPI.getNotification();
1304
+ ```
1305
+
1306
+ ### notification.register
1307
+
1308
+ Register notification listener function
1309
+
1310
+ ```js
1311
+ notification.register(listener)
1312
+ ```
1313
+
1314
+ * listener: listener function
1315
+
1316
+ ##### Example:
1317
+
1318
+ ```js
1319
+ notification.register((data) => {
1320
+ console.log(data);
1321
+ })
1322
+ ```
1323
+
1324
+ - Return result example:
1325
+
1326
+ ```json
1327
+ {
1328
+ "event": "networkConnection",
1329
+ "msg": true
1330
+ }
1331
+ ```
1332
+
1333
+ * event: event name
1334
+ * msg: event content
1335
+
1336
+ ### notification.unregister
1337
+
1338
+ Unregister, used to cancel the registration of `notification.register`
1339
+
1340
+ ```js
1341
+ notification.unregister()
1342
+ ```
1343
+
1344
+ ### notification.emit
1345
+
1346
+ Cancel registration, used to cancel the registration of `notification.register`
1347
+
1348
+ ```js
1349
+ notification.emit(event, msg)
1350
+ ```
1351
+
1352
+ * event: event name
1353
+ * msg: event content
1354
+
1355
+ ##### Example:
1356
+
1357
+ ```js
1358
+ import {CoreAPI} from '@cutos/core';
1359
+
1360
+ CoreAPI.init();
1361
+
1362
+ let notification = CoreAPI.getNotification();
1363
+ notification.register((data) => {
1364
+ console.log(data);
1365
+ })
1366
+ notification.emit('notification-1', 'msg-1')
1367
+ ```
1368
+
1369
+ - Return result example:
1370
+
1371
+ ```json
1372
+ {
1373
+ "event": "notification-1",
1374
+ "msg": "msg-1"
1375
+ }
1376
+ ```
1377
+
1378
+ ### System notification
1379
+
1380
+ ##### Network status notification
1381
+
1382
+ ```json
1383
+ {
1384
+ "event": "networkConnection",
1385
+ "msg": true
1386
+ }
1387
+ ```
1388
+ * networkConnection: Network status notification
1389
+ * true: online; false: offline
1390
+
1391
+
1392
+ # Logger API
1393
+
1394
+ ### CoreAPI.getLogger
1395
+
1396
+ Get the log instance object
1397
+
1398
+ ```js
1399
+ let logger = CoreAPI.getLogger();
1400
+ ```
1401
+
1402
+ ### logger.info
1403
+
1404
+ Information
1405
+
1406
+ ```js
1407
+ logger.info(remark, content, type = "LWA")
1408
+ ```
1409
+
1410
+ * remark: remark;
1411
+ * content: content;
1412
+ * type: type, default is LWA if not passed.
1413
+
1414
+ ##### Example:
1415
+
1416
+ ```js
1417
+ logger.info('face-api', 'success')
1418
+ ```
1419
+
1420
+ * Return result log file example:
1421
+
1422
+ ```json
1423
+ {
1424
+ "dateTime": 1709891709950,
1425
+ "status": "The server is alive!"
1426
+ }
1427
+ ```
1428
+
1429
+ ### logger.warning
1430
+
1431
+ Warning
1432
+
1433
+ ```js
1434
+ logger.warning(remark, content, type = "LWA")
1435
+ ```
1436
+
1437
+ * remark: remark;
1438
+ * content: content;
1439
+ * type: type, default is LWA if not passed.
1440
+
1441
+ ##### Example:
1442
+
1443
+ ```js
1444
+ logger.warning('face-api', 'warning-content')
1445
+ ```
1446
+
1447
+ * Return result log file example:
1448
+
1449
+ ```json
1450
+ {
1451
+ "type": "LWA",
1452
+ "level": "warning",
1453
+ "remark": "face-api",
1454
+ "content": "warning-content"
1455
+ }
1456
+ ```
1457
+
1458
+ ### logger.error
1459
+
1460
+ Error
1461
+
1462
+ ```js
1463
+ logger.error(remark, content, type = "LWA")
1464
+ ```
1465
+
1466
+ * remark: remark;
1467
+ * content: content;
1468
+ * type: type, default is LWA if not passed.
1469
+
1470
+ ##### Example:
1471
+
1472
+ ```js
1473
+ logger.error('face-api', 'fatal-content')
1474
+ ```
1475
+
1476
+ * Example of returned result log file:
1477
+
1478
+ ```
1479
+ AxiosError: Network Error
1480
+ ```
1481
+
1482
+ ### logger.debug
1483
+
1484
+ Debug
1485
+
1486
+ ```js
1487
+ logger.debug(remark, content, type = "LWA")
1488
+ ```
1489
+
1490
+ * remark: remark;
1491
+ * content: content;
1492
+ * type: type, default is LWA if not passed.
1493
+
1494
+ ##### Example:
1495
+
1496
+ ```js
1497
+ logger.debug('face-api', 'debug-content')
1498
+ ```
1499
+
1500
+ * Example of returned result log file:
1501
+
1502
+ ```json
1503
+ {
1504
+ "type": "LWA",
1505
+ "level": "debug",
1506
+ "remark": "face-api",
1507
+ "content": "debug-content"
1508
+ }
245
1509
  ```