Net Lightning. For OS/2 and Linux Release I 6/15/98
Copyright 1998 Stu Mark
http://nyti.spaghetti.com
fordii@j51.com

If you're used to my normal style of documentation (see
http://nyti.spaghetti.com/murynt.doc) This will probably be a bit of a
letdown for you. I'm in a rush to do a lot of things this summer, and
documentation is not exactly number 1 on my list.
Sad though really. It's my only useful outlet for my love of writing. I'm
working on a book though. Really. I am. You'll like it. Maybe I'll get more
into it as I start reading the old tomes.

But back to the topic at hand. I just came up with the name, this morning,
inspired by a thunderstorm in North Carolina.

N E T   L I G H T N I N G

Now how cool is that. Given the actual function of the program, it would be
better titled "Net Lighting", but a name is a name and a rose has thorns.
Anything is better than the name of the executable: xcontrol.

I'm drafting this file from the Murray docs, of course, so you're going to
find similarities and the really long winded stuff, I'm just going to copy
straight. This isn't a 2-week-in-the-bathroom system though, so it shouldn't
take long to get through the important parts.

As always: I love Roman Numerals.

I. Net Lightning. (The program of the hour)

Release I. I like roman numerals. I'm going to assume that at some point I
will have a fix for one version (os/2 or linux) that the other doesn't
need, so the release numbers will probably eventually separate, but for now,
the first release. They're both Release I.

Net Lightning OS/2 and Linux.
Concept and implementation by Stu Mark. But then again, a server is a server.
Copyright 1998.

Net Lighning is a simple server that makes it simple to control your x-10
devices from a computer. Basically I've translated flag files into the x-10
protocol. So all you have to do is create flag files with specific names and
the device will act accordingly. Net Lightning also reads information from
the interface and will execute commands if you want to when a particular
device performs an action.

II. Requirements. (What you need to make it go.)
I require that you read this. I require that you take a look around you and
notice the world. Life's too short for you to spend your time listening to me
preach about how life's too short. Go to Europe. It does wonders. If you live
in Europe, go to India. Don't go to the U.S. It's depressing.
You've got to have a computer running OS/2 2.0 or later, or Linux. I use
2.0.34 of the linux kernel, it's a pretty simple program, it'll probably work
in the 1.x releases, but I'm sure the 2.x will be fine.
You will need power for your computer. I can't help you here. It's a
society/government thing.
But Most Importantly: You NEED The X-10 Computer Interface (CM10A/CM11A)
You've got to have a serial port to hook it up to, and a wall outlet to plug
it in to. Now that I think about it, something tells me they don't have a
European version of X-10. I dunno. Maybe they do. If they don't then you
have little use of this program except to glean whatever little wisdom may be
in this doc file. But assuming there is no European X-10 system, then you
have no need of this program, you aren't reading this and therefore don't
live in Europe so that it's not a problem for you to visit there.
If you don't have x-10 and there's no wisdom in this file, then I highly
recommend you download Murray.
Also, if you don't have X-10. I recommend it. I think it's fun. Another
stupid little hobby of mine. Go visit them at http://www.x10.com

III. Non-Requirements. (What you don't need to make it not go.)
You don't have to be the ruler of the world/country/golf club/lemonade stand.
I don't require any monetary payment for this program. But I wouldn't mind
it :) See below. It doesn't time out or stop working. Credit where credit is
due and all that, but if you want changes, it'll cost ya. (stinky greedy
american)
You don't need a windows machine. They don't make very good servers so I
didn't port this to windows. (Dig #1)
You don't need to wear socks. I don't, and it works fine for me.

IV. Our Forefathers. (There is much to be said for the history of our world)
This was an answering machine message I made up once. Spoken in a very slow
drawling voice:
Four score and seven years ago, our forefathers did not have telephones. They
did not have answering machines and if they weren't there, you couldn't talk
to them. Isn't science wonderful.

