forked from cradlepoint/sdk-samples
-
Notifications
You must be signed in to change notification settings - Fork 0
/
NCOS_API_for_Applications.html
1219 lines (1130 loc) · 43.3 KB
/
NCOS_API_for_Applications.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>NCOS_API_for_Applications</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style type="text/css">
/* GitHub stylesheet for MarkdownPad (http://markdownpad.com) */
/* Author: Nicolas Hery - http://nicolashery.com */
/* Version: b13fe65ca28d2e568c6ed5d7f06581183df8f2ff */
/* Source: https://github.com/nicolahery/markdownpad-github */
/* RESET
=============================================================================*/
html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video {
margin: 0;
padding: 0;
border: 0;
}
/* BODY
=============================================================================*/
body {
font-family: Helvetica, arial, freesans, clean, sans-serif;
font-size: 14px;
line-height: 1.6;
color: #333;
background-color: #fff;
padding: 20px;
max-width: 960px;
margin: 0 auto;
}
body>*:first-child {
margin-top: 0 !important;
}
body>*:last-child {
margin-bottom: 0 !important;
}
/* BLOCKS
=============================================================================*/
p, blockquote, ul, ol, dl, table, pre {
margin: 15px 0;
}
/* HEADERS
=============================================================================*/
h1, h2, h3, h4, h5, h6 {
margin: 20px 0 10px;
padding: 0;
font-weight: bold;
-webkit-font-smoothing: antialiased;
}
h1 tt, h1 code, h2 tt, h2 code, h3 tt, h3 code, h4 tt, h4 code, h5 tt, h5 code, h6 tt, h6 code {
font-size: inherit;
}
h1 {
font-size: 28px;
color: #000;
}
h2 {
font-size: 24px;
border-bottom: 1px solid #ccc;
color: #000;
}
h3 {
font-size: 18px;
}
h4 {
font-size: 16px;
}
h5 {
font-size: 14px;
}
h6 {
color: #777;
font-size: 14px;
}
body>h2:first-child, body>h1:first-child, body>h1:first-child+h2, body>h3:first-child, body>h4:first-child, body>h5:first-child, body>h6:first-child {
margin-top: 0;
padding-top: 0;
}
a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
margin-top: 0;
padding-top: 0;
}
h1+p, h2+p, h3+p, h4+p, h5+p, h6+p {
margin-top: 10px;
}
/* LINKS
=============================================================================*/
a {
color: #4183C4;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* LISTS
=============================================================================*/
ul, ol {
padding-left: 30px;
}
ul li > :first-child,
ol li > :first-child,
ul li ul:first-of-type,
ol li ol:first-of-type,
ul li ol:first-of-type,
ol li ul:first-of-type {
margin-top: 0px;
}
ul ul, ul ol, ol ol, ol ul {
margin-bottom: 0;
}
dl {
padding: 0;
}
dl dt {
font-size: 14px;
font-weight: bold;
font-style: italic;
padding: 0;
margin: 15px 0 5px;
}
dl dt:first-child {
padding: 0;
}
dl dt>:first-child {
margin-top: 0px;
}
dl dt>:last-child {
margin-bottom: 0px;
}
dl dd {
margin: 0 0 15px;
padding: 0 15px;
}
dl dd>:first-child {
margin-top: 0px;
}
dl dd>:last-child {
margin-bottom: 0px;
}
/* CODE
=============================================================================*/
pre, code, tt {
font-size: 12px;
font-family: Consolas, "Liberation Mono", Courier, monospace;
}
code, tt {
margin: 0 0px;
padding: 0px 0px;
white-space: nowrap;
border: 1px solid #eaeaea;
background-color: #f8f8f8;
border-radius: 3px;
}
pre>code {
margin: 0;
padding: 0;
white-space: pre;
border: none;
background: transparent;
}
pre {
background-color: #f8f8f8;
border: 1px solid #ccc;
font-size: 13px;
line-height: 19px;
overflow: auto;
padding: 6px 10px;
border-radius: 3px;
}
pre code, pre tt {
background-color: transparent;
border: none;
}
kbd {
-moz-border-bottom-colors: none;
-moz-border-left-colors: none;
-moz-border-right-colors: none;
-moz-border-top-colors: none;
background-color: #DDDDDD;
background-image: linear-gradient(#F1F1F1, #DDDDDD);
background-repeat: repeat-x;
border-color: #DDDDDD #CCCCCC #CCCCCC #DDDDDD;
border-image: none;
border-radius: 2px 2px 2px 2px;
border-style: solid;
border-width: 1px;
font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
line-height: 10px;
padding: 1px 4px;
}
/* QUOTES
=============================================================================*/
blockquote {
border-left: 4px solid #DDD;
padding: 0 15px;
color: #777;
}
blockquote>:first-child {
margin-top: 0px;
}
blockquote>:last-child {
margin-bottom: 0px;
}
/* HORIZONTAL RULES
=============================================================================*/
hr {
clear: both;
margin: 15px 0;
height: 0px;
overflow: hidden;
border: none;
background: transparent;
border-bottom: 4px solid #ddd;
padding: 0;
}
/* TABLES
=============================================================================*/
table th {
font-weight: bold;
}
table th, table td {
border: 1px solid #ccc;
padding: 6px 13px;
}
table tr {
border-top: 1px solid #ccc;
background-color: #fff;
}
table tr:nth-child(2n) {
background-color: #f8f8f8;
}
/* IMAGES
=============================================================================*/
img {
max-width: 100%
}
</style>
</head>
<body>
<h1>NCOS API for Applications</h1>
<hr />
<h2>Quick Links</h2>
<h4><a href="#overview">Overview</a></h4>
<h4><a href="#ncos">NCOS Info</a></h4>
<h4><a href="#sdk_app_info">NCOS SDK and Application Info</a></h4>
<h4><a href="#logging">Logging</a></h4>
<h4><a href="#ping">Ping</a></h4>
<h4><a href="#gpio">GPIO</a></h4>
<h4><a href="#gps">GPS</a></h4>
<h4><a href="#modem">Modem</a></h4>
<h4><a href="#cpu">CPU and Memory Utilization</a></h4>
<h4><a href="#usb">USB Mass Storage</a></h4>
<h4><a href="#ncm">NetCloud Manager (NCM)</a></h4>
<h4><a href="#serial">Serial Port Access</a></h4>
<p><a name="overview"></a></p>
<h2>Overview</h2>
<p>The NCOS trees, also referred to as the NCOS config store, are essentially the APIs to NCOS query and control. Router tree item values can be read to determine their status or to verify the results of POST and PUT operations performed on them. Router tree items can be written to control and configure their values. All data is exchanged in the JSON format. The JSON format is described at <a href="http://www.json.org/">http://www.json.org/</a>. The data can be accessed via the device CLI, a python application, or using curl. </p>
<p>The NCOS config store consist of the following trees:</p>
<ul>
<li>
<strong>control</strong>
<ul>
<li>Elements used for controlling functions of NCOS.</li>
</ul>
</li>
<li>
<strong>config</strong>
<ul>
<li>Elements used for NCOS configuration.</li>
</ul>
</li>
<li>
<strong>status</strong>
<ul>
<li>Elements to get the status of the NCOS.</li>
</ul>
</li>
<li>
<strong>state</strong>
<ul>
<li>Should not to be used by applications.</li>
</ul>
</li>
</ul>
<p>This document does not describe every item in the NCOS config store. There are sections that cover functionality and how the config store can be used for that function (i.e. Ping, GPIO, GPS, Modem, etc.). Many functional areas will span multiple tree types depending on the use case. Anything which is done via the router UI, utilizes the router trees.</p>
<h2>CLI Example</h2>
<p>The following example of how to query NCOS system logging information using the <strong>cat</strong> or <strong>get</strong> command and then changing the logging level to <strong>info</strong> with the <strong>set</strong> command. Note the JSON format in the output. These trees can also be traversed using lthe Linux change directory command (i.e. cd /config/system/logging). This can be very useful to see what is contained in each branch of the tree.</p>
<pre><code> [admin@IBR900-267: /$ cat /config/system/logging
{
"console": false,
"enabled": true,
"firewall": false,
"level": "debug",
"max_logs": 1000,
"modem_debug": {
"lvl_error": false,
"lvl_info": false,
"lvl_trace": false,
"lvl_warn": false
},
"remoteLogging": {
"enabled": false,
"serverAddr": "192.168.20.171",
"server_port": 514,
"system_id": false,
"utf8_bom": false
},
"services": []
}
[admin@IBR900-267: /$ set /config/system/logging/level "info"
[admin@IBR900-267: /$ cat /config/system/logging
{
"console": false,
"enabled": true,
"firewall": false,
"level": "info",
"max_logs": 1000,
"modem_debug": {
"lvl_error": false,
"lvl_info": false,
"lvl_trace": false,
"lvl_warn": false
},
"remoteLogging": {
"enabled": false,
"serverAddr": "192.168.20.171",
"server_port": 514,
"system_id": false,
"utf8_bom": false
},
"services": []
}
</code></pre>
<h2>Python Example</h2>
<p>All sample apps include a cs.py file which contains the CSClient class. This class is a wrapper for the TCP interface to the NCOS trees. Below is an example of how to query NCOS system logging information and then change the logging level to <strong>debug</strong> using the CSClient class.</p>
<pre><code> # Import the CSClient file which contains the necessary functions
# for NCOS config store access
import cs
appName = 'ref_app'
cs.CSClient().log(appName, 'action({})'.format(command))
# Read the logging level
ret_value = cs.CSClient().get('/config/system/logging/level')
# Output a syslog for the current logging level
cs.CSClient().log(appName, 'Current Logging level = {}'.format(ret_value))
ret_value = ''
# Set the logging level to debug when the app is stopped.
ret_value = cs.CSClient().put('/config/system/logging', {'level': 'debug'})
# Output a syslog for the new current logging level
cs.CSClient().log(appName, 'New Logging level = {}'.format(ret_value))
</code></pre>
<h2>Curl Example</h2>
<p>On Linux, the curl command can also be used to access items in the NCOS trees. Use curl 'GET' to read and 'PUT' to write. Below is an example of getting the SDK status.</p>
<p>The user specific information in the curl command is:</p>
<ul>
<li>NCOS device user name: admin</li>
<li>NCOS device password: 44224267</li>
<li>
<p>NCOS device IP address: 192.168.0.1</p>
<pre><code> $ curl -s --digest --insecure -u admin:44224267 -H "Accept: application/json" -X GET http://192.168.0.1/api/status/system/sdk | /usr/bin/env python3 -m json.tool
{
"success": true,
"data": {
"service": "started",
"mode": "devmode",
"summary": "Service started"
}
}
curl -s --digest --insecure -u admin:44224267 -H "Accept: application/json" -X GET http://192.168.0.1/api/config/system/logging/level | /usr/bin/env python3 -m json.tool
{
"success": true,
"data": "debug"
}
curl -s --digest --insecure -u admin:44224267 -H "Accept: application/json" -X PUT http://192.168.0.1/api/config/system/logging/level -d data='"info"' | /usr/bin/env python3 -m json.tool
{
"success": true,
"data": "info"
}
</code></pre>
</li>
</ul>
<p><a name="ncos_info"></a></p>
<h2>NCOS Info</h2>
<p>There are three different trees that provide NCOS product type information. Most are self explanatory.</p>
<h3>Product Info /status/product_info/:</h3>
<pre><code> cat /status/product_info/
{
"company_name": "Cradlepoint, Inc.",
"company_url": "http://cradlepoint.com",
"copyright": "Cradlepoint, Inc. 2017",
"mac0": "00:30:44:22:42:67",
"manufacturing": {
"board_ID": "909507",
"mftr_date": "1643",
"serial_num": "WA164300000518"
},
"product_name": "IBR900LP6"
}
</code></pre>
<h3>Firmware Info /status/fw_info/:</h3>
<pre><code> cat /status/fw_info/
{
"build_date": "Wed Mar 8 18:57:21 MST 2017",
"build_type": "RELEASE",
"build_version": "cc2619b",
"custom_defaults": false,
"fw_update_available": false,
"major_version": 6,
"manufacturing_upgrade": false,
"minor_version": 3,
"patch_version": 1,
"upgrade_major_version": 0,
"upgrade_minor_version": 0,
"upgrade_patch_version": 0
}
</code></pre>
<h3>Feature Info /status/feature:</h3>
<p>The feature information provides a list of feature licenses. The two SDK licenses will only exist if the features have been enabled via the ECM. The value 'Router SDK' means that device apps have been enabled while the value 'Router SDK - Dev Mode' means that the development mode is enabled.</p>
<pre><code> cat /status/feature
{
"db": [
[
"46a03bd2-91ae-11e2-a305-002564cb1fdc",
"Extended Enterprise License",
1123,
1064
],
[
"b7b3eb09-53c5-4a5c-88d8-f9456870087c",
"Router SDK - Dev Mode",
7606,
7597
],
[
"9568fa81-d8e0-4223-a18c-0b1784f21f2a",
"Router SDK",
7607,
7597
]
],
"expiring_alert": false
}
</code></pre>
<h3>System ID /config/system/system_id:</h3>
<p>This is a customizable identity that will be used in device reporting and alerting. The default value is the product name and the last three characters in the MAC address of the device. It is used as a hostname to DHCP, so it must conform to standard hostname conventions.</p>
<pre><code> cat /config/system/system_id
"IBR900-267"
</code></pre>
<h3>Ethernet /status/ethernet:</h3>
<p>Shows current state of the Ethernet ports and their speed.</p>
<pre><code> cat /status/ethernet
[
{
"link": "up",
"link_speed": "1000FD",
"port": 0
},
{
"link": "up",
"link_speed": "1000FD",
"port": 1
},
{
"link": "down",
"link_speed": "Unknown",
"port": 2
}
]
</code></pre>
<p><a name="sdk_app_info"></a></p>
<h2>SDK and Application Info</h2>
<p>SDK and application information can be found in <strong>/status/system/sdk</strong>. It contains the state of the NCOS SDK service and any application. If there are any errors with installing or starting an application, they are contained in this tree.</p>
<h3>/status/system/sdk:</h3>
<p>The main items in SDK status tree are:</p>
<ul>
<li>
<strong>mode</strong>
<ul>
<li>
This indicates the route SDK mode which affects how apps can be installed.
<ul>
<li>standard - Normal NCOS mode when apps can be installed via NCM.</li>
<li>devmode - Development mode which allows apps to be installed directly from a computer. This is set from the Tools menu of NCM.</li>
</ul>
</li>
</ul>
</li>
<li>
<strong>service</strong>
<ul>
<li>The state of the NCOS SDK service in the router. </li>
</ul>
</li>
<li>
<strong>summary</strong>
<ul>
<li>A more detailed version of the NCOS SDK service state.</li>
</ul>
</li>
<li>
<strong>apps</strong>
<ul>
<li>A list of any apps that are installed with details about each app. Most are items self explanatory. However, note the 'state' which indicated the current state of the app. This can be installing, started, error, etc.</li>
</ul>
</li>
</ul>
<h4>No App installed:</h4>
<pre><code> cat /status/system/sdk
{
"mode": "devmode",
"service": "started",
"summary": "Service started"
}
</code></pre>
<h4>App installed:</h4>
<pre><code> cat /status/system/sdk
{
"apps": [
{
"_id_": "616acd0c-0475-479e-a33b-f7054843c971",
"app": {
"auto_start": true,
"date": "2017-03-31T15:49:17.537335",
"name": "hello_world",
"reboot": true,
"restart": false,
"uuid": "616acd0c-0475-479e-a33b-f7054843c971",
"vendor": "Cradlebpoint",
"version_major": 1,
"version_minor": 0
},
"state": "started",
"summary": "Started Application",
"type": "developer"
}
],
"mode": "devmode",
"service": "started",
"summary": "Service started"
}
</code></pre>
<p><a name="logging"></a></p>
<h2>Logging</h2>
<p>NCOS device logging can be queried or configured via <strong>/config/system/logging</strong>. This includes setting the log level along with sending logs to a syslog server. </p>
<pre><code> cat /config/system/logging/
{
"console": false,
"enabled": true,
"firewall": false,
"level": "debug",
"max_logs": 1000,
"modem_debug": {
"lvl_error": false,
"lvl_info": false,
"lvl_trace": false,
"lvl_warn": false
},
"remoteLogging": {
"enabled": false,
"serverAddr": "192.168.0.171",
"server_port": 514,
"system_id": false,
"utf8_bom": true
},
"services": []
}
</code></pre>
<ul>
<li>
<strong>console</strong>
<ul>
<li>Not Used.</li>
</ul>
</li>
<li>
<strong>enabled</strong>
<ul>
<li>Not Used.</li>
</ul>
</li>
<li>
<strong>firewall</strong>
<ul>
<li>Not Used.</li>
</ul>
</li>
<li>
<strong>level</strong>
<ul>
<li>Setting the log level controls which messages are stored or filtered out. A log level of Debug will record the most information while a log level of Critical will only record the most urgent messages.</li>
</ul>
</li>
<li>
<strong>max_logs</strong>
<ul>
<li>This is the maximum number of log messages the service will store. After this limit is reached, the oldest are lost as new messages come in. However, based on the platform, the limit may be smaller.</li>
</ul>
</li>
<li>
<strong>modem_debug</strong>
<ul>
<li>Used to set the modem logging level. Not recommended for application use.</li>
</ul>
</li>
<li>
<strong>remoteLogging</strong>
<ul>
<li>
enabled
<ul>
<li>Set true to send log messages to the specified Syslog Server.</li>
</ul>
</li>
<li>
serverAddr
<ul>
<li>The Hostname or IP address of the Syslog Server.</li>
</ul>
</li>
<li>
server_port
<ul>
<li>The Port Number of the Syslog Server.</li>
</ul>
</li>
<li>
system_id
<ul>
<li>Set true to include the devices "System ID" at the beginning of every log message. This is often useful when a single remote syslog server is handling logs for several devices.</li>
</ul>
</li>
<li>
utf8_bom
<ul>
<li>The log message is sent using a UTF-8 encoding. By default the device will preprend the Unicode Byte Order Mark (BOM) to the syslog message in compliance with the Syslog protocol, RFC5424. Some syslog servers may not support, fully, RFC5424 and will treat the BOM as ASCII text which will appear as garbled characters in the log. If this occurs, set this option to false.</li>
</ul>
</li>
</ul>
</li>
<li>
<strong>services</strong>
<ul>
<li>Not recommended for application use.</li>
</ul>
</li>
</ul>
<p><a name="ping"></a></p>
<h2>Ping</h2>
<p>Ping can be used to test communication to another host on the network. All ping operations and results are found in the /control/ping tree.</p>
<pre><code> cat /control/ping
{
"result": "",
"start": {
"bind_ip": false,
"deadline": "Same as timeout",
"df": "do",
"family": "inet",
"fwmark": null,
"host": null,
"iface": null,
"interval": 1,
"num": 4,
"size": 56,
"srcaddr": null,
"timeout": 11
},
"status": "",
"stop": ""
}
</code></pre>
<h3>Starting a Ping:</h3>
<p>Write operations to <strong>control/ping/start</strong> will initiate a ping. The following will start a basic ping when written: {"host": "www.google.com", "size": 64}. An IP address can also be used.</p>
<p><strong><em>NOTE:</em></strong> Concurrent ping operations are not supported.
</p>
<p>Ping Options for <strong>control/ping/start</strong>:</p>
<ul>
<li>
<strong>iface</strong>: device UID, interface name, or Network name
<ul>
<li>Allows ping to be sourced from an interface</li>
</ul>
</li>
<li>
<strong>bind_ip</strong>: boolean
<ul>
<li>Causes ping to bind to an IP on the interface specified by "iface".
</li>
</ul>
</li>
<li>
<strong>srcaddr</strong>: IP Address
<ul>
<li>Causes ping to be sourced from the specified IP address.</li>
</ul>
</li>
<li><strong>deadline</strong>: seconds</li>
<li>
<strong>timeout</strong>: seconds
<ul>
<li>If specified, ping will continue until either "num" packets are sent, or "timeout" seconds have elapsed. The two options are equivalent, and if both are specified, the lesser of the two is used</li>
</ul>
</li>
<li>
<strong>df</strong>: {<em>do</em>, <em>want</em>, or <em>dont</em>}
<ul>
<li>
Specify the Path MTU discovery option:
<ul>
<li><em>do</em>: Asserts the "Don't Fragment" flag in the ICMP requests, prohibiting fragmentation</li>
<li><em>want</em>: Allows local fragmentation, and will fragment the ICMP request if the ICMP request exceeds the outbound interfaces' MTU</li>
<li><em>dont</em>: Do not assert the "Don't Fragment" flag, allowing fragmentation, and will fragment the ICMP Requests in response to ICMP fragmentation responses</li>
</ul>
</li>
</ul>
</li>
<li>
<strong>fwmark</strong>: null/non-null
<ul>
<li>If non-null, then the SO_MARK socket option is set, causing the packetssent through the socket to be marked.</li>
</ul>
</li>
<li>
<strong>family</strong>: {<em>inet</em> or <em>inet6</em>}
<ul>
<li>If <em>inet</em>, then ping for IPv4 is used; if <em>inet6</em>, then the equivalent of ping6 is used.</li>
</ul>
</li>
<li>
<strong>host</strong>: Hostname, or IP address
<ul>
<li>Specifies the destination for the ICMP requests</li>
</ul>
</li>
<li>
<strong>interval</strong>: seconds
<ul>
<li>The number of seconds to wait between each ICMP request</li>
</ul>
</li>
<li>
<strong>num</strong>: integer
<ul>
<li>The number of ICMP requests to send before exiting. If "deadline" or "timeout" is also specified, then ping will exit after "num" packets have been sent, or min(deadline, timeout") seconds have elapsed.</li>
</ul>
</li>
<li>
<strong>size</strong>: bytes
<ul>
<li>Size of the ICMP request</li>
</ul>
</li>
</ul>
<h3>Stopping a Ping:</h3>
<p>Write operations to control/ping/stop will halt the ping in progress, if any. If a ping is not in progress, this is ignored.</p>
<h3>Retrieving Results and Status:</h3>
<p>Reading from <strong>control/ping/results</strong> will return the additional results since the last read, or the start of the ping, whichever is most recent. Reading the results will clear out the results immediately after they are read; the reader will need to concatenate the results if desired.</p>
<p><strong><em>NOTE:</em></strong> If more than 10 results accumulate between reads, the oldest results will be truncated such that the maximum number of result lines will never exceed 10.</p>
<p>Reading from <strong>control/ping/status</strong> will return the current state of the ping in progress. Unlike the results, this will persist through multiple reads. The status can be one of 'running', 'done', 'stopped', or 'error'. If any packets were transmitted during the Ping, then when the ping stops, the result summary will be posted to <strong>control/ping/results</strong> (and cleared when read)</p>
<p><a name="gpio"></a></p>
<h2>GPIO</h2>
<p>Some Cradlepoint devices have GPIO connectors and pins built into their power connectors The following information is related to GPIO router config store tree items.</p>
<h3>/config/system/gpio_actions</h3>
<p>Includes configuration data for all user configurable pins - This configuration dat reports if the pin is enabled, it's direction, and what action it is currently assigned to the pin. The available actions are:</p>
<p>if value of direction is <em>in</em>, available values for "current_action" are:</p>
<ul>
<li>
<em>in_action_sensing</em> Input Sensing:
<ul>
<li>In this mode the logic state (high or low) is automatically sensed by the device and is readable as the Current Value.</li>
</ul>
</li>
<li>
<em>in_action_ignition</em> Ignition Sensing:
<ul>
<li>(available on power connector only) In this mode the device will turn off after the input has been held low for the timeout period in seconds. The device will then reboot when the input is returned to high. If the input is held low for less than the timeout period before returning to high, no action is taken.</li>
</ul>
</li>
<li>
<em>in_action_reset</em> Device Reset:
<ul>
<li>(available on power connector only) In this mode an external device can reset the device by holding the input low for 10-seconds.</li>
</ul>
</li>
</ul>
<p>if value of direction is <em>out</em>, available values for "current_action" are:</p>
<ul>
<li>
<em>out_action_low</em> Default/Open:
<ul>
<li>In this mode the output pin is not used and is at 0V (ground potential).</li>
</ul>
</li>
<li>
<em>out_action_high</em> or <em>out_action_router_running</em> Set Closed/Router Running:
<ul>
<li>In these modes the output pin is logic low while the router is booting and transitions to logic high when the router is fully running. If the router is reset, the output returns to low until the router has fully rebooted.</li>
</ul>
</li>
<li>
<em>out_action_modem_connected</em> Modem Connected:
<ul>
<li>In this mode the output pin is logic low until the modem has connected to the tower. If the connection drops, this output is set low until the connection is restored.</li>
</ul>
</li>
</ul>
<p>The "pin" value is for internal purposes only. Please see <a href="#gpio_acions"><strong>/status/gpio_action</strong></a> for more information.</p>
<p><a name="gpio_acions"></a></p>
<h3>/status/gpio_actions</h3>
<p>Used to view capabilities of the GPIOs. Here you can see what actions a pin supports, and what direction it can be set to (some pins are fixed direction and some are bidirectional). You can also get the "pretty_value" string, which outputs the current state of the GPIO in human readable form. It is updated every time this field is accessed.</p>
<h3>/control/gpio</h3>
<p>Used to bypass the GPIO service and set values to gpio pins manually. Not recommended</p>
<h3>/status/gpio</h3>
<p>Used to read the GPIO values directly from the pins.</p>
<h3>/config/system/connector_gpio</h3>
<p>Deprecated - DO NOT USE.</p>
<p><a name="gps"></a></p>
<h2>GPS</h2>
<h3>GNSS vs GPS</h3>
<p>GNSS stands for Global Navigation Satellite Systems and GPS stand for Global Positioning System. GNSS is an umbrella term for all the satellite-based positioning systems, including GPS. GPS itself is the US satellite system but the term "GPS" is used interchangeably for all satellite positioning systems. See <a href="https://en.wikipedia.org/wiki/Satellite_navigation">https://en.wikipedia.org/wiki/Satellite_navigation</a> for more details about satellite navigation.</p>
<p>The most common assumption is that all modems are capable of GPS. In order for a cellular modem to support GPS, GPS must be a function of both the modem and carrier. GPS requires the following four elements:</p>
<ul>
<li>A cellular modem that supports GPS.</li>
<li>A cellular carrier that allows the GPS functionality on that modem.</li>
<li>Sufficient GPS signal level at the modem deployment location.</li>
<li>GPS antenna (depending on the model of modem or Cradlepoint).</li>
</ul>
<p>From an app access perspective, most use cases only needs to verify that GPS is enabled and get the GPS location data. This is described below.</p>
<h4>config/system/gps/enabled</h4>
<p>This is either true or false and indicates gps enablement.</p>
<h4>config/system/gps/enable_gps_keepalive</h4>
<p>By default, the GPS hardware goes into a low power state after a certain interval of inactivity. To prevent the GPS hardware from entering this low power state, set “enable<em>gps</em>keepalive” to true. When “enable<em>gps</em>keepalive” is enabled, the GPS service will poll the GPS hardware every 10 seconds and prevent the GPS from entering a low power state. Coming out of a low power state takes extra time to regain the GPS lock so set this flag to keep the hardware from falling asleep. Note this flag has no effect if the GPS service itself is not enabled.</p>
<h4>Get GPS location data</h4>
<p>The current GPS data can be found in <strong>/status/gps/</strong>.
</p>
<p>This contains two fields: fix and nmea. </p>
<ul>
<li>
<strong>fix</strong>:
<ul>
<li>a struct containing parsed information about the current GPS fix. </li>
</ul>
</li>
<li>
<strong>nmea</strong>
<ul>
<li>an array of National Marine Electronics Association (NMEA) strings. </li>
</ul>
</li>
</ul>
<p>An example output is:</p>
<pre><code> cat /status/gps
{
'fix': {'age': 1.2596200000261888,
'altitude_meters': 850.8,
'ground_speed_knots': 0.0,
'heading': 323.4,
'latitude': {'degree': 43.0,
'minute': 37.0,
'second': 10.84808349609375},
'lock': True,
'longitude': {'degree': -116.0,
'minute': 12.0,
'second': 20.53081512451172},
'satellites': 9,
'time': 204921},
'nmea': ['$GPGSV,4,1,16,05,14,275,24,07,61,082,30,08,40,063,28,09,29,167,26*71\r\n',
'$GPGSV,4,2,16,11,18,116,27,13,17,316,27,17,02,189,23,27,12,036,24*77\r\n',
'$GPGSV,4,3,16,28,53,243,25,30,67,317,32,33,,,35,38,,,34*7B\r\n',
'$GPGSV,4,4,16,39,,,34,40,,,34,41,,,34,42,,,34*73\r\n',
'$GPGGA,204920.0,4337.180827,N,11612.342184,W,1,09,0.9,850.8,M,-11.0,M,,*61\r\n',
'$GPVTG,323.4,T,308.9,M,0.0,N,0.0,K,A*27\r\n',
'$GPRMC,204920.0,A,4337.180827,N,11612.342184,W,0.0,323.4,110417,14.6,E,A*27\r\n',
'$GPGSA,A,2,05,07,08,09,11,13,27,28,30,,,,1.2,0.9,0.8*3C\r\n']
}
</code></pre>
<p><a name="modem"></a></p>
<h2>Modem</h2>
<p>The modem status and control information is part of the WAN tree. This is a very critical and complicated aspect of the device functionality. Please note that there is no direct access to the modem AT commands. For now, this section will only describe how to enable and disable a modem, along with some status information, as this has been requested by several application developers. </p>
<p>The list of modems in the system can be found here: get /status/wan/devices. While this will list all the wan devices, not all modems may be configured with a SIM card. Modem devices start with 'mdm-'. </p>
<pre><code> get status/wan/devices
{
"ethernet-wan": {
...
},
"mdm-feb80139": {
...
},
"mdm-fee5c7f2": {
...
}
}
</code></pre>
<p>To determine if a modem does not have SIM card inserted, see here: get status/wan/devices/mdm-<uid>/status/error_text. Where <uid> is the modem's unique identifier. The response will be 'null' if the SIM card is present.</p>
<pre><code> get status/wan/devices/mdm-fee5c7f2/status/error_text
"SIM error: NOSIM"
</code></pre>
<p>Here is an example of the diagnostic information for a modem with a SIM. This contains much data about the modem including its signal quality. Note that the "DBM" field is the modems RSSI.</p>
<pre><code> get status/wan/devices/mdm-fee5c7f2/diagnostics/
{
"BANDDLFRQ": "2110-2155",
"BANDULFRQ": "1710-1755",
"CARRID": "Verizon Wireless",
"CARRIER_SWITCH_DEFAULTS": "",
"CELL_ID": "2934137 (0x2cc579)",
"CFGAPNMASK": "72",
"CGSN": "356526070342666",
"CHIPSET": "9X30C",
"CLONE_INSTANCE": "0",
"CS": "UP",
"CUR_PLMN": "311480",
"DBM": "-61",
"DEFAPN": "3",
"DEFAPNTYPE": "IP",
"DISP_IMEI": "356526070342666",
"DISP_MEID": "35652607034266",
"DORMANT": "Active",
"EMMCOMMSTATE": "RRC Connected",
"EMMSTATE": "Registered",
"EMMSUBSTATE": "Normal Service",
"FW_CARRIER_LOAD": "VERIZON",
"GSN": "356526070342666",