AmbientGuard

Ein ESP32-C6 basiertes IoT-Umgebungsüberwachungssystem mit BME280-Sensor, MAX17048 Batteriemonitor, Deep Sleep und InfluxDB-Integration.

Inhaltsverzeichnis

• Übersicht
• Features
• Hardware
• Software
• API-Dokumentation
• Installation
• Konfiguration
• Verwendung
• Projektstruktur
• Entwicklung
• Versionen
• Beitragen
• Lizenz

Übersicht

AmbientGuard ist ein kompaktes, energieeffizientes Umgebungsüberwachungssystem, das mit dem ESP32-C6 Mikrocontroller entwickelt wurde. Das Projekt kombiniert moderne IoT-Technologien mit präzisen Sensoren zur kontinuierlichen Überwachung von Umweltbedingungen. Daten werden über WiFi an eine InfluxDB-Datenbank gesendet und können mit Grafana visualisiert werden.

Features

Sensoren

• BME280 - Kombinierter Sensor für:

  • Temperatur (±1°C Genauigkeit)
  • Luftfeuchtigkeit (±3% Genauigkeit)
  • Luftdruck (±1 hPa Genauigkeit)

• MAX17048 - LiPo Fuel Gauge für:

  • Batteriespannung (1.25mV Genauigkeit)
  • State of Charge (SOC) in Prozent

Konnektivität

• WiFi 6 (802.11ax) - Moderne WLAN-Technologie mit vollständiger Abwärtskompatibilität
• Hostname: AmbientGuard
• Automatische Wiederverbindung bei Netzwerkausfällen

Datenübertragung

• InfluxDB v2 - Zeitreihen-Datenbank für Sensor-Daten
• HTTP-basierte Line Protocol - Effiziente Datenübertragung
• Device-ID Unterstützung - Mehrere ESP32-Geräte unterscheidbar

Energieeffizienz

• Deep Sleep Mode - 5 Minuten Sleep-Zyklus für minimalen Stromverbrauch
• Automatisches Wake-up - Timer-basiertes Aufwachen
• WiFi Cleanup - Optimierte Ressourcennutzung

Sicherheitsfeatures

• 20-Sekunden Safety-Delay - Zeitfenster für Firmware-Flashing beim ersten Boot
• BOOT-Button Modus - Tiefschlaf-Deaktivierung für Entwicklungszwecke
• Wake-up Reason Detection - Unterscheidung zwischen Power-on und Sleep-Wake-up

Status-Anzeige

• Serielle Ausgabe - Detaillierte Logs für Entwicklung und Monitoring
• Umfassende Fehlerbehandlung - Robustes Error-Handling für alle Komponenten

Technische Features

• Modulare Bibliotheks-Architektur - Wiederverwendbare Komponenten
• ESP-IDF 5.5.0 - Aktuelles Framework
• Git-basierte Versionskontrolle - Saubere Entwicklungshistorie
• 2MB Flash Partition Table - Optimierte Speichernutzung

Hardware

Gesamtansicht der AmbientGuard Hardware

BME280 Sensor im Detail

Hauptkomponenten

• ESP32-C6FH4 (QFN32) - Mikrocontroller mit WiFi 6, Bluetooth 5, IEEE 802.15.4
• BME280 - Umwelt-Sensor (I2C-Schnittstelle)
• MAX17048 - LiPo Fuel Gauge (I2C-Schnittstelle)
• USB-C - Stromversorgung und Programmierung

Hardware-Spezifikationen

Mikrocontroller: ESP32-C6 (RISC-V, 160MHz)
RAM: 320KB
Flash: 2MB (ESP32-C6FH4)
WiFi: 802.11ax (WiFi 6)
Bluetooth: 5.0
IEEE 802.15.4: Unterstützt

Pinout

GPIO-Pinout des ESP32-C6

Pinout des BME280 Sensors

