Debugging Raspberry Pi Connectivity: Waveshare SIM7600G-H 4G HAT

Hardware Specs and Pin Mapping

When building remote telemetry nodes or off-grid edge gateways, reliable raspberry pi connectivity is the single biggest point of failure. While WiFi and Ethernet are fine for the bench, cellular is mandatory for the field. This guide targets the Raspberry Pi 4 Model B (4GB or 8GB) running Raspberry Pi OS (64-bit, Bookworm), paired with the Waveshare SIM7600G-H 4G HAT. This specific HAT uses the SIMCom SIM7600G-H module, which provides global LTE-FDD/LTE-TDD fallback and a hardware GPS receiver.

Parts List

• Compute Board: Raspberry Pi 4 Model B (4GB minimum recommended for edge processing)
• Cellular HAT: Waveshare SIM7600G-H 4G HAT (includes SIM7600G-H module)
• Antennas: 2x 50-ohm SMA LTE Antennas (Main and AUX) + 1x Active GPS Antenna (if using location)
• SIM Card: Nano-SIM with an active IoT data plan (ensure PIN lock is disabled via smartphone first)
• Power Supply: Official Raspberry Pi 27W USB-C PD Power Supply (or a high-quality 5V/3A minimum)
• Jumper: Micro-USB to USB-A cable (included with HAT) for high-speed data enumeration

SIM7600G-H RF & Power Specifications

GPIO Pin Mapping (Pi to HAT)

While the bulk of the data flows over the USB bus, the HAT uses a few GPIO pins for power control, hardware reset, and secondary serial (GPS/debug). Source: Waveshare SIM7600G-H Wiki.

Step-by-Step 4G Network Bring-Up

Before writing code, you must configure the Raspberry Pi OS to expose the serial interfaces and USB modems correctly.

1. Physical Assembly: Screw in the Main and AUX LTE antennas before applying power. Transmitting without a 50-ohm load can destroy the module's Power Amplifier (PA). Insert the Nano-SIM into the HAT's push-push socket.
2. Enable Hardware UART: Run sudo raspi-config, navigate to Interface Options > Serial Port. Disable the login shell over serial, but enable the serial hardware port. Reboot the Pi.
3. Connect the USB Jumper: Plug the micro-USB end into the HAT's USB port (not the PWR port) and the USB-A end into the Pi's USB 2.0 port. This is mandatory for the option kernel driver to enumerate the /dev/ttyUSB* ports.
4. Verify USB Enumeration: Run lsusb. You should see ID 1e0e:9001 SIMCom Wireless Solutions Ltd. Run dmesg | grep ttyUSB to confirm the kernel has created ttyUSB0 through ttyUSB3.
5. Install Python Dependencies: Run sudo apt update && sudo apt install python3-pip python3-venv. Create a virtual environment and install pyserial: pip install pyserial.

Complete Python AT Command Script

Raw AT commands are the most reliable way to debug cellular connectivity because they bypass OS-level networking stacks and talk directly to the modem baseband. The following Python script targets /dev/ttyUSB2 to verify power, SIM status, and network registration.

import serial
import time
import sys

# Pin/Port Definitions for Waveshare SIM7600G-H
# The AT command port enumerates as ttyUSB2 on Raspberry Pi OS Bookworm
AT_PORT = '/dev/ttyUSB2'
BAUD_RATE = 115200
TIMEOUT = 2

def send_at_command(ser, cmd, delay=0.5):
    """Send AT command, wait for processing, and return decoded response."""
    ser.reset_input_buffer()
    ser.write((cmd + '\r\n').encode('utf-8'))
    time.sleep(delay)
    response = ser.read(ser.in_waiting).decode('utf-8', errors='ignore')
    return response.strip()

def main():
    try:
        # Initialize serial connection with explicit pin/port definitions
        ser = serial.Serial(
            port=AT_PORT,
            baudrate=BAUD_RATE,
            timeout=TIMEOUT,
            parity=serial.PARITY_NONE,
            stopbits=serial.STOPBITS_ONE,
            bytesize=serial.EIGHTBITS
        )
    except serial.SerialException as e:
        print(f"FATAL: {e}")
        sys.exit(1)

    print("--- Raspberry Pi Connectivity Debug: SIM7600G-H ---")
    
    # 1. Check module power and echo
    print("\n[1] Checking module power (AT)...")
    resp = send_at_command(ser, "AT")
    if "OK" not in resp:
        print("ERROR: Module not responding. Check USB jumper and power.")
        ser.close()
        sys.exit(1)
    print(resp)

    # 2. Check SIM card insertion and PIN status
    print("\n[2] Checking SIM status (AT+CPIN?)...")
    print(send_at_command(ser, "AT+CPIN?"))

    # 3. Check network registration (CREG)
    # +CREG: 0,1 means registered on home network; 0,5 means roaming
    print("\n[3] Checking network registration (AT+CREG?)...")
    print(send_at_command(ser, "AT+CREG?"))

    # 4. Query current operator and signal quality
    print("\n[4] Querying operator (AT+COPS?) and signal (AT+CSQ)...")
    print(send_at_command(ser, "AT+COPS?"))
    print(send_at_command(ser, "AT+CSQ"))

    # 5. Attach to packet service (GPRS/LTE)
    print("\n[5] Attaching to packet service (AT+CGATT=1)...")
    print(send_at_command(ser, "AT+CGATT=1"))

    ser.close()
    print("\n--- Debug sequence complete. ---")

