lease - get a lease on the node's communications link

lease
lease -establish [<time>]       [nodeHost]
lease -renew <leaseID> [<time>] [nodeHost]
lease -terminate <leaseID>      [nodeHost]

The lease utility establishes and manages comms leases on the node's communications link.  The lease utility asserts that the cpu not sleep and that wireless network connections be maintained for a specified duration (specified in seconds).  Any number of people/programs/etc can separately take out a lease.  As long as any lease is still valid, the communications link will stay active and the CPU will remain awake.  When the time that you specified for your lease has elapsed (assuming you haven't renewed the lease), the lease expires.  If it was the last lease to be active, the communications link will then go down. (The cpuAwake utility keeps the cpu from sleeping, but does not keep wireless network connections).

There are three operations that can be performed by lease: "-establish", "-renew", and "-terminate".  The default operation (if you don't specify any of the above) is "-establish", which establishes a new lease.  This returns a new leaseID, which is simply an integer that you can use to reference this lease for further operations. The following example will renew lease 6 on localhost for 300 seconds (5 minutes):

lease -renew 6 300

The following example terminates the lease (i.e. makes it immediately invalid):

lease -terminate 6

The default options for lease are:

-establish
time = 900 (seconds, which is 15 minutes)
nodeHost = localhost

Thus, simply issuing the command "lease" is equivalent to:

lease -establish 600 localhost

The command-line parser is very forgiving -- parameters can be in almost any order.  The only constraint is that for "-renew", <leaseID> must occur before <time>.  Anything that begins with "//" or an alphabetic character is assumed to be the nodeHost.
 
When a lease is established on a MOOS subnode, another lease is automatically established on the surface node as well, to ensure that the wireless link stays connected for at least as long as the original lease is in effect.

Be aware that if you hold the comms line open with a long lease, not only will you cost the system a lot of power, but data will not be downloaded to the portal in the interim.  That's because the trigger for downloading the data is bringing up the comms link.  If you have a lease, the link doesn't go down during that time, and thus doesn't need to be brought back up. This is not a bug in lease, but is inherent in the design of the SIAM software.

When attempting to establish a lease on a node which is not currently connected, lease will wait until a connection is detected then proceed with lease establishment. This operation does not currently function reliably.

ENVIRONMENT

The following environment variables must be set:

• JAVA - name of the JVM. E.g. on a Sidearm, JAVA should be set to j9. On a workstation with Sun's Java installed, JAVA could be set to java.
• SIAM_HOME - top of the SIAM directory tree
• SIAM_CLASSPATH - on a Sidearm, SIAM_CLASSPATH should be set to $JAVA_HOME/lib/jclMax/classes.zip:$JAVA_HOME/lib/prsnlmot.jar:$JAVA_HOME/lib/RXTXcomm.jar:$SIAM_HOME/classes.  On X86 system, SIAM_CLASSPATH should be set to $SIAM_HOME/classes

SEE ALSO

cpuAwake.