Building a Zigbee Arduino Sensor Node: XBee 3 UART Wiring & Code

Standard Arduino and ESP32 microcontrollers do not have native 802.15.4 radios, meaning you cannot transmit Zigbee Arduino payloads directly from the silicon. To build a reliable Zigbee sensor node, you must interface a dedicated Zigbee system-on-module (SoM) via UART. The industry standard for this is the Digi XBee 3 Zigbee 3.0 module, which handles the complex mesh networking, encryption, and RF stack, leaving your microcontroller to simply format the payload.

This guide walks through building a battery-ready environmental sensor node using an Adafruit Feather ESP32 V2 and an XBee 3 module in API mode. We will cover exact wiring, provide complete compilable C++ code with error handling, and detail the exact debugging steps for the most common Zigbee delivery failures.

Parts List & Hardware Specifications

Using a 3.3V native microcontroller is critical here. The XBee 3 module operates strictly at 3.3V logic and is not 5V tolerant. Feeding 5V UART lines from a standard Arduino Uno into the XBee DIN pin will permanently destroy the module's RF front-end.

For the Zigbee firmware on the XBee module, ensure you have used Digi XCTU software to flash the Zigbee 3.0 Router/End Device firmware and set the module to API Mode (ATAP=1) before soldering it to the breakout.

Pin Mapping & Wiring Steps

The Adafruit Feather ESP32 V2 uses the ESP32 Arduino core, which allows flexible UART pin mapping. We will map Serial1 to GPIO 16 (RX) and GPIO 17 (TX) to avoid conflicts with the native USB serial port used for debugging.

1. Prepare the Breakout: Solder male headers to the SparkFun XBee Explorer. Insert the XBee 3 module, ensuring the notch aligns correctly.
2. Wire the UART: Connect Feather GPIO 17 to Explorer DIN, and GPIO 16 to Explorer DOUT. Double-check this cross-wiring; TX-to-TX will result in silent failure.
3. Wire Power: Connect 3V3 and GND. Do not use the 5V/VBUS pin on the Feather.
4. Connect the Sensor: Wire the BME280 to the Feather's I2C bus (SDA to GPIO 22, SCL to GPIO 20, VIN to 3V3, GND to GND).

Complete Arduino Zigbee Code (API Mode)

This code targets the Adafruit Feather ESP32 V2. It reads the BME280 sensor and transmits the payload to a predefined Coordinator's 64-bit MAC address using the Digi XBee API. You must install the XBee-Arduino library (by Andrew Wickert) and the Adafruit BME280 Library via the Arduino Library Manager before compiling.

#include <XBee.h>
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME280.h>

// --- Pin Definitions & Hardware Config ---
#define XBEE_RX_PIN 16
#define XBEE_TX_PIN 17
#define XBEE_BAUD 9600

// Target Coordinator 64-bit Address (Replace with your actual Coordinator MAC)
uint8_t COORD_MSB[] = {0x00, 0x13, 0xA2, 0x00};
uint8_t COORD_LSB[] = {0x41, 0x55, 0x66, 0x77};
XBee64BitAddress coordAddr = XBee64BitAddress(COORD_MSB, COORD_LSB);

// Hardware Initialization
XBee xbee;
Adafruit_BME280 bme;

void setup() {
  // USB Serial for debugging
  Serial.begin(115200);
  while(!Serial && millis() < 5000); // Wait up to 5s for USB serial

  // Initialize Hardware Serial1 for XBee
  Serial1.begin(XBEE_BAUD, SERIAL_8N1, XBEE_RX_PIN, XBEE_TX_PIN);
  xbee.setSerial(Serial1);

  // Initialize I2C Sensor
  if (!bme.begin(0x77)) {
    Serial.println("FATAL: Could not find BME280 sensor on I2C bus.");
    while (1) delay(10);
  }
  
  Serial.println("Zigbee Arduino Node Initialized.");
}

