From 8d3061f9c29ff930ac295a67a4e3873e3951d30a Mon Sep 17 00:00:00 2001 From: John Doe <6mxo89sqh@relay.firefox.com> Date: Sun, 6 Jun 2021 22:28:07 +0530 Subject: [PATCH 1/2] README.md restructuring --- README.md | 289 +++++++----------------------------------------------- 1 file changed, 33 insertions(+), 256 deletions(-) diff --git a/README.md b/README.md index fe030fb6..098e6667 100644 --- a/README.md +++ b/README.md @@ -8,194 +8,50 @@ -## Quickstart Guide -**Instructions to follow on your laptop and phone below. To fetch OTP automatically, Step 2 is compulsory** - -### 1. On your laptop -1. Make sure [Python 3.8+](https://python.org) is installed. *Note: If you are using Windows, follow [How to run on windows](#how-to-run-on-windows) and you may not require Python to be installed* -2. Clone this repo: ```git clone https://github.com/bombardier-gif/covid-vaccine-booking.git``` or download zip file and extract -3. Install the requirements: - - ```pip install -r requirements.txt``` on Windows - - ```pip3 install -r requirements.txt``` on Linux or Mac -4. Run the script: - - ```python src\covid-vaccine-slot-booking.py``` on Windows - - ```python3 src/covid-vaccine-slot-booking.py``` on Linux or Mac -5. Alternatively follow [these](#using-docker) steps to run this script using docker -6. Follow the steps. For more detailed guide: [Steps](#steps) - -### 2. On your Phone (Required for fetching OTP automatically) -1. **Android Phone**: Follow either [Option 1: IFTTT app](#option-1-ifttt) or [Option 2: CoWIN OTP Retriever app](#option-2-cowin-otp-retriever) -2. **iPhone**: Follow [Using Shortcuts app](#using-shortcuts-app) +## Guide +### Pre-requisites +1. [Setup on Windows/Linux/MacOS/Docker/AWS](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/Setup) (Required) +2. [KVDB Bucket](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/KVDB) +3. Phone Setup + 1. Android + 1. [CoWIN OTP Retriever](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/CoWIN-OTP-Retriever) (Recommended) + 2. [IFTTT](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/CoWIN-OTP-Retriever/IFTTT) + 2. [iPhone](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/CoWIN-OTP-Retriever/Shortcuts) + +### Usage + +`./covid-vaccine-slot-booking.py [--mobile ] [--token ] [--kvdb-bucket ## Contents - [Before you start](#before-you-start) - - [What this repository does](#what-this-repository-does) - - [Setup Guide: Android](#setup-guide-for-android) - - [Option 1: IFTTT app](#option-1-ifttt) - - [Screenshots](#ifttt-steps-in-screenshots) - - [Option 2: CoWIN OTP Retriever app](#option-2-cowin-otp-retriever) - - [Screenshots](#cowin-otp-retriever-steps-in-screenshots) - - [Setup Guide: iOS](#setup-guide-for-ios) - - [Using Shortcuts app](#using-shortcuts-app) - - [Screenshots](#shortcuts-steps-in-screenshots) - [COVID-19 Vaccination Slot Booking Script](#covid-19-vaccination-slot-booking-script) - [Important](#important) - - [Usage](#usage) - - [Third-Party Package Dependency](#third-party-package-dependency) - [Steps](#steps) - - [How to run on windows](#how-to-run-on-windows) - - [Using Docker](#using-docker) - [Troubleshooting common problems](#troubleshooting-common-problems) ## Before you start 1. If you face any issues please refer to the [troubleshooting section](#troubleshooting-common-problems) at the end of this doc -2. The captcha is a bit buggy and you may be required to make 5-6 tries before you are able to book -3. If you are still facing errors and want to run this script on windows using exe, please see the section below [How to run on windows](#how-to-run-on-windows) -4. Instructions for iOS have also been added. See the [Setup Guide for iOS](#setup-guide-for-ios) for details. Please note that its not possible to automate the OTP auto read on iOS completely, however its possible to make it a 1 tap process, which is far better than seeing and entering the OTP manually. - -## What this repository does -1. Automates OTP read from the SMS after the token expires. -2. Randomly chooses one of the available slots instead of waiting for input from the user. -3. Reduces the polling wait to optimize on the polling frequency (hence the name bombardier) - - -#### How it works via IFTTT app on Android -1. https://ifttt.com/ is used to create a SMS trigger. The trigger happens when the OTP SMS is received -2. The trigger sends the text of the SMS to a REST service, I have used a free service which needs 0 setup for a shared storage - -#### How it works via CoWIN OTP Retriever app on Android -1. The [CoWinOTPRetriever Android app](./CoWinOtpRetreiver.apk) has been created to automatically read the OTP SMS and then send it to the shared storage -2. You only need to install and start the app, enter your CoWIN registered phone number, and then start the OTP listener. - -#### How it works via Shortcuts app on iOS -1. [Shortcuts app](https://apps.apple.com/us/app/shortcuts/id915249334) is used to create an SMS trigger. The trigger happens when the OTP SMS is received -2. The trigger sends the text of the SMS to a REST service, I have used a free service which needs 0 setup for a shared storage - -#### In Parallel -1. The script runs continuously to poll (same logic as the original repository) -2. Whenever the OTP expires, an OTP is requested -3. When the OTP SMS is received on the **Android**, phone, the above logic triggers to store the OTP SMS in the shared storage. On **iOS**, when the OTP SMS is received, the above logic triggers a notification which the user has to long press and confirm after which the OTP is stored in shared storage -4. The script polls the shared storage to get the OTP -5. Once the OTP is received, the polling resumes -6. If a free slot is found, rather than waiting for an input, it randomly chooses a slot and attempts to book - -
- -## KVDB setup -Regardless of Android or iOS, you will need a KVDB bucket configured to act as a key value store for your OTP messages coming from the IFTTT app or CoWIN OTP Retriever. You will need to update your personal key every 14 days or buy a pro account on kvdb. -Steps to get your own KVDB bucket: - -1. Go to https://kvdb.io/ -2. Click on Get started now -3. Enter your email and click on Create bucket -4. You will get a bucket key. It is just a random sequence of characters eg. ASth4wnvVDPkg2bdjsiqMN -5. Keep this key saved somewhere in your notes. We will need it. - -## Setup Guide for Android - -### Option 1: IFTTT - -1. Create an account in ifttt.com (A premium paid account is recommended for a quicker response) -2. Create a new applet -3. If this..... click on Android SMS trigger -4. Select "New SMS received matches search" and use CoWIN as the search key -5. Then... Choose a service named Webhooks and then select make a web request -6. Paste the url: https://kvdb.io//99XXXXXXXX replace 99XXXXXXXX with your phone number and with your own key that you got in the previous step of KVDB setup. -7. Method is PUT -8. Content Type PlainText -9. Body: Add ingredient and select Text -10. On your android phone, install ifttt app -11. Login -12. Ensure that the battery saver mode, and all other optimizations are removed. The appshould always run (This is the key for quick response). - 1. **Tip**: If your IFTTT is not triggered when your SMS is received: https://www.androidpolice.com/2020/05/30/how-to-prevent-apps-sleeping-in-the-background-on-android/ - Also a premium account is faster -13. Clone this repository -14. Go to `src` directory and run the script `cd src && python covid-vaccine-slot-booking.py` -15. On Mac I had to do the following too - ```bash - brew install python-tk - brew install SoX - ``` -18. Run the script, use the steps given below to enter your preferences -19. Hopefully you get the slot -20. Stay healthy and stay safe! - - -#### IFTTT steps in screenshots: - -| | -|:-------------------------:| -| Step 1 Step 1 | - -| | | -|:-------------------------:|:-------------------------:| -|Step 2 Step 2 |Step 3 Step 3 | -|Step 4 Step 4 |Step 5 Step 5 | -|Step 6 Step 6 |Step 7 Step 7 | -|Step 8 Step 8 |Step 9 Step 9 | - -
- -### Option 2: CoWIN OTP Retriever -1. Install the [CoWinOTPRetriever Android app](./CoWinOtpRetreiver.apk?raw=true) by enabling installation from unknown sources. -2. Follow this guide to install apps from unknown sources: https://www.verizon.com/support/knowledge-base-222186/ -3. Allow the app to run in background so that the app does not stop even if you multi-task or leave the phone idle. (Note that, there still might be some phone model specific settings and optimizations which could stop the app from running in background. Check point number 8) -4. Grant sms access to allow the app to read CoWIN OTP sms. -5. Enter 10 digit mobile number registered on the CoWIN portal. Also enter your personal KVDB bucket value. -6. Switch ON the OTP Listener. -7. If the OTP is successfully sent to the key value store, you will see the status as shown below. -8. Ensure that the battery saver mode, and all other optimizations are removed. The app should always run (This is the key for quick response). - Tip: If you don not see a success message on the app when you receive an OTP: https://www.androidpolice.com/2020/05/30/how-to-prevent-apps-sleeping-in-the-background-on-android/ -8. Security tip: Make sure to change back your settings to disallow app installation from unknown sources. - -#### CoWIN OTP Retriever steps in screenshots -| | | | -|:-------------------------:|:-------------------------:|:-------------------------:| -|Step 1 Step 1 |Step 2 Step 2 |Step 3 Step 3 | -|Step 4 Step 4 |Step 5 Step 5 |Step 6 Step 6 | -|Step 7 Step 7 |Step 8 Step 8 |Step 9 Step 9 | -|Step 10 Step 10 |Step 11 Step 11 | | - -
- -## Setup Guide for iOS - -### Using Shortcuts app -1. Open the shortcuts app -2. Tap on the + button at the top right -3. Tap on `Create Personal Automation` -3. Select the `Message` option -4. Put `CoWIN` in the Message Contains option & leave everything blank. Tap on Next button -5. Tap on `Add action` and search for the option `Set Variable`. Give the variable name `text` and input as `Shortcut Input` -6. Then add another action and select `URL` and paste the url: https://kvdb.io//99XXXXXXXX replace 99XXXXXXXX with your phone number and with your bucket value from the KVDB setup step -7. Then add another action and select `Get Contents of Url`. Click on show more. Change the method to `PUT`. Request Body to `File` and in the file row tap on `Choose Variable` and select `text` which we defined in Step 6. -8. Click Next and save this automation. -9. Clone this repository -Go to `src` directory and run the script `cd src && python covid-vaccine-slot-booking.py` -15. On Mac I had to do the following too - - `brew install python-tk` - - `brew install SoX` -18. Run the script, enter your phone number. -19. Now as soon as OTP is recieved you will also get a notification from shortcuts app. Long press it and click on run. It will start OTP auto read process. -20. Use the steps given below to enter your preferences. -21. Now whenever the script session expires, it will send the notification described in step 13 and repeat the process to trigger OTP auto read. -22. It is recommended that you set a different notification tone for this notification to be able to distinguish. -23. Hopefully you get the slot -24. Stay healthy and stay safe! - -#### Shortcuts steps in screenshots - -| | | | -|:-------------------------:|:-------------------------:|:-------------------------:| -|Step 1 Step 1 |Step 2 Step 2 |Step 3 Step 3 | -|Step 4 Step 4 |Step 5 Step 5 |Step 6 Step 6 | -|Step 7 Step 7 |Step 8 Step 8 |Step 9 Step 9 | -|Step 10 Step 10 |Step 11 Step 11 | | - -
+2. If you are still facing errors and want to run this script on windows using exe, please see the section below [How to run on windows](#how-to-run-on-windows) +3. Instructions for iOS have also been added. See the [Setup Guide for iOS](#setup-guide-for-ios) for details. Please note that its not possible to automate the OTP auto read on iOS completely, however its possible to make it a 1 tap process, which is far better than seeing and entering the OTP manually. ## COVID-19 Vaccination Slot Booking Script @@ -209,43 +65,6 @@ This very basic CLI based script can be used to automate covid vaccination slot - API Details: https://apisetu.gov.in/public/marketplace/api/cowin/cowinapi-v2 - And finally, I know code quality probably isn't great. Suggestions are welcome. - -### Usage: - -For the anyone not familiar with Python and using Windows, using the ```covid-vaccine-slot-booking.exe``` executable file would be the easiest way. [Download it from here](https://github.com/bombardier-gif/covid-vaccine-booking/releases/latest). It might trigger an anti-virus alert. That's because I used ```pyinstaller``` to package the python code and it needs a bit more effort to avoid such alerts. - -OR - -If you have no idea how to install Python in Windows, then either `git clone` the repository or [Download the source here](https://github.com/bombardier-gif/covid-vaccine-booking/archive/refs/heads/main.zip). Then you can double click on `windows.bat` which will automatically take care of the dependencies and start the program. - -*Note: It might take a little bit more time to run for first time becuase it extracts the python runtime and installs dependencies, but from the next time onwards, it'll be instant* - -OR - -Run the script file as show below by [downloading the source](https://github.com/bombardier-gif/covid-vaccine-booking/releases/latest): - -``` -python src\covid-vaccine-slot-booking.py -``` -If you're on Linux, install the beep package before running the Python script. To install beep, run: -``` -sudo apt-get install beep -``` -If you already have a bearer token, you can also use: -``` -python src\covid-vaccine-slot-booking.py --token=YOUR-TOKEN-HERE -``` - -### Third-Party Package Dependency: -- ```tabulate``` : For displaying data in tabular format. -- ```requests``` : For making GET and POST requests to the API. -- ```inputimeout``` : For creating an input with timeout. - -Install all dependencies by running: -```pip install -r requirements.txt``` - -
- ## Steps: 1. Run script: ```python src\covid-vaccine-slot-booking.py``` @@ -379,48 +198,6 @@ Install all dependencies by running:
-## How to run on windows - -### Quick Start -1. *Step 1* - `git clone` or [Download](https://github.com/bombardier-gif/covid-vaccine-booking/releases/latest) the Repository -2. *Step 2* - Double click to run `windows.bat` to install all dependencies & start this script -3. *Step 3* - If you're running this script for the very first time. It will extract the Python dependencies and run the script - -windowsinstaller - - -### Advanced -1. **Step 1** - [Download the source or exe](https://github.com/bombardier-gif/covid-vaccine-booking/releases/latest). -2. **Step 2 -** Go to folder **tests** then **windows exe**.**zip**. Unzip the folder and Now run the program "**captcha_tests.exe**". If you see a dialog box click on quit, and you will see a Captcha. If this is what happened you are all good to go. -3. Now come back to main folder unzip "**windows exe.zip**"go to this "**windows exe**" folder - Now start the program "**covid-vaccine-slot-booking.exe**", you will not see any error. -4. DO NOT DELETE ANY FOLDER OR FILE. - -
- -## Using Docker - -You can also run this script using docker. It's useful in case you don't want to -install all required dependencies manually (python etc.). Follow these steps: - -1. Make sure [docker](https://docs.docker.com/get-docker/) is installed on your system. -2. Run with following command -```bash -docker run --rm \ - -v $(pwd)/configs:/configs \ # Stores the configs in your current directory. Windows users please change this path or use powershell. - -e "TZ=Asia/Kolkata" \ # Work with IST Timezone - -it \ # interactive - docker.pkg.github.com/bombardier-gif/covid-vaccine-booking/cowin:latest [--config /configs/] [--mobile ] [--no-tty] -``` -3. (Optional Pro-Tip) After your first run, replace `-it` with `-d` to run as daemon. -4. For Docker on AWS, add `--network="host"` in docker run command. AWS Metadata service won't work without this. - -
- -## Using on AWS - -Refer [here](docs/AWS.md). - ## Troubleshooting common problems ### Problem 1 @@ -464,7 +241,7 @@ Refer [here](docs/AWS.md). | | | |:-------------------------:|:-------------------------:| | image
Using IFTTT: This number must match the number you enter while running the script. |image
CowinOTPRetriever App: Make sure the switch is flipped on. | - + ## Running unit tests with `pytest` - Install `pytest` from `requirements.txt` if not already installed From 60130d312549f38e83a48646c7ff1f4f599721d4 Mon Sep 17 00:00:00 2001 From: John Doe <6mxo89sqh@relay.firefox.com> Date: Mon, 7 Jun 2021 13:28:21 +0530 Subject: [PATCH 2/2] Corrected links in README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 098e6667..a21f76b1 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ 3. Phone Setup 1. Android 1. [CoWIN OTP Retriever](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/CoWIN-OTP-Retriever) (Recommended) - 2. [IFTTT](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/CoWIN-OTP-Retriever/IFTTT) - 2. [iPhone](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/CoWIN-OTP-Retriever/Shortcuts) + 2. [IFTTT](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/IFTTT) + 2. [iPhone](https://github.com/bombardier-gif/covid-vaccine-booking/wiki/Shortcuts) ### Usage