pskowronek/epaper-clock-and-more

e-paper clock + weather + AQI + traffic delays - using Waveshare 2.7inch & 4.2inch eink displays running on Raspberry Pi

Language versions:

Clock + weather + AQI + traffic - on Raspberry Pi & e-paper

This is a forked project of waveshare-clock that only displayed clock and weather and supported only Waveshare 4.2inch B&W displays. This project enhances the original project to support Waveshare 2.7inch displays with red dye (BWR) and adds the following additional features:

• gauges for current traffic drive times for two configured destinations (thanks to Google Maps API)
• gauge for air quality index (AQI) of home location (thanks to Airly.eu API or World Air Quality Index API)
• weather gauge can display:
  • current temperature + weather status icon plus forecast: daily min/max temperatures (thanks to OpenWeather API & Weatherbit.io)
  • alerts issued by EU countries (thanks to meteoalarm - limited support for EU countries i.e. where ATOM feed is available)
• buttons support to display detailed information about: weather, air quality, traffic and system information (on supported devices, i.e. 2.7inch HUT with switches)
• font with relaxed license already included in the project

For both new gauges one may configure warning levels - in such a case the particular gauge becomes red (on supported devices, i.e. 2.7inch BWR).

Screenshots / Photos

Screenshots

Photos

More photos of the assembled e-paper 2.7inch display sitting on top of Raspberry Pi zero enclosed in a custom-built LEGO™ housing and running this project are here.

BTW, these LEGO bricks are almost 30 years old (!)

Hardware Requirements

• Raspberry Pi Zero or similar
• e-paper display 2.7inch HUT or e-paper display 4.2inch B&W display with SPI
• 8-16GB SD card

Installation

• install Raspbian on SD card using this instruction
• enable and configure WiFi before you start the system - more here
• enable ssh (but be careful - don't expose ssh port to internet, or change the password ASAP) - on SD card create ssh file, it can be empty (for example touch /Volumes/boot/ssh)
• find the IP of RPi by scanning your local network or take a look at your router to find a new device connected to your network
• SSH to your raspberry: ssh [email protected]
• Python 3 should be already present, you may want to verify this by running: python3 --version
• check if SPI (required by display) is enabled: sudo raspi-config
• install git: sudo apt install git
• install python pip: sudo apt install python3-pip
• install the following packages as they might be required by Pillow:
  • libopenjp2-7: apt-get install libopenjp2-7
  • libtiff5: apt-get install libtiff5
• on Raspberry Pi OS Bullseye you may need to do the following:
  • set gpio group for /dev/gpiomem: sudo chgrp gpio /dev/gpiomem && sudo chmod g+rw /dev/gpiomem
  • add gpio group to user: sudo adduser USER gpio
• issue the command to fetch this project: git clone https://github.com/pskowronek/epaper-clock-and-more.git
• go to the project directory: cd epaper-clock-and-more and install required python modules: pip3 install -r requirements.txt
  • if it fails then please try to analyze any error statements and follow instructions if provided
  • the most common issue is Pillow's requirement regarding libjpeg - if it is the case then invoke sudo apt-get install libjpeg-dev and retry pip3 install
  • before you report a bug, try to google it first :)
