forked from HeyuX10Automation/heyu
-
Notifications
You must be signed in to change notification settings - Fork 0
/
x10config.5
2240 lines (2028 loc) · 88.1 KB
/
x10config.5
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
.TH X10CONFIG 5 local
.SH NAME
.B x10config\^
- Configuration file format for HEYU, an X-10 CM11A serial interface control program
.SH DESCRIPTION
.I Heyu
is a program for controlling an X-10 "CM11A" home control device.
See the \fIheyu\fP(1) man page for usage information.
.PP
The configuration file contains several critical pieces of information
that the \fIheyu\fP program needs in order to function, plus a number
of user options. These are all specified by keywords known as
\fBdirectives\fP which are explained below. In general, directives may
appear in any order in the configuration file, however see the exception
to this rule under the heading for the ALIAS directive.
.PP
The configuration file, named x10config, is normally stored in the (hidden)
subdirectory .heyu under your home directory, i.e., $HOME/.heyu/x10config
.PP
For system-wide use, the configuration file may alternatively be stored
as file x10.conf in the directory /etc/heyu (or as otherwise defined in
Configure.sh for your operating system).
.PP
The configuration file may be located in an additional subdirectory
level under either of the directories above. The additional subdirectory
level can have a name of your choice, for example "mysub". In this case
you must specify the name of the subdirectory with the HEYUSUB environment
variable in order for Heyu to find it, for example HEYUSUB=mysub. Somewhat
more convenient however is to locate the configuration file in a subdirectory
named simply /0 ... /9, e.g. $HOME/.heyu/3/x10config, in which case Heyu
can be instucted to use the appropriate directory with the command line
option \'-0\' ... \'-9\'.
.PP
Finally, the configuration file may be stored in any arbitrary location
on your hard drive with any arbitrary filename, but the full pathname will
have to be specified either with the \'-c\' Heyu command line option or
with the X10CONFIG environment variable.
.PP
If the HEYUSUB environment variable is NOT set or the \'-0\' ... \'-9\'
not specified, then the search will start with
$HOME/.heyu/x10config and continue with /etc/heyu/x10.conf, stopping with the
first one it finds. If not found, Heyu will exit with an error message.
.PP
If the HEYUSUB environment variable IS set or the \'-0\' ... \'-9\' is
specified, the search for the configuration
file will start with $HOME/.heyu/<subdirectory>/x10config, then, if not found,
will continue looking for /etc/heyu/<subdirectory>/x10.conf. Examples:
.br
$HOME/.heyu/mysub/x10config
.br
/etc/heyu/mysub/x10.conf
.br
/etc/heyu/4/x10.conf
.br
If not found under either of these places, Heyu will exit with an error message.
.PP
(The main reason for implementing the subdirectory feature is to enable Heyu
to be used for more than one CM11A interface, with separate configuration
and other files for each. If you have only one CM11A interface, you probably
won\'t find a need to bother with it.)
.PP
The directory in which the configuration file is located MUST be writable
by Heyu.
.PP
Case sensistivity:
.br
The following entities ARE case-sensitive: Filenames; Pathspecs;
Serial ports (and the keyword "dummy" used when there is no CM11A connected);
Heyu and shell commands; Alias, Scene, Usersyn, Script,
and Launcher labels.
.br
The following entities are NOT case sensitive: Names of directives and
values of directives other than those listed above; Housecode letters.
.SH TTY directive
The TTY directive is the most important. Syntax is simply the word
TTY, a space and then the full path name for the serial port to which
the CM11A is attached. /dev/ttyS0 would be the first serial port
(corresponding to COM1 under MS-DOS). /dev/cua0 will also work.
.br
Examples:
.br
TTY /dev/ttyS0
.br
TTY /dev/cua2
.br
TTY /dev/usb/ttyUSB0 (implies a USB-Serial adapter)
.PP
To configure Heyu for a CM10A interface (instead of a CM11A or CM12),
append the keyword "CM10A", e.g.:
.br
TTY /dev/ttyS0 CM10A
.PP
Note: If you\'ve started Heyu before configuring for the CM10A, you
must stop and start it up again. I.e., \'heyu stop\', then \'heyu start\'.
.SH TTY dummy directive
Setting the directive
.br
TTY dummy
.br
tells Heyu there is no CM11 powerline interface connected and Heyu
commands which attempt to communicate with the interface will result
in a quick error message. However commands which involve only the
heyu_engine and heyu_aux daemons will continue to function, e.g.,
setting and reading flags or countdown timers, and executing scripts
launched by RF signals forwarded from heyu_aux. (Like the name of the
serial port it replaces, the word "dummy" is case sensitive.)
.SH HOUSECODE directive
The housecode directive indicates the housecode for which the CM11A is
to store in its internal registers the on/off/dim status of individual units
when signals are sent or received over the AC power line. The \'heyu reset\'
command (with no housecode parameter supplied) will program the CM11A to use
the housecode provided by this directive. (It will not do this automatically.)
.br
Example:
HOUSECODE D
.br
The default for this directive is housecode A.
.SH ALIAS directive
An alias associates a label (front_porch) with an X10 device (A10)
so that we don\'t have to remember that the front porch light is house
code A, device 10. In other words, we can use a mnemonic to represent
a device.
.br
There are a few other directives in which the user may choose to
reference an alias label in place of a housecode|unitcode address.
In these cases the alias directive must appear before the other directive
in the configuration file in order to be resolved. Therefore it\'s a
good idea to group all the alias directives at or near the beginning
of the file.
.br
Alias labels can refer to one or more X10 devices with the same housecode,
however Heyu\'s monitor will display the alias label only if the alias
references a single device address.
.br
The format for an alias is:
.br
ALIAS Label Housecode|Devices [Module_type [Module option]]
.br
where the Housecode letter and Device string are concatenated.
.br
\fBLabel\fP can be any contiguous string (maximum length 32 characters)
of alphanumeric characters or period \'.\', hyphen \'-\', or underscore \'_\',
except that the the hyphen and underscore may not be the first character
in the string. The label may not be the word \'macro\'.
.br
Alias labels are case sensitive, so that \'kitchen\' and \'Kitchen\'
represent two distinct aliases.
.br
\fBHousecode\fP is a case-insensitive letter A-P (or a-p).
.br
\fBDevices\fP can be 4 things:
.IP
1. A single number (example 1)
.br
2. A group of numbers separated by commas (example 1,2,14,15)
.br
3. A range separated by a dash (example 1-8)
.br
4. A combination of 2 and 3 (example 1-8,14,15)
.br
.PP
\fBModule_type\fP is optional and defines for Heyu the attributes
of the particular kind of module assigned to the Housecode|Unit.
.br
Heyu uses this information to determine what state the module
should be in when the module receives any particular command. E.g.,
it will know that an appliance module will never be in a
dimmed state even though it may be sent a dim command.
.br
Unlike many popular software programs which attempt to do your
thinking for you, Heyu does not decide what X10 command to send
based on the Module_type defined for the specific housecode|unit
address or alias. It does only what you tell it to do, and
defining a Module_type does not restrict Heyu from sending
a command which the module may not support. E.g., if you tell
Heyu to send a dim command to an appliance module, it will do
so without question. But the physical module will not respond and
the Heyu state will reflect that fact.
.br
The following generic module types and/or specific model numbers
are currently recognized. The names are not case-sensitive:
.br
*** WARNING - WARNING - WARNING ***
.br
The X-10 LM465 Lamp Module and WS467 Wall Switch Module were
redesigned in 2007 but the model numbers, appearance, and packaging
remained unchanged. The new designs, designated here as module
types LM465-1 and WS467-1, have quite different features and
characteristics from the original designs. Among other differences,
they support a subset of Extended Code commands. They
can be distinguished by executing \'heyu xon Hu\' and \'heyu xoff Hu\'
at the command prompt. The redesigned modules will respond and turn
respectively On and Off; the original modules won't respond.
.br
Among the potential problems, there\'s an apparent design error
in the redesigned WS467 Wall Switch firmware making it not backwards
compatible with the original design. A standard X10 bright or dim
or dimb signal won\'t turn it On from the Off state unless preceded
by an on signal.
.br
\fILM465-1\fP (LM-1) - Redesigned LM465 lamp module.
.br
\fILM\fP (StdLM LM465 PLM01 PLM03) - Original standard X-10 lamp module.
.br
\fILM12\fP () - Marmitek standard X-10 lamp module.
.br
\fILMS\fP (?) - X-10 2-way lamp module (responds status on/off).
.br
\fIAM\fP (StdAM AM486 AM466 PAM01 PAM02) - Standard X-10 appliance module.
.br
\fIAM12\fP () - Marmitek standard X-10 appliance module.
.br
\fISR227\fP (PA011) - X-10 socket module.
.br
\fIAMS\fP (RR501 PAT01) - X-10 2-way switch (responds status on/off).
Some 2-way modules can be configured to automatically return a StatusOn/Off
whenever they are turned On/Off. For these, the module type parameter
"DEFER" instructs Heyu not to update the stored states of the module with
the On/Off signal but let the ensuing StatusOn/Off signal do it. (Otherwise
the changed state following the StatusOn/Off would always be unchanged.)
.br
\fIRAIN8II\fP () WGL model Rain8II 2-way irrigation controller which
can be configured to automatically respond with a StatusOn/Off signal
when turned On/Off.
.br
\fIWS467-1\fP (WS-1) - Redesigned WS467 wall switch module.
.br
\fIWS\fP (StdWS WS467) - Standard X-10 wall switch module.
.br
\fILW10U\fP () - Marmitek dimming wall switch module.
.br
\fIWS12A\fP (XPD3) - X-10 dimming wall switch module.
.br
\fIWS13A\fP (XPS3) - X-10 non-dimming wall switch module.
.br
\fILM15A\fP (PSM04) - X-10 Socket Rocket screw-in non-dimming lamp module.
.br
\fILM15\fP () - Marmitek screw-in non-dimming lamp module.
.br
\fIAM14A\fP (AM15A PAM21 PAM22) - X-10 2-way appliance module (Extended codes).
.br
\fILM14A\fP (PLM21) - X-10 2-way lamp module (Extended codes).
.br
\fISL1AM\fP (?) - SwitchLinc 1-way switch (Preset codes).
.br
\fISL2AM\fP (?) - SwitchLinc 2-way switch (Preset codes).
.br
\fISL1LM\fP (?) - SwitchLinc 1-way dimmer (Preset codes).
.br
\fISL2LM\fP (SL2380W) - SwitchLinc 2-way dimmer (Preset codes).
.br
\fILL1LM\fP (?) - LampLinc 1-way dimmer (Preset codes)
.br
\fILL2LM\fP (LL2000STW) - LampLinc 2-way dimmer (Preset codes)
.br
\fIRS114\fP () ACT user-programmable 2-way switch module.
With this module, support for AllUnitsOff, AllLightsOn, and
AllLightsOff signals is user programmable. Module type parameters
AUF, ALO, and ALF match Heyu's support with the module's programming.
.br
\fIRF234\fP () ACT user-programmable 2-way switch module. This 230V
module has similar to but not identical characteristics with the RS114.
Based on data from a single device, it appears the RS234 does not
maintain its address after being turned On or Off.
.br
\fIAMEXC16\fP (?) - Module of the appliance type with
exclusive addressing: An on command turns On only the last
unit addressed. All other modules of this type on the
same housecode turn themselves Off and become unaddressed.
.br
\fIAMEXC8\fP (RAIN8) - Modules of the appliance type with
exclusive addressing within groups of 8 units, i.e., 1-8,
9-16. Other modules on the same housecode and within the same
group of units turn themselves Off when the last addressed
unit in that group is turned On. A typical device of this
type is the WGL Rain8 Irrigation Controller.
.br
\fIAMEXC4\fP (XM10A XM13A) - Similar to AMEXC8 but with
exclusive addressing within groups of 4, i.e., 1-4,
5-8, 9-12, 13-16. Typical modules of this type are X-10\'s
XM10A and XM13A camera power supplies.
.br
\fIPR511\fP () - X-10 PR511 2-way Motion Sensing floodlight
.br
\fINONE\fP - No module; supports no X10 commands.
.br
\fIREMOTE2\fP - Not actually a module, it can be used as
a \'target\' for X10 commands sent by a transmitter
with only On/Off codes (like a keychain remote
or motion sensor), when there is no physical module
assigned to that Housecode|Unit.
.br
\fIREMOTE4\fP - Like the above, but for a four function
transmitter like a PalmPad which can send Dim and
Bright codes in addition to On and Off.
.br
\fIREMOTE6\fP - Like the above, but for a six function
transmitter like the Mini- or Maxi-Controller which
can send On, Off, Dim, Bright, LightsOn, and AllOff
codes.
.br
Note that the above two REMOTEs function a little
differently than lamp modules. The state for an On
(or a LightsOn for REMOTE6) code will always be
recorded as fully On regardless of prior state,
and the state for Dim/Bright codes can range from
fully Off through fully On and vice-versa. This
allows their use in scripts for controlling things
other than modules.
.br
\fIREMOTE3\fP - Similar to REMOTE4 except that the On
command is ignored by the state engine except for
addressing the particular unit in the housecode -
it does not change the stored brightness level.
The Off command does set the brightness level to
zero and the Bright and Dim commands make incremental
changes in this level within the range fully Off
to fully On. (The Bright and Dim signals sent by
RF remotes do not include a unit code. This module
type allows using the On signal to address a
particular unit without changing the stored brightness
level and then using the Dim and Bright commands for
some analog control purpose via a script.)
.br
\fIREMOTEP\fP - Again not actually a module, but can be
used as a target for transmitters which send only
the Preset (1-32) codes.
.br
\fISHUTTER\fP (SW10) - Shutter and shade controller
which support Extended Code Type 0 commands. The
Marmitek SW10 Shutter Motor Controller is the only
module known to support these commands and Marmitek
keeps it a secret. This Heyu model supports Extended
Type 0 functions 0x01, 0x02, 0x03, 0x04, and 0x0B.
The Heyu model also supports the standard On and Off
commands, but not Dim or Bright, to which the shutter
module is reported to react in an unpredictable manner.
.br
\fIVDATA\fP - A virtual module which can store a data
byte as if it were a (raw) brightness level 0-255.
Data is written to this virtual module only with the
\'heyu vdata HU <data>\' command - it is unaffected
by any other X10 command.
.PP
The following security transmitter models are included for
use with RF auxiliary input from a W800RF32A or RFXCOM receiver.
.PP
\fIDS10A\fP - (PDS01) X-10 DS10A Security Door/Window Sensor
.br
\fIDS90\fP - (DS18-1) X-10 DS90 Sec Door/Window Sensor (2 chan)
.br
\fIDS18-1\fP - () ElekHomica DS18 Sec Door/Window Sensor (2 chan)
.br
\fIDS18\fP - () ElekHomica DS18 Sec Door/Window Sensor (1 chan)
.br
\fIMS10A\fP - (PMS01) X-10 MS10A Security Motion Sensor (See section "MS10A WARNING" in man page x10aux(5))
.br
\fISH624\fP - (PSR01) X-10 Security Remote
.br
\fIKR10A\fP - (PKR02, KR21) X-10 Security Keyfob Remote.
.br
\fIKR18\fP - (KR18E) Marmitek Security Keyfob Remote.
.br
\fISD10\fP - () Marmitek SD10 Smoke Detectors
.br
\fISD90\fP - () Marmitek SD90 Smoke Detectors
.br
\fIBMB-SD18\fP - () BMB SD18 Smoke Detector
.br
\fIMS90\fP - (MS18E) Marmitek MS90 Security Motion Sensor
.br
\fIEH-CWSD10\fP - () ElekHomica EH-CWSD10 Smoke Detector
.br
\fIEH-WD210\fP - () ElecHomica EH-WD210 Water Detector
.br
\fIGB10\fP - () Marmitek GB10 Glass Break Detector
.br
\fISVDATA\fP - () Generic X10 Security Remote (all \'vdata\')
.PP
Most (but not all) security sensors transmit a 16-bit security
ID which is detectable with the RFXCOM RF receiver operating
in variable length packet mode (the default). For backward
compatibility, the directive \'SECURID_16 NO\' instructs Heyu
to ignore the upper 8-bits.
.PP
Some security sensors, notably the Aux channel of the DS90
Door/Window sensor, have a firmware bug whereby a parity bit
used to check the upper 8 bits of the 16-bit security ID is
incorrect in every other RF repetition, which means that
half the signals are discarded as noise. The configuration
directive \'SECURID_PARITY NO\' instructs Heyu to disregard
the parity bit. It's use is less risky than throwing away
half the signals, but if none of your sensors exhibit this bug
there's no need to use it. Configuration directive
\'DISPLAY_RAW_RF NOISE\' can be used to determine whether
the bug exists.
.PP
Unlike the larger SH624 security remote, the smaller KR10A, KR18,
and KR21 security keyfob remotes have no physical Away/Home or
Max/Min switches, and by default transmit the swAway and
swMin flags when the Arm button is pressed. Appending the
parameters SWHOME and/or SWMAX to the alias directive for these
keyfob remotes results in the flags being decoded respectively
as swHome and/or swMax.
.PP
Alternatively, appending the parameter DUMMY to the above security
keyfob remote alias directive results in the signals
transmitted by the Arm and Disarm button presses being decoded
instead as Alert and Clear, thus allowing the remote to be used
for a user-defined purpose unrelated to Arm and Disarm.
.PP
Module type SEC_IGNORE can be used to ignore signals from X10 Security
sensors which may not be under your control, e.g., signals from a
nearby neighbor\'s sensor. An unused Housecode/Unit address must
be sacrificed. Specify the Security IDs for one or more sensors to
be ignored.
.br
Example:
.br
ALIAS Neighbor_Sensors P6 SEC_IGNORE 3C 4E 2A
.PP
The following entertainment transmitter model is included
for use with RF Auxiliary input from a W800RF32A, RFXCOM, or
MR26A receiver.
.PP
\fIUR81A\fP - (UR61A) X-10 Entertainment Universal Remote.
.PP
The following module types are used to override the settings
defined by the TRANSCEIVE and RFFORWARD directives for
specific units and functions within a housecode. Each requires
one of the parameters TRANSCEIVE, RFFORWARD, or RFIGNORE be
specified following the module name in the ALIAS directive.
.PP
\fIPALMPAD\fP - Controls RF On, Off, Dim, Bright.
.br
\fIKEYCHAIN\fP - Controls RF On and Off
.br
\fIONLYON\fP - Controls RF On
.br
\fIONLYOFF\fP - Controls RF Off
.br
\fIMS12\fP, \fIMS13\fP, \fIMS14\fP, \fIMS16\fP - Controls RF On and Off
.PP
(The MSxx module types are similar to the KEYCHAIN module type
but are defined as "sensors" and as such will be listed in the table
displayed by \'heyu show sensors\'.)
.PP
Example: If housecode C is set to be transceived, specifying:
.br
ALIAS XMMS_Control C1-6 KEYCHAIN RFFORWARD
.br
allows using the On/Off buttons C1-6 on a RF remote to launch
scripts controlling the XMMS audio player software on the PC
without the delay of a powerline signal. The other unit
buttons continue to transceive powerline signals to lamps
and appliances.
.PP
\fIPLCSENSOR\fP - A target for a transmitter which sends
X10 On and Off signals over the power line and which has
a "heartbeat", i.e., it periodically retransmits its current
state. The Heyu config directives HIDE_UNCHANGED and
INACTIVE_TIMEOUT apply to this module type as they do for
RF security sensors.
.PP
The following module type decodes RF signals transmitted
from RFXSensor modules and received by a W800RF32A/AE or
RFXCOM RF receiver, and maps them to a Housecode|Unit
address.
.br
\fIRFXSENSOR\fP - A decoder for RFXSensor transmitters
and external sensors. Two parameters are required, the
base_address of the sensor and a mnemonic for the type
of sensor, e.g., Temperature/Humidity, Temp/Barometric
Pressure, etc. The mnemonic will be one of: TH, TB, TV,
TP, TT, or T.
.br
Example:
.br
ALIAS Basement L9 RFXSENSOR 0x20 TH
.br
The RF signals sent by the sensor with base_address 0x20 will
be decoded as RFX Temperature and Relative Humidity functions
received (RCVA) at Housecode|Unit L9.
.br
See man page x10rfxsensors(5) for full details.
.PP
The following module types decode RF signals transmitted
by RFXMeter sensors. Each requires as a parameter the
ID address of the sensor.
.br
\fIRFXPOWER\fP - Electric Watt-Hour meter.
.br
\fIRFXWATER\fP - Water meter.
.br
\fIRFXGAS\fP - Gas meter.
.br
\fIRFXPULSE\fP - Pulse meter.
.br
\fIRFXCOUNT\fP - General counter.
.br
Example:
.br
ALIAS MyWaterMeter C9 RFXWATER 0x04
.PP
Module type DIGIMAX decodes RF signals transmitted by the
DigiMax 210 wireless thermostat and received by the 433.92 MHz RFXCOM
X10 RF receiver in variable length packet mode. Its parameter is the 16-bit
ID of the thermostat.
.PP
Module types ORE_xxx decode signals transmitted by various Oregon
remote sensors and received by the 433.92 MHz RFXCOM X10 RF receiver
in variable length packet mode. See man page x10oregon(5) for
full descriptions.
.PP
Module type ELS_ELEC1 decodes signals transmitted by the Electrisave
CM113 Electricity Monitor sensor and received by the 433.92 MHz
RFXCOM X10 RF receiver in variable length packet mode. The optional
directive "ELS_VOLTAGE <voltage>" specifies a nominal AC voltage to be
multiplied by the measured current to display an apparent power. See page
X10oregon(5) for more information.
.PP
Module type OWL_ELEC2 decodes signals transmitted by the OWL CM119
Electricity Monitor sensor and received by the 433.92 MHz
RFXCOM X10 RF receiver in variable length packet mode. The directive
"OWL_VOLTAGE <voltage>" specifies the nominal AC voltage to be used
to compute the Power and Energy values. See page X10oregon(5) for
more information.
.PP
SwitchLinc and LampLinc modules can be manually
configured to always turn on to some level less than
the maximum (32), or always resume the previous setting.
If you've configured your modules in either of these
ways, you must inform Heyu of the fact by adding the
module option \'ONLEVEL nn\' or \'ONLEVEL RESUME\'.
.PP
NOTE: In order for the Heyu state engine to properly track
the state of modules with the \'resume\' feature (LM14A
and SwitchLinc/LampLinc option), its memory must be synchronized
with the module\'s memory. This can be done by sending the
module an X10 command setting it at a known level greater
than the \'Off\' level, or by having it respond to a status
request with a preset/xstatus level greater than the \'Off\'
level.
.PP
Examples:
.br
ALIAS hall_light B7
.br
ALIAS patio_lights B2,4-6
.br
ALIAS porch_light D1 WS467
.br
ALIAS livingroom_lamp H7 SL2LM ONLEVEL 20
.PP
It is advisable to define single-unit aliases for all
housecode|units in addition to any multiple-unit aliases
which may be convenient for use in Scenes/Usersyns/Macros,
and to define a Module_type only for single-unit aliases.
.br
(Once a Module_type is defined, it applies to that same
housecode|unit however used, e.g., in the above example
Heyu will understand that D1 is a WS467 dimmer when
either \'heyu turn porch_light on\' or \'heyu turn D1 on\'
is executed, or if D1 is also included in a multiple-unit
alias like D1,2-5,7)
.PP
Modules not defined for a Housecode|unit in an ALIAS directive
are assigned to be the default module, which is a standard
X-10 lamp module. This can be changed with the DEFAULT_MODULE
directive.
.PP
Note: Versions of Heyu prior to 2 used a different format for aliases:
No ALIAS directive was used and the Housecode letter and Units were
separated by whitespace, e.g., simply \'hall_light B 7\'. For compatibility,
Heyu version 2 will still accept this format, however its use is discouraged
and deprecated. (Module type cannot be specified with this format.)
.SH DEFAULT_MODULE directive
Sets the module attributes of all Housecode|Units which are not defined in an
alias directive. If not otherwise specified by this directive, the default
module is the standard X-10 plug-in lamp module (StdLM).
.SH START_ENGINE directive
Many of Heyu\'s features require the Heyu state engine daemon heyu_engine
to be running. This directive instructs Heyu how heyu_engine is to be
started. With the default value of MANUAL, the engine must be started by
entering \'heyu engine\' at the command line. With the value AUTO, the
engine will be started automatically along with Heyu\'s other background
processes when \'heyu start\' is run. Example:
.br
START_ENGINE AUTO
.SH LOG_DIR directive
Use this directive to specify the directory in which the Heyu state
engine daemon should write its log file \'heyu.log.<tty>\'. The keyword
\'NONE\' (which is the default) instructs Heyu to not write a log
file.
.PP
Example:
.br
LOG_DIR /var/log/heyu/
.PP
The log file will contain entries like appear in the Heyu monitor, and in
addition, an entry whenever a script (excluding heyuhelper) is launched.
It will also collect the text output of a launched script, if that output
isn't redirected to a different file.
.PP
Two or more instances of Heyu running on the same computer can share
a common log file by appending the keyword "COMMON". If each instance of
Heyu is started with the base subdirectory switch (-0 through -9), each
entry in the log file \'heyu.log.common\' will display the subdirectory
number (0 through 9) from whence the signal originated.
.PP
Example:
.br
LOG_DIR /var/log/heyu common
.PP
Note that the log file will continue to grow. Manually delete or
trim it from time to time, or configure a Unix utility like \'logrotate\'
to manage it.
.SH DATE_FORMAT directive
Specifies how a numeric date is displayed. The syntax for this directive is:
.br
DATE_FORMAT <order> [<separator>]
.br
where <order> is
.br
YMD => Year/Month/Day (Default)
.br
DMY => Day/Month/Year
.br
MDY => Month/Day/Year
.br
and where the optional <separator> is \'/\' (Default), \'-\', or \'.\'
.PP
Examples:
.br
DATE_FORMAT YMD \'/\' => 2008/01/23 (Heyu default)
.br
DATE_FORMAT YMD \'-\' => 2008-01-23 (ISO 8601 standard)
.br
DATE_FORMAT DMY \'-\' => 23-01-2008 (many European countries)
.br
DATE_FORMAT DMY \'.\' => 23.01.2008 (Germany traditional)
.br
DATE_FORMAT MDY \'/\' => 01/23/2008 (USA traditional)
.PP
The specified order of Month and Day also applies to the date ranges
specified for Timers in schedule files to be uploaded to the CM11A
EEPROM. The separator between month and day must be \'/\', \'-\' or
\'.\' but does not have to be the same as that specified with
DATE_FORMAT. The separator between the begin and end dates may optionally
be either \'-\' or \':\'. (Use the latter for clarity when the Month/Day
separator is a \'-\'.)
.br
Examples:
.br
TIMER smtwtfs 01/23-12/31 ... (with DATE_FORMAT YMD or MDY)
.br
TIMER smtwtfs 23-01:31-12 ... (with DATE_FORMAT DMY)
.PP
Dates where the month name is spelled out are not affected by this directive
and usually appear like:
.br
Wed 23 Jan 2008
.SH LOGDATE_YEAR directive
Instructs Heyu whether or not the dates reported for entries in the
Log file and Monitor should include the year. The choices are YES or NO,
with the default being NO, to omit the year.
.SH TAILPATH directive
Use this directive to specify the full pathname of the system \'tail\'
command if it\'s not on the normal PATH accessable to Heyu. The Heyu
command \'logtail\' will use this pathspec to call \'tail\'.
.SH HEYU_UMASK directive
Governs the permissions for files created by Heyu. The default for this
directive is 0000 which results in files having permissions rw_rw_rw_.
The value 0002 results in files having permissions rw_rw_r__ ; the
value 0022 results in files having permissions rw_r__r__.
.br
Example:
.br
HEYU_UMASK 0002
.SH USERSYN directive
.SH SCENE directive
These directives, new to Heyu version 2, specify a semicolon-separated
list of Heyu commands. These can then be executed sequentially by
issuing only the usersyn or scene label as a Heyu command. In addition,
the label can be used in a macro as if it were a command.
.br
In the current release, the ONLY difference between a SCENE and USERSYN is
whether they appear in the scene or usersyn list displayed by the \'heyu show\'
command. What applies below for a SCENE applies equally to a USERSYN.
.br
The format for either a scene or usersyn is similar:
.br
SCENE Label command1; command2; command3; ...
USERSYN Label command1; command2; command3; ...
.br
The commands in a scene can accept either actual device addresses or aliases.
(The alias directive must appear before any scene directive which
references it.)
.br
Examples:
.br
SCENE dim_all dim A1-3 8; dim B2 8; dim c7 8
SCENE night_lights off porch_light; on garage_light; dim hall 8
.br
Issuing the command \'heyu dim_all\' would result in each of the
commands defined in that scene to be executed in turn.
.br
Scenes can also be defined with positional parameters which are replaced by
actual parameters when they are executed. The positional parameters are
designated by a \'$\' sign followed by a number 1 to N optionally enclosed
in curly brackets, e.g., \'$2\', \'${7}\'. The number
represents the position of the parameter in the argument list supplied when
the scene is executed.. A positional parameter can be used as part or all
of either a device address or a dim level, but not as part of a scene label
or a Heyu command
.br
Examples:
.br
SCENE blinker on $1; off $1; on $2; off $2
SCENE Dim_all dim A1-3 $1; dim B2 $1; dim c7 $1
.br
These could then be executed by running:
.br
heyu blinker A3 B7
heyu Dim_all 7
.br
Rules for scenes (interpret "scene" as meaning either scene or usersyn):
.PP
1. A scene label is a case-sensistive ASCII string (maximum length
32 characters) not beginning with \'-\' or \'_\' and not
containing blanks or the \'+\' or \'$\' characters.
.PP
2. A scene label may not be the same as a Heyu command or any of
its synonyms. A scene label may not duplicate a usersyn label
and vice-versa. As of the current implementation, a scene
label MAY be the same as an alias label, and it MAY be the same
as a macro label, but these feature may be restricted
in future releases if too much user confusion results.
.PP
3. Only "direct" and CM17A commands can be used in scenes - "administrative"
commands like \'help\', \'info\', etc., are invalid in scenes,
as are commands identified as "legacy" commands from Heyu version 1.
(Running \'heyu help\' will identify each of these types of commands.)
.PP
4. A command in a scene may not be another scene.
.PP
5. Commands in scenes are checked for syntax when the configuration
file is read, but there is no checking of any parameter containing
a positional parameter until the scene is actually executed or
specified in a macro. The syntax checking is performed as if the scene
is to be executed at the command line, so if a scene contains a
command which is invalid for an uploaded macro, that error won\'t
be flagged until the \'heyu upload [check]\' command is run.
.PP
6.There is no restriction on how a positional parameter is used within
a parameter so long as the result is valid when the scene is executed.
Use the optional curly brackets if the result could otherwise be
ambiguous. The positional parameter is first replaced by the actual
parameter, then the result is checked against the list of aliases.
.PP
7. The number of positional parameters supplied when a scene is
executed must agree exactly with the number specified in the scene
definition. Thus if \'$4\' is the highest numbered positional parameter
specified in a scene, then 4 and only 4 parameters must be supplied
when the scene is executed.
.PP
8. If more than one scene is used in a macro, or if scenes are intermixed
with regular macro commands, they must be separated by semicolons.
.PP
9. Memory for scenes is dynamically allocated so there is no fixed
size limit for scenes intended for execution from the command line.
Bear in mind however the limited (1024 byte) EEPROM space in the CM11A
when scenes are expanded in macros, although most common X10 commands
occupy only 3 or 4 bytes when converted to binary.
.PP
10. The highest numbered positional parameter in a scene is by default
limited to 8. (In most cases anything over that is more likely an error.)
But this limit may be changed with configuration directive MAX_PPARMS.
.PP
.SH MAX_PPARMS directive
Specifies the highest numbered positional parameter allowed in a scene.
The number may have any value between 1 and 999. The default is 8.
.PP
.SH STATUS_TIMEOUT directive
Specifies how long Heyu will wait for a module to reply to a
status command before timing out. The default is 2 seconds. Some modules,
SwitchLinc dimmers in particular, may require increasing this to 3.
The allowed limits for this directive are 1-5 seconds.
(Don't use a value any higher than the minimum needed for satisfactory
status reporting.) Example:
.br
STATUS_TIMEOUT 2
.PP
.SH SPF_TIMEOUT directive
Specifies how long Heyu will wait for a module to reply to a
"SPecial Function" status command before timing out. The default is 3
seconds. To date, there is only one special function in Heyu, the
display of the temperature as encoded in a preset command returned
from a two-way thermostat or remote thermometer. (See below.)
.SH RCS_DECODE directive
.SH RCS_TEMPERATURE directive
This is the same directive - use either but not both. The name has been
changed since Heyu now supports decoding other RCS status reports such
as fan status on/off in addition to temperature.
.br
This directive instructs the Heyu monitor to decode and display the
status reports encoded in a Preset command transmitted from a two-way thermostat
or remote thermometer employing the algorithm used by the RCS TX15-B and TXB16
thermostats (shown as a table in the thermostat user\'s guide).
.br
The Smarthome TempLinc Model 1625 remote thermometer uses the same
algorithm for the temperature report, which is:
.br
temperature = -60 + 32*(unit - 11) + (preset_level - 1)
.PP
If the Heyu State Engine is running, the decoded temperature is stored
at the (fictitious) unit 0 address H0, where \'H\' is the housecode of the
thermostat or thermometer. It can be recovered with the \'heyu rcstemp H\'
command. Provided a valid temperature has been stored, any script launched
by Heyu can recover the temperature as the value of environment variable
X10_H0 or the environment variable alias for H0. (Since these environment
variables are created only if valid data has been stored, a check for their
existance, e.g., [ "X10_H0" != "" ], may be required before using
them in a script or shell command.)
.PP
*** WARNING - WARNING - WARNING ***
.br
The use of Heyu or any other power-line protocol software to
control a heater lacking a built-in failsafe mechanism is not
only unwise, it is hazardous to life and downright foolhardy.
DON\'T DO IT!
.PP
This directive may have the values: OFF for no decoding;
a list if housecodes enclosed in square [] brackets for which decoding
is to be performed; or ALL to decode any housecode. The default is OFF.
.br
Examples:
.br
RCS_DECODE OFF (no decoding)
.br
RCS_DECODE [CFH] (decode on housecodes C, F, and H)
.br
RCS_DECODE ALL (decode on any housecode)
.br
Note: This directive need not be used in order to query the thermostat with
the \'heyu rcs_req ...\' or \'heyu temp_req ...\' commands - it only enables
the temperature or other status to be displayed in Heyu\'s monitor,
regardless of whether or not the thermostat\'s transmission was initiated
by these commands. (The TempLinc Model 1625
remote thermometer can be programmed to transmit a temperature report any
time the temperature changes.)
.PP
.SH ACK_HAILS directive
Setting this directive to YES will instruct the Heyu state engine daemon
(if running) to send a hail_ack with the default housecode whenever it
receives a hail signal over the power line. The hail_ack is sent as if
from a launched script. The choices are YES or NO, with the default
being NO.
.br
Example:
.br
ACK_HAILS NO
.SH AUTOFETCH directive
When a state command which returns the addressed state
of a module is executed at the command line, Heyu by
default (AUTOFETCH YES) instructs the state engine to first update the
state file, since Heyu only automatically updates this file
following an X10 function. Setting the value of the directive to NO
disables this action for (only) those specific state commands.
Most users will want to accept the default value of YES. See the
description of the \'fetchstate\' command in man page heyu(1) for
a more detailed discussion of this issue.
.SH TIMER_LOOPCOUNT directive
Specifies the base loopcount for the fast timing loops needed by some
CM17A and experimental commands. To determine the value for this
directive, run \'heyu utility calibrate\'.
.SH FORCE_ADDR directive
Heyu doesn\'t normally send a separate Housecode|Unit address byte for
commands like all_lights_on which don\'t actually require the unit number
(the housecode is included with the function), or for extended commands
which contain the unit number within the function code. However X-10\'s
ActiveHome software always sends this byte, generally using unit 13.
This directives forces Heyu to always send an address byte.
.br
If always sending an address byte cures some problem you are having,
choose YES. Otherwise take the default of NO.
.br
Example:
.br
FORCE_ADDR NO
.SH SPOOLFILE_MAX directive
This directive sets the limit on the size of the spoolfile beyond which
the Heyu relay daemon will rewind it once it detects a period of
inactivity (currently 5 seconds). The size set by this directive may
be between 20 and an absolute maximum 1048576 bytes (but don\'t use this
max value). The default limit is 1000000 bytes. For changes in this
directive to become effective when Heyu is already running, use the
\'heyu restart\' command.
.br
Note that re-synchronization with the Heyu state engine daemon or monitor
takes a couple of seconds, during which time Heyu will ignore incoming X10
signals or macro executions. So don't set a low limit except for testing
purposes.
.SH SECTION directive
This directive and anything which follows it on the line is treated the
same as a comment and totally ignored by Heyu. It is provided to enable
user-definable breakpoints for use by an external program or script to
reorganize the Heyu configuration file.
.SH CHECK_RI_LINE directive
When the CM11A receives an X10 signal over the power line it asserts
the Ring Indicator (RI) serial line for a short time prior to sending
the signal to the computer. This directive tells Heyu whether or not
to check this serial line before attempting to transmit a command so
as to help avoid collisions on the powerline. The default is YES.
This check is normally bypassed for serial port hardware which does
not support the serial control lines, so setting this directive to
NO should only be required in exceptional situations. One such
situation occurs with USB-Serial adapters using an older Prolific
chip under Linux, resulting in the message "RI serial line may be stuck"
after a long delay. Note that this check will be ineffective if the
CM11A RI line is disabled by the following directive.
.SH RING_CTRL directive
Setting the value of this directive to DISABLE instructs Heyu to disable
the CM11A Ring Indicator (RI) line of the CM11A, which would otherwise
be asserted each time an X10 signal is received over the powerline.
In addition, Heyu commands like \'heyu ping\' and \'heyu wait\' which
normally employ the CM11A Ring_Enable command for their functionality
will substitute the CM11A Ring_Disable command. This directive is
not totally effective because the CM11A asserts the RI line when it is
powered up, before Heyu has a chance to disable it, e.g., in the event
of a momentary interruption in AC power.
.br
The ONLY reason for disabling the RI line is that some computers have
a "Start on Ring" feature and/or "Awake from Sleep on Ring" feature which