rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten

04 · Anschluss

Dieses Kapitel beschreibt die physische Verdrahtung des rbAmp-Moduls mit Boards der ESP32-Familie: Pinbelegung auf der Niederspannungsseite, Versorgungsanforderungen, Spannungspegelkompatibilität von I²C, Buslänge und die Standard-Default-Pins für die 7 unterstützten ESP32-Chips (esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32h2).

Das Modul selbst ist vollständig Niederspannung; bei UI*-Varianten ist die einzige Netzreferenz ein L–N-Abgriff hinter einem galvanisch getrennten Teiler. Die NS-Seite (Versorgung + I²C + optional DRDY) wird zuerst beschrieben; der Netz- und CT-Anschluss steht unten unter Netz- und CT-Anschluss.

Belegung der Niederspannungsseite

Die Niederspannungspins des Moduls: VCC, GND, SDA, SCL und die optionale Datenbereit-Leitung.
Das Modul arbeitet mit 3.3-V-I²C-Logik und ist5-V-tolerantan den Signalleitungen. Alle Niederspannungs-Pins sind vollständig galvanisch vom Netz getrennt.

Pin Signal Zweck
VCC +5 V (4.5..5.5 V) Modulversorgung; mindestens 4.5 V für korrekten Betrieb
GND Masse Mit dem Master geteilt — verpflichtend
SDA I²C SDA I²C-Daten
SCL I²C SCL I²C-Takt
DRDY Data-ready (optional) Open-Drain, LOW-Impuls ca. 10 µs etwa alle 100 ms

Leistung

VCC-Parameter

  • Nennspannung: 5 V DC
  • Zulässiger Bereich: 4.5..5.5 V
  • Stromaufnahme: typisch ~15 mA, Spitze ~25 mA bei Flash-Schreibvorgängen
  • Welligkeit: < 50 mV Spitze-Spitze (für die Messgenauigkeit)

Das Modul hat einen eingebauten Spannungsregler, einen RC-Filter, Keramikkondensatoren und eine Ferritperle — eine zusätzliche Filterung ist vom Benutzer nicht nötig. Das Modul kann über die Schiene +5V oder +5V0 eines beliebigen DevKitC-Boards (USB-5-V-versorgt) betrieben werden.

Kompatibilität der I²C-Spannungspegel

  • SDA / SCL arbeiten mit 3.3-V-Logik (eingebaute Pull-ups ziehen die Leitungen auf 3.3 V).

  • Die Leitungen sind 5-V-tolerant, aber die ESP32-Familie arbeitet ohnehin mit 3.3 V — es werden keine Pegelwandler benötigt.

  • Der ESP-IDF-Treiber i2c_master verwendet Open-Drain-Ausgänge an den GPIOs — kompatibel mit den eingebauten Pull-ups des Moduls.

Verhalten beim Einschalten

  • Kaltstart: ca. 250 ms bis zum ersten gültigen Ergebnis.
  • Nach einem Reset (Software oder Brown-out): ca. 250 ms bis zur Wiederherstellung.
  • Bis zum ersten gültigen Ergebnis lesen die Register als 0, mit dem Flag DATA_VALID = 0.

Die Komponente wartet innerhalb von rbamp_begin(dev) selbst, bis das Modul bereit ist — Anwendercode ruft einfach rbamp_begin() auf und fährt fort.

Isolation

Das Modul selbst ist vollständig Niederspannung — es gibt keine Hochspannungsmessschaltung auf ihm. Der Strom wird über eine CT-Zange gemessen, die magnetisch von außen durch die isolierte Leitung koppelt, ohne elektrischen Kontakt zum Netzdraht. Bei spannungsmessenden (UI)-Varianten ist die einzige Netzreferenz die L–N-Klemme, die einen galvanisch getrennten* Messteiler speist; Varianten nur für Ampere haben gar keinen Netzanschluss.

Consequences:

  • Die GND des Moduls ist nicht mit Netzphase oder Neutralleiter verbunden.
  • Die Niederspannungs-Pins werden ohne Netzbezug an den ESP32 angeschlossen: Die Zange koppelt magnetisch, und der UI-Spannungsabgriff liegt hinter einem galvanisch getrennten Teiler. Das ersetzt nicht die Vorsichtsmaßnahmen beim Netzanschluss im nächsten Abschnitt.
