      'Lucid Dream Inducer' V1.10 - A program for Amiga computers

                   Copyright © 1994-1995 by Tero Auvinen
                       email: ta3153@bessel.tutech.fi


                 Read the whole documentation before using!
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Contents:
~~~~~~~~~

        1. Legal things
        2. What is 'Lucid Dream Inducer'
        3. Requirements
        4. Installation
        5. Usage
        6. Bugs & more, technical stuff
        7. History


1. Legal things
===============


Copyright © 1994-1995 by Tero Auvinen

'Lucid Dream Inducer' (LDI) is a *mailware* program. You are required send me
email if you use this program frequently!!! Permission is granted to freely
distribute this program without ANY profit (except for some reasonable media
fee). The program may not be altered in any way and *cannot* be used for com-
mercial purposes in any situation.


NO WARRANTY!

I hereby reject any liability or responsibility for these or any other direct
/indirect consequences from the use of LDI whatsoever. This includes, but is
not limited to, damage to your equipment, damage to your data, personal inju-
ries, financial loss or any other kinds of side-effects. It is your responsi-
bility to take any precautions necessary to protect yourself from these or any
other effects.

If the laws of your country or territory state that I am responsible of any-
thing mentioned above, you may not use or distribute this program.


2. What is 'Lucid Dream Inducer'?
=================================

LDI (Lucid Dream Inducer) is a program designed to affect your dreams, and by
doing so, it may help you to have lucid dreams. LDI does this by either exe-
cuting a program/script (for playing samples/speech etc.) or for example
flashing a LED thru the parallel port.

If you are newbie in lucid dreaming, check out the following web page:
'http://www.lucidity.com'. There you can find some general information about
lucid dreaming. (And great books about LD'ing too.)

Look at the hardware prices, say 'YIKES!!!!!', and learn how to use this
program instead :) Ok, they need to get the R&D money from somewhere, so
you might consider supporting their valuable work by buying their products.

   *** I'm NOT in any way connected with Lucidity Institute!!! ***

In order to use the full power of this program, you need be familiar with
electronics.


3. Requirements
===============

LDI requires Kickstart 2.0+ and ReqTools.library 37+(not included). And if you
want to use LED-inducing you have to build a little bit of electronics into the
parallel port. Read chapter "6. Bugs & more, technical stuff" for information
about this.

This program is written in a system friendly matter EXCEPT what comes to the
parallel port handling, it bangs straight to the hardware... So, it might *not*
work on A600, A1200 and up. (It's been reported that LDI works atleast on
A500 & A1200.)


4. Installation
===============

Just copy the executable somewhere the along the path. Or if you want to, make
a bootable disk which you can use on some old A500 :)

The program searches the prefs file from ENVARC: Remember to assign ENVARC:
somewhere if you use floppy!

The REM file (eye movement data) is initially saved with the filename
'ldi:sfile', so remember to assign ldi: somewhere too. Or if you are using
floppy, rename it as 'ldi'.


5. Usage
========

If you want it to detach from cli, 'run >nil: <nil:' it. But beware, then you
cannot see any of the possible DOS error messages that may occur when using the
'Command' cue mode!


-= LDI's main interface (GUI) =-

Well, just move those sliders and you'll get the idea. Each slider changes some
value which is on the same vertical level as the slider. Clicking in the
container area of the gadget allows finer control of the values.

You can also use cursor keys to fine-tune the cuetime. When pressing right shift
the time changes in 10 minute steps.

The program has two operating modes, in the following descriptions the 
'Detect REM' mode behaviour is in parentheses.

Operating modes:

Normal     - The program doesn't care about eye movements, it just makes cues
             according to the delays & times set by the user.

Detect REM - The program monitors the parellel port, in order to detect the REM
             sleep. (More about this in the technical chapter.)

Slider gadgets:
~~~~~~~~~~~~~~~
"Cue starts at"    - This is the time when LDI makes the first cue.
                     (Defines when LDI starts to monitor for eye movements.)

"Repat after..."   - These two settings define how often and how many times the
                     cue is repeated.
                     (Only the first setting has any meaning, it defines the
                      time that the program waits after a cue. After the
                      specified time has passed, the program starts to monitor
                      for eye movements again.)

"ON/OFF times"     - These two gadgets define the 'frequency' of which the
                     dataline 0 on the parallel port toggles when making cue.
                     These two settings affect only the 'Parallel' type cue.
                     (Same action as above.)

"Number of cycles" - This setting defines how many 'ON/OFF' sequences are made
                     per cue. This setting affects only the 'Parallel' type cue.
                     (Same action as above.)

Button gadgets:
~~~~~~~~~~~~~~~
"Test"             - This button causes one COMPLETE cue to occur.

                     On the right side of the gadget you can see the approximate
                     duration of the cue. If the approx. cue duration exceeds 
                     the 'Repeat after' time, then you are going to get into 
                     trouble. This also applies to the 'Command' type cues, but
                     you have to estimate the time that the command takes to 
                     run yourself.

