-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README with detailed package information, add .gitignore entri…
…es for Protobuf files, refactor TowerComms message handling methods, and adjust data types in packets.proto.
- Loading branch information
Showing
9 changed files
with
255 additions
and
17 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
name: Run Ruff Linter | ||
|
||
on: | ||
pull_request: | ||
branches: | ||
- main | ||
- dev | ||
|
||
jobs: | ||
lint: | ||
runs-on: ubuntu-latest | ||
|
||
steps: | ||
- name: Check out code | ||
uses: actions/checkout@v3 | ||
|
||
- name: Set up Python 3.12 | ||
uses: actions/setup-python@v4 | ||
with: | ||
python-version: '3.12' | ||
|
||
- name: Cache dependencies | ||
uses: actions/cache@v3 | ||
with: | ||
path: | | ||
~/.cache/pypoetry | ||
~/.cache/pip | ||
key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }} | ||
restore-keys: | | ||
${{ runner.os }}-poetry- | ||
- name: Install dependencies | ||
run: | | ||
python -m pip install --upgrade pip | ||
pip install poetry | ||
poetry install --with dev | ||
- name: Run ruff linter | ||
run: | | ||
poetry run ruff check . |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
name: Run Tests | ||
|
||
on: | ||
pull_request: | ||
branches: | ||
- main | ||
- dev | ||
|
||
jobs: | ||
test: | ||
runs-on: ubuntu-latest | ||
|
||
steps: | ||
- name: Check out code | ||
uses: actions/checkout@v3 | ||
|
||
- name: Set up Python 3.12 | ||
uses: actions/setup-python@v4 | ||
with: | ||
python-version: '3.12' | ||
|
||
- name: Cache dependencies | ||
uses: actions/cache@v3 | ||
with: | ||
path: | | ||
~/.cache/pypoetry | ||
~/.cache/pip | ||
key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }} | ||
restore-keys: | | ||
${{ runner.os }}-poetry- | ||
- name: Install dependencies | ||
run: | | ||
python -m pip install --upgrade pip | ||
pip install poetry | ||
poetry install --with dev | ||
- name: Run tests | ||
run: | | ||
poetry run pytest |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -176,3 +176,7 @@ cython_debug/ | |
|
||
# Poetry | ||
poetry.lock | ||
|
||
# Protobuf | ||
*_pb2.py | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
This software is Copyright © 2024 The Regents of the University of California. All Rights Reserved. Permission to copy, modify, and distribute this software and its documentation for educational, research and non-profit purposes, without fee, and without a written agreement is hereby granted, provided that the above copyright notice, this paragraph and the following three paragraphs appear in all copies. Permission to make commercial use of this software may be obtained by contacting: | ||
|
||
Office of Innovation and Commercialization | ||
9500 Gilman Drive, Mail Code 0910 | ||
University of California | ||
La Jolla, CA 92093-0910 | ||
innovation@ucsd.edu | ||
|
||
This software program and documentation are copyrighted by The Regents of the University of California. The software program and documentation are supplied “as is”, without any accompanying services from The Regents. The Regents does not warrant that the operation of the program will be uninterrupted or error-free. The end-user understands that the program was developed for research purposes and is advised not to rely exclusively on the program for any reason. | ||
|
||
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN “AS IS” BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,143 @@ | ||
# radio-telemetry-tracker-tower-comms-package | ||
# Radio Telemetry Tracker Tower Communications Package (Comms Package) | ||
|
||
The **Radio Telemetry Tracker Tower Communications Package** is a Python-based library designed to facilitate mesh network communication between radio telemetry towers using Meshtastic devices. It provides a robust framework for configuration management, ping data transmission, and error handling between towers in a distributed network. | ||
|
||
> Note: This package is intended as a shared component for tower-based radio telemetry systems. It provides the communication infrastructure between towers but is not meant for standalone use. | ||
## Table of Contents | ||
- [Radio Telemetry Tracker Tower Communications Package (Comms Package)](#radio-telemetry-tracker-tower-communications-package-comms-package) | ||
- [Table of Contents](#table-of-contents) | ||
- [Overview](#overview) | ||
- [Prerequisites](#prerequisites) | ||
- [Installation](#installation) | ||
- [Configuration](#configuration) | ||
- [Usage](#usage) | ||
- [Message Types](#message-types) | ||
- [Development](#development) | ||
- [License](#license) | ||
|
||
## Overview | ||
|
||
This package provides: | ||
|
||
- **Mesh Network Communication**: Interface with Meshtastic devices for tower-to-tower communication | ||
- **Message Types**: Protobuf-defined messages for configuration, pings, and errors | ||
- **Acknowledgments**: Built-in support for message acknowledgments and retries | ||
- **Position Tracking**: Integration with GPS data from Meshtastic devices | ||
- **Simulation Support**: Simulated mesh interface for development and testing | ||
|
||
## Prerequisites | ||
|
||
- Python 3.13 | ||
- Poetry for dependency management | ||
- Meshtastic-compatible device for real deployment | ||
- Protocol Buffers compiler for development | ||
|
||
## Installation | ||
|
||
1. Add as a dependency to your project: | ||
```bash | ||
poetry add git+https://github.com/UCSD-E4E/radio-telemetry-tracker-tower-comms-package.git | ||
``` | ||
2. Or clone for development: | ||
```bash | ||
bash | ||
git clone https://github.com/UCSD-E4E/radio-telemetry-tracker-tower-comms-package.git | ||
cd radio-telemetry-tracker-tower-comms-package | ||
poetry install | ||
``` | ||
|
||
## Configuration | ||
|
||
The library supports two interface types: | ||
|
||
1. **Meshtastic Interface**: | ||
```python | ||
from radio_telemetry_tracker_tower_comms_package import NodeConfig, TowerComms | ||
config = NodeConfig( | ||
interface_type="meshtastic", | ||
device="/dev/ttyUSB0", # Serial port for Meshtastic device | ||
) | ||
``` | ||
2. **Simulated Interface** (for testing): | ||
```python | ||
from radio_telemetry_tracker_tower_comms_package import NodeConfig, TowerComms | ||
config = NodeConfig( | ||
interface_type="simulated", | ||
numeric_id=1, # Unique node ID | ||
user_id="Tower1" # Human-readable name | ||
) | ||
``` | ||
|
||
## Usage | ||
|
||
Basic usage pattern: | ||
|
||
1. **Initialize communications**: | ||
```python | ||
from radio_telemetry_tracker_tower_comms_package import TowerComms, NodeConfig | ||
def on_ack_success(packet_id: int): | ||
print(f"Packet {packet_id} acknowledged") | ||
def on_ack_failure(packet_id: int): | ||
print(f"Packet {packet_id} failed") | ||
config = NodeConfig(interface_type="meshtastic", device="/dev/ttyUSB0") | ||
comms = TowerComms(config, on_ack_success, on_ack_failure) | ||
``` | ||
2. **Register message handlers**: | ||
```python | ||
def handle_ping(data: PingData): | ||
print(f"Ping received from {data.node_id} at freq {data.frequency}") | ||
comms.register_ping_handler(handle_ping) | ||
``` | ||
3. **Start communication**: | ||
```python | ||
comms.start() # Opens the mesh interface | ||
``` | ||
4. **Send messages**: | ||
```python | ||
comms.send_request_config(destination=2, want_ack=True) | ||
ping_data = PingData(frequency=915000000, amplitude=0.8, latitude=32.7, longitude=-117.1, altitude=100) | ||
comms.send_ping(ping_data, destination=None) # Broadcast | ||
``` | ||
5. **Stop communication**: | ||
```python | ||
comms.stop() # Closes the mesh interface | ||
``` | ||
|
||
|
||
## Message Types | ||
|
||
- **ConfigData**: Tower configuration parameters | ||
- **PingData**: Radio ping detection data with GPS coordinates | ||
- **ErrorData**: Error messages and diagnostics | ||
- **RequestConfigData**: Configuration request messages | ||
|
||
## Development | ||
|
||
1. Install development dependencies: | ||
```bash | ||
poetry install --with dev | ||
``` | ||
2. Run tests: | ||
```bash | ||
poetry run pytest | ||
``` | ||
3. Check code style: | ||
```bash | ||
poetry run ruff check . --fix | ||
``` | ||
|
||
## License | ||
|
||
This project is licensed under the terms specified in the [LICENSE](LICENSE) file. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters