interactivipi Files

/* interactivipi
 * (c) 2020 Peter Ganzhorn
 *
 * This Program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3, or (at your option)
 * any later version.
 *
 * This Program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

Currently this software suite contains two tools for interactive input for the Raspberry Pi:
- rotenc
- pushbtn

Compilation:
Compile with 'make'.
Individual tools can be built with 'make <name>' (e.g. 'make rotenc' will only build rotenc)

Usage:
Both tools allow a config file location to be passed as command line argument.
If no config file is specified on the command line, the tools will look for config files in default locations, which are:
~/.<name>
/etc/<name>.conf
Where <name> stands for 'rotenc' or 'pushbtn'.

The config file syntax is the same for both tools.
- The '#' symbol is used for comments. Individual lines will not be read after a '#' symbol.
- Whitespaces may be used, leading and tailing whitespaces are also allowed.
- Upper- and lowercase characters are not distinguished (e.g. 'LiNe' and 'line' are treated the same).
- All options are specified as 'option = argument' on a single line.
- Config file sections are marked by brackets containing the section names (e.g. '[entity_name]').
- Indiviual entities (e.g. rotary encoders or buttons) need to be put in a section.
- General options need to be specified before the first section starts.


General options for all tools:
numbering = wpi/bcm/phy
	Changes the pin numbering scheme for the Raspberry Pis J8 header GPIO pins.
	wpi = wiringPi (default)
	bcm = Broadcom
	phy = Physical/Header numbering
logFile = logfile location (optional)
logOpts = logging options as comma-separated list of
		append: Append to existing logFile
		timestamp: Prepend timestamp before messages
		print: Print log messages on screen (and write to log file)
		symbols: Prepend symbols indicating importance of messages
		relatime: Use time since program start instead of date and time for timestamps
		color: Colorize messages depending on importance for on-screen output
logLevel = Controls log verbosity, use on of the following:
		debug: shows lots of messages
		verbose: shows more than usually desired
		info / default: reasonable amount of messages
		warn: show only warnings and errors
		error: show only errors


***************************************************************************************************
rotenc:
Rotary encoder input.
Currently up to 4 rotary encoders are supported.

Possible general options:
	delay: delay in ms between execution of commands. Default: 100
		if the encoder is being turned, this will delay execution of commands to avoid running too many executions.

Per-encder options:
	pin_a: First pin number given in selected numbering scheme
	pin_b: Second pin number given in selected numbering scheme
	cmd_plus: Command to execute for turns in positive direction
	cmd_minus: Command to execute for turns in negative direction
		Commands can contain ${%} which will be replaced with number of steps the encoder turned.
	mode: Mode of operation. Possible settings:
		rel: Relative mode using number of turns since last check (default)
		abs: Absolute mode with incremental counting of encoder position
	sequence: Encoder sequence or detent type. Possible values are:
		full: Detent after a full sequence. (default)
		half: Detent after a half sequence.
		quarter: Detent after a quarter sequence or no detents at all.
		If you do not know what type of encoder you have, start with full and reduce to half/quarter
		if the encoder does not update every single 'click'.
	seq_align: Determines the start point of the sequence. Possible values:
		0-3 for 'full' sequence
		0-1 for 'half' sequence
		Experiment with this if the encoder is missing the first update after a direction change.
	limit: Max. number of increments reported per update in relative mode. (Limits turning speed)
	limit_max: maximum value reported in absolute mode. (Limits value range)
	limit_min: minimum value reported in absolute mode. (Limits value range)


***************************************************************************************************
pushbtn:
Input from push buttons.

Possible general options:
	debounce: Number of milliseconds to wait until pin state is determined (default = 5).
		Useful if your button is not hardware-debounced.

Per-button options:
	pin: Pin number given in selected numbering scheme
	timeout: Long-press detection delay in milliseconds
	exec: Command to execute for 'short presses' (shorter than timeout ms)
	alt_exec: Command to execute for 'long presses' (longer than timeout ms)