"Start/Stop"       - This button puts the program into waiting state until the
                     time defined in "Cue starts at" takes place. This button
                     also brings the program back from the waiting state.

                     When pressing this button second time, the program displays
                     a 'Statistics' window. (Doesn't quite work yet.)

                     On the right side of the gadget you can see the approximate
                     overall duration of all the cues. (Applies only to the
                     parallel & non-rem detecting mode.)


Cycle gadget:      - This gadget defines the cue type, it has three states:
~~~~~~~~~~~~~
                      'Parallel'
                        o When making cue, dataline 0 in parallel port is toggled.

                      'Command'
                        o When making cue, the 'command' from the string gadget
                          is executed SYNCHRONOUSLY, so if the command crashes
                          or hangs LDI hangs too because it waits until the 
                          executed command returns.

                      'Both'
                        o When making cue, LDI makes BOTH cues, 'Command' and
                          'Parallel', in that order!


Menus:
~~~~~~
Project

 o Load settings
   - Loads settings from ENVARC:LDI.prefs

 o Save settings
   - Saves current settings (including the position of the main window)
     to ENVARC:LDI.prefs

 o About
   - Displays some information about the program (And my email address too!)

 o Quit
   - This item doesn't have ANY practical use :)

Misc

 o Set cue threshold...
   - (Applies in the 'Detect REM' mode only.)
     This value defines the number of eye movements per minute that the program
     has to detect before it makes a cue.

     The cue is made when the following condition is true:
     'Eye movements' => 'cue threshold level'.
     The condition is tested once in a minute.

     Example: If the program detects 30 eye movements in a minute and the
     threshold value is 34, no cue is made.

 o Detect REM
   - When this item is checked, the program makes cues only when the
     'set cue threshold' condition is met.

 o Save REM file
   - The program logs the eye movement data. So, you can save the log file
     for later analyzing (program called "rem" in the archive will do that).
     This file will be saved upon exit with the following (initial)
     filename: 'ldi:sfile'. Well, there is another way of saving it. Just
     check out the 'Statistics' window when pressing the 'Start/Stop' gadget
     for the second time. (Applies only if this item is checked.)


Keys:
~~~~~
You can also use cursor keys to fine-tune the cuetime. When pressing right shift
the time changes in 10 minute steps.

Pressing 't' when LDI's window is activated, toggles the state of the
dataline 0. (To help you adjust the right brightness for the LED for example.)

Pressing 'ESC' quits the program.


6. Bugs & more, technical stuff
===============================

Known bugs:
~~~~~~~~~~~
Under some circumstances, the program just might go crazy.
Report all strange behaviour!

LDI doesn't check EVERYTHING. Don't use it when you are *VERY* low on memory.
But on the other hand, then you probably can't even start the program.
(no memory for window etc.)


Parallel port:
~~~~~~~~~~~~~~
Dataline 0 in the parallel port is used as output when in 'Parallel' mode.

Dataline 1 is used as input for the eye movement detector hardware. HIGH state
means 'eye movement detected'. (Sampled once per second.)

Dataline 2 is used as 'Reality test button' input. LOW state in this line
causes a cue to occur IMMEDIATELY.


Hardware:
~~~~~~~~~
REM-detection:
I've built an eye movement detector hardware. And it works too.
Email me for more info about it.

LED inducer:
I've built a little circuit which consists of:
2 resistors, 1 pot(preset), 1 transistor, 1 LED (red, 5mm diam.)

It's made up so that when dataline 0 goes HIGH, the transistor saturates and
the LED lights up.

I have NOT included any schematics of this circuit.

If you want to, you could build one yourself.

BUT I'M NOT IN ANY WAYS RESPONSIBLE IF YOU END UP WITH FRIED AMIGA!!!!
READ THE CHAPTER '1.LEGAL THINGS' !!!

Misc info:
~~~~~~~~~~
I've built a headset too, it's made from an old sunglasses :) I tried using
swim-goggles too but they cause 'pressure' to my eyes, so they are somehow
uncomfortable to use. And when I'm sleeping with the headset on, a wire goes
from headset into the computer (into the rem-detector hardware, actually).

I'm currently working on more comfortable headset/goggles/mask/whatever.

    __/\__                                                          __/\__
    \ oø /   Comments, suggestions and bug reports *are* welcome.   \ oø /
    / \/ \            email: ta3153@bessel.tutech.fi                / \/ \
    ¯¯\/¯¯                                                          ¯¯\/¯¯


7. History
==========

1.10 - Added few more functions, including: REM detection, support for
       'Reality test' button, saving of the eye movement data.

1.09 - (not released)
       Squashed that address error bug! It truly was my mistake.
       I used the imsg->iaddress field in a way that it shouldn't be used.
       Stupid me, it even says in RKRM's when NOT to rely on iaddress
       contents...

1.08 - First public release, problems with intuimessage handling(?!)
