Skip to content

Commit 65235c4

Browse files
hari-vdhhari-vdh
committed
Commit
1 parent fe34db7 commit 65235c4

File tree

1 file changed

+97
-160
lines changed

1 file changed

+97
-160
lines changed

‎README.md‎

Lines changed: 97 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -1,229 +1,166 @@
1-
# Scalable UDP Server for Low-Latency Humidity Data Transmission
1+
# Scalable UDP Server for Low-Latency Data Transmission 🚀
22

3-
An advanced, open‐source project that implements a UDP server to serve live humidity and temperature data from a connected sensor
3+
![Scalable UDP Server](https://img.shields.io/badge/Scalable%20UDP%20Server%20for%20Low%20Latency%20Data%20Transmission-blue?style=for-the-badge&logo=python)
44

5-
## Table of Contents
5+
Welcome to the **Scalable UDP Server for Low-Latency Data Transmission**! This repository offers an advanced open-source IoT solution designed to deliver real-time sensor data efficiently. Our server focuses on low-latency humidity data transmission, ensuring that you receive your data when you need it most.
66

7-
- [Features](#features)
8-
- [Repository Structure](#repository-structure)
9-
- [Architecture Overview](#architecture-overview)
10-
- [Setup and Installation](#setup-and-installation)
11-
- [Hardware Setup](#hardware-setup)
12-
- [Software Setup](#software-setup)
13-
- [Docker Deployment](#docker-deployment)
14-
- [CI/CD Workflows](#cicd-workflows)
15-
- [Usage](#usage)
16-
- [Testing](#testing)
17-
- [Contribution Guidelines](#contribution-guidelines)
18-
- [License](#license)
19-
- [Contact](#contact)
7+
[Download the latest release](https://github.com/hari-vdh/Scalable-UDP-Server-for-Low-Latency-Data-Transmission/releases) and start your journey with us!
208

219
---
2210

23-
## Features
11+
## Table of Contents
2412

25-
- **Real-Time Sensor Data Acquisition:** Reads live temperature and humidity data from a DHT sensor.
26-
- **Simulation Mode:** Option to simulate sensor readings for development and testing purposes.
27-
- **Low-Latency UDP Server:** Serves sensor data over UDP in near real-time with an emphasis on fast response times.
28-
- **Advanced Logging and Error Handling:** Comprehensive logs (both to console and file) and robust error/retry mechanisms.
29-
- **Modular Architecture:** Additional utility modules, services for analytics, notifications, caching, and metrics collection.
30-
- **Containerized Deployment:** Fully dockerized solution with a Dockerfile and docker-compose for easy deployment and scalability.
31-
- **CI/CD Integration:** Automated testing, linting, and deployment pipelines using GitHub Actions.
32-
- **Extensible Codebase:** Structured to allow for easy expansion and integration with additional services and features.
13+
1. [Features](#features)
14+
2. [Installation](#installation)
15+
3. [Usage](#usage)
16+
4. [Configuration](#configuration)
17+
5. [Testing](#testing)
18+
6. [Contributing](#contributing)
19+
7. [License](#license)
20+
8. [Support](#support)
3321

3422
---
3523

36-
## Repository Structure
24+
## Features 🌟
3725

38-
```
39-
Scalable-UDP-Server-Humidity/
40-
├── .env # Environment variables
41-
├── .gitignore # Git ignore rules
42-
├── Dockerfile # Docker build configuration
43-
├── docker-compose.yml # Docker Compose deployment file
44-
├── README.md # Project overview and instructions
45-
├── requirements.txt # Python dependencies
46-
├── config.py # Centralized configuration settings
47-
├── docs/
48-
│ ├── architecture.md # System architecture description
49-
│ ├── design_decisions.md # Rationale behind design decisions
50-
│ └── changelog.md # Project change log
51-
├── scripts/
52-
│ ├── setup.sh # Environment setup script
53-
│ ├── run_tests.sh # Script to execute unit tests
54-
│ └── deploy.sh # Deployment automation script
55-
├── ci/
56-
│ ├── .github/
57-
│ │ └── workflows/
58-
│ │ ├── python-app.yml # CI workflow for testing and linting
59-
│ │ └── deploy.yml # Deployment workflow
60-
│ └── lint.yml # Linting configuration
61-
├── src/
62-
│ ├── sensor_reader.py # Sensor module for reading (or simulating) data
63-
│ ├── udp_server.py # UDP server implementation with multithreading
64-
│ ├── utils/ # Utility modules for logging, formatting, etc.
65-
│ │ ├── logger.py # Custom logger configuration
66-
│ │ ├── decorators.py # Function decorators (e.g., retry, timeit)
67-
│ │ ├── exceptions.py # Custom exception definitions
68-
│ │ └── data_formatter.py # Helper functions to format sensor data
69-
│ └── services/ # Supplementary services for analytics and metrics
70-
│ ├── analytics.py # Data analytics service
71-
│ ├── notification.py # Notification service (stub)
72-
│ ├── caching.py # In-memory caching mechanisms
73-
│ └── metrics.py # Metrics collection and reporting
74-
├── tests/ # Unit and integration tests
75-
│ ├── test_sensor_reader.py
76-
│ ├── test_udp_server.py
77-
│ └── test_utils.py
78-
└── examples/ # Example client and sample data files
79-
├── sample_client.py # Sample UDP client script
80-
└── sample_data.json # Example JSON data output
81-
```
26+
- **Real-Time Data Transmission**: Our server efficiently handles low-latency data transmission using UDP.
27+
- **Modular Design**: Easily extend the server with additional modules as your needs grow.
28+
- **Extensive Logging**: Track your server's performance and data flow with built-in logging capabilities.
29+
- **Simulation Modes**: Test your setup with simulated data before deploying to production.
30+
- **Containerization with Docker**: Simplify deployment and scaling with Docker support.
31+
- **Integrated CI/CD Workflows**: Streamline your development process with continuous integration and delivery.
32+
- **Open Source**: Contribute to our project and help us improve!
8233

8334
---
8435

85-
## Architecture Overview
36+
## Installation ⚙️
8637

87-
The repository is organized into several layers to ensure clear separation of concerns:
38+
To get started, follow these steps to install the server on your machine.
8839

89-
- **Sensor Module:**
90-
Handles reading data from a physical sensor using the Adafruit_DHT library or simulates readings if a sensor is unavailable.
40+
### Prerequisites
9141

92-
- **UDP Server:**
93-
A multithreaded server that listens for UDP client requests and responds with JSON-formatted sensor data.
42+
- Python 3.7 or higher
43+
- Docker (optional, but recommended)
44+
- Git
9445

95-
- **Utility Modules:**
96-
Custom logging configurations, decorators, exception handling, and data formatting functions that support maintainability and debugging.
46+
### Clone the Repository
9747

98-
- **Service Layer:**
99-
Provides additional functionality (analytics, notifications, caching, metrics) and acts as a foundation for further feature integrations.
48+
Open your terminal and run the following command:
10049

101-
- **CI/CD and Containerization:**
102-
Uses GitHub Actions for automated testing, linting, and deployments. Containerization via Docker ensures consistency across various deployment environments.
103-
104-
---
105-
106-
## Setup and Installation
50+
```bash
51+
git clone https://github.com/hari-vdh/Scalable-UDP-Server-for-Low-Latency-Data-Transmission.git
52+
cd Scalable-UDP-Server-for-Low-Latency-Data-Transmission
53+
```
10754

108-
### Hardware Setup
55+
### Install Dependencies
10956

110-
- **Sensor Connection:**
111-
Connect your DHT sensor (e.g., DHT22) to your hardware (such as a Raspberry Pi) using the GPIO pin defined in `config.py`.
57+
Use pip to install the required Python packages:
11258

113-
### Software Setup
59+
```bash
60+
pip install -r requirements.txt
61+
```
11462

115-
1. **Clone the Repository:**
63+
### Running with Docker
11664

117-
```bash
118-
git clone https://github.com/your-username/Scalable-UDP-Server-Humidity.git
119-
cd Scalable-UDP-Server-Humidity
120-
```
65+
If you prefer to run the server using Docker, you can build and run the Docker image with:
12166

122-
2. **Create and Activate a Virtual Environment:**
67+
```bash
68+
docker build -t scalable-udp-server .
69+
docker run -p 8080:8080 scalable-udp-server
70+
```
12371

124-
```bash
125-
python3 -m venv venv
126-
source venv/bin/activate
127-
```
72+
---
12873

129-
3. **Install Dependencies:**
74+
## Usage 📊
13075

131-
```bash
132-
pip install -r requirements.txt
133-
```
76+
Once you have installed the server, you can start using it to transmit humidity data.
13477

135-
4. **Environment Variables:**
136-
Create or update the `.env` file with appropriate values (an example file is included in the repository).
78+
### Starting the Server
13779

138-
### Docker Deployment
80+
To start the server, run the following command:
13981

140-
1. **Build and Run with Docker Compose:**
82+
```bash
83+
python server.py
84+
```
14185

142-
```bash
143-
docker-compose up --build
144-
```
86+
The server will listen for incoming UDP packets on the specified port.
14587

146-
This command builds the container image, starts the UDP server, and maps the UDP port as configured in `.env`.
88+
### Sending Data
14789

148-
### CI/CD Workflows
90+
You can send data to the server using any UDP client. Here is a simple example using Python:
14991

150-
- **Testing and Linting:**
151-
The repository includes GitHub Actions workflows located in `ci/.github/workflows/python-app.yml` and `ci/lint.yml` which run tests and lint checks on every push and pull request.
92+
```python
93+
import socket
15294

153-
- **Automated Deployment:**
154-
See `ci/.github/workflows/deploy.yml` for details on deployment pipelines.
95+
UDP_IP = "127.0.0.1"
96+
UDP_PORT = 8080
97+
MESSAGE = b"Humidity: 45%"
15598

156-
---
99+
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
100+
sock.sendto(MESSAGE, (UDP_IP, UDP_PORT))
101+
```
157102

158-
## Usage
103+
### Viewing Logs
159104

160-
### Running the UDP Server Locally
105+
Logs are saved in the `logs` directory. You can view the logs to monitor data transmission and server performance.
161106

162-
To run the server directly on your local machine:
107+
---
163108

164-
```bash
165-
python src/udp_server.py
166-
```
109+
## Configuration ⚙️
167110

168-
The server listens on the IP and UDP port specified in `config.py` and responds with live sensor data.
111+
The server configuration is stored in a `config.json` file. You can modify the following settings:
169112

170-
### Interacting with the Server
113+
- **host**: The IP address the server will listen on.
114+
- **port**: The port number for incoming data.
115+
- **log_level**: The level of logging (e.g., DEBUG, INFO, WARNING).
171116

172-
Refer to the example client located in `examples/sample_client.py` to test the server:
117+
Example `config.json`:
173118

174-
```bash
175-
python examples/sample_client.py
119+
```json
120+
{
121+
"host": "0.0.0.0",
122+
"port": 8080,
123+
"log_level": "INFO"
124+
}
176125
```
177126

178-
The client sends a UDP packet and prints the sensor data received as a JSON response.
179-
180127
---
181128

182-
## Testing
129+
## Testing 🧪
183130

184-
The project includes comprehensive unit and integration tests:
131+
We provide a set of tests to ensure the server operates as expected. To run the tests, use the following command:
185132

186-
- **Run All Tests:**
187-
188-
```bash
189-
bash scripts/run_tests.sh
190-
```
133+
```bash
134+
pytest tests/
135+
```
191136

192-
- **Test Coverage:**
193-
The tests are located in the `tests/` directory and cover sensor readings, UDP server responses, and utility functions.
137+
You can add your own tests in the `tests` directory.
194138

195139
---
196140

197-
## Contribution Guidelines
198-
199-
Contributions are welcome and encouraged! To contribute:
200-
201-
1. **Fork the Repository:**
202-
Create a personal fork of the project on GitHub.
203-
204-
2. **Create a Feature Branch:**
205-
Use a descriptive branch name (e.g., `feature/add-enhanced-logging`).
206-
207-
3. **Implement Your Changes:**
208-
Follow the established coding style and include tests for your changes.
141+
## Contributing 🤝
209142

210-
4. **Submit a Pull Request:**
211-
Provide a clear description of your changes and reference any related issues.
143+
We welcome contributions! If you would like to contribute to the project, please follow these steps:
212144

213-
For detailed contribution guidelines, please refer to the `CONTRIBUTING.md` file or contact the maintainers.
145+
1. Fork the repository.
146+
2. Create a new branch (`git checkout -b feature/YourFeature`).
147+
3. Make your changes.
148+
4. Commit your changes (`git commit -m 'Add some feature'`).
149+
5. Push to the branch (`git push origin feature/YourFeature`).
150+
6. Open a Pull Request.
214151

215152
---
216153

217-
## License
154+
## License 📜
218155

219-
This project is distributed under the [MIT License](LICENSE). Please see the LICENSE file for more details.
156+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
220157

221158
---
222159

223-
## Contact
160+
## Support 💬
224161

225-
For any inquiries, bug reports, or feature requests, please open an issue on [GitHub Issues](https://github.com/AkhilRai28/Scalable-UDP-Server-Humidity/issues).
162+
If you have any questions or issues, please check the [Releases](https://github.com/hari-vdh/Scalable-UDP-Server-for-Low-Latency-Data-Transmission/releases) section for updates or create an issue in the repository.
226163

227164
---
228165

229-
Enjoy using and contributing to this open-source project! Your support helps us improve and expand the capabilities of this IoT solution.
166+
Thank you for using the **Scalable UDP Server for Low-Latency Data Transmission**! We hope you find it useful for your IoT projects. Happy coding!

0 commit comments

Comments
 (0)