git.sur5r.net Git - i3/i3.github.io/blob - docs/user-contributed/conky-i3bar.html

   1 ---
   2 layout: default
   3 title: Docs
   4 group: Docs
   5 ---
   6 <div id="content" class="usergen">
   7 <h1>User-contributed article: Using conky with i3bar</h1>
   8
   9 <p>
  10 As explained in the i3 documentation, it’s possible to <a
  11 href="http://i3wm.org/docs/userguide.html#_displaying_a_status_line">use an
  12 external program to build the status information displayed
  13 by i3bar</a>.
  14 One of those programs is <a href="http://conky.sourceforge.net/">conky, a free,
  15 light-weight system monitor</a>.
  16 </p>
  17
  18 <p>
  19 Since conky does not support the i3bar protocol by default, we could use the
  20 plain text output format, but then we cannot have i3bar display colors. This
  21 article shows how to configure conky to have colors with i3bar.
  22 </p>
  23
  24 <p>
  25 As explained in more detail in the <a
  26 href="http://i3wm.org/docs/i3bar-protocol.html">i3bar protocol description</a>,
  27 i3bar can receive input serialized as JSON, and this way has color support,
  28 among other things (urgency flag, shortening description if more space is needed).
  29 </p>
  30
  31 <h2>Example of colored status with conky</h2>
  32
  33 <p>
  34 First of all we have to understand how i3bar expects JSON input:
  35 We have to provide an "infinite array", each element on that array is a "status
  36 line" that is displayed at a certain moment by i3bar.
  37 </p>
  38
  39 <p>
  40 Let's make a short example.
  41 We want to build a very simple status that displays the amunt of free space in
  42 home folder and the percentage of used RAM.
  43 Here's a sample JSON text for achieving our goal:
  44 </p>
  45
  46 <pre><tt>{"version":1}
  47 [
  48  [].
  49
  50  [ { "full_text": "Home 84.0G Free", "color": "#ffffff" },
  51    { "full_text": "RAM 32%" , "color": "#ffffff" } ],
  52
  53  [ { "full_text": "Home 84.0G Free", "color": "#ffffff" },
  54    { "full_text": "RAM 34%" , "color": "#ffffff" } ],
  55
  56  [....],
  57  [....],
  58  ...</tt></pre>
  59
  60 <p>
  61 The first line tells i3bar that we are using JSON input.
  62 The second line is the opening of the "infinite array".
  63 Each line after second is one "instance status" to be displayed in i3bar,
  64 </p>
  65
  66 <h2>Wrapper script</h2>
  67
  68 <p>
  69 To obtain this output with conky we have to use it in combination with a short script.
  70 The script will write down the "fixed" part of the output (first and second line), then it will call conky.
  71 It will be conky’s duty to write each of the "instances".
  72 </p>
  73
  74 <p>
  75 The script is quite simple:
  76 </p>
  77
  78 <pre><tt>#!/bin/sh
  79
  80 # Send the header so that i3bar knows we want to use JSON:
  81 echo '{"version":1}'
  82
  83 # Begin the endless array.
  84 echo '['
  85
  86 # We send an empty first array of blocks to make the loop simpler:
  87 echo '[],'
  88
  89 # Now send blocks with information forever:
  90 exec conky -c $HOME/.conkyrc</tt></pre>
  91
  92 <p>
  93 Let's save this script as <tt>conky-i3bar</tt> in <tt>$HOME/bin</tt>.
  94 In the i3 config file the <tt>bar</tt> config will be something like that
  95 </p>
  96
  97 <pre><tt>bar {
  98     status_command $HOME/bin/conky-i3bar
  99 }</tt></pre>
 100
 101 <h2>conky configuration</h2>
 102
 103 <p>
 104 Now we have to write a <tt>~/.conkyrc</tt> file in order to obtain the desired status:
 105 </p>
 106
 107 <pre><tt>[
 108     { "full_text": "Home 84.0G Free" , "color": "#ffffff" },
 109     { "full_text": "RAM 32%" , "color": "#ffffff" }
 110 ],</tt></pre>
 111
 112 <p>
 113 Here's a sample conkyrc that updates every 2 seconds. Just to make things a litte bit more exciting
 114 we put a condition in the script in order to write the occupied RAM in red if the amount is more than 90%:
 115 </p>
 116
 117 <pre><tt>conky.config = {
 118     out_to_x = false,
 119     own_window = false,
 120     out_to_console = true,
 121     background = false,
 122     max_text_width = 0,
 123
 124     -- Update interval in seconds
 125     update_interval = 2.0,
 126
 127     -- This is the number of times Conky will update before quitting.
 128     -- Set to zero to run forever.
 129     total_run_times = 0,
 130
 131     -- Shortens units to a single character (kiB->k, GiB->G, etc.). Default is off.
 132     short_units = true,
 133
 134     -- How strict should if_up be when testing an interface for being up?
 135     -- The value is one of up, link or address, to check for the interface
 136     -- being solely up, being up and having link or being up, having link
 137     -- and an assigned IP address.
 138     if_up_strictness = 'address',
 139
 140     -- Add spaces to keep things from moving about?  This only affects certain objects.
 141     -- use_spacer should have an argument of left, right, or none
 142     use_spacer = 'left',
 143
 144     -- Force UTF8? note that UTF8 support required XFT
 145     override_utf8_locale = false,
 146
 147     -- number of cpu samples to average
 148     -- set to 1 to disable averaging
 149     cpu_avg_samples = 2,
 150 };
 151
 152 conky.text = [[
 153 {% raw %}[
 154     { "full_text": "Home ${fs_free /home} Free" , "color": "\#ffffff" },
 155     { "full_text": "RAM ${memperc}%" , "color": ${if_match ${memperc}<90}"\#ffffff"${else}"\#ff0000"${endif} }
 156 ],{% endraw %}
 157 ]];
 158 </tt></pre>