BME280 Sensor:
- VCC → 3.3V
- GND → GND
- SCL → GPIO 14 (I2C Clock)
- SDA → GPIO 20 (I2C Data)
- CSB → 3.3V - I2C Kommunikation
- SDO → GND - Adresse 0x76 verwenden

MAX17048 Fuel Gauge:
- VCC → 3.3V
- GND → GND
- SCL → GPIO 14 (I2C Clock, shared with BME280)
- SDA → GPIO 20 (I2C Data, shared with BME280)
- I2C Adresse: 0x36

Software

Framework

• ESP-IDF 5.5.0 - Espressif IoT Development Framework
• PlatformIO - Entwicklungsumgebung

Bibliotheken

• lib/bme280/ - BME280 Sensor-Driver
• lib/max17048/ - MAX17048 Fuel Gauge-Driver
• lib/wifi_config/ - WLAN-Konfiguration und -Management
• src/influxdb_client.* - InfluxDB HTTP-Client

Programmiersprache

• C - Systemnahe Programmierung für maximale Effizienz

API-Dokumentation

BME280 Sensor Library

Funktionen

esp_err_t bme280_init(void)

Initialisiert den BME280 Sensor und konfiguriert die I2C-Schnittstelle.

• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler
• Verwendung: Muss vor allen anderen BME280-Funktionen aufgerufen werden

esp_err_t bme280_config(void)

Konfiguriert den BME280 Sensor für optimale Messungen.

• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler
• Konfiguration: Forced Mode, 1x Oversampling, Filter Off

esp_err_t bme280_read_calib_data(bme280_calib_data_t *calib_data)

Liest Kalibrierungsdaten aus dem Sensor.

• Parameter: calib_data - Pointer zur Kalibrierungsdaten Struktur
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

esp_err_t bme280_start_measurement(void)

Startet eine Messung im Forced Mode.

• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

esp_err_t bme280_read_data(bme280_data_t *data)

Liest Messwerte vom Sensor.

• Parameter: data - Pointer zur Datenstruktur
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

esp_err_t bme280_measure(bme280_data_t *data)

Komplette Messung: Startet Messung und liest Werte.

• Parameter: data - Pointer zur Datenstruktur
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

Datenstrukturen

bme280_data_t

typedef struct {
    float temperature;    // °C
    float pressure;       // Pa
    float humidity;       // %
} bme280_data_t;

bme280_calib_data_t

typedef struct {
    // Temperatur Kalibrierung
    uint16_t dig_T1;
    int16_t  dig_T2, dig_T3;

    // Luftdruck Kalibrierung
    uint16_t dig_P1;
    int16_t  dig_P2, dig_P3, dig_P4, dig_P5, dig_P6, dig_P7, dig_P8, dig_P9;

    // Luftfeuchtigkeit Kalibrierung
    uint8_t  dig_H1;
    int16_t  dig_H2, dig_H3;
    int16_t  dig_H4, dig_H5;
    int8_t   dig_H6;
} bme280_calib_data_t;

MAX17048 Fuel Gauge Library

Funktionen

esp_err_t max17048_init(void)

Initialisiert den MAX17048 Fuel Gauge und liest die Version.

• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler
• Verwendung: Muss vor allen anderen MAX17048-Funktionen aufgerufen werden

esp_err_t max17048_read_voltage(float *voltage)

Liest die Batteriespannung.

• Parameter: voltage - Pointer zur Spannungsvariable (in Volt)
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler
• Auflösung: 1.25mV pro LSB

esp_err_t max17048_read_soc(float *soc)

Liest den State of Charge (SOC) der Batterie.

• Parameter: soc - Pointer zur SOC-Variable (in Prozent, 0-100%)
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

esp_err_t max17048_read_data(max17048_data_t *data)

Liest sowohl Spannung als auch SOC.

• Parameter: data - Pointer zur Datenstruktur
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

Datenstrukturen

max17048_data_t

