c4ctrl

Command line client and utilities for AutoC4.

This repository consists of:

• c4ctrl.py - the command line client and python module
• kitchentext - a python script to display multiple lines of text on the Kitchenlight
• c4ctrl.vim - a plugin for the vim text editor
• _c4ctrl - command line completion file for zsh

Dependencies

• Python 3.?: https://www.python.org/
• Paho Python Module: https://github.com/eclipse/paho.mqtt.python

Installation

Install the Paho Python Module somewehere into $PYTHONPATH or run c4ctrl.py with a modified $PYTHONPATH variable. Another way to run c4ctrl.py without installing the Paho Module system-wide is to add the following line of code at the start of c4ctrl.py, right after import sys, and modify it to match your setup:

sys.path.append("/home/somepony/somedir/paho.mqtt.python/src")

You may want to create symbolic links to c4ctrl.py and kitchentext in a directory in your $PATH. For example:

$ ln -s /home/somepony/somedir/c4ctrl/c4ctrl.py /home/somepony/bin/c4ctrl
$ ln -s /home/somepony/somedir/c4ctrl/kitchentext /home/somepony/bin/kitchentext

Usage

Please run c4ctrl.py with the -h or --help flag to display all available options.

$ c4ctrl.py -h

Preset file location

c4ctrl searches for preset files in the directory $XDG_CONFIG_HOME/c4ctrl/, defaulting to $HOME/.config/c4ctrl/. If you use the -o flag and this directory does not exist, c4ctrl will ask if it shall create it for you. Preset files have no suffix and the file name is the preset name.

Preset file format

Preset files consist of topics and payloads, separated by a single equal sign '='. Lines beginning with '#' are considered to be comments and are ignored (in fact, every line beginning with a non-alphanumeric character is). Spaces and tab characters will also be ignored. You may add them to structure the preset file.

# The first three bytes of the payload are the values for red, green and blue.
# Some devices take up to 7 bytes.
# **Note:** 4 and 7 channel cans use the last byte for brightness. You most
# likely want to set this to 'ff' as shown below.

# Full notation for 7 channel dmx cans.
dmx/plenarsaal/vorne1 = 0033ff 000000ff
#                                    ^^ Brightness

# Normal notation.
dmx/plenarsaal/vorne2 = 0033ff

# Short notation (same as '0033ff').
dmx/plenarsaal/vorne3 = 03f

Virtual presets

The presets off and random are built-ins and are always available. Note that random is not really random, but a kind of 'colorful random'.

kitchentext

Kitchenlight utility script. kitchentext is written in python and depends on c4ctrl.py.

$ kitchentext -h

c4ctrl.vim

A vim plugin to help with the creation and editing of preset files. Depends on c4ctrl[.py]. Install by putting c4ctrl.vim into your ~/.vim/plugin/ directory or create a symbolic link there.

$ mkdir -p ~/.vim/plugin
$ ln -s /home/somepony/somedir/c4ctrl/c4ctrl.vim ~/.vim/plugin/c4ctrl.vim

Usage

:C4ctrl get                    -- Read current state into buffer.
:C4ctrl open $name             -- Open local preset $name.
:C4ctrl set [w|p|f] [-magic]   -- Apply current buffer or range/selection as
                                  preset to room [w]ohnzimmer, [p]lenarsaal or
                                  [f]nordcenter. Default is all rooms.
:C4ctrl kitchentext [register] -- Display text in register, selected text or
                                  text in range on the Kitchenlight.
:C4ctrl write $name            -- Save current buffer as preset $name.

Commands and options (excluding preset names) may be abbreviated as long as they stay unambiguous (e.g. :C4 s w -m is a valid command). Completion works for commands, options and preset names. The recommended workflow looks like this:

Read the current state of all ambient lights into a new buffer.

:C4 g

Make some edits. Note: Dmx cans taking 4 or 7 bytes use the last byte for brightness. You most likely want this to be 'ff' (as seen below).

dmx/wohnzimmer/tuer1 = 00ff00 000000ff
                                    ^^

The set command optionally takes a range or selection. This way you can apply changes to a subset of lights or a single light only. Alternatively you can give a room name as option.

:.C4 s      <-- apply changes in the current line only (note the dot)
:'<,'>C4 s  <-- apply selected lines (use with <SHIFT>-V)
:C4 p       <-- apply all changes to plenarsaal

You can write your preset into c4ctrls config directory with the write command. Note: c4ctrl stores it's presets in $XDG_CONFIG_HOME/c4ctrl/ (likely $HOME/.config/c4ctrl). The vim plugin will not create this directory for you if it doesn't exist. c4ctrl will. Either create the directory by hand or run c4ctrl -o pony on the command line after applying your changes.

:C4 w pony

You may open existing presets with open.

:C4 o pony

_c4ctrl

Completion script for zsh.

Installation

Put _c4ctrl somewhere into $fpath (or alter $fpath in your ~/.zshrc). See also: http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Directories

For example: Add the following lines to your ~/.zshrc before any 'compinstall' stuff:

# Add custom zsh script directory to fpath
fpath=($fpath ~/.local/share/zsh)

Then create the directory and put a link to _c4ctrl there.

$ mkdir -p ~/.local/share/zsh
$ ln -s /home/somepony/somedir/c4ctrl/_c4ctrl ~/.local/share/zsh/_c4ctrl