AVR-EVTD(8)

NAME
avr-evtd - Linkstation AVR Event daemon

SYNOPSIS
avr-evtd [ -d /dev/tty ] [i | c | v]

DESCRIPTION
avr-evtd is a simple and small user space interface to the Linkstation AVR micro-controller. It doesn't have a lot of special features, but it's main task is to provide 'keep-alive' messages to the Linkstation's on-board AVR device. This device controls/monitors the fan, various LEDs, timed power up and two buttons. This daemon provides the necessary initialization to the device and also stimulates the LEDs depending on various fault conditions. It also monitors a power button (located at the front) and a reset button (located at the rear). avr-evtd searches for a configuration file located within /etc/melco at start-up time. If this file does not exist, then avr-evtd reverts to reading the file located at /etc/default/avr-evtd. Additionally, avr-evtd may, if requested, periodically check the root (Under user control and could be /dev/hda1) partition and the user working partition (For example, /dev/hda3) to ensure they are mounted. Also, if requested, it will determine if sufficient space remains and if not then the AVR is requested to illuminate the DISK LED. This periodic checking also takes place on the configuration files. If they are deemed to have been updated, then the daemon will respond accordingly.

Any failures are normally routed through the log files. With timed shutdown/power up, a warning will be broadcast to all users (console message) when within 5 or less minutes of power off. Also, fan failure alerts will be broadcast in this fashion. Failure to determine mounted working partition will result in the DIAG LED flashing three times, repeatedly.

A new feature of this daemon is the ability to code events for single or groups of days. This allows the user to add any number of power-on/off events as required. This also has the added benefit of being able to shut down the device for longer periods. The internal AVR timer has a 12-bit resolution timer which can power up the Linkstation from a maximum of a sixty eight hour sleep: from time of invocation. The AVR is updated again at time of power down/shutdown to re-validate the timer, in case of time updates (either by user or NTP). This will also preserve the 68 hour sleep resolution.

OPTIONS

-d  /dev/tty Specifies the UART device used to communicate with the AVR. This is normally taken care of by the scripts but can be specified in the configuration file. See below for details.

-c  Don't fork, i.e. run in the foreground (debug use only).

-i  Returns the port memory location for the device specified by -d /dev/tty

-v  Display daemon version.

THE CONFIGURATION FILE
The avr-evtd configuration file is the fallback file in the event that the stock melco files do not exist. The file is read at initial start-up in order to determine if timed shutdown is required and if the disk usage is to be monitored. The file should be always located within the /etc/default directory and a sample file is provided. The file format is similar to other Unix configuration files - comments begin with a # character and extend to the end of the line; blank lines are ignored. Configuration commands consist of an initial keyword followed by an argument. Arguments may be strings or times written in HH:MM (UTC) format. Optional arguments are delimited by [ ] in the following descriptions, while alternatives are separated by |.

DEBUG
    [ON | OFF] This is reserved for admin only. Allows logging of certain information. A log file will be maintained in /etc/avr-evtd logging events and when run from command line, the process will log data to the console.

TIMER
    [YES | NO] The timer command informs the daemon if it has to provide time controlled shutdown and power up. If TIMER is set to NO then this function is not available and the commands SHUTDOWN and POWERON are ignored and have no effect. The same applies if any day events are specified and the TIMER is set to NO then these events will also be ignored.

DEVICE
    [/dev/tty] This informs the AVR which UART to use when communicating with the AVR. The communication path between the micro-controller and this daemon is via a serial link. This keyword is not for general use and is provided to allow advanced users the option of overriding automatic configuration. This would normally be set to /dev/ttyS1 but on some systems it is /dev/ttyS0. The selection of the correct port is performed by the daemon start script and is not normally required to be altered.

[<day>|<day>-<day>]
    [ON=HH:MM | ON= | OFF=HH:MM | OFF=] This defines events for either a single day or group of days, '-' separator. Any number of ON and OFF events can be specified and can be extended over additional lines. <day> can be any number of days of the week specified as either SUN, MON, TUE, WED, THR, FRI, and SAT. For example:
    MON-WED=ON=09:00,OFF=23:00
    THR=ON=09:00
    FRI=OFF=01:00
    In this example, the first power on event is Monday at 09:00. At 23:00 the Linkstation will power down. This is repeated for Tuesday and Wednesday. On Thursday, the Linkstation will power on at 09:00 and will power off on Friday at 01:00. The unit will then remain off for Saturday and Sunday and not power up again till 09:00 on Monday. The unit is capable of sleeping for no more than 68 hours (due to the resolution of the internal timer). Again, this time MUST be specified in UTC format and follow HH:MM.

    Five minutes before power off is required, a message is broadcast to all console users. At shutdown, an event message is sent to the event script. See below for more details.

SHUTDOWN
    [HH:MM] This specifies the time that the Linkstation will be powered down. This time MUST be specified in UTC and must follow the format HH:MM. If the user alters this configuration file whilst the daemon is running, then the change will be seen and the new settings will be implemented. If the new time entered is passed the current time, then the shutdown time will be for the following day. If single or multiple day events are specified, then this becomes the default power down time for any undefined days.

POWERON
    [HH:MM] This specifies the time that the Linkstation will be automatically powered up; as long as now unexpected power outage occurs. Again, if this time is less than the SHUTDOWN time then it is for the following day. Both the TIMER set to ON and the SHUTDOWN and the POWERON times are valid will timed shutdown/power up be enabled. This will be reported in the message log along with any errors in the configuration file.
    If single or multiple day events are specified, then this becomes the default power on time for any undefined days.