typedef struct {
    float voltage;  // Volt
    float soc;      // Prozent (0-100)
} max17048_data_t;

WiFi Configuration Library

Funktionen

void wifi_event_handler(void* arg, esp_event_base_t event_base, int32_t event_id, void* event_data)

Event Handler für WiFi-Ereignisse.

• Parameter: Standard ESP-IDF Event Handler Parameter

esp_err_t wifi_init(void)

Initialisiert das WiFi-System. Muss nur einmal beim Start aufgerufen werden.

• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler
• Hinweis: Nur einmal pro Programmstart aufrufen

esp_err_t wifi_connect(void)

Stellt eine WiFi-Verbindung her. Kann mehrfach aufgerufen werden.

• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

bool wifi_is_connected(void)

Prüft den WiFi-Verbindungsstatus.

• Rückgabe: true wenn verbunden, false wenn nicht verbunden

esp_err_t wifi_set_hostname(const char* hostname)

Setzt den Hostname für das ESP32-C6.

• Parameter: hostname - Der gewünschte Hostname
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

void wifi_cleanup(void)

Deinitialisiert das WiFi-System und gibt Ressourcen frei.

• Rückgabe: Keine

InfluxDB Client Library

Funktionen

esp_err_t influxdb_init(void)

Initialisiert den InfluxDB-Client (nur Logging).

• Rückgabe: ESP_OK bei Erfolg

esp_err_t influxdb_send_sensor_data(float temperature, float humidity, float pressure, float battery_voltage, float battery_soc)

Sendet Sensordaten an InfluxDB.

• Parameter: Alle Sensorwerte (Temperatur, Luftfeuchtigkeit, Druck, Batteriespannung, SOC)
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

esp_err_t influxdb_write(const char *line_protocol)

Sendet rohe Line-Protocol-Daten an InfluxDB.

• Parameter: line_protocol - InfluxDB Line Protocol String
• Rückgabe: ESP_OK bei Erfolg, Fehlercode bei Fehler

bool influxdb_is_available(void)

Prüft die Verfügbarkeit des InfluxDB-Servers.

• Rückgabe: true wenn Server erreichbar, false sonst

Hauptprogramm

void app_main(void)

Hauptfunktion des AmbientGuard Systems.

Ablauf:

1. Safety-Delay für Firmware-Flashing (nur beim ersten Boot)
2. BOOT-Button-Check für Flash-Modus
3. Hardware-Initialisierung (BME280, MAX17048)
4. WiFi-Initialisierung
5. Batteriedaten lesen (MAX17048)
6. Sensordaten lesen (BME280)
7. WiFi-Verbindung herstellen
8. Daten an InfluxDB senden
9. WiFi trennen und aufräumen
10. Deep Sleep aktivieren (5 Minuten)

Installation

Voraussetzungen

• PlatformIO installiert
• ESP32-C6 Development Board (ESP32-C6FH4)
• BME280 Sensor
• MAX17048 Fuel Gauge (optional, aber empfohlen)
• USB-C Kabel
• InfluxDB Server (siehe RASPBERRY_PI_SETUP.md)

Verdrahtung

Aufbau der Hardware

Es ist zu beachten, dass keine Pullup-Widerstände für SDA und SCL benötigt werden, da diese intern aktiviert wurden. Sollte die Adresse 0x77 für den BME280 gewünscht sein, kann SDO auf 3.3V gehängt werden.

Fertiger Aufbau

Repository klonen

git clone https://github.com/WindowPlaceBrain/AmbientGuard.git
cd AmbientGuard

Abhängigkeiten installieren

pio lib install

Kompilieren und flashen

pio run --target upload

Konfiguration

WLAN- und InfluxDB-Konfiguration

1. Bearbeiten Sie die Datei src/credentials.h:

#ifndef CREDENTIALS_H
#define CREDENTIALS_H

// WLAN Netzwerk Name (SSID)
#define WIFI_SSID "Ihr-WLAN-Name"

