From b72a1ac605dff32615fedf6aa08860c0cb9b8568 Mon Sep 17 00:00:00 2001 From: Shy Date: Tue, 18 Apr 2017 10:24:04 +0200 Subject: [PATCH] Extended documentation --- README.md | 131 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 125 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4e10435..8bb4137 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,91 @@ # 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 Client: [[https://github.com/eclipse/paho.mqtt.python]] +* 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. +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. +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 ``` @@ -34,12 +99,66 @@ Depends on *c4ctrl[.py]*. Install by putting *c4ctrl.vim* into your :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 -V) +:C4 p <-- apply all changes to plenarsaal +``` + +You can write your preset into *c4ctrl*s 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*). +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 +``` +