LukeCollishaw 1.0.0

COVID Alarm Clock

COVID Alarm Clock

The purpose of the COVID Alarm Clock is to allow the user to schedule alarms that will give them updates on the news and on the weather. The application will also give the user automatic notifications, with a particular focus on COVID-19. It uses the UK's official COVID-19 API to give the user updates similar to what might be said in a daily press briefing.

The application aims to keep the user informed about COVID-19, because having people better informed about the current state of COVID-19 in the UK will help them make informed decisions about their own risk management.

This application is designed for both users who want an alarm clock to keep them informed, as well as developers who would like to use or extend the project's functionality.

Installation

Use the package manager pip to install the covid alarm clock, alongside it's prerequisites.

The program uses:

• pyttsx3
• Flask
• requests

pip install pyttsx3
pip install Flask
pip install requests

Usage and Initial Configuration

Before attempting to use the alarm clock, you should take a look at the configuration file (config.json). You should sign up for an API key for the news API and weather API. Then you will need to paste these API keys into the relevant section of the configuration file (explained in the 'Further Configuration' section).

To use the alarm clock, simply run the main.py module. This can be done on most systems by running python main.py from the terminal while in the directory where the Python module is located. If you have Python2 and Python3, you should run python3 main.py instead.

If you have successfully installed all of the application's prerequisite modules listed in the installation step above, the application should begin to run. It will run a local webserver which will act as the user interface for the application.

To access this interface, go to your web browser, and enter 127.0.0.1:5000 into the URL (search) bar. This should take you to the application's user interface. From there you can create new alarms by filling in the form and clicking 'submit'. All alarms will be listed on the left-hand-side of the site. You can also remove any alarms by clicking on the little 'x' on the top-right of the alarm. All notifications will be on the right-hand-side of the site. Notifications will pop up automatically.

Further Configuration

Preface

It is imperative that you set up your API keys, which is explained as part of the Usage section of this README file, but there is the opportunity for further configuration.

Project configuraiton

"app-name": "ECM1403 CA3 Smart Alarm",
"static-file-paths": {
    "favicon": "/static/images/pill.png",
    "image": "image.jpg"
}

• app-name refers to the name of the application that is listed on the web UI.
• static-file-paths includes the absolute path of the favicon, starting from the directory where the main.py module is located, and the name of the image assuming the image is in the /static/images file path.

Configuring external services

"external-services": {
    "refresh-rate": 3600
}

• external-services is the list of external APIs that this application uses, and it includes news, weather, and covid. Each of these have their own configuration that will be further explained.
• refresh-rate is how often (in seconds) the application will try to fetch the latest news, weather, and COVID data. It is recommended to keep this value at at least 600 seconds, since the APIs may block your API key if too many requests are sent. By default this is set to 3600 seconds, i.e. an hour. The APIs will, themselves, only update ever so often, (i.e. the news API updates hourly), so it is inadvisable to have a low refresh-rate time.

News

"news": {
    "url": "https://newsapi.org/v2/top-headlines?",
    "api-key": "c8e82381ca4e4d7598c52e6aeecd3b21",
    "use-sources": "y",
    "sources": "bbc-news",
    "country": "gb",
    "category": "health",
    "search-term": "covid"
}

• url refers to the URL that the application will make a request to. It is very unlikely you will need to modify this.
• api-key refers to your own API key. You will need to sign up to NewsAPI to obtain your own API key. Your key should be kept private and you should never share it, not even with other developers if you are requesting support!
• use-sources means whether the news API should choose to filter by sources. This should be either set to y for true, or any other value for false. Please note that if use-sources is y then it will use sources (such as BBC news), but it will not filter by country (such as GB), or by category (such as health). Any search-term provided will be used regardless of use-sources.
• sources refers to the sources that should be considered, such as bbc-news.
• country refers to countries that should be considered, such as gb for Great Britain (United Kingdom).
• category refers to categories that should be considered, such as health.
• search-term refers to a search term to filter articles by, such as covid to only get articles that include the term covid.

A list of valid sources can be found here. At least one source, country, or category must be provided. Search term is optional.

Weather

"weather": {
    "url": "http://api.openweathermap.org/data/2.5/weather?",
    "api-key": "93a1eca7115f5a3a87a421e2e51bb925",
    "city": "Exeter",
    "units": "metric",
    "notify-automatically-for": {
        "thunderstorm": "y",
        "drizzle": "y",
        "rain": "y",
        "snow": "y",
        "atmosphere": "y",
        "clear": "y",
        "clouds": "y"
    }
}

• url refers to the URL that the application will make a request to. It is very unlikely you will need to modify this.
• api-key refers to your own API key. You will need to sign up to OpenWeatherMap to obtain your own API key. Your key should be kept private and you should never share it, not even with other developers if you are requesting support!
• city refers to the city to get weather data for, such as Exeter.
• units refers to the units of temperature measurement. Available options are: standard (Kelvin), metric (Celcius), and imperial (Faranheit).
• notify-automatically-for is either yes (y) or no (anything else) for each of the options. This works such that when the application requests the weather from the API, if the weather has changed since last request, and the weather is a type of weather we care about (such as snow), then it will produce a notification. Available weather types to notify for include: thunderstorm, drizzle, rain, snow, atmosphere (such as mist), clear, and clouds.

Covid

"covid": {
    "filter-by": "nation",
    "nation": "England",
    "region": "Exeter"
}

• filter-by refers to what to filter the COVID data by. Available options are: overview, nation, and region.
  • overview will give an overview of the whole UK, but since only England counts deaths, any death data will not be available.
  • nation will give an overview of the provided nation, and if that nation counts deaths, death data will be available.
  • region will give an overview of the provided region, and if that region is in a nation that counts deaths, death data will be available.
• nation refers to the nation to filter by. Available options are: England, Wales, Scotland, and Northern Ireland.
• region refers to the region of the UK. For example, South West refers to the area that covers Devon (alongside other counties).

Common Pitfalls

Configuration

• When making adjustments to the configuration file, config.json, a common mistake is making an error with regards to the syntax of the file. Make sure that after editing the config file that it can successfully parse an online JSON parser, such as this one.

• When making adjustments to the images, it is common to forget to include the file extension, or be using the wrong file extension. If the file is called image.png, then having "image": "image" or "image": "image.jpg" will mean that the application is unable to access (and therefore render) the image.

• When making adjustments to the images, it is common to forget that, as stated in the Usage section of this README, that the favicon requires an absolute file path starting from the directory where the main.py module is located, whereas the image assumes that there are directories /static/images in the directory where the main.py module is located.

External Libraries

• There is no guarantee of reliability in terms of service or uptime from any external library that this application uses. If an external library is down, there will be information in the LOG file.

Module Imports

• This application uses the modules listed in the Installation stage of this README. It is possible that you were unable to successfully install these modules, which would cause errors with running this application. It is recommended to read the pip installation instructions for your OS for any module you are having difficulty installing. You should contact the developer of the specific module(s) that you are having difficulty installing for further support as we are not responsible for the development, maintenance, or support of these modules.

Extending or Contributing

It is possible to extend this project for your own use. This project is covered by the license located in the LICENSE.md file.