Table of Contents

• Installation
• Quick Start
• CLI Commands
• Configuration
• How It Works
• Project Architecture
• Project Structure
• Exponential Backoff
• Troubleshooting
• FAQ
• Contributing
• License

Installation

Prerequisites: Node.js 20+ and npm.

npm install -g ism-wifi

Verify it's installed:

ism-wifi --version

Quick Start

Run the tool:

ism-wifi

On first execution, you'll be guided through setup:

======================================
       ISM WiFi Auto Login
======================================

No configuration found.

Let's configure ISM WiFi.

Username: 24je0758
Password: ********
Connectivity check interval [30]:

Configuration saved.

Starting monitoring...

[15:31:11] ✓ Internet OK

The tool runs in the terminal until you press Ctrl+C.

CLI Commands

| Command | Description | |---------|-------------| | ism-wifi | Start monitoring (runs setup first if no config) | | ism-wifi setup | Re-run interactive configuration | | ism-wifi config | Display current configuration | | ism-wifi login | Perform a single login attempt and exit | | ism-wifi reset | Delete saved configuration | | ism-wifi change-interval | Change the connectivity check interval | | ism-wifi version | Print package version | | ism-wifi help | Display usage information |

ism-wifi

Starts the monitoring loop. Checks internet connectivity every N seconds. If the connection drops, it attempts to log in to the captive portal automatically.

If no configuration exists, the interactive setup wizard runs first.

ism-wifi setup

Re-runs the interactive configuration wizard. Useful if your credentials change or you want to reconfigure the tool.

Username:
Password:
Connectivity check interval [30]:

ism-wifi config

Displays your current saved configuration. The password is masked for security.

Username : 24je0758

Interval : 30 seconds

SSL Verify : false

Password : 2********

ism-wifi login

Performs a single login attempt and exits. Useful for testing or scripting.

ism-wifi reset

Deletes the saved configuration. Asks for confirmation first.

? Are you sure you want to delete the saved configuration? (y/N)

ism-wifi change-interval

Change the check interval interactively without re-entering credentials.

New check interval in seconds (current: 30):

Configuration

Configuration is stored automatically in your home directory. No manual file editing required.

| OS | Config path | |----|------------| | Windows | C:\Users\<username>\.ism-wifi\config.json | | Linux | ~/.ism-wifi/config.json | | macOS | ~/.ism-wifi/config.json |

Example config.json:

{
  "username": "24je0758",
  "password": "...",
  "checkInterval": 30,
  "verifySSL": false
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | username | string | — | Your IIT ISM network credential username | | password | string | — | Your network password (stored in plain text) | | checkInterval | number | 30 | Seconds between connectivity checks (max 30) | | verifySSL | boolean | false | Whether to verify the portal SSL certificate |

How It Works

High-Level Flow

flowchart TD
    A[Start] --> B{Config exists?}
    B -->|No| C[Run setup wizard]
    C --> D[Save config]
    B -->|Yes| D
    D --> E[Start monitoring loop]
    E --> F[Check internet]
    F --> G{Internet OK?}
    G -->|Yes| H[Sleep N seconds]
    H --> E
    G -->|No| I[Attempt login]
    I --> J[Verify after 3s]
    J --> K{Access granted?}
    K -->|Yes| H
    K -->|No| L[Wait with backoff]
    L --> I

Login Retry Flow

flowchart LR
    A[Login failed] --> B[Wait 1s]
    B --> C[Retry login]
    C --> D{Success?}
    D -->|No| E[Wait 2s]
    E --> F[Retry login]
    F --> G{Success?}
    G -->|No| H[Wait 4s]
    H --> I[Retry login]
    I --> J{Success?}
    J -->|No| K[Wait 8s]
    K --> L[Retry login]
    L --> M{Success?}
    M -->|No| N[Wait 16s]
    N --> O[Retry login]
    O --> P{Success?}
    P -->|No| Q[Wait 30s]
    Q --> R[Retry login]
    R --> S{Success?}
    S -->|No| T[Give up until next cycle]
    D -->|Yes| U[✓ Internet restored]
    G -->|Yes| U
    J -->|Yes| U
    M -->|Yes| U
    P -->|Yes| U
    S -->|Yes| U

Connectivity Check

Every checkInterval seconds, the tool sends a GET request to:

https://clients3.google.com/generate_204

• HTTP 204 → Internet is available ✓
• Anything else (timeout, redirect, DNS failure, SSL error, connection refused) → Internet unavailable ✗

The request has a 10-second timeout. If no response is received within that time, connectivity is assumed lost.

Login

When connectivity is lost, the tool sends a POST request to the captive portal:

POST https://netaccess.iitism.ac.in:6082/?url=

Content-Type: application/x-www-form-urlencoded

username=<username>&password=<password>

After the login request, it waits 3 seconds, then performs another connectivity check. Only when HTTP 204 is received is the login considered successful.

Project Architecture

flowchart TD
    CLI[cli.js] --> CONFIG[config.js]
    CLI --> MONITOR[monitor.js]
    CLI --> LOGIN[login.js]
    MONITOR --> CONN[connectivity.js]
    MONITOR --> LOGIN
    LOGIN --> CONN
    CONFIG --> UTILS[utils.js]
    LOGGER[logger.js] --> UTILS
    MONITOR --> LOGGER
    CLI --> LOGGER

    subgraph Entry
        BIN[bin/ism-wifi.js] --> CLI
    end

    subgraph Core
        CONFIG
        CONN
        LOGIN
        MONITOR
    end

    subgraph Shared
        UTILS
        LOGGER
        CONST[constants.js]
    end

    CLI --> CONST
    CONFIG --> CONST
    CONN --> CONST
    LOGIN --> CONST
    MONITOR --> CONST

| Module | Responsibility | |--------|---------------| | bin/ism-wifi.js | Entry point — calls src/index.js | | src/cli.js | Commander setup, command routing | | src/config.js | Load, save, delete config; interactive setup | | src/connectivity.js | HTTP 204 check via native fetch | | src/login.js | POST credentials to portal, verify | | src/monitor.js | Main monitoring loop, retry logic | | src/logger.js | Colored terminal output | | src/utils.js | sleep, path helpers, formatting | | src/constants.js | URLs, delays, messages |

Project Structure

ism-wifi/
├── bin/
│   └── ism-wifi.js          # CLI entry point
├── src/
│   ├── cli.js               # Command definitions and routing
│   ├── config.js             # Configuration management
│   ├── connectivity.js       # Internet connectivity checking
│   ├── login.js              # Captive portal login
│   ├── monitor.js            # Monitoring loop
│   ├── logger.js             # Colored terminal output
│   ├── utils.js              # Shared utilities
│   ├── constants.js          # Shared constants
│   └── index.js              # Public API
├── test/
│   ├── cli.test.js           # CLI command tests
│   ├── config.test.js        # Config roundtrip tests
│   ├── connectivity.test.js  # Connectivity check tests
│   ├── login.test.js         # Login module tests
│   └── utils.test.js         # Utility function tests
├── package.json
├── CHANGELOG.md
├── LICENSE
├── README.md
└── .gitignore

Exponential Backoff

When a login attempt fails, the tool retries with increasing delays:

Attempt 1  → wait 1 second
Attempt 2  → wait 2 seconds
Attempt 3  → wait 4 seconds
Attempt 4  → wait 8 seconds
Attempt 5  → wait 16 seconds
Attempt 6+ → wait 30 seconds (capped)

This prevents hammering the portal while still recovering quickly from transient failures. If all retries fail, the tool returns to the main monitoring loop and tries again on the next interval.

Troubleshooting

Login keeps failing

Run ism-wifi setup to re-enter your credentials. Ensure your username and password match what you use on the IIT ISM network portal.

SSL / certificate errors

The tool disables SSL certificate verification for the captive portal by default (verifySSL: false). This is because the portal often uses self-signed certificates. You can enable verification by editing ~/.ism-wifi/config.json and setting "verifySSL": true.

Network not detected

The tool checks connectivity by requesting https://clients3.google.com/generate_204. If this URL is blocked or redirected by your network (other than the captive portal), the tool may incorrectly report no internet. You can test this URL manually in your browser.

"No configuration found" after setup

Ensure the config file was saved correctly. Check ~/.ism-wifi/config.json exists and contains valid JSON.

Permission denied (Linux/macOS)

If you installed globally with npm install -g, you might need sudo on some systems:

sudo npm install -g ism-wifi

Alternatively, configure npm for global installs without sudo.

FAQ

Q: Does this run in the background? A: No. It runs in the terminal and stays active until you press Ctrl+C.

Q: Is my password stored securely? A: It is stored in plain text in ~/.ism-wifi/config.json. Use OS-level disk encryption (BitLocker, FileVault, LUKS) to protect your home directory.

Q: Does it work on macOS? A: Yes. The tool is tested on Windows, Linux, and macOS.

Q: Can I change the check interval without re-entering my password? A: Yes. Use ism-wifi change-interval to update just the interval.

Q: What happens if the internet goes down while I'm away? A: The tool automatically detects the outage, logs in when connectivity is partially restored, and resumes monitoring.

Q: How do I stop the tool? A: Press Ctrl+C. You'll see:

Stopping ISM WiFi...

Goodbye!

Q: Do I need to run this on startup? A: Not required. Run it manually when you need it, or set it up as a startup command in your terminal profile.

Contributing

Contributions are welcome!

Setup

git clone <your-fork>
cd ism-wifi
npm install

Running tests

npm test

Tests use Node's built-in node:test framework — no external test runner needed.

Guidelines

• ES Modules only (import/export)
• Async/await throughout
• JSDoc comments on all exported functions
• Small focused functions
• No global mutable state
• Cross-platform compatible
• Run npm test before submitting

Pull requests

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a PR with a clear description

License

MIT