Islamic Prayer Times - ESP32 TTGO T-Display

374 Views, 4 Favorites, 0 Comments

Islamic Prayer Times - ESP32 TTGO T-Display

This is an Arduino IDE project that uses a readily-available development board that includes a small TFT screen - LilyGo TTGO T-Display - to retrieve and display Islamic prayer time data according to the geolocation of the user.

A short video of the device's operation is here.

ESP32 Dev. Board

The LilyGo TTGO T-Display is an ESP32 device and is available from all the usual outlets. The standard 'shell' available through the same stores makes a glaringly obvious omission - space for a battery! A 402030 or 402035 lithium battery is ideal and can be stuck to the back of this case/shell.

There are a number of freely-available .stl files for this board that incorporate space for a lithium battery. A search will reveal many to suit your needs. Here is one example.

There is almost no soldering required except for wiring the supplied JST connector to a battery. You can be up and running in a very short time once the Arduino IDE and necessary libraries are installed. Please refer to the ReadMe.md file in the GitHub repository.

APIs & Keys

Prayer data is retrieved from https://muwaqqit.com in JSON format via the site's JSON endpoint. This API requires the user's latitude and longitude coordinates along with other basic information to provide a full month's prayer data.

Geolocation information is retrieved from Google using the Google Maps API. This requires a personal API key. There are many resources to guide you through how to obtain the API key. You are responsible for managing API call frequency and any costs should you rack-up API calls over the free monthly allowance. This API is accurate enough for the purpose of the project.

A GPS module could have been implemented, but this adds unnecessary bulk to the device. The WiFiLocation library fully manages the retrieval of lat/long and accuracy data. Other 'free' services and libraries are available, like the GeoIP library. However, accuracy is hit-and-miss when connected to the internet via a mobile 'phone. Hard-wired internet connections return reasonably accurate geolocation data.

Be aware that in sparsely populated areas where WiFi access points are limited, geolocation accuracy may be compromised, leading to inaccurate prayer times.

Muwaqqit

There are a number of prayer-time APIs available. This is one of the most configurable, accurate and reliable sources for prayer data. The developer has thoroughly researched this science, gaining the approval of scholars of the subject. Please consider supporting Muwaqqit.

Arduino Sketch

I'm not the most accomplished or elegant coder. You may find that some parts/functions resemble example code from the installed libraries. I'm a great believer of not reinventing the wheel! I'm sure you'll find ways to streamline the code.

ArduinoJSON

This library is used to extract the required data to display on the TFT screen and serial port. The WiFiLocation library also uses ArduinoJSON. Please also consider supporting Benoit.

This project was started over four years ago, and stalled due to my lack of understanding how to extract JSON elements or how to use ArduinoJSON. Having purchased Benoit's book, and access to more examples, I was able to complete what I'd planned on achieving in a few days! My coding skills are rudimentary at best, so please go easy on me. :-)

WiFiManager

This library is incorporated to eliminate the need to hard-code one's WiFi credentials.

Supplies

Hardware

LilyGo TTGO T-Display Module (16M)

T-Display Shell

402030 Lithium Battery

402035 Lithium Battery

Software

Muwaqqit API Documentation

Arduino IDE

Google Maps API

GitHub Project Sketch

Arduino IDE

ESP32 Board Install - V2.0.17

If not already, install the Arduino IDE. You'll need to install ESP32 Board files. Instructions are available at a number of sites. Random Nerd Tutorials is a reliable source.

There have been some issues with the V3 release of Espressif's ESP32 Board library, which caused some compilation problems. Downgrading to V2.0.17 resolved the problems experienced. It may also be prudent to downgrade the Arduino ESP32 Board to V2.0.13

Libraries

Search for the following Libraries and install the versions shown:

ArduinoJSON - V7.2.1

ArduinoJSON provides an elegant and powerful solution to extracting JSON data.

TFT_eSPI - V2.5.43

TFT_eSPI library's setup file will need to be modified. Locate where TFT_eSPI is installed. Ensure the User_Setup_Select.h file is correctly configured for the TTGO T-Display ST7789 driver:

Comment out the line as below:

//#include <User_Setup.h> // Default setup is root library folder

Uncomment line as below:

#include <User_Setups/Setup25_TTGO_T_Display.h> // Setup file for ESP32 and TTGO T-Display ST7789V SPI bus TFT

WiFiLocation - V1.2.9

WiFiLocation leverages Google's Maps API to retrieve longitude and latitude coordinates without the need use a GPS receiver. The returned coordinates are extremely accurate!

WiFiManager - V2.0.17

This library is incorporated to eliminate the need to hard-code one's WiFi credentials. If no WiFi credentials are stored or the stored SSID is not present, an Access Point is enabled for you to launch the WiFi Configuration Portal.

Arduino Sketch

Download the latest version of the Sketch from GitHub and save it to your Sketch directory and open for editing.

Board Type & COM Port

Set the Board type to ESP32 Dev Module.

Plug in your TTGO board into an unused USB port. Select the correct COM Port linked to the Board.

Google API Key

Insert your Google Maps API Key in the line iindicated:

const char* googleApiKey = "Paste Your Google API Key Here";

Upload Sketch

You're now ready to compile and upload the code to the TTGO device. There shouldn't be any compilation errors and your device is ready for use. If you encounter any errors, review the reported errors, correct any issues and re-upload.

Sketch Function Descriptions

String fetchJSON() // Fetch JSON data from Muwaqqit