V. Great Days. (There is much that we should probably skip when talking
about the history of our world)
It was on the eve of the great day. The Great Day as it was commonly held.
For our parents told us of it. They relished in the memories of the times
when all was good and well. The feel pity for us young ones who will never
know such simple times. Even in the times of plight, their world held such
great beauty and charm as we will never know. They sit in their rocking
chairs and drink their lemonade. They toast each other for all they have
lived through, but they know not of what the world is to bring them. Never
has anybody in all of human history seen what we have seen. Never have they
walked these paths. And they will never know.
And for what. For nothing. 

VI. Net Lightning Features (What it's all about)
As stated above, Net Lightning does two things. It will allow you to control
your X-10 modules by simply placing flag files and it will allow you to run
tasks on your PC when it recieves a signal from a remote or a 2-way module.

The specifics: By flag file, I mean the existance of a file. It doesn't
matter what's in the file, just that it's there. Only 2 commands are
supported. On and Off. You can make a device turn on or off just by creating
a file. These files are scanned for once a second. It may seem like a lot,
but it doesn't take very long, the FS caches the directory contents and
really, what else is your machine doing that this is going to cause such a
problem. I'm a big fan of event oriented systems, but when it comes down to
it, polling for files works real well, and it's a lot simpler to write. When
the file is scanned, it will be deleted so that Net Lightning won't pick it
up again. If there is a problem deleting the file (like, oh say, you're
taking a really long time to open/write/close the file) it will keep getting
rescanned. So be quick about making the file. touch works nicely.

The naming convention of the files are as follows. Real simple
D<devicenumber><Y|N>
This means you create a file that starts with "D" for device, then the number
of the device, say "3", then "Y" OR "N". Y is for turning the device on, N
is for turning it off. This is because O for on and O for off doesn't work
well :)

Linux note: Case doesn't matter. Any case will be picked up. 
D1n is equivalent to d1N
Ex:
d13y  <-- this will turn on device 13 of the housecode set in the config file (see below)
d2n   <-- this will turn off device 2.

The other side is the notification. When Net Lightning gets a signal from
the X-10 interface (again, it will only process on and off signals) it will
look in the config file to see if there's something to do for that device
and that function (on/off).

Details about format and naming conventions are below.

VII. Ner Flub. (Nixo Nada Nyet Neigne Nikasa Nipsa No)
Ne'er owen Ner Flub. Hozen plendt mik schlab. Fen herron clek timk dow
jevrohizah mekooloo, feg grintz den habloo. Sie denger dee plankz oriop
Seat Asura, re Renault Twingo, re Fiat Punto. Blehn kerod nact iblee oohoen
gvendel li flena dorenam naepli triepha. 

VIII. Sorry about that. (Err...)
Sorry about that.

IX. Installation. (Section 8, section 3)
There is only one copy of this document, but there are two distributions.
One with the OS/2 executable in it, one with Linux Binary in it.
So I will describe both cases here.
The Os/2 distribution is a zip file with the exe, this doc file and a short
sample config file. The Linux distribution is a gzipped tar of the same.
This is the doc file. If you're reading this, you're doing pretty good so
far, and I probably don't have to explain to you how to unzip the archive.
In the unlikely event that you managed to unzip just the doc file, let me
assure you that it is quite necessesary for you to unzip/unarchive/extract
the other two files. Preferable into the same directory. Also remember to
look both ways before you cross the street.

What directory you use doesn't matter. The program defaults to the current
directory when it has to do something.
Well, gee what else. Since it's a server, I guess you're going to want to
put it in your startup somewhere.
The program itself accepts one parameter: The name of the config file it
should read from. If you don't specify it, it'll default to xcontrol.cfg in
the current directory. When booting, this is the root path in linux and the
root directory of your boot drive in OS/2. Chances are this is not what you
want, so you're going to want to specify the full path of the config file
on the command line:

Linux: I put it in my /etc/rc.d/rc.local (I use slackware)
The program doesn't run as a daemon by itself so you're going to have to do
something like this:
/usr/local/bin/xcontrol /etc/xcontrol.cfg &
The & is necessary so that it won't hang the rc.local script, because
Net Lightning never exits.

OS/2: I dunno. Make a shadow to it in your startup folder or something. Make
sure in the parameters box you put the full path of the config file.
Something like: c:\netlitin\xcontrol.cfg

