-
Notifications
You must be signed in to change notification settings - Fork 0
/
heather.txt
7954 lines (7954 loc) · 386 KB
/
heather.txt
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
//
// Lady Heather's GPS Disciplined Oscillator Control Program
// (now works with many different receiver types and even without a GPS
// receiver. Also works with precision rubidium/cesium oscillators and
// frequency / time interval counters).
//
// Copyright (C) 2008-2019 Mark S. Sims
//
//
// Lady Heather is a monitoring and control program for GPS receivers, GPS
// Disciplined Oscillators, precision oscillators (rubidium and cesiem), and
// frequency / time interval counters. Heather is oriented more towards the
// time keeping functionality of GPS and less towards positioning. It supports
// numerous GPS (and Glonass, Beidou, Galileo, etc) devices including:
//
// GPS Receivers:
// Ashtech Z12 receiver
// Furuno GT-8031 (uses $PFEC commands)
// Furuno GT-87xx (using eSIP commands)
// GPSD interface (mainly a Linux/macOS/FreeBSD thing - GPSD provides
// a shared read-only interface to numerous GPS devices.
// Jupiter-T (aka Zodiac)
// Motorola binary
// NMEA
// NVS BINR binary (115200:8:N:1)
// Sirf binary
// Trimble TSIP binary receivers
// Trimble TAIP receivers
// Trimble SV6/SV8/ACE-III
// Trimble Accutime / Palisade receivers
// Trimble RT17 format receivers (like the NetRS)
// TymServe 2000 (not yet tested)
// Ublox UBX binary
// Venus/Navspark (115200:8:N:1)
//
// GPSDO's (GPS disciplined oscillators):
// Brandywine GPS-4 receiver
// DATUM STARLOC II GPSDO - inferior wannabe Thunderbolt
// Jackson Labs LTE Lite
// Lars simple GPSDO controller (used with any 1PPS output GPS receiver)
// Lucent RFTG-m GPSDO
// Lucent KS24361 REF0/Z3811A Z3812A
// NEC GPSDO ... STAR-4 compatible at 115,200 baud
// Oscilloquartz STAR-4 GPSDO (management interface)
// Oscilloquartz OSA-453x GPSDO
// SCPI - Nortel telecom GPSDOs like NTWB and NTPX in SCPI mode
// SCPI (Z3801A/Z38015/Z3816/etc style)
// SCPI (HP5xxxx style)
// Spectrum TM4 (not fully tested)
// Trimble TSIP binary GPSDOs (like the Thunderbolt and numerous
// "telecom" GPSDOs.
// TruePosition GPS
// UCCM - small Trimble / Symmetricom / Samsung telecom GPSDOs
// (57600 baud)
// Zyfer Nanosync 380 (19200:8:N:1)
//
// Atomic frequency references:
// HP 5071A cesium beam oscillator
// Spectratime/Temex LPFRS rubidium
// Spectratime/Temex RMO rubidium (same as LPFRS)
// Spectratime SRO100/SRO70 rubidium
// SRS PRS-10 rubidium oscillator
// Symmetricom SA22 rubidium (60 Mhz and 58.9824 MHz ref freq)
// Symmetricom X72 rubidium
// Symmetricom X99 rubidium
//
// Clocks:
// Acron Zeit WWVB receiver
// Gravity/solid earth tide clock (uses system clock to display
// solid earth tides and gravity offset, Requires manual entry
// of latitude/longitude/altitude)
// No receiver, uses system clock.
//
// Time and frequency counters:
// Generic frequency/time interval counters
// HP531xx counters
// Lars simple GPSDO controller
// PICPET simple timestamping interval counter chip
// TAPR TICC time interval counter
//
// Misc:
// Simple terminal emulator
// RPN calculator
//
//
// Permission is hereby granted, free of charge, to any person obtaining
// a copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//
//
// Original Win32 port by John Miles, KE5FX (john@miles.io)
// Help with Mac OS X port by Jeff Dionne and Jay Grizzard
// (note: OS/X version uses the XQuartz package for X11 display support)
// FreeBSD support by Daniel Lawrence
//
// Temperature and oscillator control algorithms by Warren Sarkison
//
// Original adev code adapted from Tom Van Baak's adev1.c and adev3.c
// Incremental adev code based upon John Miles' TI.CPP
//
// uGal gravity calculation code slightly adapted from Tom Van Baak's
// tides.c which was derived from code by J.L. Ahern which was based upon
// equations by P. Schureman
//
// Solid earth tide code translated from Fortran solid.f using the F2C
// translator program. solid.f was written by Dennis Milbert and is based
// upon the dehandtideinel/MJD code by V. Dehandt, S. Matherws, J. Gipson,
// and C. Bruynix.
//
// Easter and moon illumination phase code from voidware.com
//
// moon_info() derived from code in John Walker's moontool.c
//
// Equation of time code adapted from code by Mike Chirico and NOAA
//
// Sun position code is Grena's Algorithm 5
//
// Moon position from code by Paul Schlyter at
// http://hotel04.ausys.se/pausch/comp/ppcomp.html
//
// Heliocentric Julian Date code adapted from code by Richard Ogley.
//
// Nutation and obliquity code derived from code by Jay Tanner and JPL
//
// Equinox/Solstice equations derived from Jan Meeus "Astronomical Algorithms"
// via Simon Cassidy.
//
// Time of perihelion derived from table by Fred Espenak, www.Astropixels.com
//
// New moon table derived from table by Fred Espenak, www.Astropixels.com
//
// Moon image code derived from code by Mostafa Kaisoun.
//
// Nortel NTGS55A recever wakeup research by Sam Sergi
//
// Linux IPv6 support by Kasper Pedersen
//
// The LZW .GIF encoder used in this program was derived from code written by
// Gershon Elber and Eric S. Raymond as part of the GifLib package. And by
// Lachlan Patrick as part of the GraphApp cross-platform graphics library.
//
// Singing clock excerpted from Palistrina, Missa Assumpta by the Tallis
// Scholars... you should buy some of their stuff... they are quite good.
//
//
//
// This file contains most of the operating system dependent routines,
// initialization routines, serial port I/O, and the screen I/O and
// plotting routines.
//
//
//
//
//
//
//
//-PROGRAM CONFIGURATION AND HELP INFORMATION
//
// Heather has two types of user commands. The first is the command line
// options. You can get a list of command line options by starting Heather
// with an invalid command line option such as "/?". This will bring up
// a scroll box of commands on Windows and several pages of commands on
// other operating systems. You can also enter "?" from the keyboard to
// bring up the command line help information.
//
// Command line options can begin with either a '/' (Windows standard)
// or a '-' (Linux / macOS standard). Either is acceptable no matter what
// operating system you are using. Options must be separated by a space.
// Note that file names may not contain spaces and quoted options are not
// supported!
//
// Once Heather has started, you can enter command line options from the
// keyboard using the "/" keyboard command. There are a few command line
// options that cannot be changed from the keyboard once Heather has started.
//
//
//
// The second set of commands are the keyboard commands. You can get a list
// of the primary keyboard commands and menus by pressing SPACE. Note that
// not all receivers support all of the keyboard commands. Keyboard menu
// commands are shown in this documentation in upper case characters, but
// either upper case or lower case are acceptable.
//
// Pressing the first key of a command menu will show a sub-menu of commands
// available under that menu. Pressing the second key of a menu command
// will either execute the command or, more commonly, prompt for a value
// to enter. The default value offered as the input is either the current
// setting or a common value to use. You can press ENTER to accept the
// offered value, ESC or ESC ESC to abort the command, enter a new value,
// or edit the offered value.
//
// LEFT and RIGHT arrows move the cursor within the string. INSERT
// toggles insert mode. HOME moves to the start of the string. END moves
// to the end of the string. DEL deletes the character at the cursor.
// DOWN arrow deletes to the end of the line. UP arrow deletes to the
// start of the line. BACKSPACE deletes the character before the cursor.
// PAGE_UP retreives the last command entered. This lets you repeat the
// last entered command value or recover from a botched line edit.
//
// If a keyboard command suggests an input value and the first character
// that you enter is a not an editing character, the offered value is
// erased so that you don't have to backspace over it to enter a new value.
//
//
//
// Heather's configuration comes from three places:
//
// First is a hard coded configuration in the program.
// Next is from the file "heather.cfg"
// Finally is from the command line that starts the program.
//
// The location of "heather.cfg" depends upon the operating system and how
// Heather was started (from a command line or from a desktop icon). You
// can determine where to place the file by bringing up the command line
// help information (described above) and scrolling down to the bottom of
// the help information. There will be a line that says:
// "Put heather.cfg file in directory ..."
// The location of the file is also shown (in GREEN) when you press SPACE
// to get the keyboard help menu.
//
// Note that if you rename the "heather" executable file, the .cfg and .cal
// file names that Heather uses will also change to match the new executable
// file name.
//
// Note that this directory is also the default directory that Heather uses
// for all of its support files (sound files, log files, screen dumps, etc).
//
// If you launch Heather from a WINDOWS desktop icon, you can set the command
// line options by right clicking on the icon and selecting PROPERTIES.
// The TARGET field will show the command command line to use.
//
// Note that in this file a lot of command line options are described as
// "toggle" options. Toggle options are like on/off switches. For instance:
// /gw - will toggle the watch display between on and off and back on
// each time it is seen.
//
// You can override this toggle action and explictly set the state.
// For instance:
// /gw0 - forces the watch display OFF
// /gw1 - forces the watch display ON
//
//
//
// LADY HEATHER'S CONFIGURATION FILE "heather.cfg" :
//
// Place the command line options that you want to use in this file
// with one command line option per line. Each option MUST start in column
// one with a '/', '-', '@', or '$' otherwise the line will be treated as
// a comment.
//
// Lines that begin with '/' or '-' set command line option values.
//
// Lines that begin with '$' send hex values to the receiver.
//
// Lines that begin with '@' send keyboard commands (all '@' lines are copied
// to temporary keyboard script file "heathtmp.scr" which is then processed
// once Heather has finished initializing the hardware, etc). See the
// description of keyboard script files below.
//
// You can also read in a ".cfg" file from the keyboard "R" menu or from
// the command line:
// /r=file.cfg - reads a .cfg configuration file. These config files are
// processed after the default "heather.cfg" file has been
// processed. You should not include a "/r=file.cfg"
// command in a .cfg file since reading config files do
// not nest!
// Note: earlier versions of Lady Heather used the /h command to read
// .cfg files. The /h command now displays command line help.
//
//
// At a minimum, most users will want to configure the com port, receiver
// type, and time zone in their default configuration.
//
// If an error is detected in a command line option in the .cfg file,
// processing of the file is stopped and the command line help screen is
// shown. The offending option is listed at the end of the help info.
//
//
//
// KEYBOARD SCRIPT FILES:
//
// Lady Heather has the ability to read keyboard script files. These
// file must have an extension of ".scr" Script files mimic typing
// from the keyboard. Script file names must be less than 128 characters
// long.
//
// Commands that would normally suggest an input do not
// do it when read from a script file. They behave
// like you first entered ESC to erase the suggestion.
//
// Commands that normally toggle a flag may be followed
// by a "1" or "0" to set the flag value directly. e.g.
// you can use GW0 in a script file to force the watch display
// OFF. A few commands (like GS) do not toggle a specific value
// and cannot be used this way.
//
// You can put more than one command on a line (separated
// by spaces) until you do a command that expects a
// parameter value or string.
//
// A '~' in a script file pauses reading from the script
// and starts reading from the keyboard until a carriage
// return is seen. This is useful for entering a parameter
// value or string. e.g. GG~ will pause the script and
// prompt for a graph title.
//
// Any text following a ';' or a '#' in a script file
// is a comment and is ignored.
//
// Script files abort upon the first error detected or any
// unrecognized command is seen.
//
// Script files can be nested up to 5 levels deep.
// Scripts can be stopped by pressing any key.
//
// You can cause processing of a keyboard script file to wait for a
// time interval or a specific time. See the section on ALARMS for
// a description of how to do this.
//
// To run a script file use the "R" keyboard command or "/r" command
// line option and specify a file name with an extension of ".scr"
//
// The function keys F1..F10 (F1..F9 on Windows) cause keyboard script
// files "f1.scr" to "f10.scr" to be read. This allows F1..F10 to be
// used as programmable function keys.
//
// Heather normally puts a short pause between each character read from
// a script file. You can toggle "fast script" mode with the /nf command
// line option.
//
//
//
//
//
//-CONFIGURING THE COM PORT:
//
// Lady Heather talks to the GPS device via a serial port (hardware or USB)
// or an internet TCP/IP connection. You need to tell Heather which
// communications device to use. For serial ports you use the "/#" command
// line option (where # is the com port number to use):
// /1 says to use COM1
// /2 says to use COM2, etc
// /0 says to not use a communications link. This can be useful if you
// are just reading a log file, etc and do not want to talk to a receiver.
//
// On Linux systems the # number you specify IS 1 MORE THAN THE SERIAL PORT
// NUMBER:
// /1 says to use /dev/ttyS0 on Linux
// /1 says to use /dev/ttys0 on macOS
// /1 says to use /dev/cuaU0 on FreeBSD
//
// /2 says to use /dev/ttyS1 on Linux
// /2 says to use /dev/ttys1 on macOS
// /2 says to use /dev/cuaU1 on FreeBSD
//
// /999 says to use /dev/heather
//
// Windows treats USB connected serial adapters as standard hardware serial
// ports. Most Linux and macOS users will be using USB serial converters.
// These operating systems treat the USB devices differently than hardware
// serial ports. For these system you can use the "/#u" command line option.
//
// /1u says to use /dev/ttyUSB0 on Linux systems and
// /1u says to use /dec/tty.usbserial on macOS.
// /1u says to use /dev/cuaU0 on FreeBSD
//
// /2u says to use /dev/ttyUSB1 on Linux systems and
// /2u says to use /dec/tty.usbserial1 on macOS.
// /2u says to use /dev/cuaU1 on FreeBSD
//
// You can also follow the com port number with an "a" to use a /dev/ttyACM
// device:
// /1a says to use /dev/tty/ACM0
// /2a says to use /dev/tty/ACM1 ,etc.
//
// If your system does not use these standard device names, you can specify
// the input device name to use with the "/id=" command line option:
// /id=/dev/your_device_name
//
// Heather also supports using a TCP/IP connection to talk to your receiver.
// /ip=addr:port
// addr can be be either a numeric address like 192.168.10.20 or a web
// address like ke5fx.dyndns.org
//
// If the :port number is not given Heather uses port 45000
//
// Note that if the specified IP address is not valid or cannot be reached
// Heather may appear to hang for quite a while until/if the connection
// attempt times out. This is particularly true for numeric IP addresses.
//
// On Linux and macOS Heather supports IPv6 addresses. If the specified
// IP address is a "bracketed" IP address [....] you can specify the port
// number to use like [....]:45000 otherwise you can force an IPv6
// connection by using a ';' before the port number.
//
//
// For hardware serial port and USB serial connections you can specify the
// serial port baud rate and data format with the "/br=" command line option:
// /br=9600:8:N:1 (9600 baud, 8 data bits, no parity, 1 stop bit)
// /br=19200:7:E:1 (19200 baud, 7 data bits even parity, one stop bit)
// /br=57600:8:O:2 (57600 baud, 8 data bits odd parity, two stop bits)
//
// Many receivers that connect via a native USB port (not a USB-serial
// converter cable) use a "CDC" driver that effectively ignores the baud
// rate, etc parameters. You can Heather's port config to anything and
// they will still work.
//
// There is another parameter (:Px) that you can add to the /br parameters
// to select which external device (see the following section on external
// devices for more information) that you want to configure.
//
// If a baud rate parameter is not given in the "/br=" string, that
// parameter is not changed. Previous versions of Heather set that
// parameter to a default value.
//
// If a baud rate command is not given, Heather will use a default value
// that is most commonly used for the receiver type it is using... which
// may not be the same as what your receiver is configured for!
//
// Another way to specify the baud rate is to follow the serial port number
// with an ',' and the baud rate info like:
// /1,9600:8:N:1
//
//
// If com data is lost or the com port disappears Heather will attempt to
// re-init the com port every "com_timeout" interval (5-25 seconds
// depending upon the receiver type and the operation being done).
// You can disable com port error recovery with the /ce command line option.
// Heather can recover from things like yanked ethernet cables and USB
// dongles and dropped WIFI connections.
//
// You can specify the com port data loss timeout (in milliseconds) with
// the "/ct=#" or "/ct?=#" command line option. /ct sets the timeout for
// all devices ports. /ct? sets the timeout for just port '?' where '?'
// is the port identifier for the port. See the section below on the
// external/extra ports for the supported port identifier characters.
//
// The timeout value must be at least 3000 msecs. The default com timeout
// is 5 seconds. A few devices extend the com timeout values to 10 to 25
// seconds while doing commands that take a long time to do (like receiver
// diagnostics and hard resets). If you don't use those commands,
// the "/ct" commands allow you to set a shorter timeout. Shorter timeouts
// make automatic recovery from dropped com links faster.
//
// Note that under Windows if you drag the window for more than the
// com timeout period you will get a data loss error!
//
// Heather now has the "!x" keyboard command for setting the receiver
// baud rate for devices that support raw satellite data.
// IF YOU SET THE RECEIVER TO A NON-DEFAULT VALUE YOU WILL NEED TO SPECIFY
// THE BAUD RATE ON THE COMMAND LINE (/br=...) WHENEVER YOU START HEATHER.
// If the receiver type can be auto-detected and the baud rate is one of
// the supported auto-detect rates (9600,19200,38400,57600,115200 baud),
// tnen you might not need to specify the baud rate.
//
// You can also use the "brx=baud_rate" command line option to set the
// receiver baud rate from the command line. The /brr command MUST come
// after the /rx?? command line option that sets the receiver type (so that
// Heather knows which command to send to the device).
//
// The !x and /brr commands currently only change the receiver baud rate.
// They do NOT change the data_bits, stop_bits, or parity settings!
//
//
//
//-EXTERNAL / EXTRA DEVICE SUPPORT
//
// Besides the main "receiver" device, Heather has support for and hooks
// for adding extra devices (such as counters, environmental sensors, and
// echoing device data to other devices). These external device ports are
// configured using the /e? command.
//
// /ed DAC/ADC port
// /ee receiver data echo port
// /ef temperature control device
// /ei secondary interval/frequency counter
// /ek NMEA echo port
// /en environmental sensor port
// /er the standard "receiver" device
// /et moon / sun / sat position tracking info
// /e0 .. /e9 - for user defineable devices
//
// The syntax for the /e? command is shown below using /ei as an example:
//
// /ei=device
//
// Where "device" can be a serial port descriptor like:
// /ei=1 (com1)
// /ei=1u (usb0)
// /ei=3,9600:8:N:1 (com3 at 9600 baud, 8 bits, no parity, 1 stop bit)
//
// You can also configure the baud rate for the external devices by
// using the ":P#" parameter on the /br= command like this example for
// the NMEA echo (/ek) port:
// /br=19200:8:N:1:PI
//
// Where "device" can be an IP address AND a non-optional port number.
// Heather uses the presence of a ':' in the device parameter to recognize
// that it is a IP address. The IP address must lead to a connection that
// is lisenting for data, otherwise Heather can lock up waiting for the
// connection or a timeout occurs.
// /ei=123.135.146.157:45000
// /ei=example.com:45000
//
// Where "device" is a Linux style device name:
// /ei=/dev/ttyUSB0
// /ei=/dev/ttyUSB1,9600:8:N:1
//
// The only external devices that Heather currently has full/tested support
// are:
//
// /ee - receiver echo port. This port echoes the receiver data
// stream to the port. The default data format of the echoed
// data is whatever the main "receiver" device is configured for.
// Any data sent to the echo port by the connected device is
// currently ignored by Heather.
//
// /ef - temperature control device (fan) port. Heather defaults to
// using the receiver data port modem control DTR/RTS lines
// for its temperature control function. The /ef command lets
// you specify a different port. This can be useful if the
// main receiver port does not have modem control signals (like
// some USB interfaced receivers).
//
// /ei - the secondary time/frequency counter port. If the main
// "receiver" is a counter (/rxi or /rx1), the /ei command lets
// you use a second counter for processing up to two more channels
// of time/frequency data (or four channels with a TAPR TICC).
// Note that Heather has no way of configuring the secondary
// counter configuration operating mode. Also the user must
// configure the main and secondary counters with the same
// settings and operating mode. To configure the second TICC
// start Heather with the second device's port specified as the
// main input device, configure it, shut down Heather, then
// restart Heather with the first TICC specified as the main
// device and the second TICC as the extra device.
//
// If the main receiver device is a GPS receiver or GPSDO, the
// data from the "secondary" /ei counter device is used to
// calculate true adevs instead of the "bogo-adevs" that are
// derived from the GPSDO self-reported loop control statistics.
// When Heather is calculating "bogo-adevs" the adev type is
// shown in lower case. Upper case is used for "TRUE" counter
// derived adevs.
//
// See the description of the /im#, /if#, and /it# commands for
// specifying what type of data the counter is sending, the
// frequecy of the oscillator being tested, and forcing the
// counter type.
//
// /ek - the NMEA echo port. This port echoes the current receiver
// position, time, and satellite infomation in standard NMEA
// format. This lets you send the receiver data to another
// program that understands NMEA but does not understand the
// data the the receiver is sending.
//
// /en - to read data from an external environmental monitor device
// that provides temperatures (up to two), humidity, and air
// pressure. Currently supported sensors are the USB sensors
// from dogratian.com amd the LFS10x devices from
// LookingForSolutions.com (like the LFS104BW). A future
// Heather-specific/optimized sensor is planned.
//
// /er - the main receiver data port. This is the same as the port
// set by the /1, /1u, /id, /ip etc commands. The /er command
// just provides an alternate way of specifying the receiver
// data connection.
//
// /et - outputs the selected sun / moon / sat position info
// out the TRACK_PORT. Can also output the time in UTC.
// This can be useful for implementing moon/sun/satellite trackers.
// Once the TRACK_PORT is open and outputing data the SUN AZ:
// SUN EL: / MOON AZ: / MOON EL: labels on the screen will be
// shown in upper case if that info is selected for output.
//
//
// Future device support:
//
// /ed - to provide control and monitoring of an external device that
// has DACs and/or ADCs for monitoring and controlling analog
// devices.
//
//
//
//
//-USING A SIMULATION INPUT FILE:
//
// You can force Heather to get its input data from a file. These are
// typically receiver data capture files captured by Heather using the WY
// keyboard option. Simulation files do not work with most of the "polled"
// receiver types such as SCPI that require two-way polling to get data
// from the receiver. They mostly work with "UCCM" type receivers that
// echo the commands sent to the receiver, but there will be a "time skip"
// indication every second.
//
// To use a simulation input file, use the /rs command line option:
// /rs=filename -or-
// /rs=filename,seek_addr
//
// ",seek_addr" is optional and if specified seeks to that byte in the
// simulation file before reading. This lets you skip over data you are
// not interested in.
//
// You should also specify "/0" on the command line to disable the com
// port, but this is not usually necessary.
//
// You can also read .raw simulation files with the keyboard "R" command.
// This does not require the /0 command to disable the serial port.
//
// If the simulation file was read in via the /rs= command line option,
// the WU keyboard command will pause reading the file. If the file was
// read in via the "R" keyboard command, WU will close the simulation file
// and resume normal processing of the receiver data stream.
//
// You can use the /sw= command line option to control how fast the
// simulation file is processed. The value is the delay in milliseconds
// to wait after each message is read. Using the /sw command can make
// keyboard response rather sluggish. You can slightly speed up reading
// of a simulation file by doing something that causes the plot area to
// not be drawn like pressing the "G" key to bring up a keyboard menu.
// As long as the menu is being shown, the simulation runs a little faster.
// Also, if the mouse cursor is in the plot area of the screen reading the
// simulation file can slow down quite a bit.
//
//
// You can also simulate a time interval counter connected as an "extra"
// input device using the /ri command. If you do this you MUST also
// specify the time interval counter type using the /it? command.
// /ri=filename -or-
// /ri=filename,seek_addr
//
//
//
//-CONFIGURING THE RECEIVER TYPE:
//
// Heather supports numerous receiver types. If you do not specify a
// receiver type Heather will attempt to automatically determine
// the receiver type.
//
// Auto-detection requires the receiver to be actively sending data that
// can be analyzed. Some receivers power up "mute" and do not automatically
// send data. You must "wake up" these receivers first by specifying the
// receiver type. Also some receivers ("polled receivers") only send data
// in response to a query message.
//
// If the receiver can work in both a NMEA and a native
// binary format, it probably powers up in NMEA. Use the
// proper /rx# command shown below to put the receiver into native binary
// mode. Binary mode offers the user full control of the receiver
// and better monitoring options. The "!m" keyboard command can
// switch most receivers back to NMEA mode. On some receivers
// it swicthes the device to its alternate language.
//
// Some Motorola receivers power up in NMEA mode, sometimes at 4800 baud.
// Receiver type auto-detect does not try 4800 baud. If you are using a
// Motorola receiver and it does not auto-detect, try starting Heather with
// the /br=4800 command line option. You can switch Motorola receivers
// that are in NMEA mode to binary mode using the "!n" keyboard command.
//
//
// You can force the receiver type with the "/rx" command line option.
// /rx - auto-detect receiver type (default)
// /rxa - Acron Zeit WWVB receiver (300:8:N:2)
// /rxai - Trimble ACE-III (9600:8:O:1)
// /rxag - Trimble Acutime GG (9600:8:O:1)
// /rxat - Trimble Acutime Gold and earlier versions (9600:8:O:1)
// /rxa3 - Trimble Acutime 360 (115200:8:O:1)
// /rxb - Brandywine GPS-4 receiver - 4800:8:N:1
// /rxca - calculator only mode
// /rxc - UCCM - Trimble / Symmetricom / Samsung GPSDOs - 57600:8:N:1
// (auto-detect sub-type)
// /rxcp - UCCM-P - Trimble / Symmetricom GPSDOs - 57600:8:N:1
// /rxcs - UCCM LPK/L8 - Samsung GPSDOs - 57600:8:N:1
// /rxcu - UCCM - Trimble / Symmetricom GPSDOs - 57600:8:N:1
// /rxd - DATUM STARLOC II GPSDO - inferior wannabe Thunderbolt
// /rxe - NEC GPSDO ... STAR-4 compatible at (115200:8:N:1)
// /rxen - Environmental sensors
// /rxes - Furuno eSIP receivers
// /rxf - Lucent RFTG-m GPSDO
// /rxfu - Furuno GT-8031 (using $PFEC commands)
// /rxg - GPSD interface (not really a Windows thing - /ip=localhost:2947)
// /rxh - HP 5071A cesium beam oscillator
// /rxi - TAPR TICC time interval counter (115200:8:N:1)
// /rxj - Jupiter-T (aka Zodiac)
// /rxk - Lucent KS24361 REF0/Z3811A (19200:8:N:1)
// /rxl - Jackson Labs LTE Lite (38400,8,N,1)
// /rxlp - Temex/Specratime LPFRS or RMO rubidium (1200:8:N:1)
// /rxm - Motorola binary
// /rxn - NMEA
// /rxo - TruePosition GPS
// /rxp - Trimble TAIP receivers (4800:8:N:1)
// /rxpa - Trimble Palisade (9600:8:O:1)
// /rxpp - Tom Van Baak's PICPET timestamping counter chip
// /rxpr - SRS PRS-10 rubidium oscillator
// /rxr - Trimble Resolution T family with odd parity
// /rxs - Sirf binary
// /rxsa - Symmetricom SA22.c rubidium with 60 Mhz osc (forced model type)
// /rxsb - Symmetricom SA22.c rubidium with 58982400.0 Hz osc (forced model type)
// /rxsy - Symmetricom X72/X99/SA22 rubidium (60 Mhz osc) (auto detect model)
// /rxss - Novatel SuperStar II (19200,8,N,1) - currently untested
// /rxsr - Spectratime SRO100/SRO70 rubidium
// /rxt - Trimble TSIP binary,
// /rxtb - terminal emulator only (with buffered keyboard).
// /rxte - terminal emulator only.
// /rxtm - Spectrum TM4 GPSDO (setting features untested)
// /rxts - TymServe 2000.
// /rxu - Ublox UBX binary,
// /rxut - Ublox UBX binary (with TP5 timing messages),
// /rxv - Venus/Navspark mixed binary / NMEA (115200:8:N:1)
// (auto-detects timing/RTK models)
// /rxvb - Venus/Navspark RTK receiver in BASE mode (115200:8:N:1)
// /rxvp - Motorol Oncore (VP) receiver
// /rxvr - Venus/Navspark RTK receiver in ROVER mode (115200:8:N:1)
// /rxvt - Venus/Navspark timing receivers (115200:8:N:1)
// /rxx - No receiver, uses system clock.
// /rxx7 - Symmetricom X72 rubidium (forced model type)
// /rxx9 - Symmetricom X99 rubidium (forced model type)
// /rxy - SCPI - Nortel telecom GPSDOs like NTWB and NTPX
// /rxz - SCPI (Z3801A style. 19200:7:O:1)
// /rx5 - SCPI (HP5xxxx style)
// /rx0 - Gravity/solid earth tide clock (uses system clock to display
// solid earth tides and gravity offset, requires manual entry
// of latitude/longitude/altitude)
// /rx1 - HP531xx (or other) counter (9600:8:N:1)
// /rx12 - Ashtech Z12 L1/L2 GPS receiver
// /rx17 - Trimble RT17 format GPS receivers (115200,8,N,1)
// /rx3 - Zyfer Nanosync 380 (19200:8:N:1)
// /rx35 - Symmetricom SA.35m rubidium(57600:8:N:2) - code not completed
// /rx4 - Oscilloquartz STAR-4 GPSDO (9600:8:N:2)
// /rx45 - Oscilloquartz OSA-453X GPSDO (9600:8:N:2)
// /rx6 - Trimble SV6/SV8 (9600:8:O:1) (also ACE-III)
// /rx8 - NVS BINR binary (115200:8:N:1)
//
// /rx says to auto-detect the receiver type. This tries
// to find the receiver type at 9600:8:N:1, then
// 115200:8:N:1, then 57600:8:N:1, then 19200:8:O:1, then 38400:8:N:1
// unless the user specified the com port parameters
// (with the /br=... command) before the /rx option. Note that for Z3801A
// receivers that use 19200:7:O:1, the auto-detect routine detects the
// incorrect data size/parity combination and uses the proper settings).
//
// /rx (auto detect) is the default mode if no /rx? command
// is given on the command line.
//
// Note that the auto-detect routine is a bit simplistic
// and might occasionally mis-recognize the receiver type.
//
//
// You can force or set the UTC leapsecond offset with the /rx? commands
// like /rxx=18 (sets the leapsecond offset to 18 seconds). This is
// useful for devices that do not report the leapsecond offset or report
// an invalid value.
//
//
// If you explicity specify the receiver type, Lady Heather
// defaults to the baud rate indicated above (or 9600:8:N:1 if
// not shown above). If your receiver is configured for
// a different baud rate, specify the serial port settings
// to use with the /br= command line option.
//
//
//
// Special notes for Trimble Resolution-T (and other) TSIP devices:
// Resolution-T devices default to ODD parity. Heather can recognize the
// TSIP data stream even if set for EVEN/NO parity, but the Res-T will not
// recognize commands sent to the device. If you let Heather auto-detect
// the receiver type and did not specify a baud rate then, after around
// 30 seconds and the receiver ID message has not been seen (which the
// receiver sends only if it accepts a query command) Heather will
// automatically try different parity settings. This feature may not
// always work and is a bit of a hack. Also, the screen and some receiver
// options may not be properly configured for the new receiver type. The
// screen can usually be configured properly by issuing a screen size
// command from the $ keyboard menu) once Heather has properly detected
// the receiver serial port settings and has determined the actual receiver
// type.
//
// If you are using a Trimble Resolution-T type of receiver, you can
// force the receiver model and/or ODD parity with the /rt command line
// option. The /rt command line option should be used with the /rxt and
// /rxr command line options or if the device is not properly auto-detected.
// /rt - use ODD parity on the serial port and config for Res-T devices.
// /rt=1 - Resolution-T
// /rt=2 - Resolution-T SMT
// /rt=3 - Resolution-T RES
// /rt=4 - Resolution-T 360
// /rt=5 - Resolution-T ICM
//
//
//
// Special notes for Trimble RT17 format receivers (like the NetRS):
// Receiver ports configured for RT17/Trimcom format outputs seem to only
// stream data. I have been unable to send configuration, etc commands
// to the receiver. Thus Heather is currently a monitoring only program
// for these receivers. You cannot change the receiver configuration or
// request information that the receiver does not automatically stream.
// You must make all configuration changes via the NetRS built-in http
// web server.
//
// Heather can auto-detect RT17 receivers as Zodiac receivers. It is
// best to force the receiver type with the /rx17 command line option.
//
// It can take a few seconds to connect to the receiver over a TCP/IP
// connection. You can configure the device's IP address by connecting
// a serial port (115200,8,N,1) to the RS-232 connector on the front panel.
// Use a terminal program (or Heather with the /rxtt /br=115200 command
// line option) and power up the receiver. You should see lots of messages
// fly by. Near the end of the boot sequence it will ask if you want to
// change the IP address. Note that some of the serial ports on the rear
// panel are straight-through connections and others are null-modem
// connections. Some NetRS manuals are incorrect in specifying which are
// which. It is suggested to use the front panel connector for boot-up
// monitoring and use a rear panel connector to talk to Heather.
//
// It is suggested to update NetRS receiver firmware to the latest available
// (ver 1.3-2) This firmware was a "security" upgrade and includes several
// fixes to earlier versions. It will work on all receivers regardless of
// their "warrenty" date. UNAVCO.COM has lots of info on using the NetRS
// receiver.
//
// Suggested port message confiuration is RT17 data with:
// 1 Hz epochs, position and measurement data
// Concise format
// Send RAW GPS data
// Send Ephmeris data data (not used by Heather, may be useful to other
// programs).
// Send IODE and cycle slip counts.
// Smooth code phase
// Smooth carrier phase
//
// If you connect an external frequency reference to the NetRS, you must
// enable it. Leaving it connected but not enabled can affect performance
// or interfere with satellite tracking.
//
// Trimcomm messsage format configured ports do not send location data,
// so use RT17 format. Trimcom data is only available over the TCP/IP
// port (default 5018).
//
// Heather supports writing L1/L2 RINEX files from the RT17 data stream.
// Note that the RT17 format does not output a GPS week number. Heather
// creates a week number from the system clock. This is used in conjunction
// with the GPS time-of-week value in the receiver raw data packet to
// generate the time display and RINEX files timestamps. If the system clock
// is inaccurate, the date will be wrong close to the GPS end-of-week.
// This can cause glitches in the RINEX output... so don't collect RINEX
// files that span the GPS week rollover period. For RINEX output don't
// select L2C data. RINEX v2.xx does not know about L2C and Heather's
// RINEX v3.xx support is currently incomplete (the observation list does
// not output the correct v3.xx observation codes... you could manually
// edit the file, though).
//
//
//
// The Acron Zeit WWVB receiver cannot be auto-detected. Always use
// the /rxa command. Support for this receiver is a hack. Heather shows
// it as tracking sat PRN 1. You should manually enter your lat/lon/altitude
// (/po=lat,lon,alt command line option or the SL keyboard command or the
// "heather.loc" file) and the utc offset (like /rxa=17 or /uo=17 command
// line options). If you don't enter your position, sat PRN 1 is shown
// at az=1, el=89. Technically the Acron Zeit speaks at 300:7:O:2, but it
// also works with 300:8:N:2 if you strip off the received parity bit
// (which Heather does). Also, it takes several seconds for Heather to
// startup and shutdown with this device under Windows.
//
//
//
// Special note for Acutime 2000 and earlier receivers... also the Palsiade:
// You MUST specify the /rxat (or /rxpa) and /rxag receiver type command
// line option. If you auto-detect the device or specify an incorrect
// TSIP receiver device, the Acutime can be put into a mdde where it
// sends TSIP messages without proper end-of-message indicators. If this
// happens, the screen data areas will go blank and you must power-cycle
// the receiver to recover! Also, note that changing most of the settings
// on these receivers cause them to do a restart and the seetings changes
// do not show up for several seconds.
//
//
//
// Special note for the Ashtech Z12 receiver: If the Z12 is configured to
// send the NMEA GPZDA time code message, the time code messages will
// corrupt the raw satellite data observation message... so Heather uses the
// system clock to display the time. This can make it appear that Heather
// is actually receiving data from the Z12. To verify that Heather is
// actually talking to the Z12, make sure that the receiver ID, firmware,
// and option info is being displayed. If raw observation messages are
// enabled you should also see satellite positions, signal strength, and
// doppler data being displayed.
//
// The Z12 has no way to read back the satellite elevation mask filter.
// If you are unsure of the current setting, set the filter (FE command).
//
//
//
// The Brandywine GPS-4 cannot be auto-detected. Also the baud rate
// must be set to 4800:8:N:1 since the Brandywine receiver cannot accept
// more than 1 char per millisecond. The Brandywine receiver will not
// work with most serial cables. Pin 4 is a receiver reset signal and if
// connected will prevent the receiver from working. Pins 6, 8, and 9
// also have non-standard uses. YOU SHOULD USE A CABLE WITH ONLY
// PINS 2, 3, and 5 CONNECTED TO THE PC! The Brandywine receiver does
// not work well with the audible "tick clock" mode.
//
//
//
// The Datum STARLOC II cannot be auto-detected. Firmware
// bugs cause it to stop outputting time messages. Always
// specify "/rxd" when running STARLOC II receivers. Also
// note that the Datum STARLOC II has NUMEROUS firmware
// bugs and generates lots of duplicate/missing time stamp errors
// and does not output satellite azimuth/elevation values. The
// firmware bugs cause many messages to be corrupted (the firmware does not
// properly "escape" any 0x10 bytes in most of the output messages, etc),
// thus any messages that contain a 0x10 byte are likely to be corruped!
// There might be firmware out there that fixes these issues, but I have
// not seen any. The STARLOC is the most miserabe excuse for a GPSDO that
// i have ever seen... the firmware seems to have been written/tested by a
// drunk chimanzee... I have fw App:1.10 16 Mar 2000, GPS:1.2 07 Jan 2000.
//
//
//
// Special note for Furuno (like GT-8031 and eSIP) receivers: Auto-detect
// may detect these as NMEA receivers, particularly if Heather has not
// previously enabled them. YOU SHOULD NOT RELY ON AUTO-DETECTING THESE
// RECEIVERS! Also, these receivers may not output any data until
// they begin tracking satellites and have an almanac. They may be
// unusable/undetectable for a long time (an hour?) after power-up.
//
// The Furuno PFEC model and version info is only available from the
// self-test results message. If the diagnostics have not been run they
// will show up as "0". Running the diagnostics will affect the receiver
// operation for a few seconds. The diagnostics are run whenever
// Heather starts up, so for the first few seconds you may see
// "No stats usable" and "Time invalid" messages.
//
// For ESIP receivers, the SU keyboard command can be used to set the
// default UTC (leapsecond) offset to use when the receiver does not have
// the current value from the satellies. This value is saved in EEPROM.
//
// Furuno ESIP receivers (like the GT87xx series) have some satellite
// data messages (that send things like satellite doppler, pseudoranges,
// and the raw navigation message that are only avialable if the baud rate
// is 115200 baud or greater.
// You can set the ESIP baud rate by using the "!u" keyboard command to
// send the following string (in uppercase!):
// PERDCFG,UART1,115200
// Note that the baud rate, cable delay, signal level mask, elevation
// mask, etc settings are NOT stored in flash memory and will be lost
// after a power cycle (unless a backup battery is in use). Also after
// changing the baud rate, you will need to specify the baud rate from
// the command line (because Heather assumes ESIP receivers run
// at 38400 baud):
// /rxes /br=115200
//
//
//
// GPSD is a Linux/macOS/FreeBSD service that provides a standardized
// interface to numerous models of GPS receivers. It is accessed
// via TCP/IP address "localhost:2947" GPSD cannot be auto-detected.
// Use "/rxg" to force GPSD mode. You can specify a particular
// GPSD device to use with the /ig=gpsd_device_name command.
// The /ig command will also do the /rxg command.
// If your GPSD system is not on "localhost:2947", specify the TCP/IP
// address with the /ip= option after the /rxg or /ig= option.
//
//
//
// The Jackson Labs LTE GPSDO device has a Venus timing receiver in it that
// runs at 38400:8:N:1 and normally generates the standard Venus messages.
// It also has a switch that enables a proprietary Jackson Labs STATUS
// message. On earlier versions of the LTE firmware enabling the STATUS
// messages disables all the Venus messages and you lose the ability to
// show satellite info, automatically get the UTC. etc. Later versions
// of the LTE firmware allow the STATUS message to be mixed in with the
// regular Venus messages.leapseoncd offset, etc. In STATUS only mode
// Heather gets the time from the receiver clock. Note that the LTE does
// not let you control the Venus receiver and you cannot change any
// settings or request data from the receiver. Because of this, Heather
// cannot get the UTC leapsecond offset.
//
//
//
// Special note for Lucent KS24361 units: the Z3811A
// (REF1) unit talk SCPI at /br=19200:8:N:1 and the
// Z3812A (REF0) unit talks at /br=9600:8:N:1 over the
// DIAGNOSTIC ports.
//