PyDIPLink

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:

pip install pydiplink

Or from source:

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:

# 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:

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:

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

Histogram and signal data

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

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:

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/ folder for complete working examples:

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

Documentation

See docs/API.md for complete API documentation.

License

MIT License - see LICENSE file.

Author

Ozan Durgut - GitHub

If you find a bug or want to request a feature, open an issue.

Organization

PyDIPLink is part of the embedDIP organization. Other code projects related to, using, or referencing PyDIPLink can be found in the embedDIP organization on GitHub.