intial test version

examples/BasicRead/platformio.ini

@@ -0,0 +1,19 @@
+[env]
+lib_extra_dirs = ../..
+
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+monitor_speed = 115200
+monitor_filters = esp32_exception_decoder
+
+[env:esp32-s3]
+platform = espressif32
+board = esp32-s3-devkitc-1
+framework = arduino
+monitor_speed = 115200
+monitor_filters = esp32_exception_decoder
+build_flags =
+    -D ARDUINO_USB_MODE=1
+    -D ARDUINO_USB_CDC_ON_BOOT=1

examples/BasicRead/src/main.cpp

@@ -0,0 +1,76 @@
+/**
+ * BluettiBLE Basic Read Example
+ *
+ * Connects to a single Bluetti power station and prints its values every poll
+ * cycle.
+ *
+ * Setup:
+ * 1. Find your device's BLE advertised name with a BLE scanner app
+ *    (e.g. "AC3001234567890").
+ * 2. Set the name and model below.
+ */
+
+#include <Arduino.h>
+#include "BluettiBLE.h"
+
+BluettiBLE bluetti;
+
+void onBluettiData(const BluettiDevice* dev) {
+    const BluettiData& d = dev->data;
+
+    Serial.printf("\n=== %s (%s) ===\n", dev->name, d.model[0] ? d.model : "?");
+    Serial.printf("Serial: %llu\n", d.serialNumber);
+    Serial.printf("Firmware: ARM %.2f / DSP %.2f\n", d.armVersion, d.dspVersion);
+    Serial.printf("State of charge: %u %%\n", d.totalBatteryPercent);
+    Serial.printf("AC output: %u W (%s)\n", d.acOutputPower, d.acOutputOn ? "ON" : "off");
+    Serial.printf("DC output: %u W (%s)\n", d.dcOutputPower, d.dcOutputOn ? "ON" : "off");
+    Serial.printf("AC input:  %u W   DC input: %u W\n", d.acInputPower, d.dcInputPower);
+    Serial.printf("Generation total: %.1f kWh\n", d.powerGeneration);
+
+    if (d.acInputVoltage > 0)
+        Serial.printf("AC in: %.1f V @ %.2f Hz\n", d.acInputVoltage, d.acInputFrequency);
+    if (d.internalDcInputVoltage > 0)
+        Serial.printf("DC in: %.1f V  %.1f A\n", d.internalDcInputVoltage, d.internalDcInputCurrent);
+    if (d.packNumMax > 0)
+        Serial.printf("Battery packs: %u (pack #%u %.1f V %u%%)\n",
+                      d.packNumMax, d.packNum, d.packVoltage, d.packBatteryPercent);
+
+    bool anyCell = false;
+    for (int i = 0; i < BLUETTI_CELLS; i++) if (d.cellVoltage[i] > 0) anyCell = true;
+    if (anyCell) {
+        Serial.print("Cells: ");
+        for (int i = 0; i < BLUETTI_CELLS; i++)
+            if (d.cellVoltage[i] > 0) Serial.printf("%.2f ", d.cellVoltage[i]);
+        Serial.println();
+    }
+
+    Serial.printf("RSSI: %d dBm  (updated %lus ago)\n",
+                  dev->rssi, (millis() - dev->lastUpdate) / 1000);
+}
+
+void setup() {
+    Serial.begin(115200);
+    delay(1000);
+
+    Serial.println("\n\n=============================");
+    Serial.println("BluettiBLE Basic Read Example");
+    Serial.println("=============================\n");
+
+    if (!bluetti.begin()) {
+        Serial.println("ERROR: failed to initialise BluettiBLE!");
+        while (1) delay(1000);
+    }
+
+    bluetti.setDebug(true);
+    bluetti.setCallback(onBluettiData);
+
+    // CHANGE THESE: your device's advertised BLE name and model.
+    // bluetti.addDevice("My Bluetti", "AC3001234567890", BLUETTI_AC300);
+    bluetti.addDevice("My Bluetti", "EL3002546110146262", BLUETTI_AC300);
+
+    Serial.printf("Configured %d device(s). Scanning...\n", (int)bluetti.getDeviceCount());
+}
+
+void loop() {
+    bluetti.loop();
+}

examples/Control/platformio.ini

@@ -0,0 +1,19 @@
+[env]
+lib_extra_dirs = ../..
+
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+monitor_speed = 115200
+monitor_filters = esp32_exception_decoder
+
+[env:esp32-s3]
+platform = espressif32
+board = esp32-s3-devkitc-1
+framework = arduino
+monitor_speed = 115200
+monitor_filters = esp32_exception_decoder
+build_flags =
+    -D ARDUINO_USB_MODE=1
+    -D ARDUINO_USB_CDC_ON_BOOT=1

examples/Control/src/main.cpp

