| Name | omnipresense JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | A comprehensive, type-safe Python interface for OmniPreSense radar sensors |
| upload_time | 2025-09-01 13:54:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8.1 |
| license | MIT |
| keywords |
doppler
fmcw
omnipresense
radar
sensor
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OmniPreSense Radar
<div align="center">
[](https://badge.fury.io/py/omnipresense)
[](https://pypi.org/project/omnipresense/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://pepy.tech/project/omnipresense)
**A comprehensive, type-safe Python interface for OmniPreSense radar sensors**
_Supports all OPS241/OPS242/OPS243 radar models with full API coverage_
> **⚠️ DISCLAIMER**: This is an **unofficial**, community-developed library. The
> author is **not affiliated** with OmniPreSense Corp. This library provides a
> Python interface for OmniPreSense radar sensors but is not endorsed or
> supported by the company.
[🚀 Quick Start](#quick-start) • [📚 Examples](#examples) • [🛠️ Troubleshooting](TROUBLESHOOTING.md) • [🤝 Contributing](CONTRIBUTING.md)
</div>
---
## ✨ Features
- 📋 **Complete API Coverage** - All commands from the [official API documentation](https://omnipresense.com/wp-content/uploads/2019/10/AN-010-Q_API_Interface.pdf)
- 🔒 **Type-Safe** - Full typing support with comprehensive enums and data classes
- 📡 **Multiple Sensor Support** - Doppler (-A), FMCW (-B), and combined (-C) sensor types
- 🧵 **Thread-Safe** - Robust serial communication with proper synchronization
- 🔧 **Context Managers** - Automatic resource cleanup with `with` statements
- 📊 **Rich Data Structures** - Structured radar readings with timestamps and metadata
- ⚡ **High Performance** - Efficient data streaming with configurable callbacks
- 🛡️ **Error Handling** - Comprehensive exception hierarchy with detailed messages
## 📡 Supported Models
| Model | Type | Features | Detection Range | Max Speed |
| ------------ | -------- | ----------------------------------- | --------------- | --------- |
| **OPS241-A** | Doppler | Motion, Speed, Direction, Magnitude | 20-25m | 31.1 m/s |
| **OPS242-A** | Doppler | Enhanced sensitivity | 20-25m | 31.1 m/s |
| **OPS243-A** | Doppler | Advanced + Range\* | 75-100m | 31.1 m/s |
| **OPS241-B** | FMCW | Range, Magnitude | 15-20m | N/A |
| **OPS243-C** | Combined | All features | 50-60m | 31.1 m/s |
\*Range measurement pending in firmware
## 🚀 Quick Start
### Installation
```bash
pip install omnipresense
```
### Basic Usage
```python
from omnipresense import create_radar, Units, OutputMode
import time
# Create radar sensor
radar = create_radar('OPS243-C', '/dev/ttyACM0')
# Use context manager for automatic cleanup
with radar:
# Configure sensor
radar.set_units(Units.KILOMETERS_PER_HOUR)
# Enable output modes (required for data transmission)
radar.enable_output_mode(OutputMode.SPEED, True)
radar.enable_output_mode(OutputMode.DIRECTION, True)
radar.enable_output_mode(OutputMode.MAGNITUDE, True)
# Define callback for radar data
def on_detection(reading):
if reading.speed and reading.speed > 1.0:
direction = reading.direction.value if reading.direction else "?"
distance = f", Distance: {reading.range_m:.1f}m" if reading.range_m else ""
print(f"Speed: {reading.speed:.1f} km/h, Direction: {direction}{distance}")
# Start streaming data
print("Move something in front of the radar...")
radar.start_streaming(on_detection)
time.sleep(10) # Stream for 10 seconds
```
> **Important**: Always enable appropriate output modes (`OutputMode.SPEED`, `OutputMode.DIRECTION`, `OutputMode.MAGNITUDE`) for data transmission. Without these, the radar will not send any data.
## 📋 Requirements
- **Python**: 3.8.1+
- **Dependencies**: `pyserial` >= 3.4
## 📁 Examples
The [`examples/`](examples/) directory contains working scripts for different use cases:
- **[`basic_usage.py`](examples/basic_usage.py)** - Simple km/h speed detection with distance
- **[`basic_usage_raw.py`](examples/basic_usage_raw.py)** - PySerial version showing raw protocol
- **[`simple_doppler.py`](examples/simple_doppler.py)** - Doppler radar with direction detection
- **[`simple_range.py`](examples/simple_range.py)** - FMCW range measurement
- **[`combined_example.py`](examples/combined_example.py)** - OPS243-C combined features
- **[`debug_usage.py`](examples/debug_usage.py)** - Comprehensive debugging tool
- **[`raw_data_test.py`](examples/raw_data_test.py)** - Raw data inspection utility
Run any example:
```bash
python examples/basic_usage.py
```
## ⚙️ Key Configuration
### Output Modes (Required)
```python
# Enable data transmission (essential!)
radar.enable_output_mode(OutputMode.SPEED, True)
radar.enable_output_mode(OutputMode.DIRECTION, True)
radar.enable_output_mode(OutputMode.MAGNITUDE, True)
```
### Units and Sensitivity
```python
# Set measurement units
radar.set_units(Units.KILOMETERS_PER_HOUR) # or METERS_PER_SECOND, MILES_PER_HOUR
# Adjust sensitivity (lower = more sensitive)
radar.set_magnitude_threshold(20) # Default: 20, Range: 1-200+
```
### Filtering
```python
# Filter readings by speed and range
radar.set_speed_filter(min_speed=1.0, max_speed=50.0)
radar.set_range_filter(min_range=0.5, max_range=25.0)
```
## 📊 Data Structure
Each radar reading provides:
```python
@dataclass
class RadarReading:
timestamp: float # Unix timestamp
speed: Optional[float] # Speed in configured units
direction: Optional[Direction] # APPROACHING/RECEDING
range_m: Optional[float] # Range in meters
magnitude: Optional[float] # Signal strength
raw_data: Optional[str] # Original data string
```
## 🛡️ Error Handling
```python
from omnipresense import RadarError, RadarConnectionError
try:
with create_radar('OPS243-C', '/dev/ttyACM0') as radar:
radar.set_units(Units.METERS_PER_SECOND)
# ... use radar
except RadarConnectionError:
print("Could not connect to radar sensor")
except RadarError as e:
print(f"Radar error: {e}")
```
## 🔧 Quick Troubleshooting
### No Data Received?
1. **Enable output modes**: `radar.enable_output_mode(OutputMode.SPEED, True)`
2. **Create motion**: Wave your hand in front of the sensor
3. **Check distance**: Ensure objects are within 0.5m-25m range
4. **Lower threshold**: `radar.set_magnitude_threshold(10)`
### Permission Denied (Linux)?
```bash
sudo usermod -a -G dialout $USER # Add user to dialout group
# Then logout and login again
```
### Port Not Found?
- **Linux**: Try `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/ttyACM1`
- **macOS**: Try `/dev/cu.usbmodem*`, `/dev/cu.usbserial*`
- **Windows**: Try `COM3`, `COM4`, `COM5`, etc.
**Need more help?** See the comprehensive [**Troubleshooting Guide**](TROUBLESHOOTING.md).
## 📚 Documentation & Support
- **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Detailed issue resolution
- **[Contributing Guide](CONTRIBUTING.md)** - Development and contribution info
- **[Examples Directory](examples/)** - Working code examples
- **[GitHub Issues](https://github.com/yourusername/OmnipresenseRadar/issues)** - Bug reports and feature requests
## 🤝 Contributing
We welcome contributions! Please see our [**Contributing Guide**](CONTRIBUTING.md) for:
- Development environment setup
- Code quality standards
- Testing guidelines
- Pull request process
## 📄 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
## ⚖️ Legal Notice
This project is an **independent, unofficial** implementation developed by the community. It is **not affiliated with, endorsed by, or supported by OmniPreSense Corp.**
- **Trademark**: "OmniPreSense" is a trademark of OmniPreSense Corp.
- **Hardware**: This library is designed to work with OmniPreSense radar sensors
- **Support**: For hardware issues, contact [OmniPreSense directly](https://omnipresense.com/support/). For library issues, use our GitHub Issues.
- **Warranty**: This software comes with no warranty. Use at your own risk.
---
<div align="center">
**⭐ Star this repo if it helps you build amazing radar applications! ⭐**
_Made with ❤️ for the radar sensing community_
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "omnipresense",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.1",
"maintainer_email": null,
"keywords": "doppler, fmcw, omnipresense, radar, sensor",
"author": null,
"author_email": "Oskar Graeb <graeb.oskar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/65/3439f50d2d25c79a7aa2e69b849737c5ba05e8c471a68b6e79e007fdb882/omnipresense-0.1.3.tar.gz",
"platform": null,
"description": "# OmniPreSense Radar\n\n<div align=\"center\">\n\n[](https://badge.fury.io/py/omnipresense)\n[](https://pypi.org/project/omnipresense/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n[](https://pepy.tech/project/omnipresense)\n\n**A comprehensive, type-safe Python interface for OmniPreSense radar sensors**\n\n_Supports all OPS241/OPS242/OPS243 radar models with full API coverage_\n\n> **\u26a0\ufe0f DISCLAIMER**: This is an **unofficial**, community-developed library. The\n> author is **not affiliated** with OmniPreSense Corp. This library provides a\n> Python interface for OmniPreSense radar sensors but is not endorsed or\n> supported by the company.\n\n[\ud83d\ude80 Quick Start](#quick-start) \u2022 [\ud83d\udcda Examples](#examples) \u2022 [\ud83d\udee0\ufe0f Troubleshooting](TROUBLESHOOTING.md) \u2022 [\ud83e\udd1d Contributing](CONTRIBUTING.md)\n\n</div>\n\n---\n\n## \u2728 Features\n\n- \ud83d\udccb **Complete API Coverage** - All commands from the [official API documentation](https://omnipresense.com/wp-content/uploads/2019/10/AN-010-Q_API_Interface.pdf)\n- \ud83d\udd12 **Type-Safe** - Full typing support with comprehensive enums and data classes\n- \ud83d\udce1 **Multiple Sensor Support** - Doppler (-A), FMCW (-B), and combined (-C) sensor types\n- \ud83e\uddf5 **Thread-Safe** - Robust serial communication with proper synchronization\n- \ud83d\udd27 **Context Managers** - Automatic resource cleanup with `with` statements\n- \ud83d\udcca **Rich Data Structures** - Structured radar readings with timestamps and metadata\n- \u26a1 **High Performance** - Efficient data streaming with configurable callbacks\n- \ud83d\udee1\ufe0f **Error Handling** - Comprehensive exception hierarchy with detailed messages\n\n## \ud83d\udce1 Supported Models\n\n| Model | Type | Features | Detection Range | Max Speed |\n| ------------ | -------- | ----------------------------------- | --------------- | --------- |\n| **OPS241-A** | Doppler | Motion, Speed, Direction, Magnitude | 20-25m | 31.1 m/s |\n| **OPS242-A** | Doppler | Enhanced sensitivity | 20-25m | 31.1 m/s |\n| **OPS243-A** | Doppler | Advanced + Range\\* | 75-100m | 31.1 m/s |\n| **OPS241-B** | FMCW | Range, Magnitude | 15-20m | N/A |\n| **OPS243-C** | Combined | All features | 50-60m | 31.1 m/s |\n\n\\*Range measurement pending in firmware\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install omnipresense\n```\n\n### Basic Usage\n\n```python\nfrom omnipresense import create_radar, Units, OutputMode\nimport time\n\n# Create radar sensor\nradar = create_radar('OPS243-C', '/dev/ttyACM0')\n\n# Use context manager for automatic cleanup\nwith radar:\n # Configure sensor\n radar.set_units(Units.KILOMETERS_PER_HOUR)\n \n # Enable output modes (required for data transmission)\n radar.enable_output_mode(OutputMode.SPEED, True)\n radar.enable_output_mode(OutputMode.DIRECTION, True)\n radar.enable_output_mode(OutputMode.MAGNITUDE, True)\n\n # Define callback for radar data\n def on_detection(reading):\n if reading.speed and reading.speed > 1.0:\n direction = reading.direction.value if reading.direction else \"?\"\n distance = f\", Distance: {reading.range_m:.1f}m\" if reading.range_m else \"\"\n print(f\"Speed: {reading.speed:.1f} km/h, Direction: {direction}{distance}\")\n\n # Start streaming data\n print(\"Move something in front of the radar...\")\n radar.start_streaming(on_detection)\n time.sleep(10) # Stream for 10 seconds\n```\n\n> **Important**: Always enable appropriate output modes (`OutputMode.SPEED`, `OutputMode.DIRECTION`, `OutputMode.MAGNITUDE`) for data transmission. Without these, the radar will not send any data.\n\n## \ud83d\udccb Requirements\n\n- **Python**: 3.8.1+\n- **Dependencies**: `pyserial` >= 3.4\n\n## \ud83d\udcc1 Examples\n\nThe [`examples/`](examples/) directory contains working scripts for different use cases:\n\n- **[`basic_usage.py`](examples/basic_usage.py)** - Simple km/h speed detection with distance\n- **[`basic_usage_raw.py`](examples/basic_usage_raw.py)** - PySerial version showing raw protocol\n- **[`simple_doppler.py`](examples/simple_doppler.py)** - Doppler radar with direction detection\n- **[`simple_range.py`](examples/simple_range.py)** - FMCW range measurement\n- **[`combined_example.py`](examples/combined_example.py)** - OPS243-C combined features\n- **[`debug_usage.py`](examples/debug_usage.py)** - Comprehensive debugging tool\n- **[`raw_data_test.py`](examples/raw_data_test.py)** - Raw data inspection utility\n\nRun any example:\n```bash\npython examples/basic_usage.py\n```\n\n## \u2699\ufe0f Key Configuration\n\n### Output Modes (Required)\n```python\n# Enable data transmission (essential!)\nradar.enable_output_mode(OutputMode.SPEED, True)\nradar.enable_output_mode(OutputMode.DIRECTION, True)\nradar.enable_output_mode(OutputMode.MAGNITUDE, True)\n```\n\n### Units and Sensitivity\n```python\n# Set measurement units\nradar.set_units(Units.KILOMETERS_PER_HOUR) # or METERS_PER_SECOND, MILES_PER_HOUR\n\n# Adjust sensitivity (lower = more sensitive)\nradar.set_magnitude_threshold(20) # Default: 20, Range: 1-200+\n```\n\n### Filtering\n```python\n# Filter readings by speed and range\nradar.set_speed_filter(min_speed=1.0, max_speed=50.0)\nradar.set_range_filter(min_range=0.5, max_range=25.0)\n```\n\n## \ud83d\udcca Data Structure\n\nEach radar reading provides:\n\n```python\n@dataclass\nclass RadarReading:\n timestamp: float # Unix timestamp\n speed: Optional[float] # Speed in configured units\n direction: Optional[Direction] # APPROACHING/RECEDING\n range_m: Optional[float] # Range in meters\n magnitude: Optional[float] # Signal strength\n raw_data: Optional[str] # Original data string\n```\n\n## \ud83d\udee1\ufe0f Error Handling\n\n```python\nfrom omnipresense import RadarError, RadarConnectionError\n\ntry:\n with create_radar('OPS243-C', '/dev/ttyACM0') as radar:\n radar.set_units(Units.METERS_PER_SECOND)\n # ... use radar\n\nexcept RadarConnectionError:\n print(\"Could not connect to radar sensor\")\nexcept RadarError as e:\n print(f\"Radar error: {e}\")\n```\n\n## \ud83d\udd27 Quick Troubleshooting\n\n### No Data Received?\n1. **Enable output modes**: `radar.enable_output_mode(OutputMode.SPEED, True)`\n2. **Create motion**: Wave your hand in front of the sensor\n3. **Check distance**: Ensure objects are within 0.5m-25m range\n4. **Lower threshold**: `radar.set_magnitude_threshold(10)`\n\n### Permission Denied (Linux)?\n```bash\nsudo usermod -a -G dialout $USER # Add user to dialout group\n# Then logout and login again\n```\n\n### Port Not Found?\n- **Linux**: Try `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/ttyACM1`\n- **macOS**: Try `/dev/cu.usbmodem*`, `/dev/cu.usbserial*` \n- **Windows**: Try `COM3`, `COM4`, `COM5`, etc.\n\n**Need more help?** See the comprehensive [**Troubleshooting Guide**](TROUBLESHOOTING.md).\n\n## \ud83d\udcda Documentation & Support\n\n- **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Detailed issue resolution\n- **[Contributing Guide](CONTRIBUTING.md)** - Development and contribution info\n- **[Examples Directory](examples/)** - Working code examples\n- **[GitHub Issues](https://github.com/yourusername/OmnipresenseRadar/issues)** - Bug reports and feature requests\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [**Contributing Guide**](CONTRIBUTING.md) for:\n- Development environment setup\n- Code quality standards\n- Testing guidelines \n- Pull request process\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n## \u2696\ufe0f Legal Notice\n\nThis project is an **independent, unofficial** implementation developed by the community. It is **not affiliated with, endorsed by, or supported by OmniPreSense Corp.**\n\n- **Trademark**: \"OmniPreSense\" is a trademark of OmniPreSense Corp.\n- **Hardware**: This library is designed to work with OmniPreSense radar sensors\n- **Support**: For hardware issues, contact [OmniPreSense directly](https://omnipresense.com/support/). For library issues, use our GitHub Issues.\n- **Warranty**: This software comes with no warranty. Use at your own risk.\n\n---\n\n<div align=\"center\">\n\n**\u2b50 Star this repo if it helps you build amazing radar applications! \u2b50**\n\n_Made with \u2764\ufe0f for the radar sensing community_\n\n</div>",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive, type-safe Python interface for OmniPreSense radar sensors",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://github.com/graeb/OmnipresenseRadar",
"Homepage": "https://github.com/graeb/OmnipresenseRadar",
"Issues": "https://github.com/graeb/OmnipresenseRadar/issues",
"Repository": "https://github.com/graeb/OmnipresenseRadar.git"
},
"split_keywords": [
"doppler",
" fmcw",
" omnipresense",
" radar",
" sensor"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7ffd99021a4e29f7a5393c9e308a5e8b09c71e7dabd5e5240ee89cfb36c7fb06",
"md5": "65f9c4620fc3b288508f832271bd2e82",
"sha256": "d7bd909940e1a4f2dfa8bf569d2a75812ffba2acd3257abf8acc74c03c6c6f13"
},
"downloads": -1,
"filename": "omnipresense-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65f9c4620fc3b288508f832271bd2e82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 17024,
"upload_time": "2025-09-01T13:54:05",
"upload_time_iso_8601": "2025-09-01T13:54:05.802866Z",
"url": "https://files.pythonhosted.org/packages/7f/fd/99021a4e29f7a5393c9e308a5e8b09c71e7dabd5e5240ee89cfb36c7fb06/omnipresense-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a653439f50d2d25c79a7aa2e69b849737c5ba05e8c471a68b6e79e007fdb882",
"md5": "85f2e694948d9cb32d5ee621b66f2d9d",
"sha256": "4066e27686136fc6ca532a2b9d54bf05d50ff2607835795a090e57dd3791a0fe"
},
"downloads": -1,
"filename": "omnipresense-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "85f2e694948d9cb32d5ee621b66f2d9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 111066,
"upload_time": "2025-09-01T13:54:07",
"upload_time_iso_8601": "2025-09-01T13:54:07.121695Z",
"url": "https://files.pythonhosted.org/packages/4a/65/3439f50d2d25c79a7aa2e69b849737c5ba05e8c471a68b6e79e007fdb882/omnipresense-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 13:54:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "graeb",
"github_project": "OmnipresenseRadar",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "omnipresense"
}