unsigned long timeToSeconds(const char* timeStr) // Function to convert time string HH:MM:SS to total seconds since midnight. Reason is to help determine which is the current prayer.

void drawflag() // Draw Palestinian Flag as a show of solidarity to all those being harmed and oppressed.

void batteryV() // Determine the charge state of the battery

void printLocalTime() // Function to print current local time and date

void checkButton() // Function to test if button pressed and held for 3 seconds to reset WiFi credentials

void print_wakeup_reason() // Send to serial device, the wake-up reason. For debug purposes

void setup() // Configuration and setup of screen, button, WiFi, Splash screen, and first retrieval & display of prayer data

void loop() // Update time and battery status on TFT. Repeat until Deep-Sleep entered after 60 seconds

Programme Flow

Here is a detailed description of the main points of the sketch.

Definition of all libraries used, initialisation of:
WiFiManager
WiFiLocation
TFT_eSPI
NTP Service
GPIO Pin definitions
definition of global variables
Setup() function
Configure TFT display
Initialise GPIO pins used
Configure Deep-Sleep wake-up button
Initialize Serial Port
Send to serial port the reason wake-up forced after Deep-Sleep
Draw flag
Display Config Portal details
Initialise WiFi config portal
If previously configured WiFi not available or WiFi not configured within 60 seconds, enter deep-sleep
Get time from NTP server
Send local time and date to serial port
Get and display prayer time data
Highlight current prayer time
Loop() function
Send local time to serial port
Update local time and date on TFT screen
Update battery status on TFT screen
Check if button on GPIO 35 pressed and held for 3 seconds
If button pressed and held, clear WiFi credentials from memory and restart device
If 60 seconds have elapsed after running Loop function, enter deep-sleep
Otherwise, repeat Loop().

Functionality

WiFi Configuration Portal

If no connection or no SSID defined, the WiFi Configuration Portal is enabled.

On a mobile device, connect to SSID "Muwaqqit-AP" - You may have to browse to 192.168.4.1

Select "Configure WiFi"

Choose WiFi network, enter password and select "Save"

Configuration portal will close and the device will connect to the chosen WiFi network and continue.

Reset WiFi SSID Credentials

If at any time you want to change the WiFi credentials, press and hold the top button for 3 seconds while prayer times are displayed to clear the current WiFi configuration.

Deep Sleep

To conserve battery life, the device is forced into Deep-Sleep mode in two places:

if the WiFi Configuration Portal has not been modified for 60 seconds,
after prayer times have been displayed for 60 seconds.

In 1. the device will remain in Deep-Sleep.

In 2. the device will restart after 60 minutes.

Wake-Up

As mentioned above, at certain points the device enter Deep-Sleep. You can force a Restart/Wake-up by pressing the lower button.

Serial Debug

With the Serial Monitor enabled, you'll see a flow of information being printed for you to verify that the device is functioning as expected, i.e geolocation data, prayer times API URL string, formatted prayer table etc.

Customising

A number of timers,delays and switches are used and are merely a starting point. The default timings are set for optimal viewing time and conservation of battery life. Here are the areas you might want to modify to your preference:

Time until Deep Sleep

This is the length of time the prayer times will remain on-screen before entering Deep-Sleep. Default value is 60000 milliseconds, denoting 60 seconds. Modify the variable 'interval' to your preference:

const unsigned long interval = 60000; // Interval before entering Deep_Sleep - 60 seconds

Deep-Sleep Period.

This is the time the device stays in Deep-Sleep mode until restarting. Default is 60 minutes. Modify the 'TIME_TO_SLEEP' variable to your desired preference:

#define TIME_TO_SLEEP 3600 /* Time ESP32 will go to sleep for... (in seconds) */

Reset WiFi SSID Credentials

If at any time you want to change the WiFi credentials, press and hold the top button for 3 seconds while prayer times are displayed to clear the current WiFi configuration and to restart the device, ready for the WiFi to be configured. You can change the length of time to hold the button by modifying this line:

delay(3000); // reset delay hold

WiFi Configuration Portal Timeout

Closes the WiFi Portal after 60 seconds on no action. Modify this line to your desired timeout:

wifiManager.setConfigPortalTimeout(60); // auto close config portal after 60 seconds

API Endpoint URL

Should you have a need to retrieve prayer times with different settings e.g for Fajr or Isha angles, please consult Muwaqqit's API documentation to further customise your desired settings.

// API endpoint

const char* api_url = "";

const char* api_url1 = "https://www.muwaqqit.com/api.json?d=";

const char* api_url2 = ";lt=";

const char* api_url3 = "&ln=";

const char* api_url4 = ";fa=-18;era=-12&ea=-13&tztype=auto&tz=";

Future Enhancements

Time-Zone

Automatically determining the user's time-zone and DST settings may be necessary to return the correct displayed time and passing correct time-zone to the Muwaqqit API. This is a Work-in-Progress and will be incorporated at a future date. In the meantime, feel free to modify the lines shown here for your location:

const long gmt_offset_sec = 0; // Adjust if necessary for your timezone

const int daylight_offset_sec = 3600; // Adjust for daylight savings

Multi-SSIDs

Unfortunately, the current version of WiFiManager does not support storage or multiple access points. This functionality is listed in the library's roadmap, so here's hoping...

Over to You

Feel free to comment with any useful thoughts and how you may have modified this project to suit your needs.

Have fun making it and supporting the services that have made this project possible!