Metadata-Version: 2.3
Name: radiacode
Version: 0.4.0
Summary: Library for RadiaCode-101
Author: Maxim Andreev
Author-email: Maxim Andreev <andreevmaxim@gmail.com>
License: MIT License
         
         Copyright (c) 2021 Maxim Andreev
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: bleak>=1.1.1,<4
Requires-Dist: pyusb~=1.3.1
Requires-Dist: aiohttp>=3.13.5,<4 ; extra == 'examples'
Requires-Dist: prometheus-client~=0.25.0 ; extra == 'examples'
Requires-Dist: matplotlib>=3.9.4,<4 ; extra == 'examples'
Requires-Dist: numpy>=2.0.2,<3 ; extra == 'examples'
Requires-Dist: pyyaml~=6.0.3 ; extra == 'examples'
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/cdump/radiacode
Project-URL: Documentation, https://cdump.github.io/radiacode/
Project-URL: Repository, https://github.com/cdump/radiacode
Provides-Extra: examples
Description-Content-Type: text/markdown

# RadiaCode Python Library

[![PyPI version](https://img.shields.io/pypi/v/radiacode)](https://pypi.org/project/radiacode)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://cdump.github.io/radiacode/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python library for interfacing with the [RadiaCode-10x](https://www.radiacode.com/) radiation detectors and spectrometers. Control your device, collect measurements, and analyze radiation data with ease.

## 🚀 Features

- 📊 Real-time radiation measurements
- 📈 Spectrum acquisition and analysis
- 🔌 USB and Bluetooth connectivity
- 🌐 Web interface example included
- 📱 Device configuration management

## 📸 Demo

Interactive web interface example ([backend](src/radiacode/examples/webserver.py) | [frontend](src/radiacode/examples/webserver.html)):

![radiacode-webserver-example](./screenshot.png)

## 🎮 Quick Start

### Examples
```bash
pip install --upgrade 'radiacode[examples]'
```

Run the web interface shown in the screenshot above:
```bash
# Via Bluetooth (use the device's MAC address, or its CoreBluetooth UUID on macOS)
$ python3 -m radiacode.examples.webserver --bluetooth-mac 52:43:01:02:03:04

# Via USB connection (Linux/macOS/Windows)
$ sudo python3 -m radiacode.examples.webserver
```

Basic terminal output example (same options as web interface):
```bash
$ python3 -m radiacode.examples.basic
```

### Library Usage Example
```bash
pip install --upgrade radiacode
```
```python
from radiacode import RadiaCode, RealTimeData

# Connect to the device over USB and release it when finished
with RadiaCode() as device:
    # Get current radiation measurements
    data = device.data_buf()
    for record in data:
        if isinstance(record, RealTimeData):
            print(f"Dose rate: {record.dose_rate}")

    # Get spectrum data
    spectrum = device.spectrum()
    print(f"Live time: {spectrum.duration.total_seconds()}s")
    print(f"Total counts: {sum(spectrum.counts)}")

    # Configure device
    device.set_display_brightness(5)  # 0-9 brightness level
    device.set_language('en')        # 'en' or 'ru'
```

#### More Features
```python
# Bluetooth connection (use the device's CoreBluetooth UUID on macOS)
device = RadiaCode(bluetooth_mac="52:43:01:02:03:04")

# Connect to specific USB device
device = RadiaCode(serial_number="YOUR_SERIAL_NUMBER")

# Energy calibration
coefficients = device.energy_calib()
print(f"Calibration coefficients: {coefficients}")

# Reset accumulated data
device.dose_reset()
device.spectrum_reset()

# Configure device behavior
device.set_sound_on(True)
device.set_vibro_on(True)
device.set_display_off_time(30)  # Auto-off after 30 seconds
```

## 📚 Documentation

The [documentation site](https://cdump.github.io/radiacode/) contains setup
guides, measurement and unit notes, spectrum examples, device configuration,
and an API reference generated from the source docstrings and type annotations.

Build it locally with:

```bash
uv sync --group docs
uv run --no-sync mkdocs serve
```

## 🔧 Development Setup
1. Install prerequisites:
   ```bash
   # Install uv
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. Clone
   ```bash
   git clone https://github.com/cdump/radiacode.git
   cd radiacode
   ```

3. Run examples:
   ```bash
   uv run python -m radiacode.examples.basic
   ```

## ⚠️ Platform-Specific Notes

### macOS
- ✅ USB connectivity supported via libusb
- ✅ Bluetooth connectivity supported via Bleak (use the device's CoreBluetooth UUID)
- 📝 Required: `brew install libusb`

### Linux
- ✅ Both USB and Bluetooth fully supported
- 📝 Required: `libusb` and BlueZ
- 🔑 May need [udev rules](radiacode.rules) for USB access without root

### Windows
- ✅ USB connectivity supported
- ✅ Bluetooth connectivity supported via Bleak
- 📝 Required: USB drivers

## License

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