title hwset
section 1
project bgscripts-core
volume General Commands Manual
date July 2020
=====
NAME
  hwset - set hardware values like audio, screen levels, and be a template for customizing
SYNOPSIS
  hwset [-d {0..10}] [-uV] [-c <conffile>] PIECE ACTION VALUE
OPTIONS
  -d {0..10}  Set debug level, with 10 as maximum verbosity.
  -u --usage  Show help message
  -V          Show script version
  -c <conffile> Use this config file in addition to the default `/usr/local/etc/bgscripts/hwset.conf` and user default of `${HOME}/.config/hwset/hwset.conf`.
PIECES
* vol for volume
* bright for screen brightness
ACTIONS
* up
* down
* set
* mute set to zero
VALUES
* 0-100 for vol piece
* 0.0-1.0 for brightness. By default, hwset controls only X server brightness and not any customized hardware values.
DESCRIPTION
  Hwset is designed to make scriptable calls for manipulating audio volume and screen brightness, and other adjustable hardware values. This is a template as well as an instantiated example.
  It is expected that an admin will have to adjust hwset (preferably in /usr/local/bin) for each system.
EXAMPLES

  Use unenumerated up/down directions to use the default increments (not clearly defined).

    hwset vol up
    hwset bright down

  Use specific values with set, up, and down.

    hwset vol up 10
    hwset bright up .2

EXTENDING HWSET
  The PIECES are hardcoded, "vol" and "bright." You will need to adjust the MAIN LOOP case statement to accept new PIECES. Different PIECES can accept custom ACTIONS as well, in the second case statement.

For a new piece named PIECE, define these functions at a minimum.

  PIECE_down

  PIECE_up

  PIECE_set

Any additional actions can be defined as function `PIECE_ACTION` and must be included in the second case statement.
  Observe how PIECE `bright` has action `get` which is only a "private function" called only by the other ACTIONS for `bright`. Calling `hwset bright get` is not allowed from the command line. `bright_get` function is useful for `bright_up` and so on. The same is so for `bright_safe`.
  A function for `PIECE_ACTION` can be passed a value, VALUE, such as a volume level, or increment level (for ACTIONS of up and down).
AUTHOR
  <bgstack15@gmail.com>
COPYRIGHT
  CC-BY-SA 4.0
BUGS
  Adjusting X server screen brightness is not the best way to control overall display brightness. But it was all I could come up with on a FreeBSD system.
SEE ALSO
  `hwset.conf(5)`
