{"id":28400536,"url":"https://github.com/mgarcia01752/pypnm","last_synced_at":"2026-05-13T20:33:40.831Z","repository":{"id":295903924,"uuid":"981762832","full_name":"mgarcia01752/PyPNM","owner":"mgarcia01752","description":"PyPNM — Python-based toolkit for parsing, analyzing, and visualizing DOCSIS 3.0/3.1/4.0 Proactive Network Maintenance (PNM) telemetry.","archived":false,"fork":false,"pushed_at":"2025-12-17T16:33:56.000Z","size":19463,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-17T17:08:32.754Z","etag":null,"topics":["docker","docsis","docsis-modems","docsis-monitoring","docsis-pnm","fastapi","pnm","proactive-network-maintenance","python"],"latest_commit_sha":null,"homepage":"http://www.pypnm.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgarcia01752.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":"SECURITY.md","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-05-11T20:34:19.000Z","updated_at":"2025-12-17T16:33:59.000Z","dependencies_parsed_at":"2025-10-30T19:09:19.082Z","dependency_job_id":"96d63ca4-b5bd-4867-b25c-79da78fe8eca","html_url":"https://github.com/mgarcia01752/PyPNM","commit_stats":null,"previous_names":["mgarcia01752/pypnm"],"tags_count":109,"template":false,"template_full_name":null,"purl":"pkg:github/mgarcia01752/PyPNM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgarcia01752%2FPyPNM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgarcia01752%2FPyPNM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgarcia01752%2FPyPNM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgarcia01752%2FPyPNM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgarcia01752","download_url":"https://codeload.github.com/mgarcia01752/PyPNM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgarcia01752%2FPyPNM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32999393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"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":["docker","docsis","docsis-modems","docsis-monitoring","docsis-pnm","fastapi","pnm","proactive-network-maintenance","python"],"created_at":"2025-06-01T10:38:12.431Z","updated_at":"2026-05-13T20:33:40.826Z","avatar_url":"https://github.com/mgarcia01752.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"docs/index.md\"\u003e\n    \u003cpicture\u003e\n      \u003csource srcset=\"docs/images/logo/pypnm-dark-mode-hp.png\"\n              media=\"(prefers-color-scheme: dark)\" /\u003e\n      \u003cimg src=\"docs/images/logo/pypnm-light-mode-hp.png\"\n           alt=\"PyPNM Logo\"\n           width=\"200\"\n           style=\"border-radius: 24px;\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# PyPNM - Proactive Network Maintenance Toolkit\n\n[![PyPNM Version](https://img.shields.io/github/v/tag/PyPNMApps/PyPNM?label=PyPNM\u0026sort=semver)](https://github.com/PyPNMApps/PyPNM/tags)\n[![PyPI - Version](https://img.shields.io/pypi/v/pypnm-docsis.svg)](https://pypi.org/project/pypnm-docsis/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pypnm-docsis.svg)](https://pypi.org/project/pypnm-docsis/)\n[![Daily Build](https://github.com/PyPNMApps/PyPNM/actions/workflows/daily-build.yml/badge.svg?branch=main)](https://github.com/PyPNMApps/PyPNM/actions/workflows/daily-build.yml)\n![CodeQL](https://github.com/PyPNMApps/PyPNM/actions/workflows/codeql.yml/badge.svg)\n[![PyPI Install Check](https://github.com/PyPNMApps/PyPNM/actions/workflows/pypi-install-check.yml/badge.svg?branch=main)](https://github.com/PyPNMApps/PyPNM/actions/workflows/pypi-install-check.yml)\n[![Kubernetes (kind)](https://github.com/PyPNMApps/PyPNM/actions/workflows/kubernetes-kind.yml/badge.svg?branch=main)](https://github.com/PyPNMApps/PyPNM/actions/workflows/kubernetes-kind.yml)\n[![GHCR Publish](https://github.com/PyPNMApps/PyPNM/actions/workflows/publish-ghcr.yml/badge.svg)](https://github.com/PyPNMApps/PyPNM/actions/workflows/publish-ghcr.yml)\n[![Dockerized](https://img.shields.io/badge/GHCR-latest-2496ED?logo=docker\u0026logoColor=white\u0026label=Docker)](https://github.com/PyPNMApps/PyPNM/pkgs/container/pypnm)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\n[![Ubuntu](https://img.shields.io/badge/Ubuntu-22.04%20%7C%2024.04%20LTS-E95420?logo=ubuntu\u0026logoColor=white)](https://github.com/PyPNMApps/PyPNM)\n\nPyPNM is a DOCSIS 3.x/4.0 Proactive Network Maintenance toolkit for engineers who want repeatable, scriptable visibility into modem health. It can run purely as a Python library or as a FastAPI web service for real-time dashboards and offline analysis workflows.\n\n## Table of contents\n\n- [Choose your path](#choose-your-path)\n- [Kubernetes | Docker](#kubernetes--docker)\n  - [Docker](#docker-deploy)\n  - [Kubernetes (kind)](#k8s-deploy)\n- [Key Features](#key-features)\n- [Prerequisites](#prerequisites)\n  - [Operating Systems](#operating-systems)\n  - [Shell Dependencies](#shell-dependencies)\n- [Getting Started](#getting-started)\n  - [Install From PyPI (Library Only)](#install-from-pypi-library-only)\n  - [1) Clone](#1-clone)\n  - [2) Install](#2-install)\n  - [3) Activate The Virtual Environment](#3-activate-the-virtual-environment)\n  - [4) Configure System Settings](#4-configure-system-settings)\n  - [5) Run The FastAPI Service Launcher](#5-run-the-fastapi-service-launcher)\n  - [6) (Optional) Serve The Documentation](#6-optional-serve-the-documentation)\n  - [7) Explore The API](#7-explore-the-api)\n- [Documentation](#documentation)\n- [Gallery](docs/gallery/index.md)\n- [SNMP Notes](#snmp-notes)\n- [CableLabs Specifications \u0026 MIBs](#cablelabs-specifications--mibs)\n- [PNM Architecture \u0026 Guidance](#pnm-architecture--guidance)\n- [License](#license)\n- [Maintainer](#maintainer)\n\n## Choose your path\n\n| Path | Description |\n| --- | --- |\n| [Kubernetes deploy (kind)](#k8s-deploy) | Run PyPNM in a local kind cluster (GHCR image). |\n| [Docker deploy](#docker-deploy) | Install and run the containerized PyPNM service. |\n| [Use PyPNM as a library](#install-from-pypi-library-only) | Install `pypnm-docsis` into an existing Python environment. |\n| [Run the full platform](#1-clone) | Clone the repo and use the full FastAPI + tooling stack. |\n\n## Kubernetes | Docker\n\n\u003ca id=\"docker-deploy\"\u003e\u003c/a\u003e\n### Docker (Recommended) - [Install Docker](docs/docker/install-docker.md) | [Install PyPNM Container](docs/docker/install.md) | [Commands](docs/docker/commands.md)\n\nFast install (helper script; latest release auto-detected):\n\n```bash\nTAG=\"v1.0.5.0\"\nPORT=8080\n\ncurl -fsSLo install-pypnm-docker-container.sh \\\n  https://raw.githubusercontent.com/PyPNMApps/PyPNM/main/scripts/install-pypnm-docker-container.sh\n\nchmod +x install-pypnm-docker-container.sh\n\nsudo ./install-pypnm-docker-container.sh --tag ${TAG} --port ${PORT}\n```\n\nIf Docker isn’t on your host yet, follow the [Install Docker prerequisites](docs/docker/install-docker.md) guide first.\n\nMore Docker options and compose workflows: [PyPNM Docker Installation](docs/docker/install.md) and [Developer Workflow](docs/docker/commands.md#developer-workflow).\n\n\u003ca id=\"k8s-deploy\"\u003e\u003c/a\u003e\n### Kubernetes (kind) dev clusters\n\nKubernetes quick links:\n- [Install kind](docs/kubernetes/kind-install.md)\n- [Deploy PyPNM](docs/kubernetes/pypnm-deploy.md)\n- [kind + FreeLens (VM)](docs/kubernetes/kind-freelens.md)\n\nWe continuously test the manifests with a kind-based CI smoke test (`Kubernetes (kind)` badge above). Follow the [kind quickstart](docs/kubernetes/quickstart.md) or the [detailed deployment guide](docs/kubernetes/pypnm-deploy.md) to run PyPNM inside a local single-node cluster; multi-node scenarios are not covered yet (see [pros/cons](docs/kubernetes/pros-cons.md)).\n\nScript-only deployment (no repo clone) is documented in [PyPNM deploy](docs/kubernetes/pypnm-deploy.md#script-only-deploy-no-repo-clone).\n\n## Prerequisites\n\n### Operating systems\n\nLinux, validated on:\n\n- Ubuntu 22.04 LTS\n- Ubuntu 24.04 LTS\n\nOther modern Linux distributions may work but are not yet part of the test matrix.\n\n### Shell dependencies\n\nFrom a fresh system, install Git:\n\n```bash\nsudo apt update\nsudo apt install -y git\n```\n\nPython and remaining dependencies are handled by the installer.\n\n## Getting started\n\n### Install from PyPI (library only)\n\nIf you only need the library, install from PyPI:\n\n  ```bash\n  pip install pypnm-docsis\n  ```\n\nUninstall and cleanup:\n\n  ```bash\n  pip uninstall pypnm-docsis\n  rm -f ~/.ssh/pypnm_secrets.key\n  ```\n\nFor full FastAPI service usage and development, use the repository-based flow below.\n\n### 1) Clone\n\n  ```bash\n  git clone https://github.com/PyPNMApps/PyPNM.git\n  cd PyPNM\n```\n\n### 2) Install\n\nRun the installer:\n\n  ```bash\n  ./install.sh\n  ```\n\nCommon flags (use as needed):\n\n| Flag | Purpose |\n|------|---------|\n| `--development` | Installs Docker Engine + kind/kubectl. See [Development Install](docs/install/development.md). |\n| `--clean`       | Removes prior install artifacts (venv/build/dist/cache) before installing. Preserves data and system configuration. |\n| `--purge-cache` | Clears pip cache after activating the venv (use with `--clean` when troubleshooting stale installs). |\n| `--pnm-file-retrieval-setup` | Launches `tools/pnm/pnm_file_retrieval_setup.py` after install. See the [PNM File Retrieval Overview](docs/topology/index.md). |\n| `--demo-mode`   | Seeds demo data/paths for offline exploration. See the [demo mode guide](./demo/README.md). |\n| `--production`  | Reverts demo-mode changes and restores your previous `system.json` backup. |\n\nInstaller extras: adds shell aliases when available; source your rc file once to pick them up.\n\n### 3) Activate the virtual environment\n\nIf you used the installer defaults, activate the `.env` environment:\n\n  ```bash\n  source .env/bin/activate\n  ```\n\n\n### 4) Configure system settings\n\nSystem configuration lives in [deploy/docker/config/system.json](https://github.com/PyPNMApps/PyPNM/blob/main/deploy/docker/config/system.json).\n\n- [Config menu](docs/system/menu.md): `source ~/.bashrc \u0026\u0026 config-menu`\n- [System Configuration Reference](docs/system/system-config.md): field-by-field descriptions and defaults\nIf you installed with `--pnm-file-retrieval-setup`, it runs automatically and backs up `system.json` first.\n\n\u003c!-- Removed duplicated Step 3/4 block --\u003e\n\n### 5) [Run the FastAPI service launcher](docs/system/pypnm-cli.md)\n\nHTTP (default: `http://127.0.0.1:8000`):\n\n  ```bash\n  pypnm\n  ```\n\nDevelopment hot-reload:\n\n  ```bash\n  pypnm --reload\n  ```\n\n### 6) (Optional) Serve the documentation\n\nHTTP (default: `http://127.0.0.1:8001`):\n\n  ```bash\n  mkdocs serve\n  ```\n\n### 7) Explore the API\n\nInstalled services and docs are available at the following URLs:\n\n| Git Clone | Docker |\n|-----------|--------|\n| [FastAPI Swagger UI](http://localhost:8000/docs)  | [FastAPI Swagger UI](http://localhost:8080/docs)  |\n| [FastAPI ReDoc](http://localhost:8000/redoc)      | [FastAPI ReDoc](http://localhost:8080/redoc)      |\n| [MkDocs docs](http://localhost:8001)              | [MkDocs docs](http://localhost:8081)              |\n\n## Documentation\n\n- [Docs hub](./docs/index.md) - task-based entry point (install, configure, operate, contribute).\n- [FastAPI reference](./docs/api/fast-api/index.md) - Endpoint details and request/response schemas.\n- [Python API reference](./docs/api/python/index.md) - Importable helpers and data models.\n\n## SNMP notes\n\n- SNMPv2c is supported  \n- SNMPv3 is currently stubbed and not yet supported\n\n## CableLabs specifications \u0026 MIBs\n\n- [CM-SP-MULPIv3.1](https://www.cablelabs.com/specifications/CM-SP-MULPIv3.1)  \n- [CM-SP-CM-OSSIv3.1](https://www.cablelabs.com/specifications/CM-SP-CM-OSSIv3.1)  \n- [CM-SP-MULPIv4.0](https://www.cablelabs.com/specifications/CM-SP-MULPIv4.0)  \n- [CM-SP-CM-OSSIv4.0](https://www.cablelabs.com/specifications/CM-SP-CM-OSSIv4.0)  \n- [DOCSIS MIBs](https://mibs.cablelabs.com/MIBs/DOCSIS/)\n\n## PNM architecture \u0026 guidance\n\n- [CM-TR-PMA](https://www.cablelabs.com/specifications/CM-TR-PMA)  \n- [CM-GL-PNM-HFC](https://www.cablelabs.com/specifications/CM-GL-PNM-HFC)  \n- [CM-GL-PNM-3.1](https://www.cablelabs.com/specifications/CM-GL-PNM-3.1)\n\n## License\n\n[`Apache License 2.0`](./LICENSE) and [`NOTICE`](./NOTICE)\n\n## Next steps\n\n- Review [PNM topology options](docs/topology/index.md) to decide how captures will move through your network.\n- Follow the [System Configuration guide](docs/system/system-config.md) to tailor `system.json` for your lab.\n- Explore [system tools](docs/system/menu.md) and [operational scripts](docs/tools/index.md) for day-to-day automation.\n\n## Maintainer\n\nMaurice Garcia\n\n- [Email](mailto:mgarcia01752@outlook.com)  \n- [LinkedIn](https://www.linkedin.com/in/mauricemgarcia/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgarcia01752%2Fpypnm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgarcia01752%2Fpypnm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgarcia01752%2Fpypnm/lists"}