Ranger 8-Way × Arduino Examples

Back to Ranger 8-Way Home　|　MBC Universal I2C Protocol (advanced)

This page has 11 product examples (5 of them use commands) + 3 shared examples, from "is it connected?" all the way to an "obstacle-avoiding car". You can copy and upload each example as it is, and every line of the code has an English comment. Never written code before? No problem. Just do them one by one, in order.

Tip

First time using Arduino? Read 🔰 First Time with Arduino: Start from Zero first. In 15 minutes you learn how to install the software, upload a program and see the result.

Wiring (the same for every example)

Figure: /images/figures/tof8/wiring-uno.svg

Important

• Use the universal I2C edition of the Ranger 8-Way. The SPIKE and EV3 editions have different firmware and cannot connect to Arduino directly.
• After power-on, the sensor needs 2 ~ 4 seconds to wake up the 8 lasers one by one. Before it is ready every distance is 0, which looks like an obstacle right in front of it. That is why every example first waits for F3 ready (at most 6 s). Do the same in your own programs.
• Unplug the USB cable before you connect the wires.

Where do the 8 lasers look? (the sensor is mounted at the front of the robot, and you stand behind the robot looking forward)

Command Overview (protocol v2)

Think of the sensor as a row of numbered "boxes". Each box holds one 16-bit number (int16, little-endian). To read: write [number] → wait 2 ms → read 2×k bytes, and you get k boxes in a row starting from that number (k ≤ 16). A number that does not exist returns -32768. The house number (I2C address) is 0x29.

Change the settings with commands (E0 ~ E4)

Tip

Tested on an Arduino Nano (2026-11-02): every command E0 ~ E4 changed the setting as expected on the universal I2C edition and read back correctly; out-of-range parameters were clamped or ignored as described below.

How to send one: write two bytes [command][parameter] (mbcCommand(0xE0, 1) in the examples). E0, E2 and E3 re-configure the laser chips, which takes about 0.1 ~ 0.5 s; during that time bit2 (busy) of the status flags F3 is 1, so wait until it is 0 before reading. E1 and E4 take effect at once. To see the current settings, read 20 ~ 23.

• Out-of-range parameters are clamped: for example E2 5 becomes 20, E2 250 becomes 200, E4 250 becomes 120 in normal mode (200 in long range). Unknown parameters are ignored: E0 9, E1 3, E3 without A5 do nothing and cause no error.
• Changing the mode (E0) resets the timing budget and the max distance: to use E2 / E4 as well, send E0 first.
• Settings are kept only in the sensor's memory: after a power cut or a reboot they are back to factory (normal mode, limit 120 cm), so send them again every time the program starts.
• "Nothing" reads as the limit: 120 in normal mode, 200 in long-range mode, or the limit you set with E4.
• The EV3 and MATRIX editions have no commands (read only).

All Examples

Tip

Suggested order: 1 → 2 → 3 → 4 → 5 → 6; to change the settings, go on with 7 ~ 11. First check the wiring (1) and get to know every box (2). Then learn the directions (3, 4) and the applications.

1️⃣ Say hello to the sensor

What it does: Checks that the sensor is connected and reads its ID card: F0 device ID (factory address + laser count), F1 protocol version, F2 firmware version, and F3 status flags printed bit by bit in plain English. Then it uses the 07 init bitmap to list whether all 8 lasers booted OK. Run this one first every time you connect a new sensor.

Steps:

1. Connect the 4 wires as in the table above, then plug the USB cable into the computer.
2. Copy the code below, paste it into the Arduino IDE and click → Upload.
3. Open the Serial Monitor (the magnifying glass at the top right) and choose 115200 baud.

Download tof8_01_hello.ino

/*
 * Ranger 8-Way × Arduino   Example 1: Say hello to the sensor
 * ------------------------------------------------------------
 * What does this example do?
 *   Checks that the sensor is connected. If it is, it prints the sensor's ID card
 *   (device ID, protocol version, firmware version) and its current status
 *   (are all 8 lasers working?).
 *   Run this example first every time you connect a new sensor.
 *
 * You need: Ranger 8-Way (universal I2C edition), Arduino UNO / Nano / UNO R4 or ESP32.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   After uploading, open the Serial Monitor and choose 115200 baud.
 *
 * Note:
 *   Waking up the 8 lasers one by one takes 2~4 s. Before the sensor is ready every distance is 0, so always wait for F3 bit0 first.
 */

#include <Wire.h>                        // Arduino's built-in I2C tool, used to talk to the sensor

const uint8_t ADDR = 0x29;               // The sensor's "house number" (I2C address). Both 2-Way and 8-Way use 0x29
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

// Helper declaration (the code is at the bottom of the file); mbcWrite's parameters can be left out
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);

