AirtelTracker is shell based script for accessing data bundle balances for your data plan from the Airtel mobile carrier.

Home Assistant calls the script periodically to retrieve the data values.

The data bundle balance is then exposed for use in dashboard and graphing in Home Assistant via a sensor entity🍾

Open your fav *nix terminal

1. Run the bootstrap script

wget -q https://raw.githubusercontent.com/Protocol789/homeassistant/main/bootstrap/bootstrap.sh -O- | sh

2. Run the Get balance command below with your Airtel web credentials in place of the $variables below

AirtelTracker/Airtel_GetBalance.sh $username '$password' -V

3. Data balances returned in JSON packet
   

• Home Assistant
• SSH access
• Access to edit Home Assistant configuration.yaml file
• Internet access from Home Assistant

• Required

  • Home Assistant
  • Your airtel web username and password used to login to Airtel broadband portal

• Optional (Recommended)

  • Home Assistant Add-ons
    • File editor
    • Advanced SSH & Web Terminal

In these installation steps, the optional prerequisites are used however you can use whatever you are most comfortable with.

1. Jump into a terminal (click open web gui) session on the Home Assistant instance and move into the /config directory via

cd config/

2. Run the bootstrap command which will download the latest release for you

wget -q https://raw.githubusercontent.com/Protocol789/homeassistant/main/bootstrap/bootstrap.sh -O- | sh

3. Time to test!
   Get the Airtel credentials and plug them into the script below where $username and '$password' are your Airtel credentials respectively

Command to run
AirtelTracker/Airtel_GetBalance.sh $username '$password' -V

2024-01-12 01:12:33 - INFO ---- Running airtel login call
2024-01-12 01:12:33 - INFO ---- -------------------------
2024-01-12 01:12:35 - INFO ---- Login: HTTP response of 200 OK!
2024-01-12 01:12:35 - INFO ---- Extracted login token
2024-01-12 01:12:35 - INFO ---- -------------------------
2024-01-12 01:12:35 - INFO ---- Starting Airtel Balance call
2024-01-12 01:12:36 - INFO ---- Get Balance HTTP response of 200 OK!
2024-01-12 01:12:36 - INFO ---- Here's your balances per bundle
{"balance":"8.45","unit":"GB","message":"success","status":"SUCCESS","statusCode":200}

4. Now its time to add the sensor entity into Home Assistant so that the JSON packet can be consumed and eventually visualized.

   Open up the configuration.yaml in File editor (click open web gui) or open the file in your favourite text editor

5. Copy the following yaml snippet into Home Assistant's configuration.yaml file

• The scan_interval is set to 30 minutes but can be set to any value you need (in seconds)

• The entity name can be whatever you like Save the file

  command_line:
    - sensor:
        name: Airtel
        scan_interval: 1800      
        command: sh /config/AirtelTracker/Airtel_GetBalance.sh $username '$password'
        value_template: "{{ value_json.status }}"
        json_attributes:
          - message
          - statusCode
          - balance
          - unit

Example config

6. Now do a FULL restart Home Assistant instance so the new configuration file and entity is loaded up

   This can be done directly from File Editor Addon

<img src="https://raw.githubusercontent.com/Protocol789/homeassistant/readme-images/.github/images/ha-fileeditor-restart.png" alt="File Editor restart Home Assistant" width="300"/>

7. Once restarted head over to Developer Tools States and filter for your new entity.

   Note the json attributes now show the total data balance available on your Airtel bundle! 👏

8. It's now time to expose the data bundle balance via a helper entity which will reference the attribute and allow you to add it to a dashboard
   Click Create Helper in bottom right corner

9. Click Template
   

10. Select Template a sensor
    

11. New helper template sensor details

The `state template` will be referencing the new entity we created in the configuration.yml and extracting the `balance` attribute out  

` {{ state_attr( 'sensor.SensorName' , 'balance' ) }} `

Select the unit of measurement, device class and state class and click `SUBMIT` buttom  

<img src="https://raw.githubusercontent.com/Protocol789/homeassistant/readme-images/.github/images/ha-sensor-details.png"  width="200" alt="template sensor details"/> 

12. Add the new sensor to a dashboard of your choosing!

13. Example of entity history

flowchart LR;
    ha["Home Assistant"]
    at["AirtelTracker"]
    ai["Airtel API"]
    ha <-- `command line` --> at <-- REST API --> ai 
    

sequenceDiagram
    participant A as Home Assistant
    participant B as Airtel Tracker
    participant C as Airtel API
    
    A->>+B: Command_Line processor 
    B->>+C: Login credentials
    C->>-B: Login token
    B->>+C: Get data balance
    C->>-B: Data balances
    B->>-A: Return balance

The base script can be run with a few arguments for logging verbosity.

• -s Silent (Default mode)

  The default mode which the script runs in. Only returns the json response success or failure information.
  This response is parsed by the command_line processor in Home Assistant and exposed into the entity

  • Replace $WebUsername and $WebPassword with your Airtel credentials used to login to the website

  ./Airtel_GetBalance.sh $WebUsername '$WebPassword' 

root@zorab-surface:~/Airtel# ./Airtel_GetBalance.sh $WebUsername '$WebPassword'
{"balance":"8.46", "unit":"GB", "message":"success", "status":"SUCCESS", "statusCode":200}

• -V Informational

  Show informational example

    ./Airtel_GetBalance.sh $WebUsername '$WebPassword' -V

  root@pc:~/Airtel# ./Airtel_GetBalance.sh $WebUsername '$WebPassword' -V
  2024-01-12 00:37:54 - INFO ---- Running airtel login call
  2024-01-12 00:37:54 - INFO ---- -------------------------
  2024-01-12 00:37:56 - INFO ---- Login: HTTP response of 200 OK!
  2024-01-12 00:37:56 - INFO ---- Extracted login token
  2024-01-12 00:37:56 - INFO ---- -------------------------
  2024-01-12 00:37:56 - INFO ---- Starting Airtel Balance call
  2024-01-12 00:37:57 - INFO ---- Get Balance HTTP response of 200 OK!
  2024-01-12 00:37:57 - INFO ---- Here's your balances per bundle
  {"balance":"8.46", "unit":"GB", "message":"success", "status":"SUCCESS", "statusCode":200}

• -G Debug

  Show debug example

  Replace $WebUsername and $WebPassword with your Airtel credentials used to login to the website

    ./Airtel_GetBalance.sh $WebUsername '$WebPassword' -G

  root@pc:~/Airtel# ./Airtel_GetBalance.sh $WebUsername '$WebPassword' -G
  2024-01-12 00:35:12 - DEBUG --- -G specified: Debug mode
  2024-01-12 00:35:12 - DEBUG --- Variable passed in postion 1: $username
  2024-01-12 00:35:12 - DEBUG --- Variable passed in postion 2: $password
  2024-01-12 00:35:12 - DEBUG --- Running payload creator
  2024-01-12 00:35:12 - DEBUG --- This is login payload:
  {"username":"$username","password":"$password"}
  2024-01-12 00:35:13 - INFO ---- Running airtel login call
  2024-01-12 00:35:13 - INFO ---- -------------------------
  2024-01-12 00:35:15 - DEBUG --- Login: HTTP code response 200
  2024-01-12 00:35:15 - INFO ---- Login: HTTP response of 200 OK!
  2024-01-12 00:35:15 - DEBUG --- Login: Body reponse is:

The scripts were tested on following systems however any *nix system should work

• Ubuntu 22.04.2 LTS (WSL)

• Home Assistant Operating System (2024)