Sicherheit

⚠ Öffnen Sie das Modulgehäuse nicht — dies hebt die Werkskalibrierung auf.

Netz- und CT-Anschluss

Netzseitige Verdrahtung: der L- und N-Spannungsabgriff und die Zange auf dem Außenleiter.

Sicherheit

⚠ Netzspannung kann tödlich sein. Schalten Sie den Stromkreis ab und sichern Sie ihn gegen Wiedereinschalten, bevor Sie die L/N-Klemmen anschließen oder die Zange anbringen; lassen Sie Netzanschlussarbeiten und jede Arbeit im Verteilerkasten von einer Elektrofachkraft ausführen. Klemmen Sie NUR EINEN Leiter (L) ein — niemals das ganze Kabel. Sichern Sie die L-Abzweigung gemäß den örtlichen Vorschriften ab (verpflichtend, bis 0.1 A; AWG26–22-Leitung genügt — der Spannungssensor zieht sehr wenig Strom).

  • Spannung (nur UI-Varianten): Das Modul misst die Spannung über die L/N-Verbindung auf seiner Netzseite: Die Platine stellt die Klemmen L (Außenleiter) und N (Neutralleiter) bereit, und die Polarität bestimmt das Vorzeichen der Leistung. I-Varianten (I1/I2/I3) haben keinen Spannungseingang.

  • Strom: Die SCT-013-Zange steckt in der 3.5-mm-CT-Buchse des Moduls (verpolungssicher; jede Buchse auf der Platine ist mit ihrem Kanal beschriftet, I0, I1, …) und schließt sich um den Außenleiter (L). Der Pfeil am Zangenkörper zeigt in Stromrichtung zur Last. Eine verkehrt herum angelegte Zange ergibt bei einer verbrauchenden Last ein negatives P.

  • Klemmen Sie den Außenleiter, nicht den Neutralleiter und nicht beide Leiter zusammen.

  • Öffnen Sie das Modulgehäuse nicht — dadurch erlischt die werkseitige Kalibrierung. Die unten genannten Pull-up-Brücken befinden sich auf der Unterseite der Platine; folgen Sie zum Erreichen den Anweisungen des Moduls.

Eingebaute Pull-up-Widerstände — auf der Platine

Wichtig: Jedes rbAmp-Modul hat eingebaute 4.7-kΩ-Pull-up-Widerstände an SDA und SCL gegen 3.3 V. Für ein einzelnes Modul am Bus sind keine externen Pull-ups nötig — schließen Sie den ESP32 direkt an.

Die i2c_master_bus_config_t des ESP-IDF erlaubt außerdem, die internen GPIO-Pull-ups über flags.enable_internal_pullup = true zu aktivieren. Sie sind schwach (~50 kΩ am ESP32) und wirken parallel zu den externen 4.7 kΩ des Moduls — die Kombination ergibt effektiv ~4.4 kΩ, was akzeptabel ist. Für Produktionsinstallationen verlassen Sie sich besser auf die externen 4.7 kΩ des Moduls; die internen GPIO-Pull-ups sind neben den Pull-ups des Moduls optional und vor allem für Bench-Tests ohne vorliegendes Modul gedacht (etwa wenn Sie nur einen Bus-Scan prüfen).

Wann die integrierten Pull-ups abzuschalten sind

Befinden sich mehrere rbAmp-Module am Bus (oder andere I²C-Geräte mit eigenen Pull-ups), ergibt die Parallelschaltung einen zu niedrigen Ersatzwiderstand, was dazu führt, dass:

  • Erhöht die Stromaufnahme des Busses
  • Kann den maximalen Senkenstrom der Ausgangsstufe des I²C-Masters überschreiten
  • Erhöht die kapazitive Last auf einem langen Bus, verbessert die Störfestigkeit aber kaum

Lösung: Auf der Unterseite der Platine jedes Moduls, neben den Pull-up-Widerständen, befinden sich Lötbrücken (Siebdruck Pull-Up). Trennen Sie sie mit einer scharfen Klinge:

  • Lassen Sie die Pull-ups nur auf einem Modul aktiviert (oder verlegen Sie sie an einen einzigen Punkt nahe dem ESP32).

  • Trennen Sie die Brücken auf den übrigen Modulen.

Faustregel

