🍓 NIELIT Raspberry Pi Practicals

📑 Table of Contents

• Overview
• Key Features
• Installation Guide
  • Standard Installation
  • Full Hardware Installation
  • Raspberry Pi OS (Bookworm) Virtual Environment
  • Enabling Hardware Interfaces (I2C, SPI, UART)
• Command-Line Interface (nielit-rpi)
  • List Practicals
  • Check Hardware & Dependencies
  • Show Practical Details
  • Run a Practical
  • Export Examples to Local Directory
• Master Practical Index (3.1 – 3.20)
• Python Library API Reference
  • GPIO Control (nielit_rpi.gpio)
  • Sensors (nielit_rpi.sensors)
  • Actuators (nielit_rpi.actuators)
  • Displays (nielit_rpi.displays)
  • Communication & IoT (nielit_rpi.communication)
  • Data Logging (nielit_rpi.storage)
  • Web Interfaces (nielit_rpi.networking)
  • Utilities & Diagnostics (nielit_rpi.utilities)
• Raspberry Pi 40-Pin GPIO Reference & Safety
• Testing & Quality Assurance
• Troubleshooting & FAQ
• License & Authors

🌟 Overview

The nielit-raspberrypi-practicals library provides a unified, object-oriented, and student-friendly Python framework covering all 20 official NIELIT Raspberry Pi practicals (Practicals 3.1 through 3.20).

Each practical is accompanied by:

• Clean Python Code: Full PEP 8 compliance, explicit type hints, and robust error handling.
• Graceful Lifecycle Management: Context managers (with statements) and automatic cleanup of GPIO pins to protect hardware.
• Standalone Documentation: Detailed READMEs with circuit schematics, components, pinout tables, and troubleshooting steps.
• Interactive Manual: Modern HTML5 laboratory manual with real-time pin tracing and 1-click code copying.

✨ Key Features

• 🎯 Complete Curriculum Coverage: 20 practicals from basic LED blinking and analog sensor reading to MQTT IoT telemetry and Flask Web servers.
• 🛡️ Hardware Safe: Built-in 3.3V logic checks, software pull-up resistors, debounce filtering, and fail-safe cleanup handlers.
• ⚡ CLI Companion: The nielit-rpi command-line utility lets students inspect diagnostics, browse practicals, and run or export experiments instantly.
• 🌐 Modern Packaging: Fully compatible with Python 3.9 through 3.12 on Raspberry Pi OS (Bookworm & Bullseye).
• 🧩 Modular OOP Architecture: Every hardware component has a dedicated, reusable controller class.

📦 Installation Guide

1. Standard Installation

Installs core GPIO and basic sensor support:

pip install nielit-raspberrypi-practicals

2. Full Hardware Installation

Installs all peripheral drivers including I2C LCD (smbus2), SPI RFID (mfrc522, spidev), DHT sensors (adafruit-circuitpython-dht), MQTT (paho-mqtt), and Web server (flask):

pip install "nielit-raspberrypi-practicals[all]"

3. Raspberry Pi OS (Bookworm) Setup

On newer Raspberry Pi OS releases (Debian Bookworm), Python enforces PEP 668 (externally managed environment). Use a virtual environment:

# Create a virtual environment with access to system packages
python3 -m venv ~/nielit-env --system-site-packages

# Activate the virtual environment
source ~/nielit-env/bin/activate

# Install package
pip install --upgrade "nielit-raspberrypi-practicals[all]"

Tip: Add source ~/nielit-env/bin/activate to your ~/.bashrc to activate the environment automatically upon terminal launch.

4. Enabling Hardware Interfaces

Ensure that I2C, SPI, and Serial interfaces are enabled on your Raspberry Pi:

# Enable I2C interface
sudo raspi-config nonint do_i2c 0

# Enable SPI interface
sudo raspi-config nonint do_spi 0

# Enable Serial UART
sudo raspi-config nonint do_serial_hw 0

🛠️ Command-Line Interface (nielit-rpi)

The package includes a powerful command-line tool named nielit-rpi.

1. List All Practicals

Display a formatted table of all 20 practicals with their hardware requirements and difficulty ratings:

nielit-rpi list

Output Preview:

ID     | Title                          | Hardware             | Difficulty     
--------------------------------------------------------------------------------
3_1    | System Information             | RPi only             | Beginner       
3_2    | GPIO LED Output                | LED + resistor       | Beginner       
3_3    | Push Button Input              | Push button          | Beginner       
3_4    | Button Controlled LED          | Button + LED         | Beginner       
3_5    | Traffic Light Controller       | 3 LEDs               | Beginner       
3_6    | PWM LED Brightness             | LED                  | Beginner       
...
3_20   | Smart Home Capstone            | PIR + LED            | Advanced       

2. Check Hardware & Dependencies

Run an automated diagnostic check on your Raspberry Pi system, kernel, Python environment, and enabled hardware interfaces (I2C, SPI):

nielit-rpi check

Output Preview:

--- System Check ---
Hostname: raspberrypi
Python version: 3.11.2
Model: Raspberry Pi 4 Model B Rev 1.4

--- Dependencies ---
[OK] gpiozero is installed
[OK] smbus2 is installed
[OK] paho-mqtt is installed
[OK] flask is installed

--- Hardware Interfaces ---
[OK] I2C interface is enabled (/dev/i2c-1 found)
[OK] SPI interface is enabled (/dev/spidev0.0 found)

3. Show Practical Details

Retrieve the aim, hardware components, circuit wiring, and safety notes for any practical:

nielit-rpi info 3_2

nielit-rpi info 3_10

4. Run a Practical Program

Execute any practical directly by its ID from any folder:

# Run system diagnostics
nielit-rpi run 3_1

# Run LED blinking practical
nielit-rpi run 3_2

# Run DHT11 temperature & humidity monitoring
nielit-rpi run 3_10

5. Export Examples for Experimentation

Export all 20 editable practical scripts into your current project folder:

nielit-rpi export-examples

Or specify a custom directory:

nielit-rpi export-examples --dest my_practicals

Students can then navigate into any folder and run or modify main.py:

cd examples/practical_3_2
python main.py

📚 Master Practical Index (3.1 – 3.20)

💻 Python Library API Reference

Import components into your own custom projects with import nielit_rpi:

1. GPIO Control (nielit_rpi.gpio)

LED Control

from nielit_rpi.gpio import LEDController
import time

# Use as a context manager for automatic cleanup
with LEDController(pin=17) as led:
    led.on()
    time.sleep(1)
    led.off()
    led.blink(on_time=0.5, off_time=0.5, n=5)

Push Button with Callbacks

from nielit_rpi.gpio import ButtonReader

btn = ButtonReader(pin=18, pull_up=True, bounce_time=0.05)

btn.when_pressed = lambda: print("Button Pressed!")
btn.when_released = lambda: print("Button Released!")
btn.wait_for_press(timeout=10)
btn.close()

PWM Brightness & Buzzer

from nielit_rpi.gpio import PWMLEDController, BuzzerController

# Fade LED
with PWMLEDController(pin=18) as pwm_led:
    pwm_led.pulse(fade_in_time=1.0, fade_out_time=1.0, n=3)

# Buzzer alert
with BuzzerController(pin=23) as buzzer:
    buzzer.beep(on_time=0.1, off_time=0.1, n=3)

2. Sensors (nielit_rpi.sensors)

Ultrasonic Distance (HC-SR04)

from nielit_rpi.sensors import UltrasonicSensor

sensor = UltrasonicSensor(trigger_pin=23, echo_pin=24, max_distance=4.0)
print(f"Current Distance: {sensor.distance_cm:.2f} cm")
sensor.close()

DHT11 / DHT22 Temperature & Humidity

import board
from nielit_rpi.sensors import DHTSensor

# Note: Uses Adafruit CircuitPython board pin definition
with DHTSensor(pin=board.D4, sensor_type="DHT11") as dht:
    reading = dht.read()
    print(f"Temperature: {reading['temperature']}°C | Humidity: {reading['humidity']}%")

PIR Motion Sensor

from nielit_rpi.sensors import PIRSensor

with PIRSensor(pin=4) as pir:
    if pir.motion_detected:
        print("Motion detected!")

Analog LDR Light Sensor (via MCP3008 ADC)

from nielit_rpi.sensors import LDRSensor

with LDRSensor(channel=0) as ldr:
    print(f"Raw Value: {ldr.value:.4f} | Voltage: {ldr.voltage:.2f}V")

3. Actuators (nielit_rpi.actuators)

5V Relay Control

from nielit_rpi.actuators import RelayController

with RelayController(pin=26, active_high=True) as relay:
    relay.on()   # Turn on connected load
    relay.off()  # Turn off load
    relay.toggle()

Servo Motor Control

from nielit_rpi.actuators import ServoController

with ServoController(pin=18, min_angle=-90, max_angle=90) as servo:
    servo.angle = 0    # Center position
    servo.angle = 90   # Maximum clockwise
    servo.angle = -90  # Maximum counter-clockwise
    servo.sweep(start=-90, end=90, step=15, delay=0.1)

4. Displays (nielit_rpi.displays)

I2C 16x2 LCD

from nielit_rpi.displays import I2CLCD

with I2CLCD(address=0x27, bus_number=1) as lcd:
    lcd.clear()
    lcd.write_string("NIELIT Ropar", line=1)
    lcd.write_string("IoT Laboratory", line=2)

5. Communication & IoT (nielit_rpi.communication)

RC522 RFID Reader

from nielit_rpi.communication import RFIDReader

with RFIDReader() as rfid:
    print("Hold an RFID card near the reader...")
    card_id, text = rfid.read()
    print(f"Card UID: {card_id} | Data: {text}")

MQTT Telemetry Publisher & Subscriber

from nielit_rpi.communication import MQTTPublisher, MQTTSubscriber

# Publish reading
pub = MQTTPublisher(broker="broker.hivemq.com", port=1883, topic="nielit/rpi/sensor")
pub.connect()
pub.publish({"temperature": 25.4, "humidity": 60})
pub.disconnect()

# Subscribe to commands
def on_message(client, userdata, msg):
    print(f"Received payload: {msg.payload.decode()}")

sub = MQTTSubscriber(broker="broker.hivemq.com", port=1883, topic="nielit/rpi/led", on_message_callback=on_message)
sub.connect()
sub.start()

6. Telemetry & Data Logging (nielit_rpi.storage)

SQLite Sensor Logger

from nielit_rpi.storage import SensorDataLogger

logger = SensorDataLogger(db_path="telemetry.db", table_name="climate")
logger.create_table(columns={"temp": "REAL", "humidity": "REAL", "status": "TEXT"})

# Log reading with automatic timestamp
logger.log_reading(temp=24.5, humidity=58.2, status="OPTIMAL")

# Query recent records
rows = logger.get_readings(limit=10)
for row in rows:
    print(row)
logger.close()

7. Web Interfaces (nielit_rpi.networking)

Web-Based GPIO Controller (Flask)

from nielit_rpi.networking import create_gpio_web_app

app = create_gpio_web_app(led_pin=17)
# Run server on port 5000 accessible across the local network
app.run(host="0.0.0.0", port=5000, debug=False)

8. Utilities & Diagnostics (nielit_rpi.utilities)

from nielit_rpi.utilities import get_system_info, cleanup_devices

# Fetch full system diagnostics dict
info = get_system_info()
print(f"RPi Model : {info.get('model')}")
print(f"Python    : {info.get('python_version')}")
print(f"Disk Free : {info.get('disk_usage', {}).get('free_gb')} GB")

⚡ Raspberry Pi 40-Pin GPIO Reference & Safety

                           3.3V Power [01] [02] 5V Power
       (I2C1 SDA) GPIO 2 / Pin 3  [03] [04] 5V Power
       (I2C1 SCL) GPIO 3 / Pin 5  [05] [06] Ground
     (GPCLK0)     GPIO 4 / Pin 7  [07] [08] GPIO 14 / Pin 8  (UART TXD)
                  Ground / Pin 9  [09] [10] GPIO 15 / Pin 10 (UART RXD)
     (SPI1_CE1)  GPIO 17 / Pin 11 [11] [12] GPIO 18 / Pin 12 (PWM0)
                 GPIO 27 / Pin 13 [13] [14] Ground
                 GPIO 22 / Pin 15 [15] [16] GPIO 23 / Pin 16
                3.3V Power [17] [18] GPIO 24 / Pin 18
     (SPI0 MOSI) GPIO 10 / Pin 19 [19] [20] Ground
     (SPI0 MISO)  GPIO 9 / Pin 21 [21] [22] GPIO 25 / Pin 22
     (SPI0 SCLK) GPIO 11 / Pin 23 [23] [24] GPIO 8 / Pin 24  (SPI0 CE0)
                  Ground / Pin 25 [25] [26] GPIO 7 / Pin 26  (SPI0 CE1)
     (I2C0 ID_SD) GPIO 0 / Pin 27 [27] [28] GPIO 1 / Pin 28  (I2C0 ID_SC)
                  GPIO 5 / Pin 29 [29] [30] Ground
                  GPIO 6 / Pin 31 [31] [32] GPIO 12 / Pin 32 (PWM0)
                 GPIO 13 / Pin 33 [33] [34] Ground
     (SPI1 MISO) GPIO 19 / Pin 35 [35] [36] GPIO 16 / Pin 36 (SPI1 CE2)
                 GPIO 26 / Pin 37 [37] [38] GPIO 20 / Pin 38 (SPI1 MOSI)
                  Ground / Pin 39 [39] [40] GPIO 21 / Pin 40 (SPI1 SCLK)

⚠️ Essential Electrical Safety Rules:

1. 3.3V Logic Limit: Raspberry Pi GPIO pins operate strictly at 3.3V. Connecting 5V directly to a GPIO input pin will permanently damage the SoC. Always use a resistor voltage divider (e.g. 1kΩ + 2kΩ on HC-SR04 Echo) or a logic level shifter.
2. Current Limiting: Maximum current draw per GPIO pin is 16 mA (and total < 50 mA across all pins). Always use a 330Ω resistor with LEDs.
3. Inductive Loads & Relays: Never drive motors, relays, or solenoids directly from GPIO pins. Use transistor/MOSFET driver stages or opto-isolated relay boards.
4. Servo Power Isolation: High-torque servos create voltage drops. Power servos with an external 5V DC supply with shared ground.

🧪 Testing & Quality Assurance

The package includes a comprehensive test suite with 100% hardware-mocked unit tests that run on Linux, Windows, macOS, and CI pipelines without requiring physical Raspberry Pi hardware.

# Clone the repository
git clone https://github.com/lovnishverma/nielit-raspberrypi-practicals.git
cd nielit-raspberrypi-practicals

# Install development dependencies
pip install -e ".[dev,all]"

# Run full pytest test suite
pytest tests/ -v

❓ Troubleshooting & FAQ

Q1: Permission denied: /dev/gpiomem or No access to /dev/mem

Fix: Add your user to the gpio group and reboot:

sudo usermod -a -G gpio,i2c,spi $USER
sudo reboot

Q2: I2C LCD not displaying anything (Blank or Black Squares)

Fix:

1. Check the potentiometer on the back of the I2C backpack and turn it with a small screwdriver to adjust display contrast.
2. Verify I2C address using i2cdetect -y 1 (default is usually 0x27 or 0x3F).

Q3: DHT11 Sensor gives RuntimeError: A full buffer was not returned

Fix: DHT sensors use time-sensitive bit-banging. Occasional timeouts are normal. The DHTSensor.read() method in this library automatically retries up to 3 times. Ensure a 10kΩ pull-up resistor is placed between VCC and Data pin.

Q4: error: externally-managed-environment when running pip install

Fix: You are on Debian Bookworm. Create and activate a Python virtual environment as shown in the Installation Guide.

📄 License & Authors

• Organization: National Institute of Electronics & Information Technology (NIELIT), Ropar
• License: NIELIT Ropar License. Copyright (c) 2026 NIELIT Ropar.
• Maintainer: Lovnish Verma (@lovnishverma)
• Email: info@nielit.gov.in / ropar@nielit.gov.in