Arduino Python Programming: Build a PySerial Environmental Data Logger

The Core Decision: PySerial Bridge vs. On-Board MicroPython

When makers search for "Arduino Python programming," they are usually looking for one of two architectures: running Python directly on the microcontroller (via MicroPython/CircuitPython) or using a Python script on a host PC to communicate with an Arduino running C++ over a serial bridge. While the Arduino Nano ESP32 now officially supports MicroPython, the PySerial bridge remains the undisputed workhorse for industrial logging, GUI control, and heavy data processing.

Parts List and Pin Mapping for the PySerial Logger

This build targets the Arduino Uno R4 WiFi. We chose the R4 over the classic Uno R3 because its 12-bit ADC and hardware I2C pull-ups eliminate the need for external resistors when wiring 3.3V sensors, and its native USB-C connector simplifies host connections. The sensor is the Adafruit BME280 (product ID 2652), which provides temperature, humidity, and barometric pressure over I2C.

Bill of Materials (BOM)

• MCU: Arduino Uno R4 WiFi (ABX00087) — ~$27.50
• Sensor: Adafruit BME280 I2C/SPI Breakout (2652) — ~$9.95
• Wiring: 4x Male-to-Female 24 AWG silicone jumper wires
• Host: Any PC/Mac/Raspberry Pi running Python 3.9+ with the pyserial library installed (pip install pyserial)

Pin Mapping Table

Firmware: Arduino C++ Setup with Error Handling

The Arduino side must be kept lean. Its only job is to poll the sensor, format the data as a comma-separated string, and print it to the serial buffer. We use a 500ms polling interval to prevent flooding the host's serial buffer, which can cause PySerial to drop bytes.

Target Board Variant: Arduino Uno R4 WiFi (ATmega328P core via Arduino IDE).

#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME280.h>

#define SEALEVELPRESSURE_HPA (1013.25)
#define POLL_INTERVAL_MS 500

Adafruit_BME280 bme; // I2C mode
unsigned long lastPoll = 0;

void setup() {
  Serial.begin(115200);
  // Wait for serial port to connect. Needed for native USB boards.
  while (!Serial && millis() < 3000) {
    delay(10);
  }

  // Initialize I2C with explicit pins for R4 clarity, though defaults work
  Wire.begin(A4, A5); 
  
  // Check for BME280 at default I2C address (0x77 or 0x76)
  if (!bme.begin(0x77, &Wire)) {
    Serial.println("ERROR:BME280_NOT_FOUND");
    while (1) {
      delay(1000); // Halt execution if sensor is missing
    }
  }
  
  Serial.println("STATUS:READY");
}

void loop() {
  if (millis() - lastPoll >= POLL_INTERVAL_MS) {
    lastPoll = millis();
    
    float temp = bme.readTemperature();
    float pressure = bme.readPressure() / 100.0F;
    float humidity = bme.readHumidity();
    
    // Validate readings to prevent sending NaN to Python
    if (isnan(temp) || isnan(pressure) || isnan(humidity)) {
      Serial.println("ERROR:SENSOR_READ_FAIL");
    } else {
      // Output format: TEMP,PRESSURE,HUMIDITY
      Serial.print(temp, 2);
      Serial.print(",");
      Serial.print(pressure, 2);
      Serial.print(",");
      Serial.println(humidity, 2);
    }
  }
}

Host Script: Python PySerial Implementation

The host script handles connection management, error catching, and CSV logging. A common mistake in Arduino Python programming is failing to handle the DTR (Data Terminal Ready) line toggle, which causes the Arduino to reset every time the Python script opens the COM port. We handle this by disabling DTR/RTS where supported, and by using read_until() to ensure we never read partial byte streams.

import serial
import serial.tools.list_ports
import time
import csv
import sys

TARGET_BAUD = 115200
CSV_FILE = "environmental_log.csv"

def find_arduino_port():
    """Automatically find the Arduino COM port based on VID/PID."""
    ports = serial.tools.list_ports.comports()
    for port in ports:
        # Arduino VID is typically 0x2341 or 0x239A (for R4 WiFi)
        if port.vid == 0x2341 or port.vid == 0x239A:
            return port.device
    return None