void setup() {
  Serial.begin(115200);                  // Open the channel to the computer at 115200 baud
  mbcBegin();                            // Get I2C ready (helper at the bottom of the file)
  delay(500);                            // Wait 0.5 s for the sensor to boot

  Serial.println(F("=== Ranger 8-Way: Say hello to the sensor ==="));
  Serial.println(F("Waiting for the 8 lasers to boot (at most 6 s)..."));

  // Wait for the sensor to say "I'm ready" (bit0 of status flags F3 = all 8 lasers initialized), at most 6 s
  if (!mbcWaitReady(ADDR, 6000)) {
    Serial.println(F("Sensor not found! Please check:"));
    Serial.println(F("  1. SDA to A4, SCL to A5 (ESP32: 21 / 22). Are they swapped?"));
    Serial.println(F("  2. VCC to 5V, GND to GND. Are they plugged in firmly?"));
    Serial.println(F("  3. Is your sensor the universal I2C edition? (SPIKE and EV3 editions do not work with Arduino)"));
    while (true) {}                      // Not found: stop here
  }

  // ---- F0 device ID: low byte = factory address, high byte = number of lasers ----
  int16_t id = mbcRead(ADDR, 0xF0);
  uint8_t factoryAddr = (uint8_t)(id & 0xFF);        // Factory address (stays the same even if the address was changed)
  uint8_t sensors     = (uint8_t)((id >> 8) & 0xFF); // hw[0] = how many lasers
  Serial.print(F("Found it! Factory address 0x"));
  Serial.print(factoryAddr, HEX);
  Serial.print(F(", "));
  Serial.print(sensors);                 // Ranger 8-Way = 8
  Serial.println(F(" lasers"));

  // ---- F1 protocol version (this example is written for version 2) ----
  Serial.print(F("Protocol version: "));
  Serial.println(mbcRead(ADDR, 0xF1));

  // ---- F2 firmware version: major×100 + minor (e.g. 102 = 1.2) ----
  int16_t fw = mbcRead(ADDR, 0xF2);
  Serial.print(F("Firmware version: "));
  Serial.print(fw / 100);
  Serial.print('.');
  Serial.println(fw % 100);

  // ---- F3 status flags: each bit means one thing ----
  int16_t st = mbcRead(ADDR, 0xF3);
  Serial.println(F("Current status:"));
  Serial.print(F("  bit0 ready            ")); Serial.println((st & 0x01) ? F("yes (all 8 lasers initialized)") : F("no"));
  Serial.print(F("  bit1 any laser failed ")); Serial.println((st & 0x02) ? F("yes! (run Example 2 to see which one)") : F("no (all 8 lasers OK)"));

  // ---- 07 init bitmap: bit0 = laser 1 (far left) ... bit7 = laser 8 ----
  int16_t initOk = mbcRead(ADDR, 0x07);
  Serial.print(F("Lasers that booted OK (left→right): "));
  for (uint8_t i = 0; i < 8; i++) Serial.print((initOk >> i) & 1 ? 'O' : 'X');
  Serial.println(initOk == 255 ? F("  all OK") : F("  a laser marked X failed to boot, please power off and on"));

  // ---- F5 seconds since boot ----
  Serial.print(F("Seconds since boot: "));
  Serial.println(mbcRead(ADDR, 0xF5));

  Serial.println(F("Wiring is correct. You can try the other examples now!"));
}

void loop() {
  // This example only checks once at startup, so loop does nothing
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see:

=== Ranger 8-Way: Say hello to the sensor ===
Waiting for the 8 lasers to boot (at most 6 s)...
Found it! Factory address 0x29, 8 lasers
Protocol version: 2
Firmware version: 2.0
Current status:
  bit0 ready            yes (all 8 lasers initialized)
  bit1 any laser failed no (all 8 lasers OK)
Lasers that booted OK (left→right): OOOOOOOO  all OK
Seconds since boot: 6
Wiring is correct. You can try the other examples now!

Note

What are the "Communication helpers"? At the bottom of every example there is the same piece of code. It "talks" to the sensor. You don't need to change it or understand it. Just remember:

• mbcRead(address, number): read one box; returns MBC_NONE (−32768) if it cannot be read
• mbcReadMany(address, first number, how many, array): read several boxes in a row starting from the first number (at most 16), all from the same moment
• mbcWrite(address, command, parameters, how many parameters): send a command; the last two can be left out when there are no parameters
• mbcWaitReady(address, max wait in ms): wait for F3 bit0 "ready"

2️⃣ See all the values at once

What it does: Prints the whole value table every 0.5 s, in three mbcReadMany parts: 01 ~ 09, 10 ~ 17 (8 lasers in cm), 18 ~ 1F (8 lasers in mm). Get to know every box here first; the later examples only pick a few of them.

Download tof8_02_all_values.ino

/*
 * Ranger 8-Way × Arduino   Example 2: See all the values at once
 * ------------------------------------------------------------
 * What does this example do?
 *   Prints the sensor's "whole value table" every 0.5 s:
 *     01 nearest cm, 02 nearest direction, 03 most open cm, 04 most open direction, 05 front cm,
 *     06 nearest mm, 07 init bitmap, 08 fault bitmap, 09 front mm,
 *     10~17 lasers 1~8 in cm, 18~1F lasers 1~8 in mm.
 *   The later examples only pick a few of these boxes. Get to know every box here first.
 *
 * You need: Ranger 8-Way (universal I2C edition) + your hand or a few books.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200. Move your hand slowly from left to right and watch the numbers move from laser 1 to laser 8.
 *
 * Note:
 *   At most 16 values can be read at a time, so we read in three parts: 01~09, 10~17, 18~1F.
 *   120 cm / 1200 mm = nothing in that direction (or that laser failed).
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);

void setup() {
  Serial.begin(115200);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 6000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  Serial.println(F("Ready! Move your hand in front of the sensor."));
}

void loop() {
  int16_t a[9];                          // 01~09
  int16_t cm[8];                         // 10~17 lasers 1~8 in cm
  int16_t mm[8];                         // 18~1F lasers 1~8 in mm
  if (!mbcReadMany(ADDR, 0x01, 9, a))  { Serial.println(F("Cannot read (01~09)")); delay(500); return; }
  if (!mbcReadMany(ADDR, 0x10, 8, cm)) { Serial.println(F("Cannot read (10~17)")); delay(500); return; }
  if (!mbcReadMany(ADDR, 0x18, 8, mm)) { Serial.println(F("Cannot read (18~1F)")); delay(500); return; }

  Serial.println(F("---------------------------------------"));
  Serial.print(F("01 nearest distance     ")); Serial.print(a[0]); Serial.println(F(" cm   (smallest of the 8; 120 = nothing around)"));
  Serial.print(F("02 nearest direction    ")); Serial.print(a[1]); Serial.println(F("      (-7 far left ~ +7 far right, 0 = straight ahead; ±8 = nothing)"));
  Serial.print(F("03 most open distance   ")); Serial.print(a[2]); Serial.println(F(" cm   (largest of the 8)"));
  Serial.print(F("04 most open direction  ")); Serial.print(a[3]); Serial.println(F("      (-7 ~ +7)"));
  Serial.print(F("05 front distance       ")); Serial.print(a[4]); Serial.println(F(" cm   (average of lasers 4 and 5)"));
  Serial.print(F("06 nearest distance     ")); Serial.print(a[5]); Serial.println(F(" mm   (10 times finer than cm)"));
  Serial.print(F("07 init bitmap          "));
  for (uint8_t i = 0; i < 8; i++) Serial.print((a[6] >> i) & 1);     // bit0 (laser 1) is printed on the left
  Serial.println(F("  (left→right, 1 = booted OK)"));
  Serial.print(F("08 fault bitmap         "));
  for (uint8_t i = 0; i < 8; i++) Serial.print((a[7] >> i) & 1);
  Serial.println(F("  (left→right, 1 = that laser has failed)"));
  Serial.print(F("09 front distance       ")); Serial.print(a[8]); Serial.println(F(" mm"));

  Serial.print(F("10~17 each laser cm  L "));
  for (uint8_t i = 0; i < 8; i++) { printPad(cm[i], 4); Serial.print(' '); }
  Serial.println(F(" R"));
  Serial.print(F("18~1F each laser mm  L "));
  for (uint8_t i = 0; i < 8; i++) { printPad(mm[i], 4); Serial.print(' '); }
  Serial.println(F(" R   (laser 1 = left 90°, lasers 4/5 = straight ahead, laser 8 = right 90°)"));

  delay(50);
  delay(450);                            // Update every 0.5 s
}

// Print a number right-aligned (width w)
void printPad(int16_t v, uint8_t w) {
  uint8_t len = (v < 0) ? 2 : 1;
  for (int16_t t = (v < 0 ? -v : v); t >= 10; t /= 10) len++;
  for (uint8_t i = len; i < w; i++) Serial.print(' ');
  Serial.print(v);
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see: (your hand at the front left, 30 cm away)

---------------------------------------
01 nearest distance     30 cm   (smallest of the 8; 120 = nothing around)
02 nearest direction    -3      (-7 far left ~ +7 far right, 0 = straight ahead; ±8 = nothing)
03 most open distance   120 cm   (largest of the 8)
04 most open direction  5      (-7 ~ +7)
05 front distance       120 cm   (average of lasers 4 and 5)
06 nearest distance     304 mm   (10 times finer than cm)
07 init bitmap          11111111  (left→right, 1 = booted OK)
08 fault bitmap         00000000  (left→right, 1 = that laser has failed)
09 front distance       1200 mm
10~17 each laser cm  L  120  120   30  120  120  120  120  120  R
18~1F each laser mm  L 1200 1200  304 1200 1200 1200 1200 1200  R   (laser 1 = left 90°, lasers 4/5 = straight ahead, laser 8 = right 90°)

Tip

Try it: Move your hand slowly from left to right and watch how the numbers "walk" from laser 1 to laser 8. Lasers 4 and 5 both look straight ahead, so when your hand is right in front, their two numbers will be very close.

3️⃣ Which direction is the nearest object?

What it does: The sensor compares its 8 lasers by itself: 01 nearest distance in cm, 02 nearest direction, 06 nearest distance in mm. The computer draws a small ruler with * at that direction, then says it with an arrow. A sumo robot uses this to "find the opponent".

You need: A box or your hand.

Download tof8_03_nearest_direction.ino

/*
 * Ranger 8-Way × Arduino   Example 3: Which direction is the nearest object?
 * ------------------------------------------------------------
 * What does this example do?
 *   The sensor compares its 8 lasers by itself and tells you which direction the nearest object is in, and how far:
 *     01 nearest distance cm, 02 nearest direction (-7 far left ~ +7 far right, 0 = straight ahead), 06 nearest distance mm.
 *   The computer draws a small ruler with * at that direction, then says it with an arrow. A sumo robot uses this to "find the opponent".
 *
 * You need: Ranger 8-Way (universal I2C edition) + a box or your hand.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200. Move your hand from the front left to straight ahead, then to the right.
 *
 * Note:
 *   When there is nothing within 120 cm, the direction becomes ±8 (meaning "which side it was on last time"), not a real object.
 *   So always look at the distance first, then the direction.
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);

void setup() {
  Serial.begin(115200);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 6000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  Serial.println(F("Ready! Move an object around the sensor."));
}

void loop() {
  int16_t v[6];                          // 01 nearest cm, 02 nearest direction, 03, 04, 05, 06 nearest mm
  if (!mbcReadMany(ADDR, 0x01, 6, v)) { Serial.println(F("Cannot read the sensor")); delay(500); return; }
  int16_t nearCm = v[0], dir = v[1], nearMm = v[5];

  // Draw a small ruler with 15 cells: one cell for each direction -7 ~ +7, * = nearest object, + = straight ahead
  Serial.print(F("L ["));
  for (int8_t i = -7; i <= 7; i++) {
    if (nearCm < 120 && i == dir) Serial.print('*');
    else if (i == 0)              Serial.print('+');
    else                          Serial.print('.');
  }
  Serial.print(F("] R   "));

  if (nearCm >= 120) {                   // Look at the distance first! When there is nothing, the direction is ±8 and cannot be trusted
    Serial.println(F("Nothing within 120 cm ahead"));
  } else {
    if      (dir <= -6) Serial.print(F("← left       "));
    else if (dir <= -2) Serial.print(F("↖ front left "));
    else if (dir <=  1) Serial.print(F("↑ ahead      "));
    else if (dir <=  5) Serial.print(F("↗ front right"));
    else                Serial.print(F("→ right      "));
    Serial.print(' '); Serial.print(nearCm); Serial.print(F(" cm ("));
    Serial.print(nearMm); Serial.print(F(" mm, direction ")); Serial.print(dir); Serial.println(')');
  }
  delay(50);
  delay(150);                            // Print one line every 0.2 s   👉 You can change this
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see: (moving your hand from the front left to straight ahead, then to the right)

L [.......+.......] R   Nothing within 120 cm ahead
L [..*....+.......] R   ↖ front left  35 cm (352 mm, direction -5)
L [.......*.......] R   ↑ ahead       28 cm (283 mm, direction 0)
L [.......+.....*.] R   → right       40 cm (401 mm, direction 6)

What does the direction mean?

Warning

Always look at the distance first, then the direction. When there is nothing within 120 cm, the direction is ±8, and there is no real object there. The example first checks "distance < 120" to make sure there is something, and only then looks at the direction.

4️⃣ Which side is most open?

What it does: Reads 03 most open distance and 04 most open direction. The sensor finds the direction among the 8 that is farthest (most empty) for you. In a maze or when avoiding obstacles, use these two boxes to "go where it is most open". It also prints 01 / 02 (the nearest), so you can compare "where to avoid" and "where to go".

You need: A few books as walls.

Download tof8_04_open_direction.ino

/*
 * Ranger 8-Way × Arduino   Example 4: Which side is most open?
 * ------------------------------------------------------------
 * What does this example do?
 *   Reads "03 most open distance cm" and "04 most open direction": the sensor finds the direction
 *   among the 8 that is farthest (most empty) for you. In a maze or when avoiding obstacles, use these two boxes to "go where it is most open".
 *   It also reads 01/02 (the nearest) and prints both, so you can compare "where to avoid" and "where to go".
 *
 * You need: Ranger 8-Way (universal I2C edition) + a few books as walls.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200. Use books to build different "walls" on the left, right and front of the sensor.
 *
 * Note:
 *   A failed laser always reads 120, so it looks like the "most open" direction. Run Example 1 before a match to check that all 8 lasers are OK.
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);

void setup() {
  Serial.begin(115200);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 6000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  Serial.println(F("Ready! Build a few walls with books next to the sensor."));
}

void loop() {
  int16_t v[4];                          // 01 nearest cm, 02 nearest direction, 03 most open cm, 04 most open direction
  if (!mbcReadMany(ADDR, 0x01, 4, v)) { Serial.println(F("Cannot read the sensor")); delay(500); return; }
  int16_t nearCm = v[0], nearDir = v[1], farCm = v[2], farDir = v[3];

  Serial.print(F("Most open → "));
  printDir(farDir);
  Serial.print(' '); Serial.print(farCm); Serial.print(F(" cm"));

  Serial.print(F("   |   Nearest → "));
  if (nearCm >= 120) Serial.println(F("nothing within 120 cm around"));
  else {
    printDir(nearDir);
    Serial.print(' '); Serial.print(nearCm); Serial.println(F(" cm"));
  }
  delay(50);
  delay(250);                            // Print one line every 0.3 s   👉 You can change this
}

// Print a direction -7 ~ +7 as words (each step ≈ 13°, ±7 ≈ ±90°)
void printDir(int16_t dir) {
  if      (dir <= -6) Serial.print(F("left"));
  else if (dir <= -2) Serial.print(F("front left"));
  else if (dir <=  1) Serial.print(F("ahead"));
  else if (dir <=  5) Serial.print(F("front right"));
  else                Serial.print(F("right"));
  Serial.print(F("(")); Serial.print(dir); Serial.print(')');
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see: (books on the left and in front, nothing on the right)

Most open → right(7) 120 cm   |   Nearest → ahead(0) 18 cm
Most open → front right(4) 95 cm   |   Nearest → front left(-4) 22 cm

Tip

A failed laser always reads 120, so it looks like the "most open" direction. Run Example 1 before a match to check that all 8 lasers are OK.

5️⃣ Radar bar chart

What it does: Reads 10 ~ 17 (8 lasers in cm) in one go and draws them as 8 bars: a longer bar = that direction is more open, a very short bar = something is blocking it. It also reads the 08 fault bitmap and marks a failed laser with XX. One look tells you where you can go.

You need: A few books as obstacles.

Download tof8_05_radar_bars.ino

/*
 * Ranger 8-Way × Arduino   Example 5: Radar bar chart
 * ------------------------------------------------------------
 * What does this example do?
 *   Reads "10~17 lasers 1~8 distance cm" in one go and draws the 8 directions as 8 bars:
 *   a longer bar = that direction is more open, a very short bar = something is blocking it. One look tells you where you can go.
 *   It also reads "08 fault bitmap" and marks a failed laser with XX.
 *
 * You need: Ranger 8-Way (universal I2C edition) + a few books as obstacles.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200.
 *
 * Where do the 8 lasers look? (standing behind the robot, looking forward)
 *   Laser 1 left 90°, laser 2 left 60°, laser 3 left 30°, lasers 4 and 5 straight ahead,
 *   laser 6 right 30°, laser 7 right 60°, laser 8 right 90°
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);

const int8_t ANGLE[8] = {-90, -60, -30, 0, 0, 30, 60, 90};   // Angle of each laser (negative = left)

void setup() {
  Serial.begin(115200);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 6000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  Serial.println(F("Ready! Put a few books next to the sensor."));
}

void loop() {
  int16_t cm[8];
  int16_t fault = mbcRead(ADDR, 0x08);   // 08 fault bitmap: bit0 = laser 1
  if (!mbcReadMany(ADDR, 0x10, 8, cm) || fault == MBC_NONE) { Serial.println(F("Cannot read the sensor")); delay(500); return; }

  Serial.println(F("====== Radar view (longer bar = more open) ======"));
  for (uint8_t i = 0; i < 8; i++) {
    Serial.print(i + 1);                 // Laser number (1~8)
    Serial.print(' ');
    if (ANGLE[i] >= 0) Serial.print('+');
    if (ANGLE[i] > -10 && ANGLE[i] < 10) Serial.print(' ');
    Serial.print(ANGLE[i]); Serial.print(F("° |"));

    if ((fault >> i) & 1) {              // This laser failed
      Serial.println(F("XX fault"));
      continue;
    }
    int8_t n = cm[i] / 5;                // One cell per 5 cm, at most 24 cells
    if (n > 24) n = 24;
    for (int8_t k = 0; k < n; k++) Serial.print('#');
    if (cm[i] >= 120) Serial.println(F("> nothing"));
    else { Serial.print(' '); Serial.print(cm[i]); Serial.println(F(" cm")); }
  }
  delay(50);
  delay(450);                            // Redraw every 0.5 s   👉 You can change this
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see: (a book 30 cm straight ahead)

====== Radar view (longer bar = more open) ======
1 -90° |########################> nothing
2 -60° |########################> nothing
3 -30° |############### 75 cm
4 + 0° |###### 32 cm
5 + 0° |###### 34 cm
6 +30° |################ 80 cm
7 +60° |###################### 110 cm
8 +90° |########################> nothing

6️⃣ Obstacle-avoiding car (advanced)

What it does: Makes a two-wheel car drive around obstacles by itself: while 05 front distance (cm) is still far, go straight; when something is ahead, look at 02 nearest direction and turn right if the object is on the left, left if it is on the right; when 09 front distance (mm) is too close, back up first. One mbcReadMany reads 01 to 09, so every decision uses data from the same moment.

You also need: A two-wheel car, an L298N motor driver board (or a TB6612 wired the same way), a battery.

Motor wiring:

Before the first run: Lift the car (wheels in the air) and upload. Check that both wheels turn forward. If a wheel turns the wrong way, change LEFT_REVERSE or RIGHT_REVERSE to true.

Download tof8_06_avoid_car.ino

/*
 * Ranger 8-Way × Arduino   Example 6 (advanced): Obstacle-avoiding car
 * ------------------------------------------------------------
 * What does this example do?
 *   Makes a two-wheel car drive around obstacles by itself:
 *     - "05 front cm" is still far → go straight
 *     - Something ahead → look at "02 nearest direction": object on the left → turn right, on the right → turn left
 *     - "09 front mm" too close (about to crash) → back up a little first, then turn
 *   mbcReadMany reads 01 to 09 in one go, so every decision uses data from the same moment.
 *
 * You need: A two-wheel car, an L298N motor driver board (or a TB6612 etc. wired the same way), a battery.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *   L298N ENA → 5     IN1 → 7     IN2 → 8      (left wheel)
 *   L298N ENB → 6     IN3 → 9     IN4 → 10     (right wheel)
 *   (ESP32 instead: ENA → 25, IN1 → 26, IN2 → 27, ENB → 14, IN3 → 32, IN4 → 33)
 *   The L298N GND must be connected to the Arduino GND! Mount the sensor at the front center of the car, lasers facing forward.
 *
 * Before the first run:
 *   Lift the car (wheels in the air), upload, and check that both wheels turn "forward".
 *   If a wheel turns the wrong way, change LEFT_REVERSE or RIGHT_REVERSE to true.
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);

// ---- Motor pins ----
#if defined(ESP32)
const int ENA = 25, IN1 = 26, IN2 = 27;  // Left wheel (pins 6~11 cannot be used on ESP32)
const int ENB = 14, IN3 = 32, IN4 = 33;  // Right wheel
#else
const int ENA = 5, IN1 = 7, IN2 = 8;     // Left wheel
const int ENB = 6, IN3 = 9, IN4 = 10;    // Right wheel
#endif

// ---- 👉 Settings you can change ----
const int     SPEED      = 130;          // Straight-line speed 0~255
const int     TURN_SPEED = 110;          // Turning speed
const int16_t TURN_CM    = 35;           // Turn when something is within this many cm ahead
const int16_t BACK_MM    = 120;          // Back up first when something is within this many mm ahead
const bool    LEFT_REVERSE  = false;     // Change to true if the left wheel turns the wrong way
const bool    RIGHT_REVERSE = false;     // Change to true if the right wheel turns the wrong way

void setup() {
  Serial.begin(115200);
  pinMode(ENA, OUTPUT); pinMode(IN1, OUTPUT); pinMode(IN2, OUTPUT);
  pinMode(ENB, OUTPUT); pinMode(IN3, OUTPUT); pinMode(IN4, OUTPUT);
  drive(0, 0);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 6000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  Serial.println(F("Starting in 3 seconds!"));
  delay(3000);
}

void loop() {
  int16_t v[9];                          // 01~09
  if (!mbcReadMany(ADDR, 0x01, 9, v)) {  // Cannot read → stop for safety
    drive(0, 0);
    delay(50);
    return;
  }
  int16_t nearCm  = v[0];                // 01 nearest distance cm
  int16_t nearDir = v[1];                // 02 nearest direction (negative = left)
  int16_t frontCm = v[4];                // 05 front distance cm
  int16_t frontMm = v[8];                // 09 front distance mm

  if (frontMm <= BACK_MM) {              // About to crash: back up first
    Serial.println(F("Too close! Backing up"));
    drive(-TURN_SPEED, -TURN_SPEED);
    delay(300);
  } else if (frontCm <= TURN_CM || (nearCm < 20 && nearDir > -3 && nearDir < 3)) {
    // Something straight ahead (or something very close near the front) → turn away from it
    if (nearDir < 0) { Serial.println(F("Obstacle on the left → turn right")); drive(TURN_SPEED, -TURN_SPEED); }
    else             { Serial.println(F("Obstacle on the right → turn left")); drive(-TURN_SPEED, TURN_SPEED); }
    delay(200);
  } else {
    drive(SPEED, SPEED);                 // Nothing ahead: go straight
  }
  delay(50);
}

void drive(int left, int right) {
  if (LEFT_REVERSE)  left  = -left;
  if (RIGHT_REVERSE) right = -right;
  setMotor(ENA, IN1, IN2, left);
  setMotor(ENB, IN3, IN4, right);
}

void setMotor(int en, int inA, int inB, int speed) {
  speed = constrain(speed, -255, 255);
  digitalWrite(inA, speed >= 0 ? HIGH : LOW);
  digitalWrite(inB, speed >= 0 ? LOW : HIGH);
  analogWrite(en, abs(speed));
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

How to tune it:

7️⃣ Ranging mode: normal / long range / accurate / fast (E0)

What it does: Uses command E0 to switch between the 4 ranging modes, to see how far it measures and how steady the numbers are. Type 0 ~ 3 in the box at the bottom of the Serial Monitor and press Enter; after each change it reads back 20 ~ 23 and prints the current settings.

You also need: A white wall or a big whiteboard straight ahead (the direction of lasers 4 and 5), about 150 cm away.

Steps:

1. Connect the 4 wires as in the table above, then plug the USB cable into the computer.
2. Copy the code below, paste it into the Arduino IDE and click → Upload.
3. Open the Serial Monitor and choose 115200 baud; the line ending setting ("Newline" or "Both NL & CR") does not matter.

Download tof8_07_range_mode.ino

/*
 * Ranger 8-Way (command example 01) × Arduino: ranging mode: normal / long range / accurate / fast
 * ------------------------------------------------------------
 * What does this example do?
 *   Uses command E0 to switch between 4 ranging modes, to see how far it can measure and how steady the numbers are:
 *     0 normal (factory default, up to 120 cm, one reading every 33 ms)
 *     1 long range (up to 200 cm, more easily affected by sunlight and black objects)
 *     2 accurate (one reading every 100 ms, steadiest numbers, up to 120 cm)
 *     3 fast (one reading every 20 ms, fastest response, numbers jump more)
 *
 * You need: Ranger 8-Way (universal I2C edition) + a white wall or a big whiteboard straight ahead (the direction of lasers 4 and 5), about 150 cm away.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200. Type 0~3 in the box at the bottom and press Enter to change the mode.
 *   In normal mode a wall 150 cm away reads 120 (= beyond the limit, treated as nothing); in mode 1 long range it reads about 150.
 *
 * Note:
 *   Changing the mode also resets the timing budget and the max distance to that mode's defaults (to use E2 / E4 as well, send E0 first).
 *   Settings are kept only in the sensor's memory; after a power cut it is back to normal mode.
 *   Commands: E0 ranging mode, E1 filter, E2 timing budget, E3 factory reset, E4 max distance (each takes 1 parameter byte).
 *   Read the current settings back: 20 ranging mode, 21 filter, 22 timing budget ms, 23 max distance cm.
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);
bool mbcCommand(uint8_t cmd, uint8_t arg);
void printSettings();

void setup() {
  Serial.begin(115200);
  Serial.setTimeout(50);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 4000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  mbcCommand(0xE3, 0xA5);                // Factory reset first, so we start from a clean state
  Serial.println(F("Type 0~3 to change the ranging mode (0 normal, 1 long range, 2 accurate, 3 fast)"));
  printSettings();
}

void loop() {
  if (Serial.available()) {
    int m = Serial.parseInt();
    while (Serial.available()) Serial.read();
    if (m >= 0 && m <= 3) {
      Serial.print(F(">>> send E0 ")); Serial.println(m);
      if (!mbcCommand(0xE0, m)) Serial.println(F("Command did not finish (timeout)"));
      printSettings();
    }
  }
  int16_t d[9];  // 01 nearest cm, 02 nearest direction, 03 most open cm, 04 most open direction, 05 front cm, 06 nearest mm, 07 init, 08 fault, 09 front mm
  if (mbcReadMany(ADDR, 0x01, 9, d)) {
    Serial.print(F("Front ")); Serial.print(d[4]); Serial.print(F(" cm (")); Serial.print(d[8]);
    Serial.print(F(" mm), nearest ")); Serial.print(d[0]); Serial.print(F(" cm at direction ")); Serial.print(d[1]);
    Serial.println();
  }
  delay(300);
}

// Send one command [code][parameter], then wait until the sensor has finished (bit2 "busy" of status flags F3 turns 0), at most 3 s
// Ranging mode, timing budget and factory reset re-configure the laser chips, about 0.1~0.5 s; filter and max distance take effect at once
bool mbcCommand(uint8_t cmd, uint8_t arg) {
  if (!mbcWrite(ADDR, cmd, &arg, 1)) return false;
  delay(20);                             // Give the sensor time to queue the command
  unsigned long start = millis();
  while (millis() - start < 3000) {
    int16_t f = mbcRead(ADDR, 0xF3);
    if (f != MBC_NONE && !(f & 4)) return true;   // bit2 = 0: done
    delay(10);
  }
  return false;
}

// Read the 4 current settings back from the sensor and print them (20 ranging mode, 21 filter, 22 timing budget ms, 23 max distance cm)
void printSettings() {
  int16_t s[4];
  if (!mbcReadMany(ADDR, 0x20, 4, s)) { Serial.println(F("Cannot read the settings")); return; }
  const char *modeName[] = {"normal", "long range", "accurate", "fast"};
  Serial.print(F("[Current settings] ranging mode ")); Serial.print(s[0]); Serial.print(F(" "));
  Serial.print((s[0] >= 0 && s[0] <= 3) ? modeName[s[0]] : "?");
  Serial.print(F(" | filter ")); Serial.print(s[1]);
  Serial.print(F(" | timing budget ")); Serial.print(s[2]); Serial.print(F(" ms"));
  Serial.print(F(" | max distance ")); Serial.print(s[3]); Serial.println(F(" cm"));
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see:

[Current settings] ranging mode 0 normal | filter 1 | timing budget 33 ms | max distance 120 cm
Front 120 cm (1200 mm), nearest 120 cm at direction 8
>>> send E0 1
[Current settings] ranging mode 1 long range | filter 1 | timing budget 33 ms | max distance 200 cm
Front 150 cm (1503 mm), nearest 150 cm at direction 0

Try it: In normal mode a wall 150 cm away reads 120 (beyond the limit = nothing); in 1 long range it is measured. Then try 2 accurate and 3 fast and compare how much the numbers jump. Long-range mode is more easily affected by sunlight and black objects.

8️⃣ Filter: steadier numbers (E1)

What it does: Uses command E1 to change the filter, and shows how much the number jumps while the same object stays still. Type 0 ~ 2 and press Enter; every second it prints "max - min within 1 s" = how many mm it jumps.

You also need: A box or a whiteboard straight ahead, about 50 cm away. Keep it still.

Steps:

1. Connect the 4 wires as in the table above, then plug the USB cable into the computer.
2. Copy the code below, paste it into the Arduino IDE and click → Upload.
3. Open the Serial Monitor and choose 115200 baud; the line ending setting ("Newline" or "Both NL & CR") does not matter.

Download tof8_08_filter.ino

/*
 * Ranger 8-Way (command example 02) × Arduino: filter: steadier numbers
 * ------------------------------------------------------------
 * What does this example do?
 *   Uses command E1 to change the filter, and shows how much the number jumps while the same object stays still:
 *     0 off (every reading as it is: fastest response, jumps the most)
 *     1 median of the last 3 readings (factory default)
 *     2 median of the last 5 readings (steadiest, a little slower to react)
 *
 * You need: Ranger 8-Way (universal I2C edition) + a box or a whiteboard straight ahead (the direction of lasers 4 and 5), about 50 cm away. Keep it still.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200. Type 0~2 and press Enter to change the filter. Every second it prints "max - min within 1 s" = how many mm it jumps.
 *
 * Note:
 *   The median removes an odd reading now and then, but when the object moves the number catches up 1~2 readings later. Use 0 when speed matters, 2 when you want steady numbers.
 *   Commands: E0 ranging mode, E1 filter, E2 timing budget, E3 factory reset, E4 max distance (each takes 1 parameter byte).
 *   Read the current settings back: 20 ranging mode, 21 filter, 22 timing budget ms, 23 max distance cm.
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);
bool mbcCommand(uint8_t cmd, uint8_t arg);
void printSettings();

void setup() {
  Serial.begin(115200);
  Serial.setTimeout(50);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 4000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  mbcCommand(0xE3, 0xA5);                // Factory reset first, so we start from a clean state
  Serial.println(F("Type 0~2 to change the filter (0 off, 1 median of 3, 2 median of 5)"));
  printSettings();
}

void loop() {
  if (Serial.available()) {
    int f = Serial.parseInt();
    while (Serial.available()) Serial.read();
    if (f >= 0 && f <= 2) {
      Serial.print(F(">>> send E1 ")); Serial.println(f);
      mbcCommand(0xE1, f);
      printSettings();
    }
  }
  // Keep reading the front mm for 1 s and remember the max and min
  int16_t lo = 32767, hi = -32768;
  unsigned long start = millis();
  while (millis() - start < 1000) {
    int16_t d[9];  // 01 nearest cm, 02 nearest direction, 03 most open cm, 04 most open direction, 05 front cm, 06 nearest mm, 07 init, 08 fault, 09 front mm
    if (mbcReadMany(ADDR, 0x01, 9, d)) {
      if (d[8] < lo) lo = d[8];
      if (d[8] > hi) hi = d[8];
    }
    delay(20);
  }
  Serial.print(F("Front mm ")); Serial.print(lo); Serial.print(F("~")); Serial.print(hi);
  Serial.print(F(", jumps ")); Serial.print(hi - lo); Serial.println(F(" mm"));
}

// Send one command [code][parameter], then wait until the sensor has finished (bit2 "busy" of status flags F3 turns 0), at most 3 s
// Ranging mode, timing budget and factory reset re-configure the laser chips, about 0.1~0.5 s; filter and max distance take effect at once
bool mbcCommand(uint8_t cmd, uint8_t arg) {
  if (!mbcWrite(ADDR, cmd, &arg, 1)) return false;
  delay(20);                             // Give the sensor time to queue the command
  unsigned long start = millis();
  while (millis() - start < 3000) {
    int16_t f = mbcRead(ADDR, 0xF3);
    if (f != MBC_NONE && !(f & 4)) return true;   // bit2 = 0: done
    delay(10);
  }
  return false;
}

// Read the 4 current settings back from the sensor and print them (20 ranging mode, 21 filter, 22 timing budget ms, 23 max distance cm)
void printSettings() {
  int16_t s[4];
  if (!mbcReadMany(ADDR, 0x20, 4, s)) { Serial.println(F("Cannot read the settings")); return; }
  const char *modeName[] = {"normal", "long range", "accurate", "fast"};
  Serial.print(F("[Current settings] ranging mode ")); Serial.print(s[0]); Serial.print(F(" "));
  Serial.print((s[0] >= 0 && s[0] <= 3) ? modeName[s[0]] : "?");
  Serial.print(F(" | filter ")); Serial.print(s[1]);
  Serial.print(F(" | timing budget ")); Serial.print(s[2]); Serial.print(F(" ms"));
  Serial.print(F(" | max distance ")); Serial.print(s[3]); Serial.println(F(" cm"));
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}

You will see:

[Current settings] ranging mode 0 normal | filter 1 | timing budget 33 ms | max distance 120 cm
Front mm 498~506, jumps 8 mm
>>> send E1 0
Front mm 492~511, jumps 19 mm

Try it: The median removes an odd reading now and then, but when the object moves the number catches up 1 ~ 2 readings later. Use 0 when speed matters, 2 when you want steady numbers.

9️⃣ Timing budget: faster or more accurate (E2)

What it does: Uses command E2 to change "how long each reading takes" (20 ~ 200 ms), and shows how many updates per second and how much the number jumps. The program turns the filter off first (E1 0) so the difference is easier to see. Type 20 ~ 200 and press Enter; 0 = back to the mode default.

You also need: A box or a whiteboard straight ahead, about 50 cm away. Keep it still.

Steps:

1. Connect the 4 wires as in the table above, then plug the USB cable into the computer.
2. Copy the code below, paste it into the Arduino IDE and click → Upload.
3. Open the Serial Monitor and choose 115200 baud; the line ending setting ("Newline" or "Both NL & CR") does not matter.

Download tof8_09_timing_budget.ino

/*
 * Ranger 8-Way (command example 03) × Arduino: timing budget: faster or more accurate
 * ------------------------------------------------------------
 * What does this example do?
 *   Uses command E2 to change "how long each reading takes" (20~200 ms), and shows how many updates per second and how much the number jumps:
 *     20 ms: about 50 updates a second, fastest response, numbers jump more
 *     33 ms: factory default
 *     200 ms: 5 updates a second, steadiest, measures a little farther
 *
 * You need: Ranger 8-Way (universal I2C edition) + a box or a whiteboard straight ahead (the direction of lasers 4 and 5), about 50 cm away. Keep it still.
 *
 * Wiring:
 *   Sensor VCC → 5V      Sensor GND → GND
 *   Sensor SDA → A4      Sensor SCL → A5         (UNO / Nano)
 *   UNO R4: SDA / SCL pins; ESP32: GPIO 21 (SDA) / GPIO 22 (SCL)
 *
 * How to see the result:
 *   Serial Monitor at 115200. Type 20~200 and press Enter. Every second it prints "how many times the value changed" and "how many mm it jumps".
 *
 * Note:
 *   Values outside 20~200 are clamped (e.g. 5 becomes 20, 300 becomes 200); 0 = back to the current mode's default.
 *   The filter (example 2) makes "how many times it changed" a little smaller; to see the raw speed, set the filter to 0 first.
 *   Commands: E0 ranging mode, E1 filter, E2 timing budget, E3 factory reset, E4 max distance (each takes 1 parameter byte).
 *   Read the current settings back: 20 ranging mode, 21 filter, 22 timing budget ms, 23 max distance cm.
 */

#include <Wire.h>

const uint8_t ADDR = 0x29;               // The sensor's house number (I2C address)
const int16_t MBC_NONE = -32768;         // Code for "no such value / cannot read"

bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p = NULL, uint8_t n = 0);
bool mbcCommand(uint8_t cmd, uint8_t arg);
void printSettings();

void setup() {
  Serial.begin(115200);
  Serial.setTimeout(50);
  mbcBegin();
  delay(500);
  if (!mbcWaitReady(ADDR, 4000)) {
    Serial.println(F("Sensor not found. Run Example 1 first to check the wiring."));
    while (true) {}
  }
  mbcCommand(0xE3, 0xA5);                // Factory reset first, so we start from a clean state
  mbcCommand(0xE1, 0);                   // Turn the filter off first, so the difference is easier to see
  Serial.println(F("Type 20~200 to change the timing budget (ms), 0 = back to default"));
  printSettings();
}

void loop() {
  if (Serial.available()) {
    long b = Serial.parseInt();
    while (Serial.available()) Serial.read();
    if (b >= 0 && b <= 255) {
      Serial.print(F(">>> send E2 ")); Serial.println(b);
      if (!mbcCommand(0xE2, (uint8_t)b)) Serial.println(F("Command did not finish (timeout)"));
      printSettings();
    }
  }
  int16_t last = -1, lo = 32767, hi = -32768;
  int changes = 0;
  unsigned long start = millis();
  while (millis() - start < 1000) {      // Keep reading for 1 s: how many times the value changed = about how many updates
    int16_t d[9];  // 01 nearest cm, 02 nearest direction, 03 most open cm, 04 most open direction, 05 front cm, 06 nearest mm, 07 init, 08 fault, 09 front mm
    if (mbcReadMany(ADDR, 0x01, 9, d)) {
      if (d[8] != last) { changes++; last = d[8]; }
      if (d[8] < lo) lo = d[8];
      if (d[8] > hi) hi = d[8];
    }
    delay(5);
  }
  Serial.print(F("Changed ")); Serial.print(changes); Serial.print(F(" times in 1 s, front mm jumps "));
  Serial.print(hi - lo); Serial.println(F(" mm"));
}

// Send one command [code][parameter], then wait until the sensor has finished (bit2 "busy" of status flags F3 turns 0), at most 3 s
// Ranging mode, timing budget and factory reset re-configure the laser chips, about 0.1~0.5 s; filter and max distance take effect at once
bool mbcCommand(uint8_t cmd, uint8_t arg) {
  if (!mbcWrite(ADDR, cmd, &arg, 1)) return false;
  delay(20);                             // Give the sensor time to queue the command
  unsigned long start = millis();
  while (millis() - start < 3000) {
    int16_t f = mbcRead(ADDR, 0xF3);
    if (f != MBC_NONE && !(f & 4)) return true;   // bit2 = 0: done
    delay(10);
  }
  return false;
}

// Read the 4 current settings back from the sensor and print them (20 ranging mode, 21 filter, 22 timing budget ms, 23 max distance cm)
void printSettings() {
  int16_t s[4];
  if (!mbcReadMany(ADDR, 0x20, 4, s)) { Serial.println(F("Cannot read the settings")); return; }
  const char *modeName[] = {"normal", "long range", "accurate", "fast"};
  Serial.print(F("[Current settings] ranging mode ")); Serial.print(s[0]); Serial.print(F(" "));
  Serial.print((s[0] >= 0 && s[0] <= 3) ? modeName[s[0]] : "?");
  Serial.print(F(" | filter ")); Serial.print(s[1]);
  Serial.print(F(" | timing budget ")); Serial.print(s[2]); Serial.print(F(" ms"));
  Serial.print(F(" | max distance ")); Serial.print(s[3]); Serial.println(F(" cm"));
}

// ============================================================
// Below are the "Communication helpers" (MBC I2C protocol v2): they talk to the sensor.
// They are the same in every MBC example. No need to change or understand them.
//   How to read: write [number] → wait 2 ms → read 2×k bytes = k int16 values in a row (little-endian) from that number
//   If a number does not exist (empty slot), the sensor returns -32768 (MBC_NONE)
// ============================================================

// Start I2C (call once in setup)
// UNO/Nano: SDA=A4, SCL=A5; UNO R4: SDA/SCL pins; ESP32: default GPIO21(SDA)/22(SCL)
void mbcBegin() {
  Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
  Wire.setWireTimeout(25000, true);      // If a wire is loose, Arduino will not freeze
#endif
}

// From the sensor at addr, read k values (1~16) in a row starting at number id, into out. Returns true if all were read
bool mbcReadMany(uint8_t addr, uint8_t id, uint8_t k, int16_t *out) {
  if (k < 1) k = 1;
  if (k > 16) k = 16;                    // At most 16 values at a time (32 bytes, the Wire buffer limit)
  Wire.beginTransmission(addr);
  Wire.write(id);                        // Tell the sensor: I want to read starting from number id
  if (Wire.endTransmission() != 0) return false;
  delay(2);                              // Wait 2 ms before reading (a must for ESP32-based products)
  uint8_t n = (uint8_t)(2 * k);
  if (Wire.requestFrom(addr, n) != n) return false;
  for (uint8_t i = 0; i < k; i++) {
    uint16_t lo = Wire.read();           // The low byte comes first
    uint16_t hi = Wire.read();           // Then the high byte (little-endian)
    out[i] = (int16_t)(uint16_t)(lo | (hi << 8));
  }
  return true;
}

// Read one value. Returns MBC_NONE if it cannot be read (not connected)
int16_t mbcRead(uint8_t addr, uint8_t id) {
  int16_t v;
  return mbcReadMany(addr, id, 1, &v) ? v : MBC_NONE;
}

// Send a command: write [id][parameters...]. p points to the parameters, n = how many bytes (leave them out if none). Returns true on success
bool mbcWrite(uint8_t addr, uint8_t id, const uint8_t *p, uint8_t n) {
  Wire.beginTransmission(addr);
  Wire.write(id);
  for (uint8_t i = 0; i < n; i++) Wire.write(p[i]);
  return Wire.endTransmission() == 0;
}

// Wait until the sensor is ready (bit0 of status flags F3 = 1), at most ms milliseconds. Returns true when ready
bool mbcWaitReady(uint8_t addr, uint16_t ms) {
  unsigned long start = millis();
  while (millis() - start < ms) {
    int16_t f = mbcRead(addr, 0xF3);
    if (f != MBC_NONE && (f & 1)) return true;
    delay(50);
  }
  return false;
}