{"id":35727283,"url":"https://github.com/impalex/icmpenguin","last_synced_at":"2026-01-13T20:41:22.396Z","repository":{"id":331186528,"uuid":"1125619477","full_name":"impalex/icmpenguin","owner":"impalex","description":"Android ping \u0026 traceroute library with native performance","archived":false,"fork":false,"pushed_at":"2025-12-31T10:09:21.000Z","size":228,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-04T05:35:37.211Z","etag":null,"topics":["android","icmp","library","ndk","networking","ping","traceroute"],"latest_commit_sha":null,"homepage":"https://impalex.github.io/icmpenguin/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/impalex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-31T03:50:21.000Z","updated_at":"2026-01-01T14:08:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/impalex/icmpenguin","commit_stats":null,"previous_names":["impalex/icmpenguin"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/impalex/icmpenguin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/impalex%2Ficmpenguin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/impalex%2Ficmpenguin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/impalex%2Ficmpenguin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/impalex%2Ficmpenguin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/impalex","download_url":"https://codeload.github.com/impalex/icmpenguin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/impalex%2Ficmpenguin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","icmp","library","ndk","networking","ping","traceroute"],"created_at":"2026-01-06T09:15:41.373Z","updated_at":"2026-01-13T20:41:22.390Z","avatar_url":"https://github.com/impalex.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"500px\" src=\"assets/logo_line_transparency.png\"/\u003e\n\u003cbr/\u003e\n\n![Maven Central](https://img.shields.io/maven-central/v/me.impa/icmpenguin?color=blue) ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg) ![SDK 24+](https://img.shields.io/badge/minSdk-24+-orange.svg)\n# icmpenguin\n\n**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.\n\nThe 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.\n\n# Key Features\n\n- **Ping Functionality:** Send ICMP echo requests with customizable parameters like TTL, timeout, packet size, interval, and data pattern.\n- **Traceroute Functionality:** Trace routes using ICMP or UDP probes, with support for stepped or concurrent strategies, port selection, and MTU discovery.\n- **Asynchronous Operations:** Built on Kotlin Coroutines for non-blocking I/O, ensuring smooth integration with Android UI threads.\n- **IPv4/IPv6 Support:** Automatic address resolution and protocol handling.\n- **MTU Discovery:** Dynamically adjust packet sizes to detect path MTU issues during traceroute.\n- **Customizable Strategies:** For traceroute, choose between stepped (with concurrency limits) or concurrent probing.\n- **Detailed Results:** Probe results include success metrics (RTT, TTL), errors (e.g., host unreachable with offender IP), and timeouts.\n- **Thread-Safety:** Uses atomics and safe concurrency in both Kotlin and C++ layers.\n- **JNI Integration:** Native code handles socket creation, packet sending/receiving, and error processing efficiently.\n\n# Advantages\n\n- **Performance:** Native C++ core minimizes overhead for socket operations, making it faster than pure Java alternatives.\n- **Flexibility:** Extensive configuration options for probes, strategies, and sizes, suitable for advanced network diagnostics.\n- **Ease of Use:** High-level APIs (``Pinger`` and ``SimpleTracer``) abstract complexity, with suspend functions and callbacks for results.\n- **Android-Friendly:** Coroutine-based, avoids UI blocking; no external dependencies.\n- **Robust Error Handling:** Detailed error codes, offender IPs, and MTU info help in troubleshooting network issues.\n- **Open-Source:** Apache 2.0 license allows free use, modification, and distribution.\n\n# Device Compatibility\n\n### IMPORTANT!\n\n**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.\n\n**Always test network functionality on physical devices.** Use the emulator primarily for UI development and logic testing.\n\n# Requirements\n- Android API Level 24+ (Android 7.0+)\n- Internet permission in manifest:\n```xml\n\u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n```\n\n# Setup\nYou can add this library to your project using Gradle.\n```groovy\ndependencies {\n  implementation(\"me.impa:icmpenguin:1.0.0-rc.1\")\n}\n```\n\n# Building from Source\nClone the repository:\n```bash\ngit clone https://github.com/impalex/icmpenguin.git\n```\nBuild with Gradle:\n```bash\n./gradlew build\n```\n\n# Usage\n## Ping Example\n\nUse the ``Pinger`` class to perform ping operations. Results are delivered via a callback.\n```kotlin\nimport me.impa.icmpenguin.ping.Pinger\n\nsuspend fun pingHost(host: String) {\n    val pinger = Pinger(\n        host = host,\n        timeout = 3000,\n        maxPingCount = 4,\n        interval = 1000\n    )\n    \n    pinger.ping { result -\u003e\n        when (result) {\n            is ProbeResult.Success -\u003e {\n                println(\"Reply from ${result.remote}: time=${result.elapsedUsec}μs ttl=${result.ttl}\")\n            }\n            is ProbeResult.Timeout -\u003e {\n                println(\"Request timed out for ${result.remote}\")\n            }\n            is ProbeResult.HostUnreachable -\u003e {\n                println(\"Host ${result.remote} unreachable via ${result.offender}\")\n            }\n            else -\u003e println(\"Result: $result\")\n        }\n    }\n}\n```\n\n## Traceroute Example\n\nUse the ``SimpleTracer`` class for simplified traceroute. Hop statuses are updated asynchronously.\n```kotlin\nimport me.impa.icmpenguin.trace.SimpleTracer\n\nsuspend fun traceRoute(host: String) {\n    val tracer = SimpleTracer(\n        host = host,\n        probeType = ProbeType.ICMP,\n        maxHops = 30,\n        probesPerHop = 3,\n        timeout = 2000\n    )\n    \n    tracer.trace { hopStatus -\u003e\n        println(hopStatus)\n    }\n}\n```\n\n## Advanced Ping Configuration\n\n```kotlin\nval pinger = Pinger(\n    host = \"google.com\",\n    ttl = 64,                           // Time To Live\n    timeout = 5000,                     // Response timeout in ms\n    maxPingCount = Pinger.INFINITE,     // Infinite pings (until stopped)\n    interval = 1000,                    // Time between pings\n    probeSize = 56,                     // Packet size including headers\n    pattern = \"PING1234\".toByteArray()  // Custom payload pattern\n)\n```\n\n## Custom Traceroute Strategy\n\n```kotlin\nval tracer = Tracer(\n    host = \"github.com\",\n    probeType = ProbeType.UDP,\n    traceStrategy = TraceStrategy.Concurrent(\n        maxHops = 30,\n        cycles = 3,              // Repeat entire trace 3 times\n        interval = 2000L         // Time between cycles\n    ),\n    portStrategy = PortStrategy.Sequential(start = 33434),\n    probeSize = ProbeSize.MtuDiscovery,  // Automatically discover MTU\n    timeout = 3000\n)\n\n// Track individual probe results\ntracer.trace { hop, result -\u003e\n    println(\"Hop $hop: $result\")\n}\n```\n\n# Documentation\n\nFor more information, please refer to the [documentation.](https://impalex.github.io/icmpenguin/)\n\n# Contributing\n\nContributions are welcome! Please submit pull requests for bug fixes or new features.\n\n# License\n```\n Copyright (c) 2025 Alexander Yaburov\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing,\n software distributed under the License is distributed on an\n \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n KIND, either express or implied.  See the License for the\n specific language governing permissions and limitations\n under the License.\n ```\n #\n Penguin loves packets! 🐧📦","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimpalex%2Ficmpenguin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimpalex%2Ficmpenguin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimpalex%2Ficmpenguin/lists"}