Pinsource

What is Pinsource?

Pinsource is a Python library for interfacing with HC-SR04 and JSN-SR04T ultrasonic distance sensors on a Raspberry Pi. It uses lgpio for GPIO access, which provides full support for all Raspberry Pi models including the Pi 5.

Pinsource is a modernised fork of the hcsr04sensor project, updated for current Raspberry Pi OS releases, distributed as a Debian package, and licensed under Apache 2.0. It is the sensor library that powers Raspi-Sump v2.

Features

Error-corrected Readings

Returns the median value of a configurable sample (default 11 readings), filtering out noise and fringe sensor values.

Temperature Compensation

Adjusts the speed of sound calculation based on ambient temperature for more accurate distance readings.

Metric & Imperial

All measurements available in metric (cm / litres) or imperial (inches / gallons) with a single constructor parameter.

Volume Calculations

Built-in methods for cuboid, standing cylinder, side cylinder, and elliptical cylinder volumes, useful for tank monitoring applications.

Raspberry Pi 5 Support

Uses lgpio instead of RPi.GPIO, enabling full support for the Pi 5 and all current Raspberry Pi models.

APT Package Install

Distributed as python3-pinsource via the Linuxnorth APT repository. No virtualenv or pip required.

Recipes Included

Ready-to-run example scripts for every method in the library, from basic distance to volume calculations.

Exception Handling

Raises SystemError if a faulty cable or sensor prevents an echo pulse, making hardware problems easy to diagnose.

Supported Platforms

Operating System

Recommended Raspberry Pi OS 13 (Trixie)
Supported Raspberry Pi OS 12 (Bookworm)

Hardware

Recommended Raspberry Pi 2 and greater
Supported Raspberry Pi B

Sensors

Supported HC-SR04 ultrasonic sensor
Supported JSN-SR04T 2.0 waterproof ultrasonic sensor
Not Supported JSN-SR04T 3.0

Installation

Pinsource is distributed as a Debian package via the Linuxnorth APT repository. This is the recommended method, no virtualenv or pip required.

Quick start

curl -fsSL https://apt.linuxnorth.org/public_key.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/linuxnorth-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/linuxnorth-archive-keyring.gpg] \
  https://apt.linuxnorth.org unstable main" \
  | sudo tee /etc/apt/sources.list.d/linuxnorth.list

sudo apt update && sudo apt install python3-pinsource

Full installation instructions ›

Hardware Setup

Pin Wiring, HC-SR04 to Raspberry Pi

The HC-SR04 has four pins. Connect them to the Raspberry Pi as follows:

VCC → 5V
Ground → Ground
Trig → GPIO 17 (configurable)
Echo → GPIO 27 via voltage divider (configurable)

Any available GPIO pins can be used for Trig and Echo. The pins above are shown as examples. Identify your pins in your code when creating a Measurement object.

HC-SR04 wiring diagram to Raspberry Pi GPIO header.

Voltage Divider

A voltage divider is required on the Echo wire. The HC-SR04 outputs 5V on the Echo pin but Raspberry Pi GPIO pins are rated for 3.3V. Use a 470 Ω resistor in series with the Echo wire, and a 1000 Ω resistor between Echo and Ground. This reduces the voltage to approximately 3.4V, within safe limits. Failure to use a voltage divider can damage your Raspberry Pi.

Voltage divider using 470 Ω and 1K Ω resistors. The orange wire is Echo; yellow goes to Ground. Thanks to GitHub user @rhiller for this photo.

Testing Your Sensor

Installing the package also installs the pinsource command-line tool, which lets you take a quick reading to verify your sensor is working correctly.

Usage

pinsource -t 17 -e 27

Sample output

trig pin = gpio 17
echo pin = gpio 27
speed = 0.1
samples = 11

The imperial distance is 12.3 inches.
The metric distance is 31.2 centimetres.

Recipes

The recipes/ directory contains ready-to-run example scripts for every method in the library. Each recipe is a standalone Python script, copy and adapt it for your own project.

Basic distance reading (static method, no error correction)
Error-corrected distance in metric and imperial units
Liquid depth measurement
Volume of cuboid, standing cylinder, side cylinder, and elliptical cylinders
Sample size and speed tuning

Browse recipes on GitHub ›

Community & Support

Documentation

Full installation guide, API reference, and recipes walkthrough.

Read the Docs

Discord

Join the Raspi-Sump Discord server where pinsource is also discussed. A Discord account is required.

Request an Invite

Issue Tracker

Found a bug or have a feature request? Open a ticket on GitHub. A GitHub account is required.

Open an Issue

Source Code

Pinsource is open source under the Apache 2.0 License. Contributions and forks are welcome.

GitHub Repository

Background

Pinsource is a modernised fork of the hcsr04sensor project, originally written in 2014. The rewrite replaces RPi.GPIO with lgpio (enabling Raspberry Pi 5 support), updates packaging to the modern Debian ecosystem, and changes the license to Apache 2.0. It serves as the sensor driver for Raspi-Sump v2 but is designed as a standalone library for any project using HC-SR04 sensors.