def main():
    port_name = find_arduino_port()
    if not port_name:
        print("FATAL: Arduino not found. Check USB connection.")
        sys.exit(1)

    try:
        # dsrdtr=False prevents the Arduino from auto-resetting on connect
        ser = serial.Serial(port_name, TARGET_BAUD, timeout=2, dsrdtr=False, rtscts=False)
        time.sleep(2) # Allow Arduino bootloader to finish and sketch to start
        ser.reset_input_buffer()
        
        print(f"Connected to {port_name} at {TARGET_BAUD} baud.")
        
        with open(CSV_FILE, mode='a', newline='') as file:
            writer = csv.writer(file)
            # Write header if file is empty
            if file.tell() == 0:
                writer.writerow(["Timestamp", "Temp_C", "Pressure_hPa", "Humidity_pct"])

            while True:
                try:
                    # read_until ensures we get a full line terminated by \n
                    raw_line = ser.read_until(b'\n')
                    if not raw_line:
                        continue # Timeout reached, loop again
                    
                    decoded_line = raw_line.decode('utf-8').strip()
                    
                    # Handle Arduino-side error strings
                    if decoded_line.startswith("ERROR:"):
                        print(f"Arduino reported: {decoded_line}")
                        continue
                    if decoded_line.startswith("STATUS:"):
                        print(f"Arduino status: {decoded_line}")
                        continue

                    # Parse CSV data
                    parts = decoded_line.split(',')
                    if len(parts) == 3:
                        temp, pressure, humidity = parts
                        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
                        writer.writerow([timestamp, temp, pressure, humidity])
                        file.flush() # Force write to disk immediately
                        print(f"[{timestamp}] T:{temp}C | P:{pressure}hPa | H:{humidity}%")
                    else:
                        print(f"Malformed data received: {decoded_line}")

                except UnicodeDecodeError as e:
                    print(f"Decode Error (baud mismatch or noise): {e}")
                    ser.reset_input_buffer()
                    
    except serial.SerialException as e:
        print(f"FATAL Serial Error: {e}")
        sys.exit(1)
    except KeyboardInterrupt:
        print("\nLogging stopped by user.")
    finally:
        if 'ser' in locals() and ser.is_open:
            ser.close()
            print("Serial port closed.")

if __name__ == "__main__":
    main()

Debugging: First Three Checks and Common Error Strings

When bridging C++ and Python over serial, failures usually manifest at the OS or protocol layer. If your script fails to log data, run through this exact decision sequence.

The First Three Things to Check When It Fails

1. Port Lock / Permissions: Is the Arduino IDE Serial Monitor still open? Only one application can hold a lock on a COM port at a time. Close the IDE monitor before running the Python script.
2. Baud Rate Mismatch: Verify that Serial.begin(115200) in C++ exactly matches TARGET_BAUD = 115200 in Python. A mismatch won't throw a connection error; it will just output garbage characters.
3. DTR Auto-Reset Loop: If the Arduino's onboard LED flashes every time Python tries to read a line, the OS is toggling the DTR line, resetting the MCU. Ensure dsrdtr=False is in your Python serial.Serial() call, or solder a 10µF electrolytic capacitor between the RESET and GND pins on the Arduino to physically block the reset pulse.

Exact Error Strings and Ranked Causes

Extending and Simplifying the Build

Once the baseline PySerial bridge is stable, you can scale the architecture up or down depending on your deployment constraints.

How to Simplify (Bench Testing Mode)

If you don't have a BME280 on hand and just want to test the Python-to-Arduino serial pipeline, strip the C++ code down to log the internal analog noise from an unconnected pin. Replace the BME280 I2C block in the loop() with:

int noise = analogRead(A0);
Serial.print(noise);
Serial.print(",0.00,0.00"); // Dummy values for pressure/humidity
Serial.println();

This eliminates I2C library dependencies and isolates the serial communication layer for debugging.

How to Extend (Networked Data Pipeline)

To push data to a cloud dashboard without tying up your host PC, leverage the secondary ESP32-S3 chip on the Arduino Uno R4 WiFi.

1. Hardware Bridge: In the Arduino IDE, use the Serial1 object to pass data from the main ATmega328P to the ESP32-S3 over the internal hardware UART.
2. Network Transport: Flash the ESP32-S3 with a lightweight MQTT publisher script (using the ArduinoESP32 core) that forwards the CSV strings to a Mosquitto broker.
3. Python Integration: Replace the PySerial host script with a Python paho-mqtt subscriber running on a Raspberry Pi or cloud VPS, decoupling the physical USB tether while maintaining the Python data processing pipeline.

By keeping the C++ firmware strictly focused on deterministic hardware polling and offloading the data formatting and storage to Python, you create a robust Arduino Python programming architecture that won't crash when left running for weeks on end.