VL53L0X 激光测距模块 接线与 STM32 实测

[platformio]

[env:bluepill_f103c8]
platform = ststm32
board = bluepill_f103c8
framework = arduino
upload_protocol = stlink
monitor_speed = 115200
lib_deps =
  adafruit/Adafruit SSD1306
  adafruit/Adafruit GFX Library
  pololu/VL53L0X

/*
 * ==================== FIRMWARE ====================
 * Project: 03_VL53L0X
 * Board: STM32F103C8T6 / BluePill
 * Firmware: VL53L0X v5 四屏动画版
 * Sensor: VL53L0X ToF 激光测距 (I2C 0x29)
 * Display: 0.96 OLED SSD1306 128x64 (I2C 0x3C)
 * Date: 2026-08-15
 *
 * v5 changes (animated 4-screen UI, on top of v4):
 * - marching dashed "signal" rays
 * - blinking warning triangle / off-screen arrow
 * - pulsing target ring
 *
 * Ranging/init code (I2C PB8/PB9, VL53L0X 0x29, OLED 0x3C, averaging,
 * cold-power recovery) is unchanged from v3.
 * ==================================================
 */

#include <Arduino.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <VL53L0X.h>
#include <Wire.h>

constexpr uint8_t OLED_ADDR = 0x3C;
constexpr uint8_t VL53L0X_ADDR = 0x29;
constexpr int SCREEN_WIDTH = 128;
constexpr int SCREEN_HEIGHT = 64;
constexpr char FW_VERSION[] = "VL53L0X v5";
constexpr uint16_t MIN_RANGE_MM = 30;      // below this -> TOO CLOSE
constexpr uint16_t MAX_RANGE_MM = 1200;    // above this -> OUT RANGE
constexpr uint8_t SAMPLE_N = 5;            // rolling-average window
constexpr uint16_t TIMEOUT_MS = 150;       // per-read timeout
constexpr uint8_t REINIT_THRESHOLD = 3;    // timeouts before re-init
constexpr uint8_t XSHUT_PIN = PB0;         // wire XSHUT here for a hard reset

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);
VL53L0X lox;

uint16_t g_samples[SAMPLE_N] = {0};
uint8_t g_sampleIdx = 0;
uint8_t g_sampleCount = 0;
uint8_t g_timeoutCount = 0;
uint16_t g_frame = 0;      // animation phase counter, incremented each loop

// ---------------- ranging helpers (unchanged) ----------------

bool i2cDeviceFound(uint8_t address) {
  Wire.beginTransmission(address);
  return Wire.endTransmission() == 0;
}

void pushSample(uint16_t v) {
  g_samples[g_sampleIdx] = v;
  g_sampleIdx = (g_sampleIdx + 1) % SAMPLE_N;
  if (g_sampleCount < SAMPLE_N) {
    g_sampleCount++;
  }
}

uint16_t averageSamples() {
  uint32_t sum = 0;
  for (uint8_t i = 0; i < g_sampleCount; i++) {
    sum += g_samples[i];
  }
  return static_cast<uint16_t>(sum / g_sampleCount);
}

void resetSamples() {
  g_sampleIdx = 0;
  g_sampleCount = 0;
}

void hardResetSensor() {
  pinMode(XSHUT_PIN, OUTPUT);
  digitalWrite(XSHUT_PIN, LOW);
  delay(10);
  digitalWrite(XSHUT_PIN, HIGH);
  delay(10);
}

bool initSensor() {
  hardResetSensor();
  if (!lox.init()) {
    return false;
  }
  lox.setTimeout(TIMEOUT_MS);
  lox.setMeasurementTimingBudget(33000);
  lox.startContinuous();

  uint16_t test = lox.readRangeContinuousMillimeters();
  return !lox.timeoutOccurred();
}

// ---------------- display helpers (new UI) ----------------

// Draw centered text using the built-in 6x8 font (6*size px per char).
void drawCentered(const char *s, int16_t y, uint8_t size) {
  display.setTextSize(size);
  int16_t w = static_cast<int16_t>(strlen(s)) * 6 * size;
  display.setCursor((SCREEN_WIDTH - w) / 2, y);
  display.print(s);
}

// Small "sensor" = filled lens + one emission ring.
void drawSensor(int16_t cx, int16_t cy) {
  display.fillCircle(cx, cy, 4, SSD1306_WHITE);
  display.drawCircle(cx, cy, 7, SSD1306_WHITE);
}

// Warning triangle with a "!" inside, centered at (cx, cy).
void drawWarning(int16_t cx, int16_t cy) {
  display.drawTriangle(cx, cy - 8, cx - 9, cy + 7, cx + 9, cy + 7, SSD1306_WHITE);
  display.drawLine(cx, cy - 4, cx, cy + 2, SSD1306_WHITE);
  display.drawPixel(cx, cy + 5, SSD1306_WHITE);
}

// Animated dashed line from x0 to x1 at height y.
void drawMarchingDash(int16_t x0, int16_t x1, int16_t y, uint8_t phase) {
  for (int16_t x = x0 - 8 + phase; x <= x1; x += 8) {
    int16_t e = x + 4;
    if (e > x1) {
      e = x1;
    }
    if (x >= x0) {
      display.drawLine(x, y, e, y, SSD1306_WHITE);
    }
  }
}

// Blink helper: true for `onFrames` frames of every `period` frames.
bool blinkOn(uint8_t period, uint8_t onFrames) {
  return (g_frame % period) < onFrames;
}

// Version label in the bottom-right corner.
void drawVersionLabel() {
  display.setTextSize(1);
  display.setCursor(116, 56);
  display.print("V5");
}

// 1. Normal distance: sensor -> target icon + big number + OK.
void showNormal(uint16_t mm) {
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  const int16_t y = 11;
  drawSensor(10, y);
  drawMarchingDash(22, 86, y, g_frame % 8);
  uint8_t ring = 8 + ((g_frame >> 3) & 1);
  display.drawCircle(100, y, ring, SSD1306_WHITE);
  display.drawCircle(100, y, 3, SSD1306_WHITE);

  uint8_t digits = (mm >= 1000) ? 4 : (mm >= 100) ? 3 : 2;
  display.setTextSize(3);
  int16_t numW = digits * 18;
  int16_t totalW = numW + 4 + 12;
  int16_t startX = (SCREEN_WIDTH - totalW) / 2;
  display.setCursor(startX, 22);
  display.print(mm);

  display.setTextSize(1);
  display.setCursor(startX + numW + 4, 36);
  display.print("mm");

  drawCentered("OK", 52, 1);
  drawVersionLabel();
  display.display();
}

// 2. Too close (< 30 mm): sensor + close object + warning.
void showTooClose() {
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  const int16_t y = 11;
  drawSensor(8, y);
  display.drawLine(20, y - 7, 20, y + 7, SSD1306_WHITE);
  if (blinkOn(8, 5)) {
    drawWarning(44, y);
  }

  drawCentered("TOO CLOSE", 26, 2);
  drawCentered("< 30 mm", 52, 1);
  drawVersionLabel();
  display.display();
}

// 3. Out of range (> 1200 mm / no target).
void showOutRange() {
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  const int16_t y = 11;
  drawSensor(8, y);
  drawMarchingDash(18, 96, y, g_frame % 8);
  if (blinkOn(8, 5)) {
    display.fillTriangle(106, y - 6, 106, y + 6, 118, y, SSD1306_WHITE);
  }

  drawCentered("OUT RANGE", 26, 2);
  drawCentered("> 1200 mm", 52, 1);
  drawVersionLabel();
  display.display();
}

// 4. Timeout: warning triangle + broken line + TIMEOUT / CHECK I2C.
void showTimeout() {
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  if (blinkOn(8, 5)) {
    drawWarning(64, 8);
  }

  int16_t lineY = 19;
  display.drawLine(12, lineY, 42, lineY, SSD1306_WHITE);
  int16_t xx = 52;
  if (blinkOn(4, 2)) {
    display.drawLine(xx - 3, lineY - 3, xx + 3, lineY + 3, SSD1306_WHITE);
    display.drawLine(xx - 3, lineY + 3, xx + 3, lineY - 3, SSD1306_WHITE);
  }
  display.drawLine(62, lineY, 90, lineY, SSD1306_WHITE);
  display.setCursor(96, lineY - 4);
  display.print("I2C");

  drawCentered("TIMEOUT", 30, 2);
  drawCentered("CHECK I2C", 52, 1);
  drawVersionLabel();
  display.display();
}

// Boot/status text screen (kept from v3).
void showStatus(const char *line1, const char *line2) {
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println(FW_VERSION);
  display.println();
  display.println(line1);
  display.println(line2);
  display.display();
}

// ---------------- setup / loop ----------------

void setup() {
  Serial.begin(115200);
  delay(300);

  Wire.setSCL(PB8);
  Wire.setSDA(PB9);
  Wire.begin();
  Wire.setClock(100000);

  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR)) {
    Serial.println("OLED init failed");
    while (true) {
      delay(1000);
    }
  }

  showStatus("OLED OK", "VL53L0X init...");
  Serial.println(FW_VERSION);

  Serial.print("OLED 0x3C: ");
  Serial.println(i2cDeviceFound(OLED_ADDR) ? "found" : "not found");
  Serial.print("VL53L0X 0x29: ");
  Serial.println(i2cDeviceFound(VL53L0X_ADDR) ? "found" : "not found");

  // Give the VL53L0X module's onboard regulator extra time to stabilize
  // after a cold power-on (BH1750/SHT30 don't need this — no regulator/laser).
  delay(500);

  if (!initSensor()) {
    Serial.println("VL53L0X warm-up failed, retrying...");
    delay(300);
    if (!initSensor()) {
      showStatus("VL53L0X failed", "Check wiring");
      Serial.println("VL53L0X init failed");
      while (true) {
        delay(1000);
      }
    }
  }

  // Re-init the OLED after the sensor's VCSEL calibration.
  delay(50);
  display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR);

  showStatus("VL53L0X ready", "PB8/PB9 I2C");
  Serial.println("VL53L0X ready");
}

void loop() {
  g_frame++;
  uint16_t mm = lox.readRangeContinuousMillimeters();

  if (lox.timeoutOccurred()) {
    resetSamples();
    g_timeoutCount++;
    if (g_timeoutCount >= REINIT_THRESHOLD) {
      g_timeoutCount = 0;
      initSensor();
    }
    showTimeout();
    Serial.println("timeout");
  } else if (mm < MIN_RANGE_MM) {
    g_timeoutCount = 0;
    resetSamples();
    showTooClose();
    Serial.println("too close");
  } else if (mm > MAX_RANGE_MM) {
    g_timeoutCount = 0;
    resetSamples();
    showOutRange();
    Serial.println("out of range");
  } else {
    g_timeoutCount = 0;
    pushSample(mm);
    uint16_t avg = averageSamples();
    showNormal(avg);
    Serial.print("distance: ");
    Serial.print(avg);
    Serial.println(" mm");
  }

  delay(50);
}