fallback-ap/README.md

<!-- Header -->
<div id="top" align="center">
  <br />

  <!-- Logo -->
  <img src="https://git.zakscode.com/repo-avatars/80775ae9cf0d2c4fb4aec035efb650e631d4d0046ab6fc04c6c041e91ba11d44" alt="Logo" width="200" height="200">

  <!-- Title -->
  ### Fallback AP

  <!-- Description -->
  Automatic fallback Wi-Fi access point for headless Linux devices

  <!-- Repo badges -->
  [![Version](https://img.shields.io/badge/dynamic/json.svg?label=Version&style=for-the-badge&url=https://git.zakscode.com/api/v1/repos/ztimson/fallback-ap/tags&query=$[0].name)](https://git.zakscode.com/ztimson/fallback-ap/tags)
  [![Pull Requests](https://img.shields.io/badge/dynamic/json.svg?label=Pull%20Requests&style=for-the-badge&url=https://git.zakscode.com/api/v1/repos/ztimson/fallback-ap&query=open_pr_counter)](https://git.zakscode.com/ztimson/fallback-ap/pulls)
  [![Issues](https://img.shields.io/badge/dynamic/json.svg?label=Issues&style=for-the-badge&url=https://git.zakscode.com/api/v1/repos/ztimson/fallback-ap&query=open_issues_count)](https://git.zakscode.com/ztimson/fallback-ap/issues)

  <!-- Links -->

  ---
  <div>
    <a href="https://git.zakscode.com/ztimson/fallback-ap/wiki" target="_blank">Documentation</a>
    • <a href="https://git.zakscode.com/ztimson/fallback-ap/releases" target="_blank">Release Notes</a>
    • <a href="https://git.zakscode.com/ztimson/fallback-ap/issues/new?template=.github%2fissue_template%2fbug.md" target="_blank">Report a Bug</a>
    • <a href="https://git.zakscode.com/ztimson/fallback-ap/issues/new?template=.github%2fissue_template%2fenhancement.md" target="_blank">Request a Feature</a>
  </div>

  ---
</div>

## Table of Contents
- [Fallback AP](#top)
  - [About](#about)
    - [Built With](#built-with)
  - [Setup](#setup)
    - [Installation](#installation)
    - [Usage](#usage)
  - [License](#license)

## About

A NetworkManager-based script for headless Linux devices (e.g. a Raspberry Pi) that keeps them reachable even when their configured Wi-Fi network isn't available. When the device loses its Wi-Fi connection, it automatically stands up a local access point so you can connect directly and reconfigure it. While that access point has no clients connected, it periodically steps aside for a short window to let NetworkManager try reconnecting to a known network in the background, then brings the access point back up if nothing was found.

Runs as a `systemd` service and is managed entirely through `nmcli`/`iw` — no extra daemons (`hostapd`, `dnsmasq`, etc.) required.

### Built With
[![Shell](https://img.shields.io/badge/Shell-000000?style=for-the-badge&logo=windowsterminal&logoColor=00ff00)](https://en.wikipedia.org/wiki/Shell_script)
[![Linux](https://img.shields.io/badge/Linux-eeeeee?style=for-the-badge&logo=linux&logoColor=000000)](https://www.linux.org/)

## Setup

<details open>
<summary>
  <h3 id="installation" style="display: inline">
    Installation
  </h3>
</summary>

#### Prerequisites
- A Linux device with a Wi-Fi adapter (`wlan0` by default) — a Raspberry Pi or similar SBC
- `NetworkManager` and `iw` (installed automatically if missing)
- Root access

#### Instructions
1. Download & Install: `curl -sL https://git.zakscode.com/ztimson/fallback-ap/raw/branch/master/install.sh | sudo bash`

</details>

<details>
<summary>
  <h3 id="usage" style="display: inline">
    Usage
  </h3>
</summary>

Once installed, the service runs automatically and requires no further interaction. A few commands are available for manual control:

- `sudo ./pi-fallback-ap.sh status` — show service, connection, and access point state
- `sudo ./pi-fallback-ap.sh start` / `stop` — manually bring the access point up or down
- `sudo ./pi-fallback-ap.sh uninstall` — remove the service and access point profile

</details>

## License
Copyright © 2026 Zakary Timson | Available under MIT Licensing