SimpleConkyScript

A fully-customizable Conky script entirely built in Lua

Installation

# Debian example procedure
sudo apt install conky-all hddtemp lm-sensors lsb-release wget x11-utils luarocks
sudo luarocks install luaposix
sudo luarocks install lua-cjson
sudo sensors-detect --auto
sudo systemctl enable --now hddtemp.service

# Universal section
mkdir ~/.conky/
cd ~/.conky/
git clone https://git.forestier.app/HorlogeSkynet/SimpleConkyScript.git
cd SimpleConkyScript/
cp config.json.dist config.json

Usage

conky -c ~/.conky/SimpleConkyScript/conky.lua

Static Analysis

sudo luarocks install luacheck
luacheck .

Configuration Documentation

This project is fully-customizable from configuration. It means that you can safely pull latest changes without tweaking any Lua code ( 😎 ).
The main idea is to describe the content of two "columns" displayed on your screen (please refer to the screen-shot above).
To achieve this, you can either use pre-defined types of entity (detailed below) or tweak global settings.

Comprehensive documentation of the `config.json` file

{
	"settings": {
		"conky": {
			// Specific settings related to Conky itself.
			// You can read further information about them here : <https://github.com/brndnmtthws/conky/wiki/Configurations#settings>.
			// Entries present by default are mostly mine, working against a Cinnamon setup.
		},
		// Below objects (as long as their associated entries) are all REQUIRED.
		"timers": {
			// Number of iterations to wait before drawing anything on the screen.
			// It allows Conky to initialize its internals and gather some data before rendering anything.
			// You MAY lower this value at your own risks.
			"startup_threshold": 3,

			// Number of iterations to wait before checking the user configuration (and reloading Conky if it changed).
			// Use `null` to disable this behavior (default).
			"config_autoreload": null,

			// Number of iterations to wait before gathering current screen resolutions (and reloading Conky if it changed).
			// This option is very useful if you are used to plug your laptop on a dock or play with multiple screens.
			"resolution_autodetect": null
		},
		"display": {
			// The width (in pixels) of the two columns drawn on screen.
			// You MAY lower this value, but don't forget about very long content that could be displayed (i.e. IPv6 addresses).
			"columns_width": 460,

			// The number of pixels to automatically add between two entities.
			"entity_padding": 7,

			// A subcommand to be run in order to retrieve the current screen dimensions (output MUST be formatted as `${WIDTH}x${HEIGHT}`).
			"resolution_exec": "xdpyinfo | grep dimensions | tr -s ' ' | cut -d ' ' -f 3"
		},
		"font": {
			// The font size and family to be used when writing down text on the screen.
			// The font family SHOULD be a "Monospaced" one (see <https://en.wikipedia.org/wiki/Monospaced_font>).
			"size": 15,
			"family": "Consolas"
		},
		"colors": {
			// Below colors are defined as RGBA values.
			// Keys speak for themselves.
			"default": [1, 1, 1, 1],
			"clock_second_hand": [1, 0, 0, 1],
			"bar_background": [0.4, 0.4, 0.4, 1],
			"graph_in": [0, 0.5, 0.66, 1],
			"graph_out": [1, 0.5, 0, 1]
		},
		"temperature": {
			// The temperature unit that will be employed.
			// You can either specify `F` for Fahrenheit or `C` for Celsius (default).
			"unit": "C",

			// The degree symbol that should be set before the unit.
			// Please be careful, the one set by default required you to use a font family supporting Unicode.
			"degree": "°",

			// The string that will be added to any temperature exceeding the set threshold (see `{drive,sensor}_temperature` entities below)
			"warning": "/!\\"
		}
	},
	"content": {
		// Entities are represented by a list of JSON objects.
		// This first list will describe entities set within the left column.
		"left": [
			{
				// An entity is an object containing at the very least a `type` key.
				// You will find below an exhaustive list of supported `type`.
				//
				// You MAY temporary "hide" any entity by setting the `disabled` key to `true`.
				// This is pretty handy to avoid cutting/pasting content in your JSON.
				//
				// One more important note about configuration values :
				// Only omitting a key or setting its value to `false` would make the option evaluate to `false` in Lua.
				"type": "...",
				"disabled": false
			},
			{
				// This entity will display a clock, as present on the screen-shot above.
				"type": "clock"
			},
			{
				// This entity will render the current date-time and output it as a 'text' object.
				// This is a regular 'text' object underly, so you MAY tweak the `align_center` setting (see `text` entity below).
				"type": "date_time",
				"format": "%H:%M:%S, %A %d/%m/%Y",
				"align_center": true
			},
			{
				// This entity will display an horizontal line, allowing you to separate entities and thus creating "blocks".
				"type": "separator"
			},
			{
				// A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'text' object.
				// For example, the lines below would produce : "Hostname: ${nodename}".
				//
				// `arg` is fully-optional and MAY be omitted.
				//
				// `align_center` is fully-optional and defaults to `false`.
				"type": "text",
				"var": "nodename",
				"arg": "",
				"name": "Hostname",
				"align_center": false
			},
			{
				// A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'bar' object.
				// `arg` is fully-optional and MAY be omitted.
				//
				// `show_percent` allows you to add the numerical percentage value next to the `name` of your 'bar' object (disabled by default).
				//
				// You MAY use `bar` with any variable evaluating to a valid percentage.
				"type": "bar",
				"var": "battery_percent",
				"arg": "",
				"name": "Battery",
				"show_percent": false
			},
			{
				// A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'graph' object.
				// `arg` is fully-optional and MAY be omitted.
				//
				// This entity is really strong, you can actually provide _any_ data to it, as long as it is consistent across time.
				"type": "graph",
				"name": "CPU activity",
				"var": "cpu",
				"arg": "cpu0"
			},
			{
				// This is the most powerful entity currently available.
				// It allows you to execute (synchronously though) a subcommand and show the (STDOUT) result as a 'text' object.
				// For example, on Debian, the lines below MIGHT produce : "Updates: 42 available".
				//
				// `interval` represents the number of iterations to wait before executing the command again (the output is cached).
				// Please be careful, with `update_interval` Conky setting set to 2 seconds, such a command would be executed each 3600 * 2 seconds, or 2 hours.
				// You MAY set `interval` to `null` to completely disable value update (the first obtained output would be kept until reloading).
				// Inversely, you MAY set `interval` to `0` (or even omit the entry) to update it during each iteration (use at your own risks).
				//
				// `pre_text` and `post_text` (fully-optional values) allow you to respectively set some texts before and after obtained output.
				// `align_center` acts described above for `text` entities.
				//
				// When the command fails, `on_error` content will be displayed.
				"type": "command",
				"exec": "apt list --upgradable -qq 2> /dev/null | wc -l",
				"name": "Updates",
				"interval": 3600,
				"pre_text": "",
				"post_text": " available",
				"align_center": false,
				"on_error": "Not detected"
			},
			{
				// `brightness` is a very specific entity.
				// Through `cur_file` and `max_file`, it computes a brightness percentage ratio and produces a 'bar' object.
				// You SHOULD specify an `interval` to avoid opening and reading two files during each iteration.
				//
				// For this entity, `name` is fully-optional and defaults to "Brightness" when not specified.
				//
				// `show_percent` is also available and MAY be tweaked.
				//
				// Please be careful, set file paths below MAY NOT work on your system.
				"type": "brightness",
				"name": "Brightness",
				"cur_file": "/sys/class/backlight/intel_backlight/actual_brightness",
				"max_file": "/sys/class/backlight/intel_backlight/max_brightness",
				"interval": 10,
				"show_percent": false
			},
			{
				// This entity allows you to show a 'top'-like output for processes, based on their CPU usage.
				// `max_processes` MAY be set between `1` and `10` (defaults to `10`).
				"type": "top_processes",
				"max_processes": 5
			},
			{
				/* ... */
			}
		],
		// This second list will describe entities set within the right column.
		"right": [
			{
				// This entity relies entirely on the LM-SENSORS program.
				// It underly uses a `sensors` call to retrieve temperature information from a chip.
				// The identifier of the `chip` to prompt MUST be specified and could be found by manually running `sensors -A`.
				// The final displayed value correspond to the chip temperature inputs average.
				//
				// `interval` acts as described for `command` type entity (see above).
				//
				// `threshold` represents the maximum temperature value that could be reached before adding the symbol specified in `settings.temperature.warning` (see above).
				// You can either specify Celsius or Fahrenheit, as long as it is consistent to the unit specified in `settings.temperature.unit` (see above too).
				//
				// When no temperature could be computed, `on_error` will be displayed.
				"type": "sensor_temperature",
				"name": "CPUs",
				"chip": "coretemp-isa-0000",
				"interval": 5,
				"threshold": 70,
				"on_error": "Not detected"
			},
			{
				// This entity works as the `sensor_temperature` above, but relies on the HDDTEMP program.
				// You'll have to specify the path to the targeted drive.
				//
				// `wake_up` allows you to force drive wake up if needed to measure its temperature (disabled by default).
				//
				// `interval`, `threshold` and `on_error` acts as described for `sensor_temperature` type entity (see above).
				"type": "drive_temperature",
				"drive": "/dev/sda",
				"wake_up": false,
				"interval": 5,
				"threshold": 60,
				"on_error": "Not detected"
			},
			{
				// This entity is a handy wrapper to the 'bar' entity.
				// By specifying any partition `mount_point`, it will display a 'bar' representing its usage.
				// `show_percent` acts as described above for `bar` entities (see above).
				"type": "partition_usage",
				"mount_point": "/home/",
				"show_percent": false
			},
			{
				// This entity will display two graphs representing the I/O rate of the specified `drive`.
				// To set graphs colors, please refer to `settings.colors.graph_{in,out}`.
				"type": "drive_io",
				"drive": "/dev/sda"
			},
			{
				// This entity will display two graphs representing the I/O rate of the specified network `interface`.
				// As `drive_io` above, please refer to `settings.colors.graph_{in,out}` to set graphs colors.
				//
				// Please be careful, such an entity will be skipped when the interface is down (see `if_up_strictness` for further information).
				"type": "network_interface_io",
				"interface": "enp0s25"
			},
			{
				// This entity will display each IP addresses associated to the specified network `interface`.
				// `hide_v6` allows you to hide any IPv6 address (disabled by default).
				//
				// Please be careful, such an entity will be skipped when the interface is down (see `if_up_strictness` for further information).
				"type": "network_interface_addr",
				"interface": "enp0s25",
				"hide_v6": false
			},
			{
				// This entity is a disguised 'text' object.
				// It allows you to show Conky version, with `{pre,post}_text` (active as within the `command` entity).
				//
				// `align_center` is available and acting as described above.
				//
				// It could be very useful to give you credits on screen-shot for instance.
				"type": "version",
				"pre_text": "Horloge's script on ",
				"post_text": "",
				"align_center": true
			},
			{
				/* ... */
			}
		]
	}
}

Frequently asked questions

My Conky does not work, it [insert your very specific issue details here]. What should I do ?

Please, refer to the official Conky's FAQ first.
If you can't find anything helpful, please contact me with your Conky terminal output attached.

Your script is cool but I'd like to install it elsewhere. How could I achieve that ?

You'll have to tweak your conky execution with an additional environment variable :

CONKY_PATH="/another/path/to/" conky -c /another/path/to/conky.lua

Rationale : There is no way to fetch the project location from the configuration file itself (conky.lua).
Fortunately for us, we may read Conky environment variables directly from Lua !

How can I get the same background image ?

There it is !

My device drive temperature is not displayed !

Yeah it happens sometimes when the hddtemp daemon is not properly configured.
Simply run the command below to enable the SUID bit, and leave other options with their default value :

sudo dpkg-reconfigure hddtemp

How can I contribute to this project ?

At the moment, SimpleConkyScript is not open to public contributions.
However, you may send patches to dev+conky@samuel.domains, I'll personally take the time to review them.

Acknowledgments

• To NAERNON for the code structure, design and ideas
• To Nelis Oostens for his clock's code, and the Lua section of Conky's wiki