DISKCHECK
    [OFF | 0..100] If this is set to OFF or 0 (zero) then disk usage/monitoring is disabled. Set to a value between 0 and 100% to monitor disk usage. If disk usage is above this specified value, then the DISK LED will be illuminated. At the same time, a disk full event message will be sent to the event script.

ROOT
    [hda1..9] No default. This allows the root partition to be defined by the user. No syntax checking is performed on this entry or validation of the partition ID.

WORK
    [hda1..9] No default. This allows the working partition to be defined by the user. Again, no syntax checking is performed on this entry or validation of the partition ID.

REFRESH
    [1..300] This defaults to 40. This provides control over the rate (in seconds) that the daemon checks the system for changes and refreshes the AVR. Any number between 1 and 300 can be entered. Anything less than the default will result in higher impact on the system: more CPU usage. Higher times will result with slower response to configuration file changes but this may not be an issue with most users.

HOLD
    [1..9] This defaults to 3. This provides control over the time (in seconds) that the user needs to hold either the reset of the power button in for a reset event (reset button) or power off event (power button).

DISKNAG
    [ON | OFF] Default if off. This provides the user control over the disk full event. The default is that once detected, just a single event is triggered. If required, setting this to on will generate repeated events, at the frequency of REFRESH until the disk is no longer deemed full.

FANSTOP
    [OFF | 0..60] Default is 30 seconds. This is the time, from report of fan failure in which the daemon will generate a fan failure event call to the event script. This allows the user to act accordingly. At present, the script is setup to power down. This can be changed to an e-mail event prior to shutdown if required. Otherwise, if a user has decided to remove the fan then this can be set to OFF to prevent shutdown from occuring. It must be stressed that alternative cooling must be sourced if this option is selected.

BUTTON OPERATION
All events, whether mechanical button operation, or software reset/shutdown actions are routed through an event script located at /etc/avr-evtd/EventSCript

POWER
    On press, a button event message is sent. On release, another event message is sent. If the button is held in for more than HOLD seconds, then a shutdown event request is sent. If the button is pressed twice within a period of one second, then a reset request event is sent.
    If the power button is pressed during the five minute timed shutdown warning, then the shutdown time is increased by five minutes. Multiple presses will keep increasing the time by five minutes (to a maximum pause of fifty minutes). This provides the user with the ability to carry on working before timed shutdown is finally activated; careful here as repeated presses maybe seen as a reboot request.

RESET
    On press, a button event message is sent. On release, another event message is sent. If the button is held in for more than twenty seconds, then a EM-Mode event request is sent. If the button is pressed twice within a period of one second, then a special event is sent which in the default state will launch the telnet daemon.

MESSAGE EVENTS
The event system has been modified such that 99% of the daemon event system is pushed through the event script. A third parameter is supplied by the daemon out to the script detailing information relevant to the generated message. For example, for a disk full message, the third parameter would detail the percentage disk space used (worst of the two monitored partitions) and when this is cleared, then this parameter would be cleared to zero.

0   User has requested (by double press of reset button) to, with the first press, launch the telnet daemon, or other client as specified in the EventScript. The script also establishes a static IP to an alias Ethernet device :EM at 192.168.11.150. If this IP is already in-use, then it will not be created. If the Ethernet is not running, then an alternative Ethernet configuration file is loaded providing a static IP at 192.168.11.150. and also a DHCP provided IP. On the THIRD double press, then a known set of group and user password files are copied to /etc. Prior to the transfer, the relevant original files are copied to .em. A file, recovery.tar, is extracted and the LEDs are flashed to indicate this new mode. A user can now gain root access using the password emergency and gain access via the telnet port 1234 to their box.

1   AVR micro-controller has requested a reset.

2   Shutdown request from the shutdown timer event.

3   Power button has been released event.

4   Power button has been pressed event.

5   Reset button (rear of unit) has been released.

6   Reset button has been pressed.

7   User has requested (by holding power button for more than HOLD seconds) to shutdown the unit.

8   User has requested (by double press of the power button) to reset the unit.

9   Disk usage greater than DISKCHECK. Parameter 3 set to percentage used or zero.

F   Fan has been stationary for FANSTOP seconds. Parameter 3 is set to 4 when cleared.

E   EM-Mode has been selected. The EM-Mode sequence is written to the desired flash location and the system is issued a reboot request. EM-Mode is an emergency boot mode that for the Linkstation it boots from an image in flash and rebuilds files on the disk. This should only be used by those who know what will happen to their disks when this Mode is selected

S   The system will shutdown in less than five minutes warning. Parameter 3 indicates shutdown delay on power press.

D   Error message handler. Parameter 3 indicates error number.

ERROR CODES
The following error messages maybe displayed in the log files during operation:

1   No stock or avr-evtd configuration files were located.

2   Power off time greater than that supported by the AVR. As this is calculated at the time the timer is established, this fault may clear at shutdown as timers are re-validated.

3   Timer declaration error in /etc/default/avr-evtd configuration file

4   Error in stock configuration file

FILES
    /etc/default/avr-evtd
    /etc/avr-evtd/EventScript
    /etc/avr-evtd/emergency-eth0
    /etc/default/events.log
    /etc/avr-evtd/recovery.tar

AUTHORS
Bob Perry <lb-source@users.sourceforge.net> (2006), with some modifications by Rogério Brito <rbrito@users.sourceforge.net> (2008, 2009).

COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.