Pull-up-Regeln für ein bis drei Module auf einem kurzen Bus und für vier oder mehr.
| rbAmp-Module am Bus | Pull-ups | |:---:|---| | 1 | Belassen (der eingebaute 4.7 kΩ genügt) | | 2 | An einem belassen, am anderen trennen | | 3 | An allen Modulen trennen, ein externes Paar 2.7…3.3 kΩ nahe dem ESP32 einsetzen | | 4…6 | An allen Modulen trennen, ein externes Paar 2.2…2.7 kΩ nahe dem ESP32 | | 7…16 | An allen Modulen trennen, ein externes Paar 1.5…2.2 kΩ nahe dem ESP32; Buskapazität prüfen (≤ 400 pF), bei Bedarf Busgeschwindigkeit senken |

Die externen Werte sind Empfehlungen (berechnet aus der I²C-Spezifikation: Senkenstrom ≤ 3 mA bei 3.3 V, Buskapazität ≤ 400 pF). Schließen Sie die externen Pull-ups an 3.3 V (den Logikpegel des Busses) an, nicht an die 5-V-Versorgung VCC.

Im Zweifel

: Messen Sie den Widerstand zwischen SDA und der 3V3-Leitung, wenn alle Geräte spannungslos sind. Er sollte im Bereich 1.5..4.7 kΩ liegen. Niedriger — zu viele aktive Pull-ups parallel.

I²C-Busparameter

  • Standardadresse: 0x50 (7-Bit)
  • Adressbereich: 0x08..0x77 (im Werk neu zuweisbar)
  • Empfohlene Geschwindigkeit am ESP32: 50 kHz (siehe den Abschnitt zur Disziplin aus Retry und Sanity unten)

  • Zeiger-Autoinkrement: nur bei Lesezugriffen. Ein Burst-Lesen + N Bytes liefert N aufeinanderfolgende Bytes ab addr (Autoinkrement). Schreibvorgänge werden NICHT automatisch inkrementiert: Ein Burst-Schreiben + N Bytes landet nur das erste Byte, der Rest wird verworfen. Mehrbyte-Register werden Byte für Byte geschrieben — eine eigene Einzelbyte-Transaktion je Adresse. Details siehe 09 · API-Referenz, Abschnitt „Multi-byte writes“.

Buslänge

I²C ist ein kurzer Bus (standardmäßig ca. 15 cm). Viele Anwender verbinden Module mit minderwertigen Steckbrücken, die viel Störung aufnehmen und viele Übertragungen verlieren — daher die kurze Grenze. Empfohlene Topologien für rbAmp:

Kabel Maximale Länge Geschwindigkeit
Standard-JST / flache 4-adrige Leitung bis 0.15 m 100 kHz
Verdrilltes Paar UTP (Cat-5/5e/6) — SDA+GND und SCL+GND in getrennten Paaren bis 1 m 100 kHz
Verdrillte Doppelleitung + I²C-Puffer (PCA9515 / TCA9617) bis 3 m 100 kHz
Differenzieller Bus (PCA9615 / LTC4332) bis 100 m 100 kHz
Sicherheit

Die oben genannten Längen wurden bei 100 kHz verifiziert. Die Standard-Busgeschwindigkeit der Komponente ist 50 kHz (siehe „ESP32-Basis-NACK-Muster“ unten), die längere Kabel besser toleriert; bleiben Sie bei 50 kHz und überschreiten Sie diese Längen nicht.

Bei Längen über 0.15 m ist ein verdrilltes Paar zwingend: SDA und SCL müssen in verschiedenen Paaren liegen, jeweils mit eigener Masse. SDA und SCL im selben Paar erzeugen eine kapazitive Übersprechkopplung, die die Flanken verzerrt.

⚠ Im Schaltschrank den I2C-Kabel abschirmen. Starke Magnetfelder in der Nähe von Netzleitern, Schützen und Transformatoren induzieren Störungen in einem ungeschirmten Kabel. Halten Sie das Kabel so kurz wie möglich und fern von der Netzverdrahtung.

Mehrmodul-Bus — die primäre Topologie

Der kanonische Anwendungsfall der Bibliothek sind mehrere rbAmp-Module an einem einzigen I²C-Bus, verwaltet von einem ESP32 über ein Fleet-Handle. Alle folgenden Regeln und Optimierungen sind genau für diese Topologie ausgelegt; ein einzelnes Modul ist ein Sonderfall (dasselbe Handle, aber die Fleet-Aufrufe werden trivial).

Mehrere rbAmp-Module an einem I2C-Bus, deren Pull-ups gemäß den Regeln behandelt werden.

Typische Installationen

Szenario Konfiguration Anzahl der Module
80 % kanonisch: Hauptzähler im Haus + Unterzähler 1× UI1 (Haupt, Netzenergie) + 3–6× UI1 (Lasten; Leistung und Wh benötigen eine UI-Variante) 4-7
Unterverteilung mit Stromaufschlüsselung 1× UI1 (Netz) + 1–2× I2/I3 (Strom je Stromkreis) 3-5
Industrielle Unterzählung 1× UI1 (Haupt) + N× I2/I3 (je Maschine, Stromaufschlüsselung) bis zu ~16

Elektrische Randbedingungen

  • Modulanzahl: bis etwa 16 (Gesamtkapazität des Busses ≤ 400 pF bei 100 kHz).
  • Adressen: Jedes Modul hat eine eigene 7-Bit-Adresse (Bereich 0x08..0x77). Alle Module werden ab Werk mit 0x50 ausgeliefert — adressieren Sie sie einzeln neu, bevor Sie sie parallel verdrahten (siehe unten zum zweiphasigen Commit und zur Bereitstellung über rbamp_provision()).
  • Pull-ups (wichtig für einen Flottenbus): Die internen Pull-ups des ESP32 (~45 kΩ) sind für einen Multi-Modul-Bus mit langen Leitungen und Störungen zu schwach. Für einen zuverlässigen Betrieb brauchen Sie externe Pull-ups (2.7…3.3 kΩ für 3 Module, niedriger für größere Busse — siehe die Tabelle oben) gegen 3.3 V an SCL/SDA an einem einzigen Punkt des Busses + ab 4 Modulen (oder früher bei einem Bus über 15 cm) werden die eingebauten Pull-ups auf allen Modulen bis auf eines abgetrennt — bei 2–3 Modulen an einem Bus bis 15 cm lassen Sie sie in Ruhe; dieser Fall ist gemessen (oder auf allen abtrennen und nur die externen behalten). Dies ist Teil der dreistufigen Abschwächung gegen Busblockaden auf einem grenzwertigen Bus — siehe 10 · Fehlerbehebung.

Adressierung — Provisionierung und Austausch

Die Werksadresse ist standardmäßig 0x50. Jedes neue oder ersetzte Modul durchläuft einmal die Provisionierung: Neuadressierung von 0x50 auf eine Arbeitsadresse plus optionales Speichern der Konfiguration (CT-Modell, group_id, Label) im Flash.

Im Code ist das ein einziger Aufruf — rbamp_provision(bus, desired_addr, save_config, &dev). Er prüft, dass auf 0x50 am Bus wirklich nur ein neues Modul liegt, adressiert es über einen zweiphasigen Commit neu (siehe unten), speichert optional die Benutzerkonfiguration und liefert ein fertiges Handle zurück.

Ablauf der Bereitstellung: Ein neues Modul an Adresse 0x50 anschließen, ihm seine Adresse geben, dann das nächste.

Sicherheit

⚠ Provisionierungsdisziplin (MUSS): Es muss genau ein jungfräuliches Modul (auf 0x50) am Bus sein, in dem Moment, in dem rbamp_provision() aufgerufen wird. Antworten zwei Module auf derselben Adresse gleichzeitig auf I²C — eine Kollision in der Datenphase —, ist das Verhalten undefiniert, und es gibt keine Möglichkeit, sie zu unterscheiden (Open-Drain mit verdrahtetem UND). Wiederherstellung: stromlos schalten, physisch auf eine Einzelmodul-Inbetriebnahme umstellen, sie nacheinander provisionieren und dann die übrigen anschließen. Siehe 10 · Fehlerbehebung, Abschnitt „Provisionierungsfehler / Adresskonflikt“.

Wenn Sie kein Flotten-Handle haben und manuell mit rbamp_prepare_address_change() + rbamp_commit_address_change() (die Low-Level-Form) neu adressieren — die Disziplin ist genau dieselbe: immer nur ein jungfräuliches Modul.

Zweiphasiger Commit für eine Adressänderung

Die Firmware unterstützt eine Adressänderung im Produktionsmodus über eine zweiphasige Sequenz:

Die Schritte einer zweiphasigen Adressänderung, vom Staging der neuen Adresse bis zur Prüfung.

Text
1. write candidate_addr → REG_I2C_ADDRESS (0x30, in RAM)
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31, armed)
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)
4. issue CMD_RESET (0x01)
5. wait ~300 ms; the new address is active

Die Komponente verpackt dies in rbamp_prepare_address_change() / rbamp_commit_address_change() — siehe 09 · API-Referenz. Die Persistenz ist erst nach einem Reset bestätigt (siehe den Hinweis „Produktions- vs. Werksmodus“ in 03_sensor_selection.md).

Energiebudget des Busses — wie viele Module Ihre Abfragerate tragen kann

Auf einem 50-kHz-Bus dauert eine einzelne Registerlese-Transaktion ≈ 200–400 µs (abhängig vom MCU-Treiber). Ein vollständiger RT-Block eines Kanals (U + I + P + PF) = 4 Floats = 16 Bytes + 4 Adressphasen ≈ 5–8 ms je Kanal.

Konfiguration Busbelegung je Zyklus Bei 50 kHz Maximale Abfragerate
1× UI1, RT-Block ~5 ms < 5 ms 100+ Hz (das Modul aktualisiert aber mit 10 Hz)
1× I3, RT-Block + Periode ca. 25 ms ca. 25 ms bis zu 10 Hz
5× UI1, RT-Block ca. 25 ms ca. 25 ms bis zu 10 Hz
16× I3, RT + Periode ca. 400 ms 400 ms > 100 ms kann mit dem Modul nicht Schritt halten (10 Hz); bestenfalls ~2 Hz
Hinweis

Die Zahlen oben sind Schätzungen und hängen vom Host-MCU und vom Treiber ab.

Regel: Bei 50 kHz liegen die bequemen Grenzen bei 8–10× I3 oder 15–16× UI1 bei 5-Hz-Polling (jedes zweite Modulfenster) und etwa die Hälfte davon bei vollen 10 Hz. Darüber hinaus:

  • Senken Sie die Abfragerate (1 Hz = 10× Reserve).
  • Auf 100 kHz mit Wiederholung umstellen (rechnen Sie mit häufigen NACKs und verlassen Sie sich auf die Wiederholung).
  • Verwenden Sie den Pin DRDY für asynchronen Betrieb — fragen Sie Module, die noch nicht bereit sind, nicht ab.

Periodensynchronisation — Synchronisieren der Perioden für enge Synchronität

Für die Tarifmessung müssen alle Module ihren Snapshot über dasselbe gleiche Zeitintervall nehmen. Zwei Strategien:

Sequenzielles Latch jedes Moduls, verglichen mit einem General-Call-Rahmen, der alle Module auf einmal latcht.

Strategie 1 — sequenzieller Snapshot + gemeinsames Einschwingen (funktioniert auf jeder Firmware):

C
/* Phase 1: sequential snapshot */
for (int i = 0; i < n; i++) {
    rbamp_latch_period(devs[i]);
}

/* Phase 2: shared settle (≥ 50 ms for the snapshot + ~1 commit cycle for witness) */
vTaskDelay(pdMS_TO_TICKS(50));

/* Phase 3: read snapshots with skip_latch=true */
rbamp_period_snapshot_t snaps[n];
for (int i = 0; i < n; i++) {
    rbamp_read_period_snapshot(devs[i], &snaps[i], 0, /*skip_latch=*/true);
}

Versatz zwischen Modulen: 16 Module × ~1 ms/Snapshot = ~16 ms bezogen auf eine 60-Sekunden-Periode → 0.027 %. Vernachlässigbar.

Strategie 2 — General-Call-Broadcast-Snapshot (muss aktiviert werden):

Alle Module empfangen den Snapshot in einem einzigen I²C-Rahmen an der Adresse 0x00:

Das Layout des 5-Byte-Snapshot-Rahmens des General-Call, der an die Adresse 0x00 gesendet wird.

Text
addr=0x00 | A5 27      (5 bytes)

Schiefe = 0 (atomar). Vorkonfiguration:

  1. Aktivieren Sie auf jedem Modul REG_FLEET_CONFIG.bit0 = 1 über CMD_SAVE_USER_CONFIG.
  2. CMD_RESET — der GC-Empfang wird beim Booten aktiviert.
  3. Nach dem Reset sendet der Master den 5-Byte-Rahmen.
  4. Zeuge: Für jedes erwartete Modul REG_V03_PERIOD_VALID (0x07) lesen. !=1 → auf Strategie 1 zurückfallen.

Wann was zu verwenden ist:

  • < 8 Module: Strategie 1 (einfacher, keine Aktivierung nötig).
  • ≥ 8 Module oder enge Synchronisierung: Strategie 2.

GC-Gruppenfilterung — ein Bus für mehrere Mandanten

REG_GROUP_ID (0x28) erlaubt Ihnen mehrere GC-Domänen auf einem Bus:

  • group = 0x00 → All-Call (alle Module mit aktiviertem GC nehmen den Snapshot).
  • group = N → nur Module mit REG_GROUP_ID = N nehmen den Snapshot auf.

Beispiel: ein Bus mit 10 Modulen, bei dem Sie 5 für Tarif A und 5 für Tarif B unabhängig voneinander snapshotten müssen:

Text
write REG_GROUP_ID = 1 on the 5 tariff-A modules
write REG_GROUP_ID = 2 on the 5 tariff-B modules

GC frame [A5 27 01 tl th] → only tariff A takes a snapshot
GC frame [A5 27 02 tl th] → only tariff B takes a snapshot
GC frame [A5 27 00 tl th] → all 10 take a snapshot (all-call)

Fehlermodi an einem Mehrmodul-Bus

Symptom Ursache Was zu tun ist
i2c bus scan zeigt nach einem nachträglichen Einbau mehrere Module auf derselben Adresse Das neue Modul auf 0x50 kollidiert mit einem bereits adressierten Die neue Adresse des Moduls getrennt einspielen, bevor es dem Bus hinzugefügt wird
Ein Modul sendet häufiger NACKs als die anderen Kabelfehler / Spannungseinbruch an diesem Modul VCC unter Last und Logikpegel prüfen
Die Wh-Werte eines Moduls weichen dauerhaft ab Der eigene Timer des Moduls weicht von der Uhr des Masters ab Energie gegen den Master-Takt integrieren (master_dt_ms)
Nach einem GC-Rahmen nimmt ein Modul den Snapshot nicht FLEET_CONFIG.bit0 = 0 oder Gruppe stimmt nicht überein Prüfen Sie REG_FLEET_CONFIG und REG_GROUP_ID

Hinweise zum Bus-Design

  • Clock-Stretching: Die aktuelle Firmware minimiert das Stretching (das Fenster __disable_irq in LatchPeriod ist kurz, ~µs). Der Snapshot selbst zieht SCL nicht nennenswert herunter. Für den Raspberry Pi BCM283x (ein bekannter Hardwarefehler beim Clock-Stretching): die übliche Vorsicht anwenden — 50 kHz + Wiederholung werden bereits empfohlen.
  • Buslänge bei mehr als 4 Modulen: Selbst bei einem verdrillten Paar wächst die wirksame Kapazität linear mit der Anzahl. Erwägen Sie einen I²C-Puffer (PCA9515) ab ≥ 8 Modulen + einer Länge über 1 m.

Ausführliche Mehrmodul-Szenarien stehen in 06 · Beispiele, in den Szenarien „Sub-metering shared bus“ und „GC broadcast snapshot“.

Pinbelegung der ESP32-Familie

Die 7 Chips, die oben in diesem Kapitel aufgeführt sind, werden unterstützt (laut idf_component.yml). Im Folgenden die empfohlenen Standard-Pins für I²C; für Produktionsinstallationen wählen Sie den GPIO anhand des Layouts Ihres Boards.

ESP32 (Original / DevKitC / WROOM)

Referenzverdrahtung eines ESP32 mit einem rbAmp-Modul, bei dem die Zange in der Buchse I0 steckt.

C
const i2c_master_bus_config_t bus_cfg = {
    .i2c_port  = I2C_NUM_0,
    .sda_io_num = GPIO_NUM_21,
    .scl_io_num = GPIO_NUM_22,
    .clk_source = I2C_CLK_SRC_DEFAULT,
    .glitch_ignore_cnt = 7,
    .flags.enable_internal_pullup = true,
};
Pin GPIO
SDA GPIO21
SCL GPIO22
DRDY jeder freie GPIO, der kein Strapping-Pin ist (beim klassischen ESP32 GPIO0/2/12/15 vermeiden)