Then you can reboot your system to make sure it starts up right. But first
I recommend you run it by hand to make sure everything is done right and
it finds the serial port and all that. Don't do it now, you still have to
set up the config file.

X. The Config File (Like there aren't enough config files in the world
already)
The options are similar between os/2 and linux, few things you should note:
There's an entry for PORT. For OS/2 it should be something like this:
PORT=COM2 or 
PORT=COM1
For Linux it should be
PORT=/dev/cua0 or 
PORT=/dev/cua1
I've got /dev/modem sym linked to /dev/cua1, so I use /dev/modem
There's an entry for SCANDIRECTORY. Again, fs specific...
OS/2: SCANDIRECTORY=c:\scanme
Linux: SCANDIRECTORY=/data/scanme
The SCANDIRECTORY is the path that Net Lightning will look for the flag
files mentioned above.
It helps a great deal if this directory exists :)

Everything else in the config file is the same between both systems.

HOUSECODE=F
This ones pretty simple. Right now the system only supports one housecode
at a time. Maybe someday it will do more. If I have a need or you pay me.
I can be bought. Set this to the letter of your housecode settings on your
devices and switches. 
I have my housecode set to F for Fuck.
In the case of a remote control signal, Net Lightning will not distingush
between housecodes, so if you hit device 4 on, for housecode A and then
housecode B, Net Lightning will percieve it as the same signal. Whoops.
I before E except after c and neighbor. Make that Perceive. I still don't
have a spelling checker.

There are these things called 2-way modules. I don't have one of these yet,
but they tell me that it has the ability to send a notification of its state.
Now I don't know if it has to be polled or not. But it's possible that it
sends a signal just like a remote control does. In this case, you could set
up something like: If you turn on a lamp in your living room (and it sends
a notification that device 2 was turned on) then run a script that waits 30
minutes then creates a file called d2n. The result is that the lamp will
go off 30 minutes after it was turned on. Neat eh? Auto sleep feature.

The format for commands in the config file is this:
"CONTROL"<device number><on/off>=<command>

For example:
control1on=echo "living room lamp. on." > /talk/t.tlk

This will cause a file called /talk/t.tlk to be created when device #1 is
turned on. In my case, the /talk directory gets scanned for files with
the .tlk extention and the contents get read out loud via my sound card.
Neat eh?

Let's face reality here. If you're going to waste money on home automation,
might as well make it really geeky.

Tech details: The Linux version executes the command from the config file
by calling the system() function with "exec " plus whatever's on the config
line. You know more about linux than I do, so you should know what effect
it has.
The OS/2 version does a DosStartSession with mostly defaults so it should
be able to run PM or VIO programs.

Examples:
control13off=reboot
You can guess what that does.

control1on=c:\music\mp123 c:\music\mympeg.mp3
This will play a song for me when I hit the on button for device 1.

XI. Logging. (What the hell was that.)
As far as I know everything works okay, so you shouldn't have any problems.
If there is a problem, something will get logged. The Linux version logs to
syslog, the OS/2 version logs to a file in the scan directory called
xcontrol.log. I think. I use the linux version because that's the machine
with the free serial port. But if I were writing this program (which I did)
I would have made it xcontrol.log, so chances are, that's what it is.
If something goes wrong it will be logged. If it's not obvious what the
problem is email me at fordii@j51.com and I'll try and help you out.
Nobody cleans the OS/2 log file so you may want to download my NYTS II
scheduler and use it to archive the logs every once in a while. Remember,
that's http://nyti.spaghetti.com

XII. Me / distribution / pricing. (Send money :)

This program is free. You can distribute it as much as you like without cost
or penalty, as long as you give it away in the original zip/tgz with all
files intact.

