Command Line Raspberry Pi: Headless I2C & GPIO Control Guide

Running a desktop environment on a microcontroller-class board is a waste of RAM and CPU cycles. When you are building a dedicated sensor node, a headless command line Raspberry Pi setup is the professional standard. It boots faster, consumes less power, and eliminates the attack surface of a GUI. However, the transition from desktop to CLI exposes hardware realities: I2C bus capacitance, permission faults, and the shift from legacy RPi.GPIO to the modern lgpio backend.

This guide walks through provisioning a headless CLI environment, wiring an I2C sensor and a relay, writing a robust Python script triggered via terminal arguments, and debugging the exact I/O errors that halt 90% of headless builds.

The Verdict: Which Board for Headless CLI Tasks?

If your project lives in a DIN-rail enclosure or a remote junction box, you do not need a Raspberry Pi 5. You need low quiescent power draw, a small physical footprint, and enough compute to handle Python scripts and SSH sessions without thermal throttling.

Parts List and Pin Mapping

Before flashing the SD card, gather the exact hardware. We are using a BME280 for environmental data and a standard opto-isolated relay module to switch a 12V/120V load (keep mains wiring to licensed professionals; we are only switching the low-voltage relay control side here).

Bill of Materials

• Compute: Raspberry Pi Zero 2 W (with pre-soldered 40-pin header)
• OS Storage: 32GB SanDisk Extreme microSD (A1 rated for minimum IOPS)
• Sensor: Adafruit BME280 I2C Breakout (includes onboard 4.7k pull-ups)
• Actuator: 5V Single-Channel Opto-Isolated Relay Module
• Power: 5V 2.5A USB-C Power Supply (official Raspberry Pi)

Pin Mapping Table

Provisioning the Command Line Raspberry Pi

The biggest shift in the Raspberry Pi OS Bookworm release is the death of dhcpcd and wpa_supplicant. If you are used to dropping a wpa_supplicant.conf file into the boot partition, stop. Bookworm uses NetworkManager. The cleanest way to provision a headless CLI node is via the Raspberry Pi Imager.

1. Flash the OS: Open Raspberry Pi Imager. Select Raspberry Pi OS Lite (64-bit) under 'Raspberry Pi OS (Other)'. This is the headless CLI version with no desktop bloat.
2. Apply Advanced Settings: Press Ctrl+Shift+X (or click the gear icon).
   • Set hostname to env-node-01.local.
   • Enable SSH (Use password authentication for now; inject your public key later).
   • Configure wireless LAN using NetworkManager syntax (the Imager handles this automatically now).
   • Set locale and timezone.
3. Boot and SSH: Insert the SD card, power the Zero 2 W, and wait 60 seconds for the first-boot resize. Connect via terminal: ssh youruser@env-node-01.local.
4. Enable I2C via CLI: Since we have no GUI, run sudo raspi-config nonint do_i2c 0. This silently enables the I2C ARM interface without navigating menus.
5. Install Dependencies: Bookworm enforces PEP 668, meaning you cannot blindly pip install globally without breaking system packages. Create a virtual environment:

   python3 -m venv ~/cli-env
   source ~/cli-env/bin/activate
   pip install smbus2 gpiozero

The Code: CLI-Triggered Python Controller

We will use argparse to build a proper CLI tool. This script uses smbus2 to read the BME280's chip ID (proving I2C communication) and gpiozero to toggle the relay. gpiozero automatically utilizes the modern lgpio backend required by Bookworm.

Save this as node_ctrl.py in your home directory.

#!/usr/bin/env python3
import argparse
import sys
from gpiozero import OutputDevice
from smbus2 import SMBus

# --- PIN & BUS DEFINITIONS ---
RELAY_PIN = 17          # BCM GPIO 17 (Physical Pin 11)
I2C_BUS = 1             # /dev/i2c-1
BME280_ADDR = 0x76      # Default Adafruit BME280 address (SDO to GND)
BME280_CHIP_ID_REG = 0xD0
EXPECTED_CHIP_ID = 0x60 # BME280 hardcoded silicon ID

def control_relay(state: bool):
    # active_high=False assumes a low-level trigger relay module
    relay = OutputDevice(RELAY_PIN, active_high=False, initial_value=False)
    if state:
        relay.on()
        print(f"[OK] Relay on GPIO {RELAY_PIN} energized.")
    else:
        relay.off()
        print(f"[OK] Relay on GPIO {RELAY_PIN} de-energized.")

def read_sensor_id():
    try:
        with SMBus(I2C_BUS) as bus:
            chip_id = bus.read_byte_data(BME280_ADDR, BME280_CHIP_ID_REG)
            if chip_id == EXPECTED_CHIP_ID:
                print(f"[OK] BME280 verified at 0x{BME280_ADDR:02X} (Chip ID: 0x{chip_id:02X})")
            else:
                print(f"[WARN] Device at 0x{BME280_ADDR:02X} returned unexpected ID: 0x{chip_id:02X}")
    except OSError as e:
        # Catches the exact I2C bus failure
        print(f"[CRITICAL] I2C Bus Failure: {e}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"[ERROR] Unexpected fault: {e}", file=sys.stderr)
        sys.exit(2)

def main():
    parser = argparse.ArgumentParser(description="Headless CLI I2C & GPIO Controller")
    parser.add_argument(
        "--action", 
        choices=["read-sensor", "relay-on", "relay-off"], 
        required=True,
        help="The hardware action to execute."
    )
    args = parser.parse_args()

    if args.action == "relay-on":
        control_relay(True)
    elif args.action == "relay-off":
        control_relay(False)
    elif args.action == "read-sensor":
        read_sensor_id()

if __name__ == "__main__":
    main()

Debugging: Fixing "Remote I/O error" and Permission Faults

When building headless I2C circuits, you will inevitably hit a wall. The most common and frustrating error string you will see in your terminal is:

OSError: [Errno 121] Remote I/O error

This is a kernel-level ACK failure. The Pi sent a clock pulse and address, but the sensor did not pull the SDA line low to acknowledge. Here are the first three things to check when this happens, ranked by probability:

1. Verify the Bus sees the Address: Run i2cdetect -y 1. If the grid is entirely empty (only dashes), your wiring is wrong, your sensor is dead, or I2C is disabled. If you see UU, another kernel driver has claimed the chip.
2. Check Pull-Up Resistors: I2C is an open-drain protocol. It requires pull-up resistors on SDA and SCL. The Adafruit BME280 breakout has them. If you are using a bare chip or a cheap clone board without them, the bus will float, causing Errno 121. Solder 4.7kΩ resistors between 3V3 and both SDA/SCL.
3. Confirm Device Tree Overlay: Run cat /boot/firmware/config.txt | grep i2c. You must see dtparam=i2c_arm=on. If it is missing or commented out, the kernel hasn't loaded the I2C driver.

Other Common CLI Faults

Extending or Simplifying the Build

Once your CLI tool reliably toggles the relay and reads the sensor ID, you have a foundational hardware abstraction layer. From here, you can scale the project in two distinct directions depending on your deployment environment.

How to Simplify (The Appliance Route)

If this node is going into a remote enclosure where you don't want to manage Linux packages, strip away the OS entirely. Migrate the logic to a Raspberry Pi Pico W running MicroPython. You lose the SSH terminal and the robust argparse CLI, but you gain instant boot times (milliseconds instead of seconds) and a massive drop in power consumption. You would replace the Python script with a simple main.py loop that reads UART serial commands from a host controller.

How to Extend (The Fleet Route)

If you are deploying ten of these nodes across a facility, typing SSH commands manually is unscalable. 1. Wrap your Python script in a systemd service so it runs on boot. 2. Add the paho-mqtt library to the virtual environment. 3. Modify the script to publish the BME280 telemetry to an MQTT broker (like Mosquitto) every 60 seconds, and subscribe to an MQTT topic to trigger the relay. 4. Use Ansible or Docker Compose to push updates to all ten Pis simultaneously over the network.

By mastering the command line Raspberry Pi workflow, you stop treating the board like a tiny desktop PC and start treating it like what it actually is: a headless, networked microcomputer ready for industrial deployment.