[dragonfly.git] / share / man / man4 / man4.i386 / tw.4

.\" Copyright (c) 1992, 1993 Eugene W. Stark
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Eugene W. Stark.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY EUGENE W. STARK (THE AUTHOR) ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man4/man4.i386/tw.4,v 1.9.2.3 2001/08/17 13:08:46 ru Exp $
.\" $DragonFly: src/share/man/man4/man4.i386/tw.4,v 1.3 2006/08/18 01:42:58 swildner Exp $
.\"
.Dd October 30, 1993
.Dt TW 4 i386
.Os
.Sh NAME
.Nm tw
.Nd TW-523 X-10 device driver
.Sh DESCRIPTION
.Nm Tw
is the driver for the TW-523 power line interface, for use with X-10 home
control products.  The X-10 protocol is compatible with a number of home
control systems, including Radio Shack ``Plug 'n Power(tm)'' and
Stanley ``Lightmaker(tm).''
.Pp
The driver supports
.Fn read
.Fn write
and
.Fn select
system calls.
The driver allows multiple processes to read and write simultaneously,
but there is probably not much sense in having more than one reader or more
than one writer at a time, and in fact there may currently be a race
condition in the driver if two processes try to transmit simultaneously
(due to unsynchronized access to the sc_pkt structure in tw_sc).
.Pp
Transmission is done by calling
.Fn write
to send three byte packets of data.
The first byte contains a four bit house code (0=A to 15=P).  The second byte
contains a five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
to 31 = Status Request).  The third byte specifies the number of times the
packet is to be transmitted without any gaps between successive transmissions.
Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
bright and dim codes) it can be another value.  Each call to
.Fn write
can specify
an arbitrary number of data bytes, but at most one packet will actually be
processed in any call.  Any incomplete packet is buffered until a subsequent
call to
.Fn write
provides data to complete it.  Successive calls to
.Fn write
leave a three-cycle gap between transmissions, per the X-10 documentation.
The driver transmits each bit only once per half cycle, not three times as
the X-10 documentation states, because the TW523 only provides sync on
each power line zero crossing.  So, the driver will probably not work
properly if you have three-phase service.  Most residences use a two-wire
system, for which the driver does work.
.Pp
Reception is done using
.Fn read
The driver produces a series of three
character packets.  In each packet, the first character consists of flags,
the second character is a four bit house code (0-15), and the third character
is a five bit key/function code (0-31).  The flags are the following:
.Bd -literal
#define TW_RCV_LOCAL	1  /* The packet arrived during a local transmission */
#define TW_RCV_ERROR	2  /* An invalid/corrupted packet was received */
.Ed
.Pp
The
.Fn select
system call can be used in the usual way to determine if there
is data ready for reading.
.Sh FILES
.Bl -tag -width /dev/tw
.It Pa /dev/tw?
the TW523 special file
.El
.Sh SEE ALSO
.Xr xten 1 ,
.Xr xtend 8
.Pp
TW-523 documentation from X-10 Inc.
.Sh AUTHORS
.An Eugene W. Stark Aq stark@cs.sunysb.edu
Commit	Line	Data
984263bc MD	1	.\" Copyright (c) 1992, 1993 Eugene W. Stark
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by Eugene W. Stark.
	15	.\" 4. The name of the author may not be used to endorse or promote products
	16	.\" derived from this software without specific prior written permission.
	17	.\"
	18	.\" THIS SOFTWARE IS PROVIDED BY EUGENE W. STARK (THE AUTHOR) ``AS IS'' AND
	19	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	20	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	21	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
	22	.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	23	.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	24	.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	25	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	26	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	27	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	28	.\" SUCH DAMAGE.
	29	.\"
	30	.\" $FreeBSD: src/share/man/man4/man4.i386/tw.4,v 1.9.2.3 2001/08/17 13:08:46 ru Exp $
de023c90	31	.\" $DragonFly: src/share/man/man4/man4.i386/tw.4,v 1.3 2006/08/18 01:42:58 swildner Exp $
984263bc MD	32	.\"
	33	.Dd October 30, 1993
	34	.Dt TW 4 i386
	35	.Os
	36	.Sh NAME
	37	.Nm tw
	38	.Nd TW-523 X-10 device driver
	39	.Sh DESCRIPTION
	40	.Nm Tw
	41	is the driver for the TW-523 power line interface, for use with X-10 home
	42	control products. The X-10 protocol is compatible with a number of home
	43	control systems, including Radio Shack ``Plug 'n Power(tm)'' and
	44	Stanley ``Lightmaker(tm).''
	45	.Pp
	46	The driver supports
	47	.Fn read
	48	.Fn write
	49	and
	50	.Fn select
	51	system calls.
	52	The driver allows multiple processes to read and write simultaneously,
	53	but there is probably not much sense in having more than one reader or more
	54	than one writer at a time, and in fact there may currently be a race
	55	condition in the driver if two processes try to transmit simultaneously
	56	(due to unsynchronized access to the sc_pkt structure in tw_sc).
	57	.Pp
	58	Transmission is done by calling
	59	.Fn write
	60	to send three byte packets of data.
	61	The first byte contains a four bit house code (0=A to 15=P). The second byte
	62	contains a five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
	63	to 31 = Status Request). The third byte specifies the number of times the
	64	packet is to be transmitted without any gaps between successive transmissions.
	65	Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
	66	bright and dim codes) it can be another value. Each call to
	67	.Fn write
	68	can specify
	69	an arbitrary number of data bytes, but at most one packet will actually be
	70	processed in any call. Any incomplete packet is buffered until a subsequent
	71	call to
	72	.Fn write
	73	provides data to complete it. Successive calls to
	74	.Fn write
	75	leave a three-cycle gap between transmissions, per the X-10 documentation.
	76	The driver transmits each bit only once per half cycle, not three times as
	77	the X-10 documentation states, because the TW523 only provides sync on
	78	each power line zero crossing. So, the driver will probably not work
	79	properly if you have three-phase service. Most residences use a two-wire
	80	system, for which the driver does work.
	81	.Pp
	82	Reception is done using
	83	.Fn read
	84	The driver produces a series of three
	85	character packets. In each packet, the first character consists of flags,
	86	the second character is a four bit house code (0-15), and the third character
	87	is a five bit key/function code (0-31). The flags are the following:
	88	.Bd -literal
	89	#define TW_RCV_LOCAL 1 /* The packet arrived during a local transmission */
	90	#define TW_RCV_ERROR 2 /* An invalid/corrupted packet was received */
	91	.Ed
	92	.Pp
	93	The
	94	.Fn select
	95	system call can be used in the usual way to determine if there
96	is data ready for reading.
984263bc MD	97	.Sh FILES
	98	.Bl -tag -width /dev/tw
	99	.It Pa /dev/tw?
	100	the TW523 special file
	101	.El
de023c90 SW	102	.Sh SEE ALSO
	103	.Xr xten 1 ,
	104	.Xr xtend 8
	105	.Pp
	106	TW-523 documentation from X-10 Inc.
984263bc MD	107	.Sh AUTHORS
984263bc MD	108	.An Eugene W. Stark Aq stark@cs.sunysb.edu