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