CO2 monitor

This projects monitors the current CO₂ emissions per kWh of electricity being generated in the Netherlands. It obtains the data from ned.nl, and gets updated every 15 minutes. It has three modes:

cli

This mode polls the API once per minute and outputs it in the current format:

2024-11-29 19:30: 310.45g CO2/kWh

tray

This creates a system tray icon showing the CO₂ emissions rounded to the nearest natural number, shown here below the tooltip:

On hover it shows more details, and on click it opens https://co2monitor.nl

screen

This mode shows the current emisions a small EPD screen connected to some GPIO pins of the Raspberry Pi. It assumes that we are running on a Raspberry Pi, and fails otherwise.

See here a photo of how it looks on my 2.9 inch screen:

It uses the current locale (specifically, LC_TIME) to determine how the date looks. See Pins for an overview of what pins need to be connected to the screen.

Installation

I show pip commands here. However, pip isn’t ideal for this: use pipx or, as I do, uv (uv tool install co2monitor[tray], for example).

$ pip install co2monitor

Is sufficient for the cli mode. The other modes require rather large libraries and are therefore excluded from the base package. Install the dependencies required for the tray mode (Qt) with

$ pip install co2monitor[tray]

And, shockingly,

$ pip install co2monitor[screen]

For the screen mode. This installs pillow, RPi.GPIO and spidev.

Development

See the Makefile for some handy dev commands. I use uv to manage my dependencies, but it does not really matter all that much.

pyproject.toml has an Entry Point, which means that it installs a binary called co2monitor in the virtual environment. If you have the virtual environment activated, you can run co2monitor. For uv, you can execute uv run co2monitor to run the project.

Usage

$ co2monitor --help

Usage: co2monitor [OPTIONS] COMMAND [ARGS]...

  Shows the current CO2 emissions per kWh of electricity in the Netherlands.

Options:
  --debug / --no-debug
  --api-key TEXT        Override API_KEY environment variable.
  --api-url TEXT        [default: https://api.ned.nl/v1]
  --user-agent TEXT     Override USER_AGENT environment varaible.
  --polltime INTEGER    [default: 60]
  --version             Show the version and exit.
  -h, --help            Show this message and exit.

Commands:
  cli     Print emissions to the commandline.
  screen  Show emissions on an EPD screen connected via GPIO.
  tray    Add a system tray icon with emissions.

Pins

https://pinout.xyz/

Screen

Product