GEMPLUG(19)

NAME
gemplug - control silver shield PM outlets

SYNOPSIS

gemplug [-opts] [<outlet-name>]
    lists available outlets along with their state

gemplug [-opts] <outlet-name> off|0|on|1
    Switch Gembird power outlets

gemplug [-opts] <outlet-name> off|0|on|1 at|after|until|for <time-spec> [at|after|until|for [...]]
    Switch Gembird outlets at specified times

DESCRIPTION

Silver Shield PM power switches are USB controlled power outlets. They are referred to here as "Gembirds".

gemplug allows you to control your Gembirds in various ways, e.g., by accessing them by name, by scheduling and managing timed jobs, by allowing to couple switch actions with other commands (including other timed switch actions), and by handling multiple devices in a transparent manner. It delegates the task of actually accessing the hardware to sispmctl(1). At the time of this writing, at least version 2.8 of sispmctl must be available before you can run gemplug successfully.

Timed jobs are handed over to the at command and rounded to the nearest minute.

For a quick start, scroll down to the section named "QUICK START".

OPTIONS
Outlet names may always be abbreviated to the right (need to match only the beginning of a name) as long as the resulting substring is still unique.

  Job related

gemplug's jobs are passed to the 'at' command for timed execution. You may examine and change the active jobs with the following commands.

-j [<outlet-name> [...]]
    list pending jobs. You may add any number of outlet names for which pending jobs are to be listed. Without any name, all pending jobs are displayed.

-k <outlet-name> [...]
    kill pending jobs. You need to name at least one outlet. To kill all pending jobs for all outlets, use ALL (in upper case) as the outlet name.

-p <jobnum> [<jobnum> [...]]
    purge individual pending jobs by job number. The job number is output in the first column (before the colon) when you list jobs by calling gemplug with the -j option.

-a
    tells gemplug to add whatever actions are given on the rest of the command line to already pending jobs (if any). If there are any jobs already scheduled for an outlet, you must give either -r or -a when you enter new timed jobs for the same outlet.

-r
    tells gemplug to remove already pending jobs (if any) for the current action's outlet before executing the rest of the command line. If there are any jobs already scheduled for an outlet, you must give either -r or -a when you enter new timed jobs for the same outlet. When an outlet is named, but no action, this is roughly the same as -k <outlet> except that the state of the outlet is printed too.

  Listing options and output control
-t
    test mode: show what actions would have been taken or scheduled without actually doing any scheduling. Pending jobs are not removed even if you also specify -r. This mode may come in handy in order to test the effect of date/time formats and other scheduling details.

-l [<outlet-name> [...]]
    list the states (on/off) of the outlets named on the rest of the command line. Without any name, lists all. Using -l without any or with exactly one argument is the same as calling gemplug without the -l.

-d [<outlet-name> [...]]
    Dumps all configuration information gemplug has accumulated for the named outlets in formatted form. If no outlet is named, information about all outlets is written out.

-c
    Never use colors in output. Colors are otherwise used to display an outlet's state and to emphasize error messages when stdout is connected to a terminal with a known $TERM.

-n
    Replaces the "(on)" and "(off)" texts used to report outlet states by either a "1" or a "0" (without the quotes). For use (possibly in conjunction with -q) in scripts.

-q
    Quiet operation. Removes all text from outlet state queries except for the raw results ("(off)", "(on)", "0", "1") and error messages.

-g <outlet-name>
    Get outlet state. Report nothing, but set the program's exit code to 0 (true) if the outlet is powered on, else to 1 (false).

-f
    Force reconfiguration. Redisplays some non-fatal errors and warnings which usually are printed only once. Normally, they are not displayed again until gemplug's internal configuration data is rebuilt because of some hardware or configuration file change.

-v
    Do verbose reporting. This is mainly a debugging option for the configuration file parser.

-v
    Do more verbose reporting. Adds some informational messages.

-v
    Add even more verbose reporting. This is mainly a debugging option for the configuration file parser.

-C
    Executes a chmod a+rw command on all Gembird device nodes. You most probably will need root privileges (e.g, from sudo) to execute this successfully. Also note that the configuration files in your home directory might be out of reach if $HOME is changed to root's home. This is not a problem with plain sudo.

-T
    Writes out templates for not yet configured devices to stdout, giving the new devices and their outlets standard names while taking some care to avoid name clashes with already existing names. Use this to inspect the new lines before adding them with the -TW command below.

