# network-pi

A [Pi](https://pi.dev) package that scans the current private IPv4 networks and shows which devices respond to an ICMP ping.

The package provides two ways to use the scanner:

- `/network-pi` opens an interactive overlay in Pi.
- `network_scan` gives the model a structured scan tool it can call when you ask about devices on the local network.

The scanner reports IP addresses and ping latency. It does not perform port scanning or identify device types.

## Demo

[Watch the network-pi overlay demo](https://cdn.jsdelivr.net/gh/rubberhose1337/network-pi@main/assets/network-pi-demo.mp4)

The [Pi package gallery](https://pi.dev/packages) uses the package's `pi.video` metadata to show this MP4 preview. On desktop, the gallery autoplays the preview when you hover over the package card.

## Requirements

- Pi with package support.
- Node.js 20 or newer.
- A system `ping` command. Windows uses the built-in `ping.exe`; Linux usually provides it through `iputils-ping`.

## Install

Once the package is available on npm, install the published package with:

```sh
pi install npm:network-pi@0.1.0
```

You can also install the tagged GitHub release:

```sh
pi install git:github.com/rubberhose1337/network-pi@v0.1.0
```

For local development or a one-off test from a clone:

```sh
pi -e ./extensions/network-pi.js
```

Restart Pi after installing or updating an extension if it was already running.

## Interactive overlay

In interactive Pi mode, run:

```text
/network-pi
```

The overlay starts scanning immediately and updates as hosts respond.

- Press `r` to run another scan after the current scan finishes.
- Press `Esc` or `q` to close the overlay.
- Pressing `Esc` or `q` during a scan also cancels the scan.

The overlay displays the networks being checked, progress, responding addresses, and latency. To keep the terminal view readable, it displays at most 32 responding devices. The underlying scan result is not limited to those 32 entries.

Opening the overlay does not require a model call.

## Model tool

Ask Pi in natural language, for example:

> Scan my current local network and list the pingable devices.

Pi can call the `network_scan` tool and summarize its structured result. You can also specify options in your request, such as:

> Scan only my `wlan0` interface, use a 1200 ms timeout, and do not include this host.

## Scan behavior

By default, network-pi:

- Discovers private IPv4 networks from the machine's local interfaces.
- Ignores loopback, link-local, and public IPv4 interfaces.
- Skips adapter names that look virtual by default, including common WSL, VMware, Hyper-V, Docker, and bridge adapters.
- Sends one ICMP ping to each usable address and records responding IP addresses with latency when available.
- Uses direct process arguments for `ping`/`ping.exe`; it does not construct or execute a shell command.

Select a virtual or VPN-style interface explicitly with `interfaceName` when that is the network you intend to scan.

## Tool options

The `network_scan` tool accepts these options:

| Option | Range / default | Description |
| --- | --- | --- |
| `interfaceName` | optional | Restrict the scan to one local interface, such as `wlan0` or `eth0`. |
| `timeoutMs` | 100-3000 ms; default 800 | Timeout for each host ping. |
| `concurrency` | 1-128; default 64 | Number of ping processes that may run at once. |
| `maxHosts` | 1-4096; default 512 | Maximum number of hosts to scan. |
| `includeSelf` | default `true` | Include the current machine when it responds. |

The extension refuses to scan a discovered network larger than `maxHosts`. This prevents an accidental scan of a very large subnet.

## Limitations and safety

- This is an ICMP reachability check only. It does not enumerate ports, services, hostnames, MAC addresses, or device types.
- A device that does not respond may still be online because firewalls, sleep modes, and network policies can block ICMP.
- The extension runs with Pi's normal extension permissions. Review the source before installing any third-party package.
- Network visibility depends on the interfaces and permissions available to the machine running Pi. It does not discover devices on networks that the machine cannot route to.

## Development

Install dependencies and run the checks with:

```sh
npm install
npm test
```

The tests cover interface discovery, subnet expansion, platform-specific ping arguments, latency parsing, and result formatting. They do not send network traffic.

To inspect the files that would be included in the npm package:

```sh
npm pack --dry-run
```