I spent a lot of time and effort on this and I like audience participation
as much as the next guy. So, if you'd like to drop me a line, my
Eddress (e-mail address (I'm trying to coin a new phrase)) is at the end of
this file.

If you're feeling generous, I will gladly accept monetary donations which
will further entice me to continue development on this an other systems
that I'm writing. Especially if you want me to do something custom for you.
I'd probably be willing to do it, I'm usually a nice guy, but time goes by
quickly and it's getting to be summer out and outside is better than inside.
You know how it is. I write this software so more and more people stay home
and play with it, so that there's less people out in the parks and on the
roads. More for me. Call me selfish. Call me Stu.

Like Murray, $5 would be nice. $10 would be even nicer. $50 will get you a
thank you card in the mail. Help support the Free Software Writers by paying
for their software. Heh. Nesting Irony.

If you're in a rush and you have a greater need to pity my financial woes
than to actually use the program RIGHT NOW, and you don't keep your
checkbook on you, here's where you can send monetary donations. (This is
also listed at the end of this file.)

	Stu Mark
	Attn.: Net Lightning.
	P.O. Box 77
	Valley Cottage, NY 10989
	U.S.A.

If you send money, I'll add you to my mailing list and send out mail
or e-mail with new releases or information about upcoming products,
versions or fixes. If I have any money left over after buying more
hardware (see Murray), maybe I'll be nice and spend some money on the
Ethiopian I use as a doormat.
(Keep in mind I wrote most of this section for Murray, and I can get into
a pretty twisted state of mind when I'm writing. I'm not really that
evil. Usually.)

XIII.  UnInstallation. (Now why would you want to delete such a cool program.)

It seems people like to uninstall software. Usually, it's more like they
whack the machine by accident and then have to reinstall.
Well, Net Lightning is pretty benign, it doesn't do anyting that you don't
tell it to. So all you pretty much have to do is delete the xcontrol[.exe]
file, the xcontrol.cfg file and the directory it was in, if it was by itself.
Deleting the exe will cause OS/2 to remove the shadow for you.
The linux people are going to have to remove the line out of the
/etc/rc.d/rc.local file themselves.

XIV.  Legalooze. (This is where I copy the vague legal section from the
Murray documentation and twist it so that it sorta applies to Net Lightning.)

Net Lightning is my idea and my program and no matter what, I thought of it
and implemented it first.

This piece of art is not published under the GNU license because, while I
stand for what they're doing, I'm personally not too thrilled with the way
they do it. So let's call it Ford-ware or Stu-ware. I have the source, you
don't. You have the executable, and this DOC file. It all comes in one nice
neat zip, and it's simpler if you distribute it that way. I wrote it. It's
mine. Say what you want, but the copyright belongs to the original creator,
which is me, Stu Mark.

Give it out freely, but give out the original zip. Please. Be nice. 
Be kind. Rewind. Don't be a prick. Rewind this flick.

There is no warranty expressed or implied, and all that other shit. You use
it at your own risk, I make no claims about what it will and won't do.
This software makes every intention of doing nothing but sending data up and
down the serial port you specify and executing commands in the config file.
If you decide to put control1on=rm -rf *
Well, that's your own fucking fault. Don't come crying to me.

XV. Binaries. (I just HAVE to mention this)
If you're an OS/2 person, I make you an EXE, and you use it. No problem.
If you're a linux person, you probably know all about the GNU people and shit
like that and how I don't agree and all that crap. So if everybody on the
planet gives out source and let them compile it on their own goofy hardware,
why don't I?
Not my gig. I don't want to support programs on hardware I don't have. I
could think up tons of reasons. But I'll spare you. I just don't agree with
the philosophy of busting my ass and then giving everything away to be
ripped off and plagarized. There are very few things that I hold near and
dear to me. This is one of them. No source for You.
Sadly, I can't figure out how to make gcc compile for a 386, so I believe it 
made a binary for a Pentium. Try it. If it doesn't work, I'll figure something
out.

XVI. Future releases/bug fixes. (There are no bugs, only design flaws.)
Net Lightning is a pretty simple program. If I didn't have to spend so much
time fighting with the interface (my 9-25 pin converter had a loose pin) I
could have pounded this out in a day, but it's over and done now, so here
it is. If you have any problems. Let me know, and I'll wait for your
payment to fix them. Just kidding.
email to fordii@j51.com

XVII. Known problems. ("It's not a problem, it's a bug. EVERYBODY has bugs.")

The only problem I know of are the limitations of the initial design. It can
only do on/off and only talks to one housecode.
I did once, however, manage to get my X-10 interface into a state where
nothing would work. Even the windows software they gave me wouldn't talk
to it. I tried unplugging it and taking the batteries out. To no avail.
Then I clicked something on the remote. It shot out some shit data then
went back to normal. Can't reproduce it. Just fyi.

XVIII. Update history.

6/15/98  Net Lightning for OS/2 and Linux Release I

XIX. My life saga. (People who like to read about my personal life.)
I'm not going to go into this here. Read the Murray documentation for the
dirt.

XX. Are you paying attention?

Coalition to get everybody to drop 95 and start using OS/2, Linux or NT.

XXI. Movie Reviews
Godzilla was the worst movie I've ever seen in my life.
They made it as nintendo generation tacky as possible. They stole the effects
entirely from Jurassic park: The damn thing didn't look anything like
Godzilla. Godzilla used to have a square head and stood up straight and
had small arms and rested his tail on the ground. What a piece of
cinematic shit.

XXII. Required Reading. (Enhance your view of the world without computers.)

If you have a spare moment and are the kind of person who can actually make
an effort to get things done, I suggest seeking out an article called
"A Week Of Sheer Fakery" by George Will. It was published in the September
15th 1997 issue of Newsweek. They don't seem to have a web page (more power
to them) and I went hunting around for an electronic version and couldn't
find one. If I had a religion, this would be its own chapter in my
"Defines" book. I can't begin to explain what a great article it is,
you're going to have to read it yourself. I leave it as an exercise for the
reader to acquire this issue of Newsweek, read it understand it and preach
it to everybody you know. This article is REQUIRED READING.

