harlow-bindicator 3.1.1

Send alert the day before and on the day of bin collection in Harlow

Harlow Bindicator

Table of Contents

• Introduction
• Features
• Installation
  • Prerequisites
  • PyPI Installation
  • Manual Installation
• Configuration
  • Required Parameters
• Usage
  • Running as a GitHub Action
  • Running Locally
  • Command Line Options
  • Scheduling with Cron
• Examples
• Notification Format
• Troubleshooting
• FAQ
• Architecture
• Contributing
• License
• Acknowledgements

Introduction

Harlow Bindicator is an automated tool that helps Harlow residents stay informed about their bin collection schedules. The application scrapes the Harlow Local Authority website to retrieve bin collection dates for a specified property and sends timely notifications through ntfy.sh when bins need to be put out. Never miss bin day again!

A "bindicator" is a notification system for bin collection days - the name is a blend of "bin" and "indicator."

Features

• Automatically retrieves bin collection dates from the Harlow Local Authority website
• Sends notifications when bins need to be put out
• Specifies which bin type needs collection (recycling, general waste)
• Can be run locally or as a GitHub Action
• Easy setup and configuration
• Customizable notification options
• Cross-platform compatibility

Installation

Prerequisites

• Python 3.7 or higher
• Chromedriver (for web scraping)
• Internet connection
• A UPRN (Unique Property Reference Number) for your address
• A ntfy.sh topic for notifications

PyPI Installation

The easiest way to install Harlow Bindicator is via pip:

pip install harlow-bindicator

Manual Installation

If you prefer to install from source:

git clone https://github.com/joe-mccarthy/harlow-bindicator.git
cd harlow-bindicator
pip install -e .

Platform-Specific Dependencies

Debian/Ubuntu

sudo apt-get install chromium-chromedriver

macOS

brew install --cask chromedriver

Windows

Download ChromeDriver from https://chromedriver.chromium.org/downloads and add it to your PATH.

Configuration

Required Parameters

• UPRN: Unique Property Reference Number that identifies your property. You can find your UPRN at Find My Address.
• ntfy.sh Topic: Create a unique topic name at ntfy.sh to receive notifications.

Usage

Running as a GitHub Action

There's a workflow file in this repository, check-binday.yml, which is scheduled to run early each morning to check for bin collections.

To use this workflow:

1. Fork this repository
2. Add two repository secrets in your GitHub settings:
   • UPRN: Your property's Unique Property Reference Number
   • NTFY_TOPIC: Your ntfy.sh topic name
3. Enable GitHub Actions for your repository

The workflow will run automatically according to the schedule defined in the workflow file.

Running Locally

After installation, you can run Harlow Bindicator from the command line:

harlow-bindicator --uprn "12345678" --topic "your-topic-name"

Command Line Options

harlow-bindicator [OPTIONS]

Options:
  --uprn TEXT         UPRN for the property to check [required]
  --topic TEXT        ntfy.sh topic to publish notifications to [required]

Scheduling with Cron

To run automatically on Linux/macOS, add a cron job:

# Edit crontab
crontab -e

# Add this line to run at 7:00 AM every day
0 7 * * * /usr/local/bin/harlow-bindicator --uprn "12345678" --topic "your-topic-name"

Examples

Basic Usage

harlow-bindicator --uprn "12345678" --topic "bin-notifications"

Notification Format

When a bin collection is detected, you will receive a notification via ntfy.sh with:

• Title: "Bin Collection Tomorrow: [Bin Type]"
• Message: Information about which bin(s) need to be put out
• Priority: Default (adjustable in future versions)

Example notification:

Bin Collection Tomorrow: Recycling

Please put out your Blue Recycling bin tonight for collection tomorrow.

Troubleshooting

Common Issues

1. ChromeDriver Error:

   • Make sure ChromeDriver is installed and in your PATH
   • Check if the ChromeDriver version matches your Chrome version

2. No Notifications Received:

   • Verify your ntfy.sh topic is correct
   • Check if you're subscribed to the topic in ntfy.sh
   • Ensure your internet connection is stable

3. UPRN Not Working:

   • Double-check your UPRN is correct
   • Verify your property is within the Harlow Local Authority area

FAQ

Q: What is a UPRN?
A: A Unique Property Reference Number (UPRN) is a unique identifier for addressable locations in the UK. You can find yours at Find My Address.

Q: What is ntfy.sh?
A: ntfy.sh is a free, simple HTTP-based publish-subscribe notification service. It allows you to send notifications to your phone or desktop without setting up any accounts.

Q: How do I receive the notifications?
A: Download the ntfy app (Android, iOS), or use the web interface. Subscribe to your topic name.

Q: Does this work for areas outside Harlow?
A: No, this tool is specifically designed for the Harlow Local Authority website. Fork the project to adapt it for other regions.

Q: How accurate are the notifications?
A: The tool scrapes the official Harlow Council website, so the notifications are as accurate as the data provided by the council.

Architecture

Harlow Bindicator works by:

1. Using ChromeDriver to open a headless browser session
2. Navigating to the Harlow Council bin collection page
3. Submitting the UPRN to retrieve collection information
4. Parsing the returned data for upcoming collections
5. Determining if a notification is needed based on the collection dates
6. Sending a notification via ntfy.sh if a collection is scheduled within the specified timeframe

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• ntfy.sh for providing a simple notification service
• Selenium for web automation
• Harlow Council for providing the bin collection data
• All contributors who have helped improve this project