.config/awesome/lain/wiki/net.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Monitors network interfaces and shows current traffic.
   8
   9 ```lua
  10 local mynet = lain.widget.net()
  11 ```
  12
  13 ## Input table
  14
  15 Variable | Meaning | Type | Default
  16 --- | --- | --- | ---
  17 `timeout` | Refresh timeout (in seconds) | integer | 2
  18 `iface` | Network device(s) | string (single interface) or table of strings (multiple interfaces) | autodetected
  19 `units` | Units | integer | 1024 (kilobytes)
  20 `notify` | Display "no carrier" notifications | string | "on"
  21 `wifi_state` | Get wifi connection status | string | "off"
  22 `eth_state` | Get ethernet connection status | string | "off"
  23 `screen` | Notifications screen | integer | 1
  24 `settings` | User settings | function | empty function
  25
  26 `iface` can be a string or an table of the form `{ "eth0", "eth1", ... }` containing a list of the devices to collect data on.
  27
  28 If more than one device is included, `net_now.sent` and `net_now.received` will contain cumulative values over all given devices.
  29 Use `net_now.devices["eth0"]` to access `sent`, `received`, `state` or `carrier` per device.
  30
  31 Possible alternative values for `units` are 1 (byte) or multiple of 1024: 1024^2 (mb), 1024^3 (gb), and so on.
  32
  33 If `notify = "off"` is set, the widget won't display a notification when there's no carrier.
  34
  35 `settings` can use the following `iface` related strings:
  36
  37 - `net_now.carrier` ("0", "1");
  38 - `net_now.state` ("up", "down");
  39 - `net_now.sent` and `net_now.received` (numbers) will be the sum across all specified interfaces;
  40 - `net_now.devices["interface"]` contains the same attributes as the old api for each interface. More on this in the "Multiple devices" section below.
  41
  42 If `wifi_state = "on"` is set, `settings` can use the following extra strings attached to `net_now.devices["wireless interface"]`:
  43 - `wifi` (true, false) indicates if the interface is connected to a network;
  44 - `signal` (number) is the connection signal strength in dBm;
  45
  46 If `eth_state = "on"` is set, `settings` can use the following extra string: `net_now.devices["ethernet interface"].ethernet`, which is a boolean indicating if an ethernet connection's active.
  47
  48 For compatibility reasons, if multiple devices are given, `net_now.carrier` and `net_now.state` correspond to the last interface in the iface table and should not be relied upon (deprecated).
  49
  50 ## Output table
  51
  52 Variable | Meaning | Type
  53 --- | --- | ---
  54 `widget` | The widget | `wibox.widget.textbox`
  55 `update` | Update `widget` | function
  56
  57 ## Notes
  58
  59 ### Setting `iface` manually
  60
  61 If the widget [spawns a "no carrier" notification and you are sure to have an active network device](https://github.com/lcpz/lain/issues/102), then autodetection is probably not working. This may due to [your user privileges](https://github.com/lcpz/lain/issues/102#issuecomment-246470526). In this case you can set `iface` manually. You can see which device is **UP,LOWER_UP** with the following command:
  62
  63 ```shell
  64 ip link show
  65 ```
  66 ## Usage examples
  67 ### Two widgets for upload/download rates from the same `iface`
  68
  69 ```lua
  70 local mynetdown = wibox.widget.textbox()
  71 local mynetup = lain.widget.net {
  72     settings = function()
  73         widget:set_markup(net_now.sent)
  74         netdowninfo:set_markup(net_now.received)
  75     end
  76 }
  77 ```
  78 ### Wifi connection + signal strength indicator and ethernet connection indicator
  79 ```lua
  80 local wifi_icon = wibox.widget.imagebox()
  81 local eth_icon = wibox.widget.imagebox()
  82 local net = lain.widget.net {
  83     notify = "off",
  84     wifi_state = "on",
  85     eth_state = "on",
  86     settings = function()
  87         local eth0 = net_now.devices.eth0
  88         if eth0 then
  89             if eth0.ethernet then
  90                 eth_icon:set_image(ethernet_icon_filename)
  91             else
  92                 eth_icon:set_image()
  93             end
  94         end
  95
  96         local wlan0 = net_now.devices.wlan0
  97         if wlan0 then
  98             if wlan0.wifi then
  99                 local signal = wlan0.signal
 100                 if signal < -83 then
 101                     wifi_icon:set_image(wifi_weak_filename)
 102                 elseif signal < -70 then
 103                     wifi_icon:set_image(wifi_mid_filename)
 104                 elseif signal < -53 then
 105                     wifi_icon:set_image(wifi_good_filename)
 106                 elseif signal >= -53 then
 107                     wifi_icon:set_image(wifi_great_filename)
 108                 end
 109             else
 110                 wifi_icon:set_image()
 111             end
 112         end
 113     end
 114 }
 115 ```