Metadata-Version: 2.4
Name: pydiplink
Version: 0.1.0
Summary: Python interface for UART image/video transfer with embedded devices
Author-email: Ozan Durgut <ozndrgt@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/EmbedDIP/PyDIPLink
Project-URL: Documentation, https://github.com/EmbedDIP/PyDIPLink#readme
Project-URL: Repository, https://github.com/EmbedDIP/PyDIPLink
Project-URL: Issues, https://github.com/EmbedDIP/PyDIPLink/issues
Project-URL: Changelog, https://github.com/EmbedDIP/PyDIPLink/blob/master/CHANGELOG.md
Keywords: uart,serial,embedded,stm32,esp32,image-transfer,opencv
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: System :: Hardware
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.4
Requires-Dist: numpy>=1.19.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.1; extra == "dev"
Requires-Dist: black>=24.1.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: types-Pillow; extra == "dev"
Dynamic: license-file

# PyDIPLink

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

PyDIPLink is a Python library for transferring images and video between microcontrollers and your computer over UART. 

If you're working on embedded vision projects and need to send images from your PC to your device, or receive camera frames from your device back to your PC, this library handles all the serial communication for you.

## What it does

PyDIPLink sends and receives images over a serial connection. It supports different image formats like RGB888, RGB565, Grayscale, YUV, HSV, and compressed JPEG. You can use it for:

- Sending test images from PC to your embedded device
- Receiving processed images from device back to PC
- Streaming JPEG frames from device to PC

The library works at high speeds (tested up to 500000 baud) and handles all the protocol details, timeouts, and error checking automatically.

## Installation

Install from PyPI:

```bash
pip install pydiplink
```

Or from source:

```bash
git clone https://github.com/EmbedDIP/PyDIPLink.git
cd PyDIPLink
pip install -e .
```

## How to use it

### Command line tool

Once installed, you can run the command line tool:

```bash
# Start listening on default port (/dev/ttyUSB0 at 500000 baud)
pydiplink

# Or specify your port and baud rate
pydiplink --port /dev/ttyUSB1 --baud 115200
pydiplink --port COM3 --baud 500000  # Windows

# Set a default image to send when your device requests one
pydiplink --image myimage.jpg
```

The tool will sit and listen for commands from your device. When the device requests an image, it sends it. When the device sends an image or JPEG frame, it saves it automatically.

### Extra features

**Video recording**

If you want to record JPEG streams to video files:

```python
from pydiplink import JpegVideoWriter

with JpegVideoWriter("output.avi", fps=30, resolution=(640, 480)) as writer:
    for i in range(300):
        frame = receive_and_show_jpeg(ser)
        if frame is not None:
            writer.write_frame(frame)
```

Or from command line:

```bash
pydiplink --record --output video.avi --fps 15
```

**Histogram and signal data**

Receive histogram or other 1D signal data from your device:

```python
import serial
from pydiplink import receive_1d_signal

ser = serial.Serial('/dev/ttyUSB0', 500000, timeout=5)
signal_data = receive_1d_signal(ser, plot=True, save_path="histogram")
ser.close()
```

## Protocol

PyDIPLink uses a simple protocol. Your device sends 3-byte commands:

- **STR** - Device requests an image from PC
- **STW** - Device sends a raw image to PC  
- **STJ** - Device sends a JPEG frame to PC
- **ST1** - Device sends signal data (optional, for histograms)

The library handles all the details automatically. Just send the command from your device and PyDIPLink will respond appropriately.

Image formats supported: RGB888, RGB565, Grayscale, YUV, HSV, and JPEG.

## Configuration

You can set these environment variables:

```bash
export DIPLINK_PORT=/dev/ttyUSB0
export DIPLINK_BAUD=500000
export DIPLINK_IMAGE=input.jpg
```

There are safety limits to prevent issues: images can't be larger than 4096x4096 pixels or 50MB total.

## Examples

Check the [examples/](examples/) folder for complete working examples:

- `basic_image_transfer.py` - Sending and receiving images
- `jpeg_streaming.py` - Video streaming

## Documentation

See [docs/API.md](docs/API.md) for complete API documentation.

## License

MIT License - see [LICENSE](LICENSE) file.

## Author

Ozan Durgut - [GitHub](https://github.com/EmbedDIP)

If you find a bug or want to request a feature, [open an issue](https://github.com/EmbedDIP/PyDIPLink/issues).

## Organization

PyDIPLink is part of the [embedDIP organization](https://github.com/embedDIP). Other code projects related to, using, or referencing PyDIPLink can be found in the embedDIP organization on GitHub.
