TINI Rapture README

What's New

3rd May 2001 - 0.9c is now available. Some bug fixes and better formatting of the source code.

25th April 2001 - I've uploaded the source code to TINI Rapture. It's at 0.9b and officially a "beta". I'm also welcoming any submissions (source code!) for new functions or parameters. I'll happily incorporate any new features into the source code base and release as appropriate.

Introduction

Installation

You can find tinirapt at the TINIRapt sourceforge project page. Please provide feedback there or direct to me (amkimian@mac.com). Thanks!

Associated with the application is a configuration file - rapt.cfg. It's best to edit this file on your PC and upload it to the TINI board using FTP. You can place this file anywhere but it's easier if you put it into the /etc folder.

Running

If you miss out the configuration file parameter Rapture will look in the root folder for a file called "rapt.cfg". If you haven't placed it there put the real file as the first parameter. E.g.
java rapt.tini -f rapt.cfg

You also may wish to run Rapture in the background. Append the ampersand symbol ("&") to your command to make this happen:
java rapt.tini &

You can also get Rapt to print out more debugging information by using the "-d" option:

java rapt.tini -d -f rapt.cfg

Configuration

Rapture is controlled through its configuration file. The file is a text file and lines beginning with the pound symbol ('#') and blank lines are ignored.

Rapture can react to four different types of "event". These are 

time based events (e.g. at 5 minutes past every hour, log the temperature) device arrival (e.g. when a one-wire device with address "x" arrives, unlock the door) device departure (e.g. if the temperature device is disconnected, record this fact in a log) and interrupts.

These events have different types of configuration but they normally have two sections - the definition of the event and the command to run when the event occurs.

Time Based Events

Time based configurations are similar to cron entries and have the following format:

[minute] [hour] [day of month] [month] [day of week] [command]
The first five parameters have a similar format:

If they are "*" then this implies every value is valid (e.g. *)
If they are a single number then just that value is valid (e.g. 5)
Numbers can be separated by commas to define a list (e.g. 05,10)
Two numbers separated by a dash define a range (e.g. 1-5 is equivalent
to 1,2,3,4,5)
A slash followed by a number defines a step through the previous
range. (e.g. 1-10/2 is equivalent to 1,3,5,7,9)

Every minute, Rapture wakes up and compares the current date and time with each time based entry. If there is a match the command is executed.

Some examples will illustrate this:

# Example 1
* * * * * @LOG 1 succeeded
# Example 2
5 * * * * @LOG 2 succeeded
# Example 3
* 5 * * * @LOG 3 succeeded
# Example 4
0 9-17 * * * @LOG 4 succeeded
# Example 5
*/10 * * * * @LOG 5 succeeded

Example 1 will be run every minute (because all fields match)
Example 2 will be run at 5 minutes past every hour (because that's the
only time minute=5 will match)
Example 3 will be run at 5 o'clock every morning
Example 4 will be run every hour from 9 to 5pm (on the hour)
Example 5 will be run every ten minutes (at 0,10,20,30,40,50 past the
hour)

Mini time based Events

[new!]

The .minitimer directive starts a section of mini-timer events. These are like timer events except that they are evaluated every second (instead of minutes). Because of this small time interval, you can simply put in the "second" configuration for each event. E.g.

.minitimer
#0-59/1 @LCD L: $ADC
0-59/2 @DAC 128
0-59/2 @LED FLIP RED
1-58/2 @DAC 255
1-58/2 @LED FLIP GREEN


With these examples, the first entry is a comment. 

The second runs every other second and puts 128 on the Digital to Analogue conversion port (in the TINITutor case - turns on the lamp to half brightness)

The third runs every other second as well and flips the state of the red LEDs on the TINITutor board.

Activity Based Events

Running Commands

Parameters to commands

 

Parameter	Description
$T	Temperature read from device
$D	Date (follow with characters to define output: y - year m - month d - day H - hour M - minute S - second other characters are echoed.
$ADC	The voltage (from 0-255) of an attached ADC.
$A	Address of one-wire device
$V	Device type
$UP	Uptime

Some macros only have meaning on device arrival or departure.

Targetting commands to devices

Because some of the commands require access to a particular 1-wire device you may wish to instruct Rapture to use a particular device instead of the default. (The default is either the first matching device or the device that signalled an arrival or departure event). You target a particular device by prefixing the command with a device description. This description is enclosed in square brackets and contains two fields - the one-wire address and the family type. Either can be asterisk ("*") which matches all devices of that class (or address).

For example, a line like this:

* * * * * [AD1234354656,*] @LOG $T

Would log the temperature read from the 1-wire component with address AD1234354656 (if it supported that function).

Example Configuration file