chiark ledctrl bot

Privacy

It can watch preferentially for individual users, but this facility should not be used without the prior consent of the target. ledctrl will notify the target that they are being watched.

If you want to know who is being told information about IRC activity, say

/msg ledctrl who

-ledctrl- monitoring #starcraft for ijackson:sc
-ledctrl- monitoring #test for ijackson:#test
-ledctrl- sending ijackson:sc to ijackson, davenant.relativity.greenend.org.uk:1447
-ledctrl- sending ijackson:#test to ijackson, davenant.relativity.greenend.org.uk:1447

Usage

1. Make sure that your LED server is operating properly, and that you can use remoteleds on chiark to manipulate the relevant LEDs.
2. If you're using a nonzero password (which is recommended, as otherwise any other chiark user could interfere with your LEDs), copy the .led-client-pass that you're using to ~/.userv/irc-ledcontrol-passwords (taking care to make sure it's not world-readable).
3. Write the configuration file saying which channels to monitor and where to send the answers. Put it in ~/.userv/irc-ledcontrol-config. See below for the file format.
4. Join #ledctrl. This is where the debug and diagnostic output goes. You should also look here if it seems not to be working at some later point. When you think everything is right, say /msg ledctrl reload username where username is your own username. If all is well it should just say <ledctrl> reloaded username and shortly afterwards your LEDs should be set.
5. If you still can't get it to work, say /msg ledctrl debug username and see if you can make any sense of the output. NB that this produces lots of output in the channel, which will disrupt other people's use of it, and cause ledctrl to become lagged, so please don't leave the debug enabled. It will turn itself off after a while anyway.
6. If you decide you don't want to use ledctrl any more, delete your config file and say /msg ledctrl reload username, which will cause ledctrl to forget about your configuration (and any stored passwords).

Configuration model

The file may contain definitions of two kinds of objects:

Monitors

These are specifications of channels to monitor, activity timeouts, and nicks to ignore, etc. Each monitor at any particular time has a particular result state which depends only on its configuration and activity on the channel.

Monitors have names of the form username:suffix where suffix is chosen by the user who defines the monitor.

devicesets

These are LED groups; each deviceset must be tied to exactly one monitor; the configuration specifies a mapping from monitor result states to LED values. Devicesets are not explicitly named, but when ledctrl needs to refer to them it may do so by the username who defined them and the line number in their configuration, or sometimes by the destination host(s) and port(s) in the specified LED group.

• ijackson:#chiark
• ijackson:#starcraft

If you define a deviceset which refers to a nonexistent monitor, it will be silently ignored.

Configuration syntax

Configuration directives

monitor monname #chan [#chan ...]

Defines a monitor named monname which monitors the specified channel(s). monname must start with username: where username is the username whose file the directive occurs in.

nick ignore [glob-pattern ...]

Defines a list of nick patterns to completely ignore. No activity on the part of nicks matching any of the patterns will have any effect.

Affects all monitors defined, until the next nick ignore.

nick nopresence [glob-pattern ...]

Defines a list of nick patterns to ignore when deciding whether anyone is present. If the affected nicks speak in channel they will still count.

Affects all monitors defined, until the next nick nopresence.

nick prefer [glob-pattern ...]

Defines a list of nick patterns to be extra interested in, when they talk on channel. See the preftalk and preftalknow monitor state conditions in the leds directive, below.

Affects all monitors defined, until the next nick nopresence.

Important: Use of this directive can amount to fairly intrusive monitoring of the activity of the affected nicks. Ask permission from the target before using this directive on a real person. ledctrl will inform the target of the surveillance.

times talk-now-time talk-time

Specifies the times, in seconds, for which someone speaking in channel will satisfy the talknow and talk conditions, respectively. talk-now-time should be no more than talk-time.

Affects all monitors defined, until the next times. The initial values are 120 and 450.

leds led-group monname state=value ...

Defines an LED group, driven by monname. Each time the monitor's state changes, the list of states will be searched, and the first which is true for the monitor's new state will take effect. If none of the states apply then the LEDs are left unchanged.

The state conditions are:

talk

Someone has spoken on channel since talk-time ago.

talknow

Someone has spoken on channel since talk-now-time ago.

preftalk

Someone matching nick prefer has spoken on channel since talk-time ago.

preftalknow

Someone matching nick prefer has spoken on channel since talk-now-time ago.

present

Someone (not matching nick nopresence) is present on channel. ledctrl itself does not count.

default

Always true. Put this at the end of the state list.

led-group and each value should be as specified in the LED protocol document. The LED group will be accessed in an exclusive manner and should not be accessed by any other LED clients.

userv

Actually, the configuration is all done with userv. The system supplies default implementations of the two services

irc-ledcontrol-config
irc-ledcontrol-passwords

which simply spit out the relevant files.

The irc-ledcontrol-config service must succeed; if you do not want ledctrl configuration it should exit zero without printing any output at all.

If irc-ledcontrol-config produces any output (even just whitespace or comments) then irc-ledcontrol-passwords must succeed, and produce a standard format LED password file. (See the LED specification documents.)