-TW
    Adds templates for not yet configured devices to your configuration file. If there's none, a new gemplugrc will be created including an initial comment describing its syntax. If there's already a configuration file on your system, it must be writable by you. If it resides in /etc/gemplug, chances are good that only root can execute this command successfully. Since we're appending at the end of the current file, no backup copy is done.

  Misc options
-x
    Script debug. It will output an enormous amount of boring lines which are of no interest to the end user. Use this if asked to do so because of a bug report.

-L, --license
    Display license information.

--version
    Display version info. Don't forget to include the output of this command if you contact the maintainer.

-h, --help
    Display help screen.

USAGE NOTES

Except for some special options, a gemplug command line always looks like one of the following four lines:

  gemplug

  gemplug <outlet-name>
Query all outlets (first line) or the named one (second line).

  gemplug device off|0|on|1
Switch an outlet.

  gemplug device off|on <timed action> ...
Switch an outlet at specified times. There are four keywords available to introduce timed actions: at, after, until and for. Each one of them must be followed by one argument describing the desired fixed time or a time interval. Note that this always must be exactly one argument. So either don't include white space in your time specification, or enclose it within single or double quotes to prevent the shell from splitting it up in to several smaller pieces.

There are two basic forms of a time specification: You may either wish to specify a time interval with after or for, or you may specify a fixed time of some day using at and until.

interval specification
    A time interval as required by after and for consists of days, hours and minutes in descending order, with at least one element marked as being d[ay], h[our], m[inute] or a ':' (separator between hours and minutes). Elements may be omitted as long as their order is preserved. Some examples of valid intervals:

        "2 days 3 hours 5 minutes" "2d 03h 5 min"
        "2d 3:05" 2d3h05 "2 3:05"
        3h05 "3:05" "3h 5 minutes" 2h5min
        "2days 3hours" 3d5h
        "2days"
        "5 min" 5m :05
        "2days 5min" "2days :05" 2d0:05

    As can be seen, nearly all combinations which make at least some sense are accepted.

    Time intervals are cumulative: They get added to the last time encountered before on the same command line, be it the end of an interval or a fixed time. Failing that (if it is the first time specification on the line), the interval is added to the current date and time to yield the fixed time the event is to be scheduled at.

fixed time-of-day specification
    The keywords at and until expect fixed time-of-day specifications. Any format which is acceptable by the GNU 'date -d' command may be used. Unfortunately, this doesn't include the ISO date format. Depending on the part of the world you live in, you might succeed or not with the kind of specification you're used to. A safe bet is to name the time of day first in hh:mm format, then (if needed) to add a space followed by the calendar date in a fairly free format, and finally to enclose the whole thing within single or double quotes, as in:

    "10:45"
    "10:45 Jun 3"
    "10:45 2008-07-24"
    "10:45 Friday"

    There's one exception to the GNU date -d rule: if you specify a time of day, but no date, the date -d command always will return today's date and time even if that time lies in the past. In this case, gemplug will assume there's no time machine available which would allow it to modify past events and schedule instead for the same time, but tomorrow.

The available syntax variations which allow you to schedule an action are as follows:

at <time-spec>
    Schedules the event described in the command line's first two non-option arguments to execute at the specified time. For the format of <time-spec>, see the paragraph "fixed time-of-day specification" above.

until <time-spec>
    Schedules the opposite action to the event described in the command line's first two non-option arguments to execute at the specified time. For the format of <time-spec>, see the paragraph "fixed time-of-day specification" above. If there's no preceding non-opposite action, gemplug will assume it is to be taken now and execute it.

after <interval-spec>
    Schedules the event described in the command line's first two non-option arguments to execute after the specified time interval. For the format of <interval-spec>, see the paragraph "interval specification" above.

for <interval-spec>
    Schedules the opposite action to the event described in the command line's first two non-option arguments to execute after the specified time interval. For the format of <interval-spec>, see the paragraph "interval specifications" above. If there's no preceding non-opposite action, gemplug will assume it is to be taken now and execute it.

While this may sound complex, it really isn't. Some examples:

    gemplug printer on for 30min
    gemplug printer off at '19:00 Friday' for 2days
    gemplug Laptop-loader on after 2h for 12h

You can tell from reading the above commands what they'll do.

Just remember that the first two non-option command line arguments describe first the outlet and then the action to be taken on it. After those two follow the specifications when to do that using any combination of at, after, until, and for. Time or interval specifications must be enclosed in quotes if there are spaces inside. That's about all.

Timed actions will only be scheduled as a whole if the entire command line proves to be correct. Else a message will be printed stating that none of the preceding parts has been scheduled.

