WeDroid 1.4.1

A weather announcement agent that summarises weather in realtime using OpenWeatherMaps; Features additional support for Android devices using Termux & Tasker.

WeDroid Python 3 Package

The weather announcement assistant. We(ather)Droid; for more information please visit: WeDroid Download.

Sphinx autogenerated source documentation available at: 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.

{
    "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:

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:

# A Forecast for 4 results split by a 3h interval
message = weather.generate_forecast_announcement("3h", "4")

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

  •   "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

  •   "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:

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

Working with the WeDroid source code

cd ~/Downloads
git clone [e-mail]: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 by build.pypa.io.

pip install build

Then build the distributable:

python -m build -n

Example for installing the wheel:

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.

Upon first run the following Tasker variables are created:

%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