Presidential Elections Monitor

Description

This is a Hardware engineer's way of monitoring the presidential poll. The system is made up of three subsystems

1. Scraper

Scrape presidential tally election data off either:

public portals and stores this to a csv file.

⚠️ These are not the official results. Please visit iebc.or.ke for more information.

2. API

Provides a simple API interface to the scraped data. The api is built with FastAPI

3. Hardware and firmware

An ESP32 microcontroller running micropython more details here

Prerequisites

API and Scraper Setup

Click to expand!

Clone the repository

$ git clone https://github.com/DanNduati/Elections_watch.git
$ cd Elections_watch/

1. Local Installation

Install dependencies

Create a python virtual environment activate it and install dependencies

$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt

Schedule the scraper

⚠️ The cron service is only available for Unix-based systems checkout the Windows OS equivalent to a cron job called a scheduled task

Schedule the scraper to run every nth duration with cron. In my case i ran the scraper every 15 minutes by adding the following to your crontab file:

$ crontab -e

*/15 * * * * <path to your virtual environment python executable> <path to the scraper script>

As usual I run my cronjobs on my Pi by adding the following to the current user's crontab file:

*/15 * * * * /home/pi/Desktop/Elections_watch/venv/bin/python /home/pi/Desktop/Elections_watch/scraper/scraper_bbc.py

Run the API server

Run the API server with exposing port 8000:

$ uvicorn api.main:app --port 8000 --host 0.0.0.0

Check the API

1. Presidential Results endpoint

GET /election/

Sample request

curl -X 'GET' \
  'http://0.0.0.0:8000/election/' \
  -H 'accept: application/json'

Sample response

{
  "data": [
    {
      "CandidateName": "William Ruto",
      "Coalition": "Kenya Kwanza Alliance",
      "Votes": 6395857,
      "Percentage": "51.1%",
      "Atleast25PercentOfCounty": "21/47",
      "CandidateImage": "https://news.files.bbci.co.uk/include/vjafeast/642-kenya-presidential-elections-results/assets/app-project-assets/img/candidates/kka.png",
      "UpdatedAt": "08/13/2022, 18:09:04 local time (GMT+3)",
      "Source": "https://www.bbc.com/news/world-africa-62444316"
    },
    {
      "CandidateName": "Raila Odinga",
      "Coalition": "Azimio la Umoja coalition",
      "Votes": 6026207,
      "Percentage": "48.2%",
      "Atleast25PercentOfCounty": "19/47",
      "CandidateImage": "https://news.files.bbci.co.uk/include/vjafeast/642-kenya-presidential-elections-results/assets/app-project-assets/img/candidates/alu.png",
      "UpdatedAt": "08/13/2022, 18:09:04 local time (GMT+3)",
      "Source": "https://www.bbc.com/news/world-africa-62444316"
    },
    {
      "CandidateName": "George Wajackoyah",
      "Coalition": "Roots Party",
      "Votes": 56700,
      "Percentage": "0.5%",
      "Atleast25PercentOfCounty": "0/47",
      "CandidateImage": "https://news.files.bbci.co.uk/include/vjafeast/642-kenya-presidential-elections-results/assets/app-project-assets/img/candidates/roots.png",
      "UpdatedAt": "08/13/2022, 18:09:04 local time (GMT+3)",
      "Source": "https://www.bbc.com/news/world-africa-62444316"
    },
    {
      "CandidateName": "David Mwaure",
      "Coalition": "Agano Party",
      "Votes": 27802,
      "Percentage": "0.2%",
      "Atleast25PercentOfCounty": "0/47",
      "CandidateImage": "https://news.files.bbci.co.uk/include/vjafeast/642-kenya-presidential-elections-results/assets/app-project-assets/img/candidates/agano.png",
      "UpdatedAt": "08/13/2022, 18:09:04 local time (GMT+3)",
      "Source": "https://www.bbc.com/news/world-africa-62444316"
    }
  ]
}

Alternatively open your browser at: http://0.0.0.0:8000/ You should see the automatic interactive Swagger API documentation:

Hardware setup

1. Load Micropython on the ESP32

Checkout this guide on how to get started with MicroPython on the ESP32

2. Install Ampy

Ampy is a cli tool to interact with MicroPython board over a serial connection.

$ pip install adafruit-ampy

3. Load firmware files and run code

Navigate to the hardware directory

$ cd hardware/

First create your wifi config module config.pyand add your wifi credentials:

WIFI_SSID = 'myssid'
WIFI_PASSWD = 'mywifipassword'

For convenience you can set AMPY_PORT and AMPY_BAUD environment variables which will be used if the port parameter is not specified. To set these variables automatically each time you run ampy, copy them into a file named .ampy

Connect your esp32 to your pc and load the firmware files

$ ampy put config.py
$ ampy put ss1306.py
$ ampy put main.py
# Confirm the board has all files
$ ampy ls
/config.py
/main.py
/ssd1306.py

Wire up your display to the ESP32:

SCL -> GPIO22
SDA -> GPIO21
5v -> 5v
GND -> GND

Power up the board, reset it and viola!

Debugging hardware issues