mirror of
https://github.com/rightup/pyMC_Repeater.git
synced 2026-03-28 17:43:06 +01:00
257 lines
6.9 KiB
Markdown
257 lines
6.9 KiB
Markdown
# pyMC_repeater
|
||
|
||
Repeater Daemon in Python using the `pymc_core` Lib.
|
||
|
||
---
|
||
|
||
I started **pyMC_core** as a way to really get under the skin of **MeshCore** — to see how it ticked and why it behaved the way it did.
|
||
After a few late nights of tinkering, testing, and head-scratching, I shared what I’d learned with the community.
|
||
The response was honestly overwhelming — loads of encouragement, great feedback, and a few people asking if I could spin it into a lightweight **repeater daemon** that would run happily on low-power, Pi-class hardware.
|
||
|
||
That challenge shaped much of what followed:
|
||
- I went with a lightweight HTTP server (**CherryPy**) instead of a full-fat framework.
|
||
- I stuck with simple polling over WebSockets — it’s more reliable, has fewer dependencies, and is far less resource hungry.
|
||
- I kept the architecture focused on being **clear, modular, and hackable** rather than chasing performance numbers.
|
||
|
||
There’s still plenty of room for this project to grow and improve — but you’ve got to start somewhere!
|
||
My hope is that **pyMC_repeater** serves as a solid, approachable foundation that others can learn from, build on, and maybe even have a bit of fun with along the way.
|
||
|
||
> **I’d love to see these repeaters out in the wild — actually running in real networks and production setups.**
|
||
> My own testing so far has been in a very synthetic environment with little to no other users in my area,
|
||
> so feedback from real-world deployments would be incredibly valuable!
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
The repeater daemon runs continuously as a background process, forwarding LoRa packets using `pymc_core`'s Dispatcher and packet routing.
|
||
|
||
Supported Hardware (Out of the Box)
|
||
|
||
The following hardware is currently supported out-of-the-box:
|
||
|
||
Waveshare LoRaWAN/GNSS HAT
|
||
|
||
Hardware: Waveshare SX1262 LoRa HAT
|
||
Platform: Raspberry Pi (or compatible single-board computer)
|
||
Frequency: 868MHz (EU) or 915MHz (US)
|
||
TX Power: Up to 22dBm
|
||
SPI Bus: SPI0
|
||
GPIO Pins: CS=21, Reset=18, Busy=20, IRQ=16
|
||
|
||
HackerGadgets uConsole
|
||
|
||
Hardware: uConsole RTL-SDR/LoRa/GPS/RTC/USB Hub
|
||
Platform: Clockwork uConsole (Raspberry Pi CM4/CM5)
|
||
Frequency: 433/915MHz (configurable)
|
||
TX Power: Up to 22dBm
|
||
SPI Bus: SPI1
|
||
GPIO Pins: CS=-1, Reset=25, Busy=24, IRQ=26
|
||
Additional Setup: Requires SPI1 overlay and GPS/RTC configuration (see uConsole setup guide)
|
||
|
||
Frequency Labs meshadv-mini
|
||
|
||
Hardware: FrequencyLabs meshadv-mini Hat
|
||
Platform: Raspberry Pi (or compatible single-board computer)
|
||
Frequency: 868MHz (EU) or 915MHz (US)
|
||
TX Power: Up to 22dBm
|
||
SPI Bus: SPI0
|
||
GPIO Pins: CS=8, Reset=24, Busy=20, IRQ=16
|
||
|
||
Frequency Labs meshadv
|
||
|
||
Hardware: FrequencyLabs meshadv-mini Hat
|
||
Platform: Raspberry Pi (or compatible single-board computer)
|
||
Frequency: 868MHz (EU) or 915MHz (US)
|
||
TX Power: Up to 22dBm
|
||
SPI Bus: SPI0
|
||
GPIO Pins: CS=21, Reset=18, Busy=20, IRQ=16, TXEN=13, RXEN=12, use_dio3_tcxo=True
|
||
...
|
||
|
||
## Screenshots
|
||
|
||
### Dashboard
|
||
|
||
*Real-time monitoring dashboard showing packet statistics, neighbor discovery, and system status*
|
||
|
||
### Statistics
|
||
|
||
*statistics and performance metrics*
|
||
|
||
## Installation
|
||
|
||
Before You Begin
|
||
|
||
Make sure SPI is switched on using raspi-config:
|
||
|
||
```bash
|
||
sudo raspi-config
|
||
```
|
||
|
||
1. Go to Interface Options
|
||
2. Select SPI
|
||
3. Choose Enable
|
||
4. Reboot when prompted:
|
||
|
||
```bash
|
||
sudo reboot
|
||
```
|
||
|
||
After reboot, you can confirm SPI is active:
|
||
```bash
|
||
ls /dev/spi*
|
||
```
|
||
|
||
You should see something like:
|
||
```bash
|
||
/dev/spidev0.0 /dev/spidev0.1
|
||
```
|
||
|
||
**Clone the Repository:**
|
||
```bash
|
||
git clone https://github.com/rightup/pyMC_Repeater.git
|
||
cd pyMC_Repeater
|
||
```
|
||
|
||
**Quick Install:**
|
||
```bash
|
||
sudo bash manage.sh
|
||
```
|
||
|
||
This script will:
|
||
- Create a dedicated `repeater` service user with hardware access
|
||
- Install files to `/opt/pymc_repeater`
|
||
- Create configuration directory at `/etc/pymc_repeater`
|
||
- Setup log directory at `/var/log/pymc_repeater`
|
||
- **Launch interactive radio & hardware configuration wizard**
|
||
- Install and enable systemd service
|
||
|
||
**After Installation:**
|
||
```bash
|
||
# View live logs
|
||
sudo journalctl -u pymc-repeater -f
|
||
|
||
# Access web dashboard
|
||
http://<repeater-ip>:8000
|
||
```
|
||
|
||
**Development Install:**
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
## Configuration
|
||
|
||
The configuration file is created and configured during installation at:
|
||
```
|
||
/etc/pymc_repeater/config.yaml
|
||
```
|
||
|
||
To reconfigure radio and hardware settings after installation, run:
|
||
```bash
|
||
sudo bash setup-radio-config.sh /etc/pymc_repeater or sudo bash manage.sh
|
||
sudo systemctl restart pymc-repeater
|
||
|
||
```
|
||
## Upgrading
|
||
|
||
To upgrade an existing installation to the latest version:
|
||
|
||
```bash
|
||
# Navigate to your pyMC_Repeater directory
|
||
cd pyMC_Repeater
|
||
|
||
# Run the upgrade script
|
||
sudo bash manage.sh
|
||
```
|
||
|
||
The upgrade script will:
|
||
- Pull the latest code from the main branch
|
||
- Update all application files
|
||
- Upgrade Python dependencies if needed
|
||
- Restart the service automatically
|
||
- Preserve your existing configuration
|
||
|
||
|
||
|
||
|
||
## Uninstallation
|
||
|
||
```bash
|
||
sudo bash manage.sh
|
||
```
|
||
|
||
This script will:
|
||
- Stop and disable the systemd service
|
||
- Remove the installation directory
|
||
- Optionally remove configuration, logs, and user data
|
||
- Optionally remove the service user account
|
||
|
||
The script will prompt you for each optional removal step.
|
||
|
||
|
||
## Roadmap / Planned Features
|
||
|
||
- [ ] **Public Map Integration** - Submit repeater location and details to public map for discovery
|
||
- [ ] **Remote Administration over LoRa** - Manage repeater configuration remotely via LoRa mesh
|
||
- [ ] **Trace Request Handling** - Respond to trace/diagnostic requests from mesh network
|
||
|
||
|
||
## Contributing
|
||
|
||
I welcome contributions! To contribute to pyMC_repeater:
|
||
|
||
1. **Fork the repository** and clone your fork
|
||
2. **Create a feature branch** from the `dev` branch:
|
||
```bash
|
||
git checkout -b feature/your-feature-name dev
|
||
```
|
||
3. **Make your changes** and test with **real** hardware
|
||
4. **Commit with clear messages**:
|
||
```bash
|
||
git commit -m "feat: description of changes"
|
||
```
|
||
5. **Push to your fork** and submit a **Pull Request to the `dev` branch**
|
||
- Include a clear description of the changes
|
||
- Reference any related issues
|
||
|
||
### Development Setup
|
||
|
||
```bash
|
||
# Install in development mode with dev tools (black, pytest, isort, mypy, etc)
|
||
pip install -e ".[dev]"
|
||
|
||
# Setup pre-commit hooks for code quality
|
||
pip install pre-commit
|
||
pre-commit install
|
||
|
||
# Manually run pre-commit checks on all files
|
||
pre-commit run --all-files
|
||
```
|
||
|
||
**Note:** Hardware support (LoRa radio drivers) is included in the base installation automatically via `pymc_core[hardware]`.
|
||
|
||
Pre-commit hooks will automatically:
|
||
- Format code with Black
|
||
- Sort imports with isort
|
||
- Lint with flake8
|
||
- Fix trailing whitespace and other file issues
|
||
|
||
|
||
|
||
## Support
|
||
|
||
- [Core Lib Documentation](https://rightup.github.io/pyMC_core/)
|
||
- [Meshcore Discord](https://discord.gg/fThwBrRc3Q)
|
||
|
||
|
||
|
||
|
||
## License
|
||
|
||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||
|
||
|
||
|
||
|