// WLAN Passwort
#define WIFI_PASSWORD "Ihr-WLAN-Passwort"

// Hostname für das ESP32-C6
#define WIFI_HOSTNAME "AmbientGuard"

// Device-ID für mehrere ESP32-Geräte (unterscheidbar in InfluxDB)
#define DEVICE_ID "ESP32_001"

// InfluxDB Konfiguration
#define INFLUXDB_SERVER "192.168.0.198"  // IP-Adresse des InfluxDB-Servers
#define INFLUXDB_PORT 8086
#define INFLUXDB_ORG "AmbientGuard"
#define INFLUXDB_BUCKET "sensors"
#define INFLUXDB_TOKEN "Ihr-InfluxDB-Token"
#define INFLUXDB_MEASUREMENT "weather"

#endif // CREDENTIALS_H

Serieller Monitor

pio device monitor --baud 115200

Verwendung

System starten

1. ESP32-C6 mit USB-C verbinden
2. Serieller Monitor starten (optional, aber empfohlen)
3. System startet automatisch:
   • Beim ersten Boot: 20 Sekunden Safety-Delay für Firmware-Flashing
   • Hardware-Initialisierung (BME280, MAX17048)
   • WiFi-Verbindung
   • Sensordaten-Messung
   • Datenübertragung an InfluxDB
   • Deep Sleep (5 Minuten)
   • Wiederholung des Zyklus

Flash-Modus (Entwicklung)

Um Deep Sleep während der Entwicklung zu deaktivieren:

1. BOOT-Button gedrückt halten während des Starts
2. System bleibt aktiv (kein Deep Sleep)
3. BOOT-Button loslassen und Reset für normalen Betrieb

Ausgabe-Beispiel

I (0) AMBIENTGUARD: =================================
I (10) AMBIENTGUARD: ESP32-C6 AmbientGuard Starting
I (20) AMBIENTGUARD: =================================
I (1020) AMBIENTGUARD: Wake-up from deep sleep (timer)
I (1050) AMBIENTGUARD: Initializing hardware...
I (1120) BME280: Initializing BME280...
I (1250) BME280: BME280 found (Chip ID: 0x60)
I (1280) BME280: BME280 initialized!
I (1300) MAX17048: Initializing MAX17048...
I (1350) MAX17048: MAX17048 found! Version: 0x0001
I (1380) AMBIENTGUARD: Hardware initialization complete
I (1400) AMBIENTGUARD: Initializing WiFi...
I (1500) WIFI_CONFIG: WiFi initialization complete
I (1520) AMBIENTGUARD: Reading battery data...
I (1580) AMBIENTGUARD: Battery: 4.14V (85.3%)
I (1600) AMBIENTGUARD: Reading BME280 sensor data...
I (1650) AMBIENTGUARD: Sensor: T=23.45°C, H=65.30%, P=1013.25hPa
I (1700) AMBIENTGUARD: Connecting to WiFi...
I (2800) WIFI_CONFIG: WiFi connected! IP: 192.168.0.100
I (2850) AMBIENTGUARD: WiFi connected successfully
I (2900) AMBIENTGUARD: Sending data to InfluxDB...
I (3100) INFLUXDB: Data written successfully
I (3150) AMBIENTGUARD: Data sent successfully
I (3200) AMBIENTGUARD: Disconnecting WiFi...
I (3250) AMBIENTGUARD: WiFi disconnected
I (3300) AMBIENTGUARD: =================================
I (3310) AMBIENTGUARD: Cycle complete
I (3320) AMBIENTGUARD: =================================
I (3350) AMBIENTGUARD: Entering deep sleep for 300 seconds...
I (3400) AMBIENTGUARD: Deep sleep configured. Good night!

Grafana Visualisierung

Siehe RASPBERRY_PI_SETUP.md für Anleitung zur InfluxDB- und Grafana-Installation.

Projektstruktur