void loop() {
  // 1. Gather Sensor Data
  float tempC = bme.readTemperature();
  float humidity = bme.readHumidity();
  
  // 2. Format Payload (Simple CSV string for this example)
  char payload[32];
  snprintf(payload, sizeof(payload), "T:%.1f,H:%.1f", tempC, humidity);
  
  // 3. Create and Send Zigbee TX Request
  ZBTxRequest zbTx = ZBTxRequest(coordAddr, (uint8_t*)payload, strlen(payload));
  xbee.send(zbTx);
  
  // 4. Error Handling: Wait for TX Status Response
  if (xbee.readPacket(5000)) {
    if (xbee.getResponse().getApiId() == ZB_TX_STATUS_RESPONSE) {
      ZBTxStatusResponse txStatus;
      xbee.getResponse().getZBTxStatusResponse(txStatus);
      
      if (txStatus.getDeliveryStatus() == 0x00) {
        Serial.println("SUCCESS: Payload delivered to Coordinator.");
      } else {
        // Exact Error String Handling
        Serial.print("Error: ZB_TX_STATUS_DELIVERY_FAILED (0x89) - Delivery Status: 0x");
        Serial.println(txStatus.getDeliveryStatus(), HEX);
      }
    }
  } else {
    Serial.println("Error: XBEE_RESPONSE_TIMEOUT - No status frame received.");
  }

  // 5. Deep Sleep (Optional: Wake every 60 seconds)
  // esp_sleep_enable_timer_wakeup(60 * 1000000ULL);
  // esp_deep_sleep_start();
  
  delay(15000); // Standard delay for testing
}

Debugging: Exact Error Strings & Ranked Causes

When working with Zigbee Arduino integrations, the RF stack runs entirely on the XBee module. Your Arduino only sees the result via API frames. Here is how to decode the two most common failure modes.

1. "Error: ZB_TX_STATUS_DELIVERY_FAILED (0x89)"

This means the XBee module successfully transmitted the packet over the air, but the destination did not acknowledge it, or the route failed. Check the Delivery Status hex code printed in the serial monitor:

• 0x21 (Network ACK Failure): The destination node is offline, out of range, or asleep and not polling its parent.
• 0x25 (Route Not Found): The mesh network cannot find a path to the coordinator. The node may have joined a different network.
• 0x26 (Address Not Found): The 64-bit MAC address hardcoded in the COORD_MSB and COORD_LSB arrays is incorrect.

2. "Error: XBEE_RESPONSE_TIMEOUT"

The Arduino sent the payload but never received the 0x8B TX Status frame back from the XBee module within 5 seconds. The first three things to check when this fails:

1. API Mode Mismatch: The XBee module must be configured with ATAP=1 (API mode without escapes) or ATAP=2 (API mode with escapes). If it is in transparent mode (ATAP=0), it will not send status frames back to the UART.
2. Baud Rate Conflict: Ensure the XBee's ATBD register matches the 9600 baud rate defined in the code. (Default for XBee 3 is 9600, but it may have been changed).
3. UART Pin Swap: Verify that Feather TX is connected to XBee DIN, and Feather RX is connected to XBee DOUT. A straight-through connection will cause a timeout.

Extending and Simplifying the Build

How to Simplify: If parsing API frames in C++ is too complex for your use case, you can switch the XBee module to Transparent (AT) Mode (ATAP=0). In this mode, you simply use Serial1.print("T:22.5,H:45.0");. The XBee will automatically wrap the serial string in a Zigbee payload and send it to the coordinator. The trade-off is that you lose delivery confirmations, RSSI data, and the ability to receive complex multi-node commands.

How to Extend: To make this a true battery-powered remote node, utilize the ESP32's deep sleep capabilities (uncomment the sleep lines in the code). To wake the XBee from sleep synchronously, connect a Feather GPIO to the XBee's DIO9 (Pin 13). Set the XBee's ATSN (Sleep Mode) to cyclic sleep, and pulse DIO9 low for 2ms before sending the UART payload to ensure the radio is awake and ready to receive data.