Scopae

Turn your Kindle into an energy-efficient waste collection calendar.

Tested and working configurations

Firmware	Working on devices
5.13.6	KT4

To make it work with other configurations, minor adjustments for lipc-properties in kindle_system.py and schedule.sh may be necessary.

Prerequisites

1. Make sure there is a scraper for your local waste collection provider's schedule or maybe contribute it yourself
2. A jailbroken Kindle
3. KUAL
4. Python >= 3.9.8 (NiLuJe's recommended)
5. NiLuJe's ScreenSavers Hack

Installation

1. Download the latest Scopae release
2. Unzip and move extensions/ and scopae/ to the root directory of your Kindle
3. Set configurations (scopae/core/config.json and the one of your provider's scraper)
4. Ensure Wi-Fi connection
5. Via KUAL execute Scopae/Setup environment and wait
6. Via KUAL execute Scopae/Start Scopae

Configuration (scopae/core/config.json)

provider

Expected value: String
Specifies which scraper script to use. The program attempts to locate the script at:
/mnt/us/scopae/scraper/provider/<provider>/main.py

---

types

Expected value: [String]
Specifies the types of waste to display and, depending on the scraper logic, potentially to exclusively scrape.

The following list shows all currently supported values and their meanings:

value	description
residual	residual waste / general waste bin
plastic	recyclables / yellow bin
paper	paper / blue bin
organic	organic waste / green bin
tree	tree pruning collection
toxic	hazardous waste collection
christmas_tree	Christmas tree collection

---

data_update_schedule

Expected value: int or null
Specifies the number of days since the last successful scrape after which an automatic data update is triggered on the next program execution.

If no regular updates of this kind are desired, set the value to null.
Independent of this parameter, scrapes are still triggered if required data is missing.

---

update_hours_after_midnight

Expected value: int
Specifies how many hours after midnight on the day of the next collection date the display should be updated. During this update, the currently displayed date is replaced with the following one.

The value can be any positive or negative number.

---

preview

Expected value: [dict]
Defines the schema used for displaying collection dates in the preview bar. The next upcoming date shown prominently in the main section is excluded.

---

preview_type

Expected value: String
Specifies the schema used for displaying dates in the preview bar.

The following modes are supported:

value	preview_config	description
static	X	Displays the next collection date for each specified waste type and preserves the given order.
dynamic		Displays the next collection date for each specified waste type, sorted by date.
upcoming	X	Displays the next X collection dates of any type, sorted by date.

---

preview_config

Expected value: Any
Any configuration value for the preview_type.

preview_type	expected value	description
static	[String]	The waste types in the order to be displayed.
dynamic	null
upcoming	int	The number of events to display.

---

Example:

{
  "provider": "alw",
  "types": ["residual", "paper", "plastic"],
  "data_update_schedule": 30,
  "update_hours_after_midnight": 10,
  "preview": [
    {
      "preview_type": "upcoming",
      "preview_config": 5
    }
  ]
}

• This configuration uses the scraper located at: /mnt/us/scopae/scraper/provider/alw/main.py.
• The displayed waste types are residual, paper, and plastic waste.
• On the first execution occurring at least 30 days after the last data update, a new data fetch is automatically triggered.
• When the day of the next collection date (shown prominently in the main section) is reached, the display is updated at 10:00 AM, replacing it with the subsequent date.
• The preview bar displays the next 5 upcoming collection dates of any type, sorted by date.

Contribute a Scraper

Your scraper should be stored in scopae/scraper/provider/<provider> and implement the abstract class BaseScraper in a class named Scraper in the file scopae/scraper/provider/<provider>/main.py.

Structure

scopae/
├── clear_logs.sh               # clears all logs
├── force_update.sh             # deletes present schedule data und calls start.sh.
├── kill_schedule.sh            # kills schedule.sh
├── lib.sh                      #
├── schedule.sh                 # manages the scheduled execution of the program via RTC wake-up and monitoring of the Kindle device's power states
├── setup.sh                    # sets up the venv and installs dependencies
├── start.sh                    # kills schedule, starts the python program and prints ss on screen
│
├── common
│   ├── csv_handler.py          # handles csv operations - csv is used to store the schedule in an accessible way
│   ├── data.py                 # contains all data classes
│   ├── exceptions.py           # custom exceptions
│   └── settings.py             # advanced configurations
│
├── core
│   ├── config.json             # user configurations
│   ├── kindle_system.py        # manages interaction with the kindle system
│   ├── main.py                 # main program entry point
│   └── renderer.py             # processes the data and renders it as an image
│
└── scraper
    ├── base_scraper.py         # scraper interface
    └── main.py                 # manages scrape requests