AmbientGuard/
├── lib/                          # Bibliotheken
│   ├── bme280/                   # BME280 Sensor-Driver
│   │   ├── bme280.h
│   │   ├── bme280.c
│   │   └── CMakeLists.txt
│   ├── max17048/                 # MAX17048 Fuel Gauge-Driver
│   │   ├── max17048.h
│   │   └── max17048.c
│   └── wifi_config/              # WLAN-Konfiguration
│       ├── wifi_config.h
│       ├── wifi_config.c
│       └── CMakeLists.txt
├── src/                          # Quellcode
│   ├── main.c                    # Hauptprogramm
│   ├── credentials.h             # Credentials (nicht im Git)
│   ├── influxdb_client.h         # InfluxDB Client Header
│   ├── influxdb_client.c         # InfluxDB Client Implementation
│   └── CMakeLists.txt
├── partitions_2mb.csv            # Custom Partition Table (2MB Flash)
├── platformio.ini               # PlatformIO-Konfiguration
├── CMakeLists.txt               # Haupt-CMake-Konfiguration
├── README.md                     # Diese Datei
└── RASPBERRY_PI_SETUP.md        # InfluxDB/Grafana Setup-Anleitung

Entwicklung

Git-Workflow

# Feature-Branch erstellen
git checkout -b feature/neue-funktion

# Änderungen committen
git add .
git commit -m "Beschreibung der Änderungen"

# Zurück zu develop
git checkout develop
git merge feature/neue-funktion

Debugging

• Serieller Monitor: pio device monitor --baud 115200
• Log-Level: Konfigurierbar über esp_log_level_set()
• Flash-Modus: BOOT-Button für Entwicklung ohne Deep Sleep

Code-Standards

• Coding Style: ESP-IDF Standard
• Kommentare: Doxygen-kompatibel
• Error Handling: Umfassende Fehlerbehandlung mit esp_err_t

Versionen

v0.5.1 - Deep Sleep Stabilisierung

Features:

• Deep Sleep mit 5-Minuten-Zyklus
• Vollständige Hardware-Reinitialisierung nach jedem Wake-up
• NVS-basierte Persistenz entfernt (vereinfachter Code)
• Optimierte WiFi-Verbindungshandhabung
• Stabile Langzeit-Betriebsfähigkeit

v0.5.0 - Deep Sleep Integration

Features:

• Deep Sleep Mode mit konfigurierbarer Dauer
• Safety-Features für Firmware-Flashing
• BOOT-Button-Modus für Entwicklung
• Timing-Messungen für Power-Analyse
• InfluxDB-Integration mit Device-ID

v0.3.0 - MAX17048 Integration

Features:

• MAX17048 Fuel Gauge Integration
• Batteriespannung und SOC-Messung
• Korrekte Spannungsberechnung (1.25mV/LSB)
• I2C-Pin-Korrektur (SDA/SCL)

v0.1.0 - Initiale Release

Features:

• ESP32-C6 Mikrocontroller mit WiFi 6 Support
• BME280 Sensor für Temperatur, Luftfeuchtigkeit und Luftdruck
• WLAN-Verbindung mit automatischer Wiederverbindung
• Hostname-Konfiguration "AmbientGuard"
• Serielle Ausgabe für Monitoring und Debugging
• Modulare Bibliotheks-Architektur

Entwicklungsumgebung

• IDE: VS Code mit PlatformIO Extension
• Framework: ESP-IDF 5.5.0
• Board: ESP32-C6-DevKitM-1
• Flash: 2MB (Custom Partition Table)

Lizenz

Dieses Projekt steht unter der GPL-3.0 Lizenz. Siehe LICENSE Datei für Details.

Kontakt

Entwickler: Luca Moser
Email: luca.moser.lm3@gmail.com
Projekt: AmbientGuard - ESP32-C6 IoT Umgebungsüberwachungssystem

---

Entwickelt mit Liebe für das Internet der Dinge