ESP32-S2

Derselbe Standard-GPIO21/22 wie beim ursprünglichen ESP32. Der S2 hat kein Bluetooth — für TLS-Szenarien stehen ~30 kB zusätzlicher Heap zur Verfügung.

ESP32-S3

Der S3 hat keine hardwareseitig festgelegten I²C-Standardpins — jeder GPIO über die Matrix. Auf den meisten WROOM-S3-Dev-Boards sind GPIO8/GPIO9 eine bequeme Wahl (prüfen Sie den Schaltplan Ihres Boards: auf dem N16R8 können diese Pins vom QSPI-Flash belegt sein; USB-JTAG belegt GPIO19/20). Passen Sie die Felder sda_io_num / scl_io_num in i2c_master_bus_config_t an:

C
.sda_io_num = GPIO_NUM_8,
.scl_io_num = GPIO_NUM_9,

Der S3 hat USB-OTG — er kann ohne externen USB-UART-Chip zum Debuggen verwendet werden.

ESP32-C2 / C3 / C6 / H2

RISC-V-Single-Core-Chips (C3 und C6 sind Single-Core; H2 ist Single-Core mit BLE+802.15.4; C2 ist Single-Core mit begrenztem RAM). Die I²C-Pins sind nicht hardwareseitig festgelegt — hier ein Beispiel für den ESP32-C3 (auf dem C3-SuperMini sind GPIO5/GPIO6 gut geeignet; auf dem C3-DevKitM-1 belegt USB-JTAG GPIO18/19, und GPIO8/9 sind Strapping-Pins):

C
const i2c_master_bus_config_t bus_cfg = {
    .i2c_port  = I2C_NUM_0,
    .sda_io_num = GPIO_NUM_5,
    .scl_io_num = GPIO_NUM_6,
    .clk_source = I2C_CLK_SRC_DEFAULT,
    .glitch_ignore_cnt = 7,
    .flags.enable_internal_pullup = true,
};

Für die anderen Chips — prüfen Sie die zielspezifische ESP-IDF-Dokumentation (docs.espressif.com → ESP-IDF v5.2+ → Ihr Chip → API-Referenz → Peripherie → I2C).

ESP32-P4 — kein unterstütztes Ziel

Der ESP32-P4 steht nicht in der unterstützten Zielliste: Die P4-Unterstützung braucht ESP-IDF v5.3+, während das Minimum der Komponente v5.2 ist (ein v5.2-Build für esp32p4 würde mit „target esp32p4 not in idf“ scheitern).

ESP32-Basismuster NACK — Bus-Geschwindigkeit 50 kHz

Mit dem ESP-IDF-v5-Treiber i2c_master zeigt rbAmp häufige NACKs bei 100 kHz, bei 50 kHz deutlich weniger (eine Eigenschaft des Treibers auf der ESP32-Seite, nicht des Slaves). Die Komponente deckt das in zwei Schichten ab:

  1. Eine Standard-Busgeschwindigkeit von 50 kHz über das Kconfig CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000. Die Komponente fordert diese Frequenz an, wenn sie ihr Gerätehandle zu dem von Ihnen erstellten Bus hinzufügt.

  2. Wiederholung pro Byte — CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 × 5 ms Pause. Bei 50 kHz liegt die Restfehlerrate unter 0.8 %.

Bei Bedarf über idf.py menuconfig überschreiben:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5     # for dense workloads
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200

Zur Diagnose von Problemen auf Bus-Ebene siehe 10 · Fehlerbehebung.

DATA_READY (DRDY)

Ein optionaler Pin zur Optimierung der Abfrage. Fragt die Anwendung das Modul nicht häufiger als einmal alle 100 ms ab, kann DRDY unverbunden bleiben.

Elektrische Parameter

  • Ausgangstyp: Open-Drain (kein aktiver Pull-up gegen VCC)
  • Ruhepegel: HIGH (erfordert einen Pull-up auf der Master-Seite — ein interner gpio_pullup_en() oder ein externer Widerstand; empfohlen werden 10 kΩ gegen 3.3 V)

  • Ready-Impuls: LOW für ~10 µs, nachdem die RT-Register mit frischen Daten aktualisiert wurden

  • Pulsrate: ~10 Hz (ein Impuls pro ~100-ms-RT-Fenster)

