Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/fightling/i3owm

Open Weather extension for i3status
https://github.com/fightling/i3owm
crates i3status i3wm open-notify openweathermap rust weather
Last synced: 2 months ago
JSON representation
Open Weather extension for i3status
Host: GitHub
URL: https://github.com/fightling/i3owm
Owner: fightling
License: mit
Created: 2021-04-29T01:36:34.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2022-07-10T17:44:49.000Z (over 2 years ago)
Last Synced: 2024-10-10T19:11:14.782Z (3 months ago)
Topics: crates, i3status, i3wm, open-notify, openweathermap, rust, weather
Language: Rust
Homepage:
Size: 103 KB
Stars: 11
Watchers: 2
Forks: 0
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        # I3owm [![Rust](https://github.com/fightling/i3owm/actions/workflows/rust.yml/badge.svg)](https://github.com/fightling/i3owm/actions/workflows/rust.yml)

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

## Contents

- [Contents](#contents)   

- [Installation](#installation)   

- [Usage](#usage)   

   - [Program Arguments](#program-arguments)   

      - [Required Arguments](#required-arguments)   

      - [Options](#options)   

      - [Optional Arguments](#optional-arguments)   

         - [ISS spotting with `--level`, `--soon` & `--prediction`](#iss-spotting-with-level-soon-prediction)   

   - [Display Format](#display-format)   

      - [Available Properties](#available-properties)   

      - [Testing your Display Format](#testing-your-display-format)   

         - [Weather](#weather)   

         - [ISS Spotting Events](#iss-spotting-events)   

         - [Complex Example](#complex-example)   

   - [Integration into i3status](#integration-into-i3status)   

- [Reference Documentation](#reference-documentation)   

- [Links](#links)   

   - [Website](#website)   

   - [*github* repository](#github-repository)   

   - [on *crates.io*](#on-cratesio)   

- [License](#license)   

## 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`    | `` | 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  -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  -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  -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 

}

```

## Reference Documentation

Beside this introduction there is a reference documentation for the source code which can be found [here](https://docs.rs/i3owm).

## Links

### Website

This README tastes better at [i3owm.thats-software.com](http://i3owm.thats-software.com).

### *github* repository

For the source code see [this repository](https://github.com/fightling/i3owm) at *github.com*.

### on *crates.io*

Published at [*crates.io*](https://crates.io/crates/i3owm).

## License

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