https://github.com/impalex/icmpenguin
Android ping & traceroute library with native performance
https://github.com/impalex/icmpenguin
android icmp library ndk networking ping traceroute
Last synced: 5 months ago
JSON representation
Android ping & traceroute library with native performance
- Host: GitHub
- URL: https://github.com/impalex/icmpenguin
- Owner: impalex
- License: apache-2.0
- Created: 2025-12-31T03:50:21.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-12-31T10:09:21.000Z (5 months ago)
- Last Synced: 2026-01-04T05:35:37.211Z (5 months ago)
- Topics: android, icmp, library, ndk, networking, ping, traceroute
- Language: Kotlin
- Homepage: https://impalex.github.io/icmpenguin/
- Size: 223 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
  
# icmpenguin
**icmpenguin** is an Android library for network diagnostics, providing tools for ping and traceroute operations. It combines Kotlin for high-level asynchronous logic using coroutines and native C++ code via JNI for low-level socket handling, supporting both IPv4 and IPv6. This allows bypassing Java/Android limitations for raw sockets like ICMP.
The library is licensed under the Apache License 2.0 and is designed for easy integration into Android applications, such as network utilities or monitoring tools.
# Key Features
- **Ping Functionality:** Send ICMP echo requests with customizable parameters like TTL, timeout, packet size, interval, and data pattern.
- **Traceroute Functionality:** Trace routes using ICMP or UDP probes, with support for stepped or concurrent strategies, port selection, and MTU discovery.
- **Asynchronous Operations:** Built on Kotlin Coroutines for non-blocking I/O, ensuring smooth integration with Android UI threads.
- **IPv4/IPv6 Support:** Automatic address resolution and protocol handling.
- **MTU Discovery:** Dynamically adjust packet sizes to detect path MTU issues during traceroute.
- **Customizable Strategies:** For traceroute, choose between stepped (with concurrency limits) or concurrent probing.
- **Detailed Results:** Probe results include success metrics (RTT, TTL), errors (e.g., host unreachable with offender IP), and timeouts.
- **Thread-Safety:** Uses atomics and safe concurrency in both Kotlin and C++ layers.
- **JNI Integration:** Native code handles socket creation, packet sending/receiving, and error processing efficiently.
# Advantages
- **Performance:** Native C++ core minimizes overhead for socket operations, making it faster than pure Java alternatives.
- **Flexibility:** Extensive configuration options for probes, strategies, and sizes, suitable for advanced network diagnostics.
- **Ease of Use:** High-level APIs (``Pinger`` and ``SimpleTracer``) abstract complexity, with suspend functions and callbacks for results.
- **Android-Friendly:** Coroutine-based, avoids UI blocking; no external dependencies.
- **Robust Error Handling:** Detailed error codes, offender IPs, and MTU info help in troubleshooting network issues.
- **Open-Source:** Apache 2.0 license allows free use, modification, and distribution.
# Device Compatibility
### IMPORTANT!
**icmpenguin** uses low-level socket APIs that require direct network stack access. While fully supported on **physical Android devices**, the **Android Emulator** has known limitations with ICMP sockets.
**Always test network functionality on physical devices.** Use the emulator primarily for UI development and logic testing.
# Requirements
- Android API Level 24+ (Android 7.0+)
- Internet permission in manifest:
```xml
```
# Setup
You can add this library to your project using Gradle.
```groovy
dependencies {
implementation("me.impa:icmpenguin:1.0.0-rc.1")
}
```
# Building from Source
Clone the repository:
```bash
git clone https://github.com/impalex/icmpenguin.git
```
Build with Gradle:
```bash
./gradlew build
```
# Usage
## Ping Example
Use the ``Pinger`` class to perform ping operations. Results are delivered via a callback.
```kotlin
import me.impa.icmpenguin.ping.Pinger
suspend fun pingHost(host: String) {
val pinger = Pinger(
host = host,
timeout = 3000,
maxPingCount = 4,
interval = 1000
)
pinger.ping { result ->
when (result) {
is ProbeResult.Success -> {
println("Reply from ${result.remote}: time=${result.elapsedUsec}μs ttl=${result.ttl}")
}
is ProbeResult.Timeout -> {
println("Request timed out for ${result.remote}")
}
is ProbeResult.HostUnreachable -> {
println("Host ${result.remote} unreachable via ${result.offender}")
}
else -> println("Result: $result")
}
}
}
```
## Traceroute Example
Use the ``SimpleTracer`` class for simplified traceroute. Hop statuses are updated asynchronously.
```kotlin
import me.impa.icmpenguin.trace.SimpleTracer
suspend fun traceRoute(host: String) {
val tracer = SimpleTracer(
host = host,
probeType = ProbeType.ICMP,
maxHops = 30,
probesPerHop = 3,
timeout = 2000
)
tracer.trace { hopStatus ->
println(hopStatus)
}
}
```
## Advanced Ping Configuration
```kotlin
val pinger = Pinger(
host = "google.com",
ttl = 64, // Time To Live
timeout = 5000, // Response timeout in ms
maxPingCount = Pinger.INFINITE, // Infinite pings (until stopped)
interval = 1000, // Time between pings
probeSize = 56, // Packet size including headers
pattern = "PING1234".toByteArray() // Custom payload pattern
)
```
## Custom Traceroute Strategy
```kotlin
val tracer = Tracer(
host = "github.com",
probeType = ProbeType.UDP,
traceStrategy = TraceStrategy.Concurrent(
maxHops = 30,
cycles = 3, // Repeat entire trace 3 times
interval = 2000L // Time between cycles
),
portStrategy = PortStrategy.Sequential(start = 33434),
probeSize = ProbeSize.MtuDiscovery, // Automatically discover MTU
timeout = 3000
)
// Track individual probe results
tracer.trace { hop, result ->
println("Hop $hop: $result")
}
```
# Documentation
For more information, please refer to the [documentation.](https://impalex.github.io/icmpenguin/)
# Contributing
Contributions are welcome! Please submit pull requests for bug fixes or new features.
# License
```
Copyright (c) 2025 Alexander Yaburov
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
```
#
Penguin loves packets! 🐧📦