Semantik

Eine fallende Flanke an DRDY garantiert, dass alle RT-Register synchronisiert und veröffentlicht sind (die Firmware aktualisiert sie in der ISR atomar, bevor sie den Pin absenkt). Nach der fallenden Flanke kann der Master den RT-Block ohne Gefahr eines geteilten Samples lesen.

Interrupt-Muster — FreeRTOS-Semaphore

ESP-IDF bietet ein sauberes Modell: Ein ISR im IRAM setzt einen binären Semaphor, und eine eigene FreeRTOS-Task wartet auf den Semaphor und liest RT.

C
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"
#include "driver/gpio.h"

#define DRDY_GPIO GPIO_NUM_4   /* a free GPIO; do not use
                                 * GPIO0/2/12/15 — strapping pins
                                 * (ESP32 classic), they can disrupt boot
                                 * if the open-drain DRDY goes LOW
                                 * during reset */
static SemaphoreHandle_t drdy_sem;

static void IRAM_ATTR drdy_isr_handler(void *arg) {
    BaseType_t hi_task_woken = pdFALSE;
    xSemaphoreGiveFromISR(drdy_sem, &hi_task_woken);
    if (hi_task_woken) portYIELD_FROM_ISR();
}

void bidir_task(void *arg) {
    rbamp_handle_t dev = arg;
    while (1) {
        if (xSemaphoreTake(drdy_sem, portMAX_DELAY) == pdTRUE) {
            float p;
            if (rbamp_read_power(dev, 0, &p) == ESP_OK) {
                /* integrate + publish */
            }
        }
    }
}

void app_main(void) {
    /* ...rbamp_new + rbamp_begin... */

    drdy_sem = xSemaphoreCreateBinary();

    /* The ISR service is installed ONCE for the whole project — if another
     * component (LCD, encoder, anything) has already installed it,
     * gpio_install_isr_service() returns ESP_ERR_INVALID_STATE.
     * This is normal, do not fail on it. ESP_INTR_FLAG_IRAM keeps the
     * ISR dispatcher in IRAM — important for the single-core C3/C6/H2/S2,
     * where non-IRAM code is unavailable while the flash cache is disabled. */
    esp_err_t err = gpio_install_isr_service(ESP_INTR_FLAG_IRAM);
    if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
        ESP_ERROR_CHECK(err);
    }

    gpio_config_t io_cfg = {
        .pin_bit_mask = 1ULL << DRDY_GPIO,
        .mode         = GPIO_MODE_INPUT,
        .pull_up_en   = GPIO_PULLUP_ENABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type    = GPIO_INTR_NEGEDGE,
    };
    gpio_config(&io_cfg);
    gpio_isr_handler_add(DRDY_GPIO, drdy_isr_handler, NULL);

    /* Priority 6 — above idle (0), below WiFi (23) and the standard
     * MQTT (5+). 4096 bytes of stack are enough for rbamp_read_* +
     * ESP_LOG; if you add an MQTT publish right in this task —
     * raise it to 6144. On dual-core ESP32/S3, for a clean
     * separation from the WiFi task (usually core 0), you can pin
     * this task to core 1: xTaskCreatePinnedToCore(..., 1).
     * On the single-core C3/C6/H2/S2 — keep xTaskCreate. */
    xTaskCreate(bidir_task, "bidir", 4096, dev, 6, NULL);
}

DRDY ist optional — Polling mit jeder Rate ≤ 10 Hz funktioniert auch ohne. Die Komponente hängt in keinem ihrer Pfade von DRDY ab.

  • 05 · Schnellstart — Ihr erstes funktionierendes Projekt
  • 06 · Beispiele — funktionierende Szenarien (einschließlich des Mehrmodul-Busses)

  • 09 · API-Referenz — der Abschnitt „Kconfig symbols“ (Kconfig-Symbole) mit der detaillierten Konfiguration der I²C-Parameter

  • 10 · Fehlerbehebung — Diagnose auf Busebene, NACK-Muster, Disziplin bei Retry und Sanity


Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/04_hardware.md (v1.7.3)