i3owm

I3owm Rust

rust implementation of Open Weather Map and open-notify (ISS spotting) add-on for i3status

Contents

Installation

To install this from Rust community’s crate registry, one must have installed Rust an Cargo. Then enter this in the terminal:

cargo install i3owm

Usage

Program Arguments

Required Arguments

Option Parameter Description
-k, --apikey <apikey> Set OpenWeatherMap API key (see at https://openweathermap.org/price)

Options

Option Description
-b, --blink Let ISS icon blink when visible
-h, --help Prints help information
-n, --notify Show notifications about ISS getting visible
-r, --reverse Reverse position (from right)
-t, --test Do not process i3status from stdin, instead show formatted string
-V, --version Prints version information

Optional Arguments

Option Parameter Description Default
-f, --format Format string including one ore more of the following keys {city} {icon} {temp}{temp_unit}
-c, --location City’s name maybe followed by comma-separated 2-letter (state code for the USA locations and) country code (ISO3166) or city ID (see https://openweathermap.org/find) or geographical coordinate as comma-separated latitude and longitude. Berlin,DE
-C, --cloudiness Maximum cloudiness in percent at which ISS can be treated as visible 25
-l, --lang Two character language code of weather descriptions en
-L, --level ISS minimum show level: watch: duration when visible; soon: latency until visible; rise: spotting time; far: max. prediction time soon
-P, --poll Duration of polling period in minutes 10
-p, --position Position of output in JSON when wrapping i3status 0
-s, --soon Duration in minutes when ISS rising is “soon” in minutes 15
-u, --units Use imperial units (metric, imperial or standard) metric
-T, --prediction set number of predicted ISS spots 100
ISS spotting with --level, --soon & --prediction

Just a note about what --level does and how it interacts with the optional arguments in --soon and --prediction:

With --level you set what you get:

Level When? Format Example
watch only if currently visible 🛰+duration 🛰+03:12
soon only if visible within soon 🛰-duration 🛰-12:34
rise when there is any prediction 🛰[date] time 🛰12:15
far prediction time in days if no prediction available 🛰>days 🛰>16

Levels are inclusive backwards. So if you set the level to rise you will see soon and watch events too.

An event is “soon” if it happens within the number of minutes you set with option --soon.

The value given by argument --prediction sets the number of spotting events that will be fetched from api.open-notify.org. So this value somehow limits the time of prediction. A maximum of 100 events is given by api.open-notify.org.

Display Format

Available Properties

Choose your display format by inserting the following properties keys into your format string:

Key Description Example
{city} City name Berlin
{main} Group of weather parameters Clouds
{description} Weather condition within the group scattered clouds
{icon} Weather icon 🌞,🌛, 🌤, ⛅, 🌧,🌦,🌩,❄,🌫
{pressure} Atmospheric pressure (sea level or ground level), hPa 1010
{humidity} Humidity, % 45
{wind} Wind direction N, NO, O, SO, S, SW, W, NW
{wind_icon} Wind direction as arrow icon ↓, ↙, ←, ↖, ↑, ↗, →, ↘
{wind_speed} Wind speed m/s, mi/h
{wind_deg} Wind direction, degrees (meteorological) 56
{deg_unit} Direction unit °
{visibility} Visibility, meter 10000
{visibility_km} Visibility, kilometer 10
{rain.1h} Rain volume for the last 1 hour, mm 12
{rain.3h} Rain volume for the last 3 hours, mm 32
{snow.1h} Snow volume for the last 1 hour, mm 11
{snow.3h} Snow volume for the last 3 hours, mm 24
{temp_min} Minimum temperature at the moment -8
{temp_max} Maximum temperature at the moment 10
{feels_like} Temperature for the human perception of weather 8
{temp} Temperature 15
{temp_unit} Temperature °C, °F, K
{speed_unit} Wind speed unit m/s
{update} Local time of last update 12:45
{iss} ISS spotting time, latency or duration +01:15 , -02:21, 12:10, >16
{iss_icon} show icon if ISS is visible 🛰
{iss_space} inserts space (' ') if any ISS information is displayed ` `

Testing your Display Format

To make testing easy i3owm has an option -t (or --test) which disables processing of input from i3status and just produces the i3owm related output string. We use that option to test some examples without i3status.

Weather

To get the weather we could use the following command line:

i3owm -t -k <key> -c Berlin,DE -f '{icon} {temp}{temp_unit} 💧{humidity}%'
Output
loading...
⛅ 11°C 💧55%
ISS Spotting Events

To get ISS spotting events we could use the following parameters:

i3owm -t -Lrise -k <key> -c Berlin,DE -f 'before {iss_icon}{iss}{iss_space}after'

This example would show the satellite icon, a time for ISS spotting and a space ` ` separator if any prediction can be made:

Output
loading...
before 🛰+03:12 after

…or…

loading...
before after

…if no ISS status is available.

This would mean that ISS is already visible for 3:12 minutes.

Complex Example

In this complex example we use the following parameters:

i3owm -tnb -Lrise -C100 -k <key> -cBerlin -f'{iss_icon}{iss}{iss_space}{icon} {temp}{temp_unit} 💧{humidity}% {wind_icon}{wind_speed}{speed_unit} ({update})'
Output
loading...
⛅ 14°C 💧70% ↑2m/s (13:47)
🛰16:37 ⛅ 14°C 💧70% ↑2m/s (13:47)

Integration into i3status

To use your i3owm command line in your i3 configuration you need to remove option -t and append a pipe symbol | and your command line to your it (usually at .config/i3/config).

bar {
  status_command i3status | i3owm <your options>
}

Reference Documentation

Beside this introduction there is a reference documentation for the source code which can be found here.

Website

This README tastes better at i3owm.thats-software.com.

github repository

For the source code see this repository at github.com.

on crates.io

Published at crates.io.

License

i3status_ext is licensed under the MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

This site is open source. Improve this page.