XXIII. Plugs (This is where I advertise for myself)

Come check out all of the other crap I've wasted my time writing.

Most highly recommended (by a lot of people other than me) is Murray.
http://nyti.spaghetti.com
If you like british humor read the doc file for it. I get email all the
time from people telling me they can't use the program, but loved the
documentation. 
Murray (Windows 95/NT and OS/2 versions available) is a program that sits
in the background running on your machine and will go out to a server
(my server, at my house, in the mud) and download a new desktop background
or system sound for you, so you don't have to, and you get a surprise
multimedia experience every time you use your machine.

You may have heard me mention Tragic. Tragic is my half done up and coming
project. It's not quite as much fun as Murray in that you can't click
"trigger item now" and get immediate satisfaction, but it does some really
cool things. I'm trying to build hype for it now, so it'll spread like
wildfire when it's done. Net Lightning is another one of the multitudes of
smaller projects that gets in the way of tragic getting done. I'll get to it.
I always do.

NYTS II is a process scheduling utility for OS/2. Yeah, I know there's
lots of schedulers out there, but I like mine. I can change it.

-----------------------------------------------------------------------------

Net Lightning for OS/2 and Linux Release I
6/15/98 Copyright Stu Mark.
e-mail: fordii@j51.com
telnet nyti.spaghetti.com on port 1111 (24 hours a day)

Check out my web site, it has a cool background.
http://nyti.spaghetti.com

Monetary donations (see section XII) can be made payable to:

Stu Mark    Attn: Net Lightning
P.O. Box 77
Valley Cottage, NY 10989
U.S.A.

Latest and greatest versions of all my software are available via ftp
at nyti.spaghetti.com

Come visit my web page (it's rather sparse right now, all my free time
goes to working on Tragic and I don't have any time to make a nice page)
at (guess where...)  http://nyti.spaghetti.com

I don't think I did much windows bashing, but in case I did...
(Any nasty remarks sent in the general direction of Window's capacity to
function, [are fully intentional,] are not opinion, but a statement of fact.
So, don't try to slam me with some bullshit libel suit.)

I've also decided to start a campaign to make it a really loud notion to
compare The Microsoft marketing department to the Marketing department at
Sirius Cybernetics Corp. Anybody with me on this? If so, mail a message
to my BBS at doom@nyti.spaghetti.com

There's more fun to be had where the grass is greener.
It makes you appreciate what you've got more.

Live long, eat shit, prosper, and die.