@@ -0,0 +1,54 @@
+/**
+ * BluettiBLE Control Example
+ *
+ * Reads the device and toggles the AC output on/off every 30 seconds to show how
+ * to send control commands. DC output toggling works the same way via
+ * setDCOutput().
+ *
+ * WARNING: this actively switches your inverter output. Only run it when it is
+ * safe to power-cycle whatever is plugged in.
+ */
+
+#include <Arduino.h>
+#include "BluettiBLE.h"
+
+BluettiBLE bluetti;
+
+static uint32_t lastToggle = 0;
+static bool desiredAC = true;
+
+void onBluettiData(const BluettiDevice* dev) {
+    const BluettiData& d = dev->data;
+    Serial.printf("[%s] SoC %u%%  AC out %u W (%s)  DC out %u W (%s)\n",
+                  d.model, d.totalBatteryPercent,
+                  d.acOutputPower, d.acOutputOn ? "ON" : "off",
+                  d.dcOutputPower, d.dcOutputOn ? "ON" : "off");
+}
+
+void setup() {
+    Serial.begin(115200);
+    delay(1000);
+
+    Serial.println("\nBluettiBLE Control Example\n");
+
+    bluetti.begin();
+    bluetti.setDebug(true);
+    bluetti.setCallback(onBluettiData);
+
+    // CHANGE THESE: your device's advertised BLE name and model.
+    bluetti.addDevice("My Bluetti", "AC3001234567890", BLUETTI_AC300);
+}
+
+void loop() {
+    bluetti.loop();
+
+    if (bluetti.isConnected() && millis() - lastToggle > 30000) {
+        Serial.printf(">> setting AC output %s\n", desiredAC ? "ON" : "OFF");
+        if (bluetti.setACOutput(desiredAC))
+            Serial.println("   command sent");
+        else
+            Serial.println("   command not supported / not connected");
+        desiredAC = !desiredAC;
+        lastToggle = millis();
+    }
+}

examples/Logger/platformio.ini

@@ -0,0 +1,19 @@
+[env]
+lib_extra_dirs = ../..
+
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+monitor_speed = 115200
+monitor_filters = time, esp32_exception_decoder
+
+[env:esp32-s3]
+platform = espressif32
+board = esp32-s3-devkitc-1
+framework = arduino
+monitor_speed = 115200
+monitor_filters = time, esp32_exception_decoder
+build_flags =
+    -D ARDUINO_USB_MODE=1
+    -D ARDUINO_USB_CDC_ON_BOOT=1

examples/Logger/src/main.cpp

@@ -0,0 +1,69 @@
+/**
+ * BluettiBLE Logger Example
+ *
+ * Prints a line only when a value of interest changes, rather than every poll
+ * cycle. Demonstrates the snapshot / change-detection pattern.
+ */
+
+#include <Arduino.h>
+#include "BluettiBLE.h"
+
+BluettiBLE bluetti;
+
+// Last-seen snapshot of the fields we care about.
+struct Snapshot {
+    bool     valid = false;
+    uint8_t  soc = 0;
+    uint16_t acOut = 0;
+    uint16_t dcOut = 0;
+    bool     acOn = false;
+    bool     dcOn = false;
+    uint32_t packetsSinceLog = 0;
+};
+
+static Snapshot prev;
+
+void onBluettiData(const BluettiDevice* dev) {
+    const BluettiData& d = dev->data;
+    prev.packetsSinceLog++;
+
+    bool changed = !prev.valid ||
+                   prev.soc   != d.totalBatteryPercent ||
+                   prev.acOut != d.acOutputPower ||
+                   prev.dcOut != d.dcOutputPower ||
+                   prev.acOn  != d.acOutputOn ||
+                   prev.dcOn  != d.dcOutputOn;
+
+    if (!changed) return;
+
+    Serial.printf("CHANGE (%lu polls): SoC %u%%  AC %u W (%s)  DC %u W (%s)\n",
+                  prev.packetsSinceLog,
+                  d.totalBatteryPercent,
+                  d.acOutputPower, d.acOutputOn ? "ON" : "off",
+                  d.dcOutputPower, d.dcOutputOn ? "ON" : "off");
+
+    prev.valid = true;
+    prev.soc   = d.totalBatteryPercent;
+    prev.acOut = d.acOutputPower;
+    prev.dcOut = d.dcOutputPower;
+    prev.acOn  = d.acOutputOn;
+    prev.dcOn  = d.dcOutputOn;
+    prev.packetsSinceLog = 0;
+}
+
+void setup() {
+    Serial.begin(115200);
+    delay(1000);
+
+    Serial.println("\nBluettiBLE Logger Example\n");
+
+    bluetti.begin();
+    bluetti.setCallback(onBluettiData);
+
+    // CHANGE THESE: your device's advertised BLE name and model.
+    bluetti.addDevice("My Bluetti", "AC3001234567890", BLUETTI_AC300);
+}
+
+void loop() {
+    bluetti.loop();
+}