• rename run-EDIT-ME.sh to run.sh and edit run.sh to configure:
  • your home location (lon & lat)
  • two destinations to check traffic delays
  • a key for traffic information from Google Maps - you can get it here *)
    • it is wise to read Google Maps documentation
    • tl;dr: basically you have to enable Distance Matrix API - follow these instructions, then you have to enable billing for it - just go there - don't worry, they won't charge you if you are below the limits
  • a key for weather forecasts from OpenWeather - you can get it here or *)
    • One Call API is being used to replace DarkSky provider
    • 2024.04 update: since One Call 2.5 access close(d) in June 2024, now 3.0 is being used. This requires a separate subscription to Open Call 3.0 (free tier, but billing data required) - see here
  • a key for weather forecasts from Weatherbit.io - you can get it here *)
    • alternative weather forecasts provider
  • a key for Air Quality Index data from Airly.eu - you can get it here *)
    • alternatively you can use World Air Quality Index API - you can get it here *)
    • WAQI (aqicn.org) works as a fallback if you don't specify any token for Airly
  • by configuring meteoalarm related settings, weather forecasts can be supplemented with alerts originating from meteoalarm.org site
    • limited to EU countries that have ATOM feeds on above page (a limitation of meteoalarmapi library)
    • there might be issues (no readings) if chosen province name contains diacritic characters - to be investigated
  • type of e-paper device, whether it is 2.7 or 4.2 (by default it is pre-configured for 2.7" BWR)
  • tweak additional settings to:
    • prefer local temperature readings as served by Airly instead of weather provider(s)
    • display warnings using black font instead of white on red canvas (more readable if red dye faded out)
    • switch 2.7 BWR into BW
    • turn off displaying hours & minutes separator
    • enable/disable debug mode, buttons etc
• run the script: ./run.sh (hit Ctrl-C to exit) and verify if it works as expected
• install this project as a service so it could automatically run when Raspberry boots up (more details here)
  • copy epaper.service to /etc/systemd/system: sudo cp epaper.service /etc/systemd/system/ **)
  • verify if service works by invoking the following command: sudo systemctl start epaper.service
  • enable this script so it could be run on system start: sudo systemctl enable epaper.service
  • reboot device to verify if it works
  • if you needed to modify epaper.service issue this command: sudo systemctl daemon-reload
  • logs can be observed in /var/log/syslog: sudo tail -f /var/log/syslog | grep run.sh
• recommended system change in case of network outage (see #18)
  • add the following line to /etc/resolv.conf: options timeout:2 attempts:1 (only 1 attempt for resolving names with 2s timeout)

*) By default data are being fetched every 10+ minutes so they should comply with developer free accounts limitations

**) If your project directory is different than /home/pi/epaper-clock-and-more then you must edit this file to reflect the correct path

Tech details

2.7inch & 4.2inch support

Since the original project supported 4.2inch B&W displays only, the code has been modified to support also 2.7inch B+W+R displays. This has been done by adding a second red canvas and down-sizing the black and red canvases to smaller resolutions as required by 2.7inch displays.

2.7inch display refresh

E-paper 2.7inch by Waveshare does not support partial refresh and every modification of displayed data requires full refresh which takes around 5s meantime flickering a lot.

2.7inch display refresh made faster

You may try to turn on experimental feature to make display refresh much faster (10x quicker for black dye, 2-3 times quicker for red dye). This has been achieved by modification of LUT tables of original epd2in7b.py Waveshare library. The LUT tables are used by the display to create "waveforms" that refresh every pixel. This of course has negative consequences - the refresh isn't perfect (but still okey) and artifacts may build-up with time. To recover the display you would need to turn off this feature and run the project for a while using original LUT tables. To see how the tables were modified issue this command: diff epd2in7b.py epd2in7b_fast_lut.py

The idea of modifying the LUT tables has been described here for 4.2" displays. Since I don't have 4.2" display I didn't try to provide similar feature for it.

To enable this feature set the following environment variable: export EPAPER_FAST_REFRESH=true

TODOs

• rework drawing.py (make it a class and gagues rendered w/o knowledge about their final placement)

License

Since this project is a fork, the original licenses still apply. The modifications and enhancements are being done under Apache 2 license and MIT (dual licence).

Authors

• Piotr Skowronek
• Original author

epaper-clock-and-more's Issues

Aqicn error

Hello,

Thank you for all these updates, they are turning out great!

I'm having a problem with the new Aqicn. I have the correct key on run.sh and commented AIRLY key definition:

# A key for AQI (Air Quality Index) from AIRLY.EU API (data for certain countries only, as yet, but you may order their device to provide data also for your neighbours)
#export AIRLY_KEY=GET_YOUR_OWN_KEY           # get the key from: https://developer.airly.eu/register

