man(1)

NAME
x10cli - command line interface to X10 I/O daemon

SYNOPSIS

x10cli [-h] [-Z] x10cli command

x10cli turn house_code [unit_code] action

x10cli fade house_code unit_code limit time [options...]

x10cli test house_code unit_code condition [level]

x10cli show house_code [unit_code]

x10cli set house_code unit_code flag

DESCRIPTION
x10cli is the command line interface to the x10iod X10 I/O daemon. x10cli allows devices to be turned on, off, and faded. Devices can be configured, and device status can be checked.

x10cli may be installed as these alternate names: setunit or set, showunit or show, turn or switch, fade or dim, x10test or test. With these names installed, the action is determined from the invoked name rather than the first command line parameter.

  turn
turn house_code unit_code <on|off|bright|up|dim|down>

With a unit code, turn turns on, turns off, brightens, or dims devices. Brightening and dimming increase or decrease the device by one fade level. Use fade to adjust by multiple levels.

turn house_code <on|off|lightson|lightsoff|alloff>

Without a unit code, turns on or off all lights on a given house code. The alloff action can turn off all devices (both lights and appliances) on a given house code, but there is no complementary allon action. This is a limitation of the X10 protocol.

  fade

fade house_code unit_code <on|off|full|min|half|level%> time [override|up|down|faststart|slowstart]

Fade adjusts the brightness level of a device to a requested level. A keyword or a percentage (with optional percent sign) indicates the desired level. The time over which to complete the fade is specified in minutes.

Note that different types of X10 devices have different fading behaviors. Cheap lamp devices can not be faded on, but must be turned on to full brightness then dimmed to the desired level; this is the default behavior. Better (two-way) devices remember their brightness when turned off, and return to this level when turned on. If using these devices, be sure to register them with setunit so fade knows how to correctly operate them. Despite the efforts to handle these different devices correctly, there is still the potential for the daemon's status to get out-of-sync with the actual device, which can cause erratic behavior. override, when used with on, off, or full, causes the device to execute a full 20 fade-up commands, ensuring that the light and daemon are forced into sync.

up and down indicate devices capable of only fade up and fade down, respectively; these are deprecated because I've never seen devices that behave this way.

By default, fade does a linear fade, whereby it fades levels at equal time intervals. slowstart and faststart adjust the rate so the fade starts slowly and speeds up, or starts quickly then slows and gradually reaches full brightness. For small values of time, fade may take nominally longer than the requested interval, especially with slowstart and faststart. For longer values of time, fade generally runs close to the requested time.

  x10test

x10test house_code unit_code <on|alive|exist|twoway|me|light>

x10test house_code unit_code <at|above|below> level

test checks X10 configuration or status. on is obvious. twoway, me, and light are configuration flags set with the setunit command. Presently, alive and exist both indicate that communication for the house/unit code has occurred in the past. In the future, alive may be changed to indicate whether a device is still responding.

The at, above, and below commands take a comparison level expressed as a percent, with optional percent sign. above and below are non-inclusive. A lamp that is off still has a non-zero fade level, which is either the last on-level for the two-way devices, or 100% for the cheaper devices.

  showunit
showunit house_code [unit_code]

showunit displays the current status of a single device if both house_code and unit_code are provided. If only house_code is indicated, then all devices for that house code are displayed.

  setunit
setunit house_code unit_code [-] <on|alive|exist|twoway|me|light>

setunit is usually used to configure the type of X10 device assigned to a particular house/unit code. All the options are flags and are turned on by setunit , unless preceded by a dash (-light, for example)
 in which case the flag is cleared. The daemon needs to know device types to accurately track status, as different devices respond differently to certain requests.

twoway and light are two flags (resulting in 4 types of devices) that define the behavior of X10 controllers.

me controls how the daemon responds: when enabled, this causes the daemon to execute an external command in response to activity seen for a house/unit code.

on, exist, and alive change the current device status, which is updated as the daemon communicates with devices.

There is presently no method to set a fade level.

OPTIONS

-h  Displays x10cli usage.

-Z  Enables debug output.

EXIT STATUS

0   test returns 0 to indicate true. All other commands return 0 on success.

>0  All commands return non-0 on error.

SIGNALS
None.

FILES

/tmp/x10
    UNIX domain socket used to send commands to x10iod(1).

/tmp/x10map
    File accessed to determine status of X10 devices.

SEE ALSO
x10iod(1).

BUGS
The program can not display a picture of a fish.