Note that you can test any combination you like with the -t (test) option. You'll get a response stating what would have been executed without actually scheduling anything. This applies to all timed actions, including the pending ones if -r is specified too.

QUICK START

If you're going to run gemplug for the first time, and if you already have installed sispmctl, and there are one or more Gembird devices connected, just start gemplug without any arguments (you may need to use sudo if you get permission errors). gemplug will suggest to create a template file for you. Follow the advice by calling gemplug with -TW. It will create a new template and write it to the first position in its search path which is writable by you.

From now on, you can execute all the commands listed here.

gemplug will also suggest you to edit that file while displaying its path. You may want to do that now or later in order to give your devices and outlets more meaningful names and to remove either the "pos =" or "serial =" statements (see "SELECTING FROM MULTIPLE DEVIES" below). If you did use sudo, chown(1) that file to be owned by you before editing.

To solve permission problems, have a glance at the section "HELPER FILES" below.

HELPER FILES

  udev rule
While the -C option has been included to allow you to make your Gembird devices world-writable without the need to know their exact /dev/ path (and there may be distribution-dependent ways to achieve the same, e.g. an USB group), the preferred way is to use an udev rule for that. A sample file, 74-sispmctl.rules, is included in the distribution, which accomplishes this task if copied over to the /etc/udev/rules.d directory.

In its default form, it makes all Gembird devices world writable when they are encountered during the boot process or when added later.

If you prefer to make your Gembirds only available to a subset of users, an alternative rule is provided. De-comment it, en-comment the original rule and follow the advice in the file's comment to create a new group and to add the users in question to it.

  Bash completion
The file gemplug-completion.sh, when put into your /etc/bash_completion.d directory, allows bash to automagically complete outlet names. Two usage examples: To have all outlet names listed, type gemplug <TAB> <TAB>. Typing gemplug t<TAB> will complete the unambigous part of all outlet names which start in 'T' or 't'. If more than one name matches, a second <TAB> will display all of them.

SELECTING FROM MULIPLE DEVICES

gemplug was developed in the frist place since there was no way to access different Gembirds connected the same computer in a reliable way.

As of sispmctl 2.7 and up, you now have 2 choices: USB topological position or serial number. Each one has its advantages and drawbacks.

  USB position
If you use the "pos =" statement in your configuration file, devices are identified by the way their signal passes USB. You can exchange Gembird devices as long as their connections (this includes all outlet positions on any hubs and cables up to and including the USB plug on your system) are left unchanged,

The advantage is that you can easily exchange the actual device (not all Gembirds here prove to be totally stable, expecially if there is a lot of other traffic on the same hub not belonging to them). The drawback is that once you change some physical connection, you'll get two informational messages - the first one to state that some Gembird has disappeared and the second that there's a new device discovered for which no configuration is available. As both inidcate the USB position, you can to insert manually the new position by replacing the old one in the configuration file. If you change your cabling often, this may become tedious and you should start to think about using serial numbers instead.

  Serial numbers
Starting with sispmctl 2.7, the serial number of Gembird devices is reported back. If you identify your Gembirds by serial number, the same physical device will keep its name wherever it is plugged on to the USB. You cannot exchange Gembirds, but you can change your cabling as you like. NOTE: As of the time of this writing, this interface doesn't always yield stable serial numbers and is therefore not yet recommended.

CONFIGURATION FILE SYNTAX
The configuration file's syntax will be written as an initial comment to the configuration file when a template is created from scratch (i.e., in the absence of a configuration file and gemplug -TW) together with a syntactically correct template file ready to edit.

The syntax rules are repeated here for reference.

  Continuation lines
A backslash immediately before end of line causes the next line to be appended (made part of the current line). The sequence \n\ causes a newline to be inserted before the next line is appended. This is only really useful with pre-on, pre-off, post-on and post-off lines.

  Comments
'#' and ':' at the start of a word (i.e. after white space or a newline) start a comment. All text up to the end of the line will be ignored.

  Case
All matching is done without regard to case (case-insensitive).

  Names (outlet and Gembird device identifiers)
Names can be made of any non-whitespace characters. They are allowed to include anything but the following:
    - They cannot start with a comment character ('#', ';')
    - White space cannot be embedded as it is a delimiter,
    - In device (=section) names '[' and ']' cannot be used (delimiters)

  Indenting
Indenting is not mandatory; leading white space is always ignored. Use it as you like, In all places where white space is allowed/required, any amount can be used.

  Key elements
All the descriptions of the key elements below are preceded by an example line demonstrating their use.

[ Gebird_name ]
    Starts a device section, giving the device and the section the name within the brackets. Any white space between brackets and device name is optional.

pos = 3.1
    Names the topological position of the device on the USB as reported by gemplug -d <one-of-its-outlets>.

serial = 01:02:03:04:05
    Names the Gembird's serial number as reported by gemplug -d <one-of-its-outlets> or sispmctl -S.

1 = Outlet-name [Alias ...]
    Number, '=', Name Aliases ... names the individual plug outlets. It can only be used if at least one of pos or serial are given before and in the same section. If both are given, they are required to match the same device. Outlet numbers (the numbers in the first column) count from number 1 upwards per device.

pre-on = <your_commands>, also post-on, pre-off, post-off
    The part after the equals sign is fed to $SHELL -c (or, if empty, /bin/sh -c) before resp. after switching on resp. off. This allows you to build timed sequences for powering up or shutdown. If you include gemplug commands there, beware of recursive loops before they eat up all your resources. Also always include the -L (no locking) option if you place a gemplug command there.

FILES

gemplugrc
    The user-editable configuration file.

compiled_rc
    gemplug's internal representation of the user's and the hardware configuration. Automatically updated when gemplugrc is found to be newer or when hardware configuration changes.

last_sispmctl_S
    The hardware configuration gemplug's complied_rc was built for is stored here. Every time the hardware configuration changes, the internal representation will be rebuilt and this file gets updated.

gemplug looks for the above files in the following places and in this order (first searched first, first match stops):

    $HOME/.config/gemplug/
    $HOME/.gemplug/
    /etc/gemplug/

gemplug needs a directory writable by the user for intermediate configuration storage. It fist tries the directory where it has found its gemplugrc configuration file. If the system administer decides to put gemplugrc into /etc/gemplug/, the user most probably will have no write access there, and the first parent-writable place along the above search path will be used to create an additional directory, gemplug/ or .gemplug/, for the user's files. So gemplugrc and gemplug's intermediate files must not necessarily be placed in the same directory.

EXIT CODE
Without the -g option, gemplug returns 0 on success or 143 on error. The -g option returns either 0 (outlet active), 1 (outlet off), or 143 (error).

CAVEATS
at Jobs are scheduled on a per user basis. This means that you can only see and handle your own jobs. You won't get informed if another user has scheduled actions for the same outlet and you cannot do anything about them.

You need a fairly recent Bash as its regexp syntax has been changed in 2007. You need GNU date and GNU stat to successfully run this program.

SECURITY
Anyone who has write access to gemplug's internal configuration file can execute any command they like within the context of the current user. This file is named compiled_rc. The first one which is found along the search path will be taken. (When it is written, the fist writable parent directory along the search path is used to create gemplug's directory and to put it in there). This means that it is usually really not a good idea to give world write permissions to /etc/gemplug/. Make sure this directory and its contents are writable by root only if you decide to put a global gemplugrc there.

EXAMPLES
Assuming your configuration file looks like that:

    # sample configuration

    [ Peripherals ]
      pos = 4-2.2
      1 = Scanner
      2 = Printer Laser
      3 = DVB-T DVBT
      4 = Backup1 Backup_1 B1 ICY ext_ATA

the commands

gemplug scanner on
    and

gemplug scanner 1
    will switch your scanner on immediately

gemplug DVBT 1 for 30min
    activates the DVB receiver for 30 minutes (note there's no white space within the time specification, else it must be enclosed in quotes), and

gemplug Backup1 until tomorrow
    will activate the external Backup for exactly 24 hours until the same time of day tomorrow.

See the USAGE chapter for a few more examples.

BUGS
There are, yes. Helpful hints are welcome at hcz@hczim.de. Include the magic word gemplug somewhere in your subject line.

sispmctl's output seems not always stable under any USB condition. Therefore, all calls are re-checked for a stable readout and/or a successful change of state.

THANKS TO
Mondrian Nuessle <nuessle@uni-mannheim.de> for writing sispmctl and maintaining it. sispmctl is the basic hardware interface gemplug relies on.

HELP
A user forum can be found at http://sourceforge.net/projects/sispmctl . You can contact the author at hcz@hczim.de. Don't forget to include the output of gemplug --version.

AUTHOR
(C)2008 by Heike C. Zimmerer. This program is licensed under the GNU Public License (GPL), version 3.

SEE ALSO
sispmctl(1), date(1)