I'm getting the following error, and a "-1" always displayed on the air quality index (replaced my key by X's)":

Getting a Aqicn status from the internet...
Starting new HTTPS connection (1): api.waqi.info
https://api.waqi.info:443 "GET /feed/here/?token=XXXXXXXXXXXXXXXXXXXXXXXXXX HTTP/1.1" 200 None
'h'
Traceback (most recent call last):
  File "/home/pi/eInk/epaper2/epaper-clock-and-more/providers/aqicn.py", line 63, in get
    hummidity=aqicn_data["data"]["iaqi"]["h"]["v"] if aqicn_data["data"]["iaqi"]["h"] else -1,
KeyError: 'h'
--- aqi: [-1, -1, -1, -1, null, -1, "n/a", "n/a"]

I'm also using the definition "here", and tried "lisbon", since that is the city I want to monitor:

# AQICN City or ID (see: https://aqicn.org/search/) to use instead of LAT&LON coords, if you set it to 'here' then it is going to be based on IP geolocation
export AQICN_CITY_OR_ID=here

No module named 'acquire'

uname -a:
Linux micro 5.10.63-v7+ #1459 SMP Wed Oct 6 16:41:10 BST 2021 armv7l GNU/Linux
python3 --version:
Python 3.9.2
python3 -m pip --version:
pip 20.3.4 from .../epaper-clock-and-more/venv/lib/python3.9/site-packages/pip (python 3.9)
python2 --version:
Python 2.7.18

Upon running trying to run I receive the following error;

Traceback (most recent call last):
  File ".../epaper-clock-and-more/main.py", line 43, in <module>
    from epaper import EPaper
  File ".../epaper-clock-and-more/epaper.py", line 10, in <module>
    from providers.airly import Airly
  File ".../epaper-clock-and-more/providers/airly.py", line 4, in <module>
    from acquire import Acquire
ModuleNotFoundError: No module named 'acquire'

Even after installing the required package the error remains;

Collecting acquire
  Using cached https://www.piwheels.org/simple/acquire/acquire-0.1.2-py3-none-any.whl (255 kB)
  Downloading https://www.piwheels.org/simple/acquire/acquire-0.1.1-py3-none-any.whl (244 kB)
     |████████████████████████████████| 244 kB 201 kB/s 

Currently running Raspbian bullseye

AIRLY get with some problem

Hello!

I'm unable to get information from AIRLY.
The logs state the following information:

Apr 23 02:05:48 raspberrypi run.sh[422]: load cache file: /home/pi/.epaper-display/cache/airly.json
Apr 23 02:05:48 raspberrypi run.sh[422]: list index out of range
Apr 23 02:05:48 raspberrypi run.sh[422]: Traceback (most recent call last):
Apr 23 02:05:48 raspberrypi run.sh[422]:   File "/home/pi/eInk/epaper-clock-and-more/providers/airly.py", line 64, in get
Apr 23 02:05:48 raspberrypi run.sh[422]:     pm25=airly_data["current"]["values"][1]['value'],
Apr 23 02:05:48 raspberrypi run.sh[422]: IndexError: list index out of range
Apr 23 02:05:48 raspberrypi run.sh[422]: --- airly: [-1, -1, -1, -1, null, -1, "n/a", "n/a"]

I have the key correctly added to run.sh and selected the following configuration (since I cannot get a key from dark sky):

# Whether to prefer Airly.eu local temperature if available instead of current temperature returned by DarkSky. Metric (Celsius) temperature only.
export PREFER_AIRLY_LOCAL_TEMP=false

Is this something that i'm doing wrong?

Thank you!

Add another weather provider - weatherbit.io

Add another weather provider - weatherbit.io

Supplement weather data with alerts provided by meteoalarm

Supplement weather with alerts provided by: https://www.meteoalarm.eu - this site only covers EU countries. Since this page sadly doesn't expose a normal API, ATOM or RSS feeds must be used.

As there's a python module for this site - meteoalarmapi I will use it. I've found the following limitations though:

• it uses ATOM feeds, which are not available across all EU countries
• the library or the use of the library may not work for province names that contain diacritics characters (the name must be specified in UTF-8 of course) - further investigation required, whether it is library fault or this project fault - TBD later

Lastly, the site itself, even though doesn't show ATOM feeds for some countries (like France) it still returns some data for some (not all) regions/provinces

Migrate the code to Python 3

Migrate the code to Python 3

• dropping 2.7 compatibility
• remove DarkSky as it doesn't work anymore
• update readme.md

Generic Sugestions

Hello!

I don't know the best way to share this information, so I created an issue that I will close in the future. It is my first time using github, hope I'm not doing something wrong.

Please, add to readme.md some text that support the following information:

• Enable on Google API the following API: Distance Matrix API
• Enable billing on Google: https://console.cloud.google.com/billing/

In some areas the air quality is not usefull, since there aren't any sensors that support these measurements.
My suggestions is to add some sort of flag the file run.sh that remove this from the eInk screen and increase the size of the traffic boxes adding a simple 3 letter label to each one, manually defined on run.sh file. This way will be easy to differentiate each location.

Thank you.

Some text is unreadable

Hello!

It is working almost perfectly, just a small detail.
Some text is over other text.

https://photos.app.goo.gl/jcSMtsLmEEBDnZKp7

Thank you

Enabling SPI not mentioned

Thanks for the app, I've got it working following the instructions, but there is one thing left out if you want to make them truly comprehensive. No where does it mention enabling SPI, which is disabled by default on Raspian. As a complete beginner I didn't know this, and the error messages it throws up if you haven't got it enabled don't make it immediately obvious what the problem is. Could I suggest that the following might be worth adding for the sake of instruction completeness -

If you are using Raspian Linux 3.18 or later you need to go into the raspberry pi config utility and enable SPI.
sudo raspi-config
Select 3 Interfacing Options and then P4 SPI - Enable/Disable automatic loading. A prompt will appear asking Would you like the ARM SPI interface to be enabled?, select Yes, then select OK on the next prompt and then Yes, then OK and then select Finish to exit the utility and then you need to reboot your Raspberry Pi.
sudo reboot

Add other ways of locomotion

Hello,

Is it possible to add an option for selecting, for instance, bicycle as the way of locomotion on run.sh?

I think that the current configuration assumes always that we are traveling by car.

Thank you

Errors with pip install

Hj Piotr!
Very interesting project! I`ve have a Pi3A, Raspbian Stretch latest version, Python 2.7.13 and a Waveshare 2.7 BW e-Paper HAT. I followed your instructions, but when I try to pip install the requirements I get several errors.

Collecting Pillow==5.2.0 (from -r requirements.txt (line 8))

Downloading https://files.pythonhosted.org/packages/d3/c4/b45b9c0d549f482dd072055e2d3ced88f3b977f7b87c7a990228b20e7da1/Pillow-5.2.0.t
100% |████████████████████████████████| 14.5MB 14kB/s
Collecting pil-compat==1.0.0 (from -r requirements.txt (line 11))
Downloading https://files.pythonhosted.org/packages/50/8e/c579535d35e944817d838d200ede3ee5bb405e839d0395c45cf700834ee8/pil_compat-1.0
e-any.whl
Collecting pillow-pil==0.1dev (from -r requirements.txt (line 14))
Downloading https://files.pythonhosted.org/packages/5d/e1/d298934cd78984a5e8d616945349ed66a74b9df0337fb1941ce76b8a2b7b/Pillow-PIL-0.1
Collecting pytz==2018.5 (from -r requirements.txt (line 17))
Downloading https://files.pythonhosted.org/packages/30/4e/27c34b62430286c6d59177a0842ed90dc789ce5d1ed740887653b898779a/pytz-2018.5-py
.whl (510kB)
100% |████████████████████████████████| 512kB 565kB/s
Collecting requests==2.18.4 (from -r requirements.txt (line 22))
Exception:
Traceback (most recent call last):
File "/usr/lib/python2.7/dist-packages/pip/basecommand.py", line 215, in main
status = self.run(options, args)
File "/usr/lib/python2.7/dist-packages/pip/commands/install.py", line 353, in run wb.build(autobuilding=True)
File "/usr/lib/python2.7/dist-packages/pip/wheel.py", line 749, in build self.requirement_set.prepare_files(self.finder)
File "/usr/lib/python2.7/dist-packages/pip/req/req_set.py", line 380, in prepare_files ignore_dependencies=self.ignore_dependencies))
File "/usr/lib/python2.7/dist-packages/pip/req/req_set.py", line 554, in _prepare_file require_hashes
File "/usr/lib/python2.7/dist-packages/pip/req/req_install.py", line 278, in populate_link self.link = finder.find_requirement(self, upgrade)
File "/usr/lib/python2.7/dist-packages/pip/index.py", line 465, in find_requirement all_candidates = self.find_all_candidates(req.name)
File "/usr/lib/python2.7/dist-packages/pip/index.py", line 423, in find_all_candidates for page in self._get_pages(url_locations, project_name):
File "/usr/lib/python2.7/dist-packages/pip/index.py", line 568, in _get_pages page = self._get_page(location)
File "/usr/lib/python2.7/dist-packages/pip/index.py", line 683, in _get_page return HTMLPage.get_page(link, session=self.session)
File "/usr/lib/python2.7/dist-packages/pip/index.py", line 792, in get_page "Cache-Control": "max-age=600",
File "/usr/share/python-wheels/requests-2.12.4-py2.py3-none-any.whl/requests/sessions.py", line 501, in get return self.request('GET', url, **kwargs)
File "/usr/lib/python2.7/dist-packages/pip/download.py", line 386, in request return super(PipSession, self).request(method, url, *args, **kwargs)
File "/usr/share/python-wheels/requests-2.12.4-py2.py3-none-any.whl/requests/sessions.py", line 488, in request resp = self.send(prep, **send_kwargs)
File "/usr/share/python-wheels/requests-2.12.4-py2.py3-none-any.whl/requests/sessions.py", line 609, in send r = adapter.send(request, **kwargs)
File "/usr/share/python-wheels/CacheControl-0.11.7-py2.py3-none-any.whl/cachecontrol/adapter.py", line 47, in send resp = super(CacheControlAdapter, self).send(request, **kw)
File "/usr/share/python-wheels/requests-2.12.4-py2.py3-none-any.whl/requests/adapters.py", line 423, in send timeout=timeout
File "/usr/share/python-wheels/urllib3-1.19.1-py2.py3-none-any.whl/urllib3/connectionpool.py", line 643, in urlopen_stacktrace=sys.exc_info()[2])
File "/usr/share/python-wheels/urllib3-1.19.1-py2.py3-none-any.whl/urllib3/util/retry.py", line 315, in increment total -= 1
TypeError: unsupported operand type(s) for -=: 'Retry' and 'int'

When I try to execute the run.sh the output is:

Traceback (most recent call last):
File "main.py", line 36, in
import sdnotify
ImportError: No module named sdnotify

Any idea what went wrong?

Thanks in advance and reards from Berlin
Wominator

Dark Sky no longer accepting sign ups - alternatives req'd

Hello,

I'm unable to generate a key for Dark Sky:

darksky blog

We are no longer accepting new signups. Please see our blog post for more information! We apologize for any inconvenience this causes.
The Dark Sky Team

Do you know if is there any alternative that I can use?

Thank you

meteoalarm fails to receive alerts

1. meteoalarm.eu moved to meteoalarm.org plus they have changed API
2. Apparently the naming convention has changed recently on meteoalarm.org (https://feeds.meteoalarm.org/) - previously abbreviated country name was used in atom feeds, now it is full country name (pl -> poland).

ad 1):

Starting new HTTP connection (1): meteoalarm.eu
http://meteoalarm.eu:80 "GET /ATOM/PL.xml HTTP/1.1" 302 206
Starting new HTTPS connection (1): meteoalarm.org
https://meteoalarm.org:443 "GET / HTTP/1.1" 200 None
syntax error: line 1, column 0

Traceback (most recent call last):
  File "meteoalarm.py", line 36, in acquire
    return 200, json.dumps(meteo.get_alert())
  File "..... meteoalertapi/meteoalertapi.py", line 34, in get_alert
    feed_data = xmltodict.parse(text)
  File "..... xmltodict.py", line 327, in parse
    parser.Parse(xml_input, True)

Add timeout to data providers

Due to how data from providers are being fetched it may happen when there's no internet connection that EPaper service will be killed by watchdog and wrong time will be displayed constantly on display.

Quick workaround is to add time outs (2s for connection, 4s for read) + newer version of meteoalertapi.

Ideally it would be nice to:

• implement timeouts this way: https://www.peterbe.com/plog/best-practice-with-retries-with-requests (where also retry count can be specified)
• let clock refresh display without waiting for data

Allow to turn off Airly (for locations without their coverage)

Allow to turn off Airly (for locations without their coverage).

The question is whether any other vendor shouldn't be used instead?

DarkSky started to return nearestStormDistance set 0 no matter storm presence

DarkSky started to return nearestStormDistance set to 0 no matter storm presence (that started happening like 2 months ago).

Their https://darksky.net/dev/docs state that this key&value is optional, and 0 means storm in close vicinity. Previously, the key was not sent in json when there was no storm.

A report has been sent to DarkSky, meanwhile I will ignore the value if is 0.

Problem with Pillow

Hello,

I've had this eInk display laying around for a few months, and since corona gave me some free time, I tried to used it with a rasp zero w, but i'm facing some problems.

Here is what i'm using:

pi@raspberrypi:~/eInk/epaper-clock-and-more $ uname -a
Linux raspberrypi 4.19.97+ #1294 Thu Jan 30 13:10:54 GMT 2020 armv6l GNU/Linux

pi@raspberrypi:~/eInk/epaper-clock-and-more $ pip --version
pip 18.1 from /usr/lib/python2.7/dist-packages/pip (python 2.7)

I'm facing the following problems white installing requirements:

 The headers or library files could not be found for jpeg,
  a required dependency when compiling Pillow from source.

  Please see the install instructions at:
     https://pillow.readthedocs.io/en/latest/installation.html

  Traceback (most recent call last):
    File "<string>", line 1, in <module>
    File "/tmp/pip-install-YFB6iY/Pillow/setup.py", line 807, in <module>
      raise RequiredDependencyException(msg)
  __main__.RequiredDependencyException:

  The headers or library files could not be found for jpeg,
  a required dependency when compiling Pillow from source.

  Please see the install instructions at:
     https://pillow.readthedocs.io/en/latest/installation.html

`
Command "/usr/bin/python -u -c "import setuptools, tokenize;file='/tmp/pip-install-9ZBpfT/Pillow/setup.py';f=getattr(tokenize, 'open', open)(file);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, file, 'exec'))" install --record /tmp/pip-record-VASzCt/install-record.txt --single-version-externally-managed --compile --user --prefix=" failed with error code 1 in /tmp/pip-install-9ZBpfT/Pillow/

`

Can you provide me with some guidance?

Thank you

AQICN - alternative provider for AQI

World Air Quality Index aka AQICN (aqicn.org) as an alternative provider for AQI.

It should work as a fallback for Airly (if airly key is not specified).

Display 'init' view to show that app is starting

Display 'init' view to show that app is starting.

It may take awhile before clock is displayed due to external data that need to be fetched.
Also useful when there's network outage and it may happen that watchdog engages and kills the app.