Metadata-Version: 2.4
Name: pymc_core
Version: 1.0.11
Summary: A Python MeshCore library with SPI LoRa radio support
Author-email: Lloyd Newton <lloyd@rightup.co.uk>
License: MIT
Project-URL: Homepage, https://github.com/rightup/pyMC_core
Project-URL: Documentation, https://rightup.github.io/rightup/pyMC_core
Project-URL: Repository, https://github.com/rightup/pyMC_core.git
Project-URL: Issues, https://github.com/rightup/pyMC_core/issues
Keywords: mesh,networking,lora,radio,iot,communication
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: PyNaCl>=1.5.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: radio
Requires-Dist: pyserial>=3.5; extra == "radio"
Provides-Extra: hardware
Requires-Dist: python-periphery>=2.4.1; extra == "hardware"
Requires-Dist: spidev>=3.5; extra == "hardware"
Requires-Dist: pyserial>=3.5; extra == "hardware"
Requires-Dist: pyusb>=1.2.1; extra == "hardware"
Provides-Extra: gpiod
Requires-Dist: gpiod>=2.4.0; extra == "gpiod"
Provides-Extra: websocket
Requires-Dist: websockets>=11.0.0; extra == "websocket"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pyserial>=3.5; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "docs"
Requires-Dist: mkdocs-git-committers-plugin-2>=1.2.0; extra == "docs"
Provides-Extra: all
Requires-Dist: pymc_core[dev,docs,hardware,websocket]; extra == "all"
Dynamic: license-file

# pyMC_Core

[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://pymc-dev.github.io/pyMC_core/)
[![PyPI](https://img.shields.io/pypi/v/pymc-core)](https://pypi.org/project/pymc-core/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**pyMC_Core** is a Python reimplementation of [MeshCore](https://github.com/meshcore-dev/meshcore) — a lightweight, portable C++ library for multi-hop packet routing using LoRa radios. Designed for **Raspberry Pi** and similar hardware, pyMC_Core communicates with LoRa modules over **SPI**.

> pyMC_Core is under active development. It's compatible with the original MeshCore protocol, but not yet as optimized or elegant as its C++ counterpart.

## Documentation

**Complete documentation is available at **[https://rightup.github.io/pyMC_core/](https://pymc-dev.github.io/pyMC_core/)**

### Quick Links
- [Node Usage Guide](https://pymc-dev.github.io/pyMC_core/node/) - Guide for using MeshNode
- [Examples](https://pymc-dev.github.io/pyMC_core/examples/) - Working code examples
- [API Reference](https://pymc-dev.github.io/pyMC_core/api/) - Detailed API documentation

## Quick Start

### Installation

> **Important**: On modern Python installations (Ubuntu 22.04+, Debian 12+), you may encounter `externally-managed-environment` errors when installing packages system-wide. Create a virtual environment first:
>
> ```bash
> # Create virtual environment
> python3 -m venv pymc_env
>
> # Activate virtual environment
> # On Linux/Mac:
> source pymc_env/bin/activate
> # On Windows:
> pymc_env\Scripts\activate
> ```

```bash
# Install from PyPI
pip install pymc-core

# For hardware support (SX1262 radios)
pip install pymc-core[hardware]

# Install all dependencies
pip install pymc-core[all]
```

### Basic Usage

```python
import asyncio
from pymc_core import MeshNode, LocalIdentity
from pymc_core.hardware.sx1262_wrapper import SX1262Radio

async def main():
    # Create radio (Waveshare HAT example)
    radio = SX1262Radio(
        bus_id=0, cs_pin=21, reset_pin=18,
        busy_pin=20, irq_pin=16, txen_pin=6,
        frequency=869525000, tx_power=22
    )
    radio.begin()

    # Create mesh node
    identity = LocalIdentity()
    node = MeshNode(radio=radio, local_identity=identity)
    await node.start()

    print("Mesh node started!")

asyncio.run(main())
```

For examples, see the [documentation](https://pymc-dev.github.io/pyMC_core/examples/).

## Hardware Support

### Supported Radios
- **Waveshare SX1262 LoRaWAN/GNSS HAT** - Popular Raspberry Pi LoRa module
- **HackerGadgets uConsole** - All-in-one extension board with LoRa support
- **FrequencyLabs meshadv-mini** - Raspberry Pi hat with E22-900M22S LoRa module

### Requirements
- Raspberry Pi (or compatible SBC)
- SX1262 LoRa module
- SPI interface enabled
- Python 3.8+

## What is MeshCore?

MeshCore enables **long-range, decentralized communication** using **multi-hop packet routing**. Devices (nodes) forward packets through neighboring nodes to reach distant ones — no central infrastructure required.

It occupies a middle ground between:

| Project | Focus |
|---------|-------|
| [Meshtastic](https://meshtastic.org/) | Casual LoRa messaging |
| [Reticulum](https://reticulum.network/) | Full encrypted networking stack |

### Use Cases
- Off-grid and emergency communication
- Tactical or field mesh deployments
- IoT mesh networks
- Remote monitoring systems

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Application   │    │   MeshNode      │    │   Hardware      │
│                 │    │                 │    │                 │
│ • Text Messages │◄──►│ • Packet Routing│◄──►│ • SX1262 Radio  │
│ • Advertisements│    │ • Identity Mgmt │    │ • SPI Interface │
│ • Telemetry     │    │ • Event Service │    │ • GPIO Control  │
│ • Group Channels│    │ • Repeater Mgmt │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## Security

- **Ed25519/X25519 cryptographic identities**
- **End-to-end encryption** for messages
- **CRC validation** for data integrity
- **Secure key exchange** protocols

## Project Structure

```
pyMC_Core/
├── src/pymc_core/          # Main package
│   ├── hardware/           # Radio hardware interfaces
│   ├── node/               # MeshNode implementation
│   ├── protocol/           # Packet protocols
│   └── events/             # Event handling
├── examples/               # Working examples
│   ├── common.py           # Shared utilities
│   ├── send_flood_advert.py
│   ├── send_direct_advert.py
│   └── ...
├── docs/                   # MkDocs documentation
│   ├── docs/               # Documentation source files
│   ├── mkdocs.yml          # MkDocs configuration
│   ├── requirements.txt    # Documentation dependencies
│   └── serve-docs.sh       # Local development script
├── .github/workflows/      # GitHub Actions
│   └── deploy-docs.yml     # Documentation deployment pipeline
└── tests/                  # Unit tests
```

## Contributing

Contributions are welcome! Please see our [contributing guide](https://pymc-dev.github.io/pyMC_core/contributing/) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/rightup/pyMC_Core.git
cd pyMC_Core

# Install development dependencies
pip install -e .[dev]


```



## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Original [MeshCore](https://github.com/meshcore-dev/meshcore) C++ implementation
- Waveshare and HackerGadgets for hardware support

## Support

- [Documentation](https://pymc-dev.github.io/pyMC_core/)
- [Issues](https://github.com/pymc-dev/pyMC_Core/issues)
- [Discussions](https://github.com/pymc-dev/pyMC_Core/discussions)
- [pyMC Discord](https://discord.gg/3s8MMaSTzq)
- [Meshcore Discord](https://meshcore.gg/)

---

*Built with ❤️ for mesh networking enthusiasts*</content>
