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
- Run the bootstrap script
wget -q https://raw.githubusercontent.com/Protocol789/homeassistant/main/bootstrap/bootstrap.sh -O- | sh
- Run the Get balance command below with your Airtel web credentials in place of the $variables below
AirtelTracker/Airtel_GetBalance.sh $username '$password' -V
- 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
In these installation steps, the optional prerequisites are used however you can use whatever you are most comfortable with.
- Jump into a terminal (click open web gui) session on the Home Assistant instance and move into the
/config
directory via
cd config/
- 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
- 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}
-
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 -
Copy the following yaml snippet into Home Assistant's
configuration.yaml
file
Important
Ensure your update the $username
and '$password'
values and note that the password must be encpasulated in single quotes '' to avoid special charectors being read by bash
-
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 filecommand_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
-
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"/>
-
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! 👏
-
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 -
New helper template sensor details
Important
Ensure you reference the name of the sensor you created in step 6 by replacing the sensor.SensorName
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"/>
-
Add the new sensor to a dashboard of your choosing!
-
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
- Replace
./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
InformationalShow 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
DebugShow 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