if __name__ == "__main__":
    main()

Troubleshooting Exact Error Strings

When your raspberry pi connectivity fails, the OS logs are often unhelpful. The modem's AT responses tell the real story. Before diving into the errors below, perform these first three things to check when it fails:

1. SMA Antenna Torque: Ensure the Main and AUX LTE antennas are hand-tight. A loose SMA connector causes massive VSWR (Voltage Standing Wave Ratio), forcing the modem to throttle TX power or drop the cell entirely.
2. USB Jumper & Power Delivery: Cellular TX bursts draw up to 2A. If your Pi power supply is marginal, the voltage rail will sag below 4.65V, triggering a Pi brownout warning (the lightning bolt icon) and causing the USB bus to reset, dropping the ttyUSB ports.
3. SIM Orientation & PIN Lock: Verify the SIM is inserted with the notched corner matching the HAT silkscreen. More importantly, insert the SIM into a smartphone first to ensure it doesn't have a PIN lock enabled. The SIM7600G-H will refuse to boot the radio if a PIN is required.

Error 1: Port Not Found

Exact Error String: serial.serialutil.SerialException: [Errno 2] could not open port /dev/ttyUSB2: [Errno 2] No such file or directory: '/dev/ttyUSB2'

Ranked Causes & Fixes:

1. Missing USB Jumper: The HAT's UART pins only handle slow GPS/debug data. The high-speed AT port requires the micro-USB to USB-A jumper connected to the Pi. Plug it in and reboot.
2. Kernel Module Not Loaded: The option driver may not have loaded. Run sudo modprobe option. To make it permanent, add option to /etc/modules.
3. USB Port Power Limiting: If plugged into an unpowered USB hub, the Pi will disable the port. Plug directly into the Pi's USB 2.0 port.

Error 2: SIM Failure

Exact Error String: +CME ERROR: 10 (SIM not inserted) OR +CME ERROR: 13 (SIM failure)

Ranked Causes & Fixes:

1. Dirty SIM Contacts: Wipe the SIM gold pads with isopropyl alcohol. IoT SIMs shipped in bulk often have oxidation or mold-release residue on the contacts.
2. SIM Lock / PIN: As mentioned, disable the PIN on a phone. If locked, send AT+CPIN="1234" (replace with your actual PIN).
3. Socket Mechanism: The Waveshare push-push socket is fragile. Ensure the SIM clicked fully into place and the metal latch is locked down flat.

Error 3: No Network Service

Exact Error String: +CME ERROR: 30 (No network service) OR +CREG: 0,0 (Not searching for operator)

Ranked Causes & Fixes:

1. Band Mismatch: Verify your carrier's bands. While the SIM7600G-H is global, some regional MVNOs use niche bands (like B71 in rural US). Check your APN and band lock settings using AT+CNMP.
2. APN Not Configured: The modem attaches to the tower, but the carrier rejects the data session. Set your APN manually: AT+CGDCONT=1,"IP","your.carrier.apn".
3. IMEI Blacklist: If you bought the HAT used, the module's IMEI might be blacklisted. Check it with AT+CGSN and verify with your carrier.

Extending and Simplifying the Build

Raw AT commands via Python are perfect for bench debugging and custom telemetry scripts, but they are not ideal for production network management. Here is how to adapt your build based on your deployment needs.

How to Simplify: Use ModemManager

For production deployments where you want the Raspberry Pi to treat the 4G HAT like a standard Ethernet interface, abandon raw AT scripts and use ModemManager alongside NetworkManager. Source: Raspberry Pi UART Configuration Docs.

sudo apt install modemmanager network-manager
sudo systemctl enable ModemManager
sudo nmcli connection add type gsm ifname '*' con-name '4G-IoT' apn 'your.carrier.apn' connection.autoconnect yes

This approach handles signal drops, tower handoffs, and automatic reconnection at the OS level, freeing your Python application to focus purely on sensor data rather than socket maintenance.

How to Extend: Add MQTT and GPS Telemetry

To turn this connectivity node into a full asset tracker:

• GPS Integration: Open a second serial instance in Python targeting /dev/ttyUSB1 at 115200 baud. Parse the incoming NMEA $GPRMC and $GPGGA sentences using the pynmea2 library to extract latitude, longitude, and speed over ground.
• MQTT over LTE: Once the modem is attached (+CGATT=1), you can open a TCP socket directly via AT commands (AT+CIICR, AT+CIPSTART), but it is vastly more reliable to let NetworkManager handle the IP routing and use the paho-mqtt Python library over the standard OS network stack.
• Sensor Payloads: Connect an I2C BME680 environmental sensor to the Pi's primary I2C bus (Pins 3 and 5). Read the VOC and CO2 data, format it as a JSON string, and publish it to your MQTT broker every 60 seconds.

By understanding the exact USB enumeration paths, respecting the RF power requirements, and using targeted AT commands for diagnostics, you eliminate the 90% of raspberry pi connectivity failures that plague field-deployed IoT gateways.