A weather announcement agent that summarises weather in realtime using OpenWeatherMaps; Features additional support for Android devices using Termux & Tasker.
Project description
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
Configuration
You will need an Open Weather Map API key to use this script.
You defined the configuration settings for WeDroid as a dictionary. You can either define this dictionary in the file calling the WeDroid
class or you can optionally define it as a separate file.
An example for storing the settings in an optional file; create a new file for example: settings.json
and insert the following:
{
"run_type": "tasker",
"intercept_task_name": "WeDroid Received",
"owm_api_key": "<own-api-key>",
"announce_temp": true,
"announce_time": true,
"announce_humidty": 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", // Value can be: INFO, DEBUG, ERROR
"location_provider": "gps", // Value can be: gps, network, passive
"location_request": "once" // Value can be: once, last, updates
}
Working with WeDroid as a package
When initiating WeDroid
; pass the newly created configuration file:
From the CLI
This assumes that you have Python 3 (minimum 3.9) installed.
Installation
pip install wedroid
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/settings.json"
In your own custom projects
WeDroid can be utilised in your own projects, example:
import os
from wedroid.core import WeDroid
custom_config = "./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 source code
cd ~/Downloads
git clone git@gitlab.com:oddineers-public/wedroid.git
Fetching 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.
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/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
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.
- Create new profile > Time > Define range and re-occurrence.
- 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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.