WeDroid 1.4.1
A weather announcement agent that summarises weather in realtime using OpenWeatherMaps; Features additional support for Android devices using Termux & Tasker.
Keywords: weather development, owm

# WeDroid Python 3 Package

The weather announcement assistant. We(ather)Droid; for more information please visit: [WeDroid Download](https://oddineers.co.uk/wedroid/).

Sphinx autogenerated source documentation available at: [oddineers-public.gitlab.io/wedroid](https://oddineers-public.gitlab.io/wedroid/)

## Weather reports
WeDroid can run either observation or forecasts styled reports.
- Observations include a summary of the weather, temperature, time.
- Forecasts return the weather status for a given interval + limit; for example 3h as the interval and 4 as the limit.
Would produce a report with 4 observations with 3 hours intervals. 

## Configuration
WeDroid will try to load its configuration from `wedroid_settings.json` using the following logic:
1. First the current running directory is checked.
2. If no configuration in current directory it checks the users home directory (_cross-platform is supported_).

This behaviour can be overridden by passing in the path to a configuration: `-c "/path/to/some/where/wedroid_settings.json"`

An example for storing the settings in an optional file; create a new file for example: `wedroid_settings.json` and insert the following:

> **Note**: You will need an Open Weather Map API key to use this script; [register at openweathermap.org](https://openweathermap.org/api).

```json
{
    "run_type": "tasker",
    "intercept_task_name": "WeDroid Received", // Tasker Task name that will process the data passed to it
    "owm_api_key": "<own-api-key>",
    "announce_temp": true,
    "announce_time": true,
    "announce_humidity": false,
    "announce_wind": false,
    "announce_sun": true,
    "sl4a_gtts": false,
    "bot_name": "WeDroid",
    "mattermost_url": "<web-hook-url>",
    "device_location": true,
    "longitude": -3.0,
    "latitude": 53.0,
    "log_level": "DEBUG",       // OPTIONAL: Value can be: INFO, DEBUG, ERROR
    "log_gps_coords": true,     // OPTIONAL: true or false, enables or disables GPS co-ordinate inclusion in log files.
    "location_provider": "gps", // Value can be: gps, network, passive
    "location_request": "once"  // Value can be: once, last, updates
}
```

## Working with WeDroid as a `package`
Installation:
```
pip install wedroid
```

Double check your configuration; the file should be named: `wedroid_settings.json`.

### Running from the CLI
This assumes that you have Python 3 (_minimum 3.9_) installed.

#### Optional - Generate a template `wedroid_settings.json` file

```
wedroid -d
```

#### Forecast styled report
```
wedroid -t "forecast" -i "3h" -l 12 
```

#### Observation styled report
```
wedroid  -t "observation" -lt "14.0" -lc 812
```

#### Observation styled report with custom configuration
```
wedroid  -t "observation" -lt "14.0" -lc 812 -c "/path/to/some/where/wedroid_settings.json"
```

### Integrating with your own custom projects
WeDroid can be utilised in your own projects, example:

```python
import os
from wedroid.core import WeDroid

custom_config = "./wedroid_settings.json"
if os.path.isfile(custom_config):
  # Pass in to WeDroid
  weather = WeDroid(custom_config)
```

From here you can access functions:
```python
# A Forecast for 4 results split by a 3h interval
message = weather.generate_forecast_announcement("3h", "4")
```

```python
# A weather observation now (compares previously values)
message = weather.generate_weather_announcement()
```

### Customising messages and weather statuses

The messages and weather responses can be customised under `./wedroid/translations/*` if working with the source directly:
- `annoucements.json` contains various message part that make-up a report, example:
  - ```json
      "sunrise-future": "The Sun will rise in {}.",
      "sunset-past": "The Sun set {} ago.",
      "sunset-future": "The Sun will set in {}.",
    ```
- `weather.json` contains a dict where the weather status codes map to a: `title, icon, description`, example
  - ```json
      "781": {
        "title": "Tornado",
        "icon": "50d",
        "description": "tornado"
      }
    ```

As a package you can pass the path the translations directory as follows, ensure that it contains `announcements.json` & `weather.json`:

```python
wedroid = WeDroid(translation_path="./some/where/translations")
```

## Working with the WeDroid source code

```
cd ~/Downloads
git clone git@gitlab.com:oddineers-public/wedroid.git
```

### Using launcher.py to get started
Forecast styled report
```
python3 launcher.py -t "forecast" -i "3h" -l 12 
```

Observation styled report
```
python3 launcher.py  -t "observation" -lt "14.0" -lc 812
```

Observation styled report with custom configuration
```
python3 launcher.py  -t "observation" -lt "14.0" -lc 812 -c "/path/to/some/where/wedroid_settings.json"
```

#### Building the module:

Install [build](https://build.pypa.io/en/stable/) by build.pypa.io.
```
pip install build
```

Then build the distributable:
```commandline
python -m build -n
```

Example for installing the wheel:
```commandline
pip install WeDroid-1.x.x-py3-none-any.whl
pip install <path_to_file>/wedroid/dist/WeDroid-1.x.x-py3-none-any.whl
```

## Tasker - Android
**NOTE: This section will make more sense once the examples are ready and Tasker Profiles + Tasks made available.**

Requirements (_Android_):
- Tasker
- Termux (_other shells are likely supported where you can install Python 3_)
- Termux:API
- Termux Tasker plugin
- Termux requirements:
  - Termux configured to access local storage
  - Termux:API configured to allow GPS access (_if you intend to let WeDroid access the devices location_)

These instructions are somewhat vague at the moment and will be expanded soon in greater details in ReadTheDocs.

When used with Tasker on Android you can define a task and/or profile which can run the WeDroid announcement service.
 
To run the script ensure the following:
- Python 3 via the Termux.
    - Termux is installed.
    - Python 3 package is installed.
    - The Task in Tasker is specifically "Run Termux Script" & the script to run is called `launcher.py` enabled and pass the following variables: `%WD_LAST_TEMP, %WD_LAST_CODE`.
- In Tasker assign the value 0 to`%WD_LAST_TEMP, %WD_LAST_CODE`.
- Run script to finish configuration and create default configuration.
- Open `wedroid_settings.json` and add your OWM API key, [create one here](https://openweathermap.org/api).

Upon first run the following Tasker variables are created:

```text
%WD_LAST_CODE
%WD_SUNRISE
%WD_SUNSET
%WD_LAST_TEMP
%WD_LAST_TIME
%WD_LAST_WIND_SPEED
%WD_LAST_WIND_DIRECTION
%WD_LAST_HUMIDITY
%WD_DAY_STATE
# The main announcement
%WD_ANNOUNCEMENT
# Announcement parts separated
%WD_TIME_MSG
%WD_WEATHER_MSG
%WD_TEMP_MSG
%WD_WIND_MSG
%WD_SUN_MSG
%WD_HUMIDITY_MSG
```

At this point the configuration aspect is complete, but we need to configure a run schedule within Tasker. 

### Tasker Profile Creation
The simplest method is to create a Tasker Profile using the Time profile.

1. Create new profile > Time > Define range and re-occurrence.
2. Next link the profile to a new task "Run Termux Script" as defined earlier.

## Documentation from source

### Generating documentation

Ensure `sphinx` is install with:
```
pip install sphinx
```
Change to docs directory
```
cd docs
```
Building docs
```
sphinx-apidoc -f -o source/ ../wedroid
make clean
make html
```
Regenerate the Sphinx readme.rst from the project README.md (_requires pandoc_):
```
pandoc --from=markdown --to=rst --output=source/readme.rst ../README.md
```

Linux one-liner
```
sphinx-apidoc -f -o source/ ../wedroid && make clean && make html
```

Windows one-liner
```
sphinx-apidoc -f -o source/ ../wedroid & make clean & make html
```