co2monitor 1.0

See the current co2 emissions per kWh of electricity in the Netherlands

Table of Contents

1. CO2 monitor
   1. cli
   2. tray
   3. screen
2. Installation
   1. Development
3. Pins
   1. Screen

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:

$ 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.

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 really ugly system tray icon showing the CO₂ emissions rounded to the nearest natural number, shown here below the tooltip:

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, pillow) 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.

Pins

https://pinout.xyz/

Screen

Product

Name	Function	Color	Pin number	GPIO
VCC	Power	Grey	1	-
GND	Ground	Brown	6	-
DIN	SPI MOSI	Blue	19	10 (SPI0 MOSI)
CLK	SPI Clock	Yellow	23	11 (SPI0 SCLK)
CS	SPI chip selection	Orange	24	8 (SPI0 CE0)
DC	Data/Command selection	Green	22	25
RST	Reset	White	11	17
BUSY	Busy status output	Purple	18	24