1# Contrib 2 3Contrib libraries, or widget types, are extra snippets of code you can 4use. Some are for less common hardware, and other were contributed by 5Vicious users. The contrib directory also holds widget types that were 6obsoleted or rewritten. Contrib widgets will not be imported by init 7unless you explicitly enable it, or load them in your rc.lua. 8 9## Usage within Awesome 10 11To use contrib widgets uncomment the line that loads them in 12init.lua. Or you can load them in your rc.lua after you require 13Vicious: 14 15```lua 16local vicious = require("vicious") 17vicious.contrib = require("vicious.contrib") 18``` 19 20## Widget types 21 22Most widget types consist of worker functions that take the `format` 23argument given to vicious.register as the first argument, `warg` as 24the second, and return a table of values to insert in the format 25string. But we have not insisted on this coding style in contrib. So 26widgets like PulseAudio have emerged that are different. These widgets 27could also depend on Lua libraries that are not distributed with the 28core Lua distribution. Ease of installation and use does not 29necessarily have to apply to contributed widgets. 30 31### vicious.contrib.ac 32 33Provide status about the power supply (AC). 34 35Supported platforms: GNU/Linux, requiring `sysfs`. 36 37* Argument: the AC device, i.e `"AC"` or `"ACAD"`. The device is linked under 38 `/sys/class/power_supply/` and should have a file called `online`. 39* Returns `{"On"}` if AC is connected, else `{"Off"}`. If AC doesn't exist, 40 returns `{"N/A"}`. 41 42### vicious.contrib.ati 43 44Provides various info about ATI GPU status. 45 46Supported platforms: GNU/Linux, requiring `sysfs`. 47 48* Argument: card ID, e.g. `"card0"` (and where possible, 49 uses `debugfs` to gather data on radeon power management) 50* Returns a table with string keys: `${method}`, `${dpm_state}`, 51 `${dpm_perf_level}`, `${profile}`, `${engine_clock mhz}`, 52 `${engine_clock khz}`, `${memory_clock mhz}`, `${memory_clock khz}`, 53 `${voltage v}`, `${voltage mv}` 54 55### vicious.contrib.batpmu 56 57### vicious.contrib.batproc 58 59### vicious.contrib.btc 60 61Provides current Bitcoin price in any currency by 62[code](https://en.wikipedia.org/wiki/ISO_4217). 63 64 65Platform independent, although requiring `curl` and either 66[lua-cjson](https://github.com/mpx/lua-cjson/) or 67[luajson](https://github.com/harningt/luajson/). 68 69* Argument: currency code, e.g. `"usd"`, `"rub"` and other. Default to `"usd"`. 70* Returns a table with string key `${price}`. 71 72### vicious.contrib.buildbot 73 74Provides last build status for configured buildbot builders 75(http://trac.buildbot.net/). 76 77Supported platforms: platform independent, though requiring Lua JSON parser 78[luajson](https://github.com/harningt/luajson/). 79 80Returns build status in the format: 81`[<builderName>.<currentBuildNumber>.<lastSuccessfulBuildNumber>]`. 82If `<currentBuildNumber>` is the same as `<lastSuccessfulBuildNumber>` only one 83number is displayed. `<buildNumber>` colors: red - failed, green - successful, 84yellow - in progress. 85 86### vicious.contrib.countfiles 87 88### vicious.contrib.cmus 89 90NOTE: This widget type has been promoted to `widgets`. 91 92Provides cmus player information using `cmus-remote`. 93 94Supported platforms: platform independent. 95 96* Argument: a table whose first field is the socket including host (or nil). 97* Returns a table with string keys: `${status}`, `${artist}`, `${title}`, 98 `${duration}`, `${file}`, `${continue}`, `${shuffle}`, `${repeat}`. 99 100### vicious.contrib.dio 101 102Provides I/O statistics for requested storage devices. 103 104* Argument: the disk as an argument, i.e. `"sda"`, or a specific 105 partition, i.e. `"sda/sda2"` 106* Returns a table with string keys: `${total_s}`, `${total_kb}`, `${total_mb}`, 107 `${read_s}`, `${read_kb}`, `${read_mb}`, `${write_s}`, `${write_kb}`, 108 `${write_mb}` and `${sched}` 109 110### vicious.contrib.mpc 111 112### vicious.contrib.netcfg 113 114### vicious.contrib.net 115 116### vicious.contrib.openweather 117 118Provides weather information for a requested city 119 120* Argument: OpenWeatherMap city ID, e.g. `"1275339"` 121* Returns a table with string keys: `${city}`, `${wind deg}`, `${wind aim}`, 122 `${wind kmh}`, `${wind mps}`, `${sky}`, `${weather}`, `${temp c}`, 123 `${humid}` and `${press}` 124 125### vicious.contrib.nvinf 126 127Provides GPU utilization, core temperature, clock frequency information about 128Nvidia GPU from nvidia-settings 129 130Supported Platforms: platform independent 131 132* Argument (optional): card ID as an argument, e.g. `"1"`, default to ID 0 133* Returns an array containing: 134 * `$1`: Usage of GPU core 135 * `$2`: Usage of GPU memory 136 * `$3`: Usage of video engine 137 * `$4`: Usage of PCIe bandwidth 138 * `$5`: Uemperature of requested graphics device 139 * `$6`: Urequency of GPU core 140 * `$7`: Uemory transfer rate 141 142### vicious.contrib.nvsmi 143 144Provides (very basic) information about Nvidia GPU status from SMI 145 146Supported platforms: platform independent 147 148* Argument (optional): card ID as an argument, e.g. `"1"`, default to ID 0 149* Returns an array containing temperature of requested graphics device 150 151### vicious.contrib.ossvol 152 153### vicious.contrib.pop 154 155### vicious.contrib.pulse 156 157Provides volume levels of requested pulseaudio sinks and functions to 158manipulate them 159 160* Argument (optional): name of a sink as an optional argument. A number will 161 be interpret as an index, if no argument is given, it will take the 162 first-best. To get a list of available sinks run 163 `pacmd list-sinks | grep 'name:'`. 164* Returns an array whose only element is the volume level 165 166#### vicious.contrib.pulse.add(percent[, sink]) 167 168* `percent` is the percentage to increment or decrement the volume from its 169 current value 170* Returns the exit status of `pacmd` 171 172#### vicious.contrib.pulse.toggle([sink]) 173 174* Toggles mute state 175* Returns the exit status of `pacmd` 176 177### vicious.contrib.rss 178 179### vicious.contrib.sensors 180 181### vicious.contrib.wpa 182 183Provides information about the wifi status. 184 185Supported Platforms: platform independent, requiring `wpa_cli`. 186 187* Argument: the interface, e.g. `"wlan0"` or `"wlan1"` 188* Returns a table with string keys: `${ssid}`, `${qual}`, `${ip}`, `${bssid}` 189 190## Usage examples 191 192### Pulse Audio widget: 193 194```lua 195vol = wibox.widget.textbox() 196local sink = "alsa_output.pci-0000_00_1b.0.analog-stereo" 197vicious.register(vol, vicious.contrib.pulse, " $1%", 2, sink) 198vol:buttons(awful.util.table.join( 199 awful.button({}, 1, function () awful.util.spawn("pavucontrol") end), 200 awful.button({}, 4, function () vicious.contrib.pulse.add(5, sink) end), 201 awful.button({}, 5, function () vicious.contrib.pulse.add(-5, sink) end))) 202``` 203 204### Buildbot widget 205 206```lua 207buildbotwidget = wibox.widget.textbox() 208vicious.register( 209 buildbotwidget, vicious.contrib.buildbot, "$1,", 3600, 210 {{builder="coverage", url="http://buildbot.buildbot.net"}, 211 {builder="tarball-slave", url="http://buildbot.buildbot.net"}}) 212``` 213