ESP32 Wireless Module

WiFi, Bluetooth, and Zigbee configuration for the Cruiser’s built-in ESP32-C6 module.

9 minute read

The Cruiser Carrier Board includes a built-in ESP32-C6 module. It can run one of two Exaviz firmware images:

WiFi + Bluetooth firmware (factory default) — WiFi 6 (802.11ax, 2.4 GHz) and Bluetooth LE 5.3, alongside board control (PoE management)
Zigbee coordinator firmware (beta, optional) — Zigbee coordination for smart home, alongside board control (PoE management)

One firmware at a time - WiFi+BT or Zigbee

The ESP32-C6 has a single 2.4 GHz radio shared by WiFi, Bluetooth, and Zigbee, so they take turns on the air. WiFi and Bluetooth share it well, which is why the factory image runs both.

A Zigbee coordinator is different: it forms and holds the network, so it has to listen continuously. In Espressif’s RF coexistence support matrix, a Zigbee router-class role alongside a WiFi access point is listed as not supported, and alongside a WiFi client as supported but unstable. Running it with Bluetooth scanning is likewise not supported.

Neither is a combination we are willing to ship, so you choose either the WiFi + Bluetooth firmware or the Zigbee coordinator firmware.

Boards ship with the WiFi + Bluetooth firmware. The Zigbee coordinator firmware is currently beta and is provided per-board on request - contact support@exaviz.com. See Zigbee Coordinator below.

External Antenna

The Cruiser’s ESP32-C6 is the ESP32-C6-MINI-1U variant, which uses an external antenna connector instead of an on-board PCB antenna. The board ships without an antenna - you supply your own.

Per the Espressif ESP32-C6-MINI-1U datasheet, the connector is the third-generation miniature RF connector, commonly labeled W.FL / MHF3 / IPEX3. Buy a pigtail branded for this generation: Hirose W.FL, Amphenol AMMC, and I-PEX MHF III all mate to the same standard, and pigtails are commonly labeled MHF3. It is not the common U.FL / MHF1 (first generation, ~2.0 mm) found on many other modules.

Use a W.FL / MHF III pigtail - do not force a U.FL connector

A U.FL / MHF1 pigtail is physically larger and will not mate with this connector. Forcing one on can damage the connector or the board. Use a W.FL (MHF III) to RP-SMA pigtail (an AMMC-compatible pigtail also works), then attach a 2.4 GHz antenna.

Choosing a Firmware

Because WiFi/Bluetooth and Zigbee live in separate firmware images, pick the one that matches your use case:

Use case	Firmware	What you get
WiFi and/or Bluetooth on the ESP32-C6	WiFi + Bluetooth (default)	WiFi 6 + BLE 5.3, no Zigbee
Zigbee coordinator for smart home	Zigbee coordinator (beta)	Zigbee, no ESP32 WiFi/BT

Recommended smart-home setup

Flash the Zigbee coordinator firmware on the ESP32-C6 and use the CM5’s own built-in WiFi for network connectivity. The CM5 WiFi uses a separate radio, so there are no radio-coexistence concerns - the ESP32-C6 is dedicated entirely to Zigbee.

WiFi Setup

The ESP32-C6 provides WiFi 6 (802.11ax) connectivity at 2.4 GHz when running the WiFi + Bluetooth firmware (the factory default). WiFi and Bluetooth are not available when the module is running the Zigbee coordinator firmware - see Choosing a Firmware.

Note: For general WiFi setup instructions (including CM5 built-in WiFi), see the WiFi Setup section.

Access Point (SoftAP) Mode

Beta feature - requires exaviz-dkms 1.1.16 or newer

Running the ESP32-C6 as a WiFi access point is a beta feature added in exaviz-dkms 1.1.16. It uses the factory WiFi + Bluetooth firmware - there is no firmware reflash; the access-point capability is in the Linux driver, so you enable it with a package update:

sudo apt update
sudo apt full-upgrade   # or: sudo apt install --only-upgrade exaviz-dkms
sudo reboot

The ESP32-C6 can act as a 2.4 GHz WiFi access point (SoftAP) - useful on a CM5 Lite (no on-board WiFi), or anywhere you want the Cruiser to serve its own WiFi network.

Access point OR client, not both at once

The ESP32-C6 runs as an access point or as a WiFi client, not both simultaneously (a limitation of the underlying esp-hosted stack). In AP mode it does not also connect to another WiFi network.

1. Confirm AP support

After updating exaviz-dkms and rebooting, install the tools and check the radio:

sudo apt install -y iw hostapd dnsmasq
# find the ESP32-C6 wifi interface (driver esp32_sdio)
for p in /sys/class/ieee80211/*; do
  [ "$(basename $(readlink -f $p/device/driver))" = esp32_sdio ] && \
    echo "esp phy=$(basename $p) iface=$(ls $p/device/net)"
done
iw phy <that-phy> info | sed -n '/Supported interface modes/,/Band/p'

You should see * AP in the supported interface modes. If you only see * managed, the installed driver predates AP support - update exaviz-dkms to 1.1.16 or newer.

2. Configure hostapd

Assume the ESP32-C6 interface is wlan0 (use the name from step 1). Create /etc/hostapd/hostapd.conf:

interface=wlan0
driver=nl80211
ssid=MyCruiserAP
hw_mode=g
channel=6
auth_algs=1
wpa=2
wpa_passphrase=change-this-passphrase
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP

On Raspberry Pi OS / Trixie (NetworkManager), tell NetworkManager to leave the interface alone so it does not fight hostapd, then give it a static IP:

sudo nmcli device set wlan0 managed no
sudo ip addr add 192.168.50.1/24 dev wlan0
sudo ip link set wlan0 up

3. Hand out DHCP with dnsmasq

Create /etc/dnsmasq.d/cruiser-ap.conf:

interface=wlan0
bind-interfaces
dhcp-range=192.168.50.10,192.168.50.100,255.255.255.0,12h
dhcp-authoritative

4. Start it

sudo systemctl unmask hostapd
sudo systemctl enable --now hostapd dnsmasq

Verify with iw dev wlan0 info (should show type AP) and journalctl -u hostapd (should show AP-ENABLED). Connect a client to MyCruiserAP; it should associate and get a 192.168.50.x address. For internet access behind the AP you will also need to set up NAT/forwarding from the Cruiser’s uplink.

Antenna

Access-point operation needs the external antenna, the same as client mode - a W.FL / MHF III to RP-SMA pigtail with your own 2.4 GHz antenna.

Bluetooth LE

The ESP32-C6 provides Bluetooth Low Energy 5.3 connectivity when running the WiFi + Bluetooth firmware (the factory default). Bluetooth is not available when the module is running the Zigbee coordinator firmware - see Choosing a Firmware.

Checking Bluetooth Status

# View Bluetooth adapter
hciconfig

# Scan for devices
sudo hcitool lescan

Using bluetoothctl

bluetoothctl
# Inside bluetoothctl:
power on
agent on
scan on
# When device appears:
pair XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX

Zigbee Coordinator

With the Zigbee coordinator firmware, the ESP32-C6 acts as a built-in Zigbee coordinator - no external USB dongle required.

Beta — requires the Zigbee firmware

Zigbee is not part of the factory WiFi + Bluetooth image. To use it you must flash the Zigbee coordinator firmware, which is currently beta. Each board’s ESP32-C6 flash is encrypted with a per-unit key, so we build an image keyed to your specific board - contact support@exaviz.com with your board serial number to request one. See Updating Exaviz Firmware.

Protocol

The Exaviz Zigbee firmware implements Espressif’s ZNSP (Zigbee NCP Serial Protocol). It is not EZSP (Silicon Labs) or ZNP (Texas Instruments), so coordinators expecting those protocols will not communicate with it.

Supported Software

Software	Status	Notes
Home Assistant ZHA (via zigpy-espzb)	Supported	The only host stack that speaks ZNSP. zigpy-espzb is itself experimental.
zigbee2mqtt	Not supported	zigbee2mqtt does not implement ZNSP.
deCONZ	Not supported	deCONZ does not implement ZNSP.

Serial Device Path

When the Zigbee firmware is running, the coordinator is exposed on /dev/ttyAMA4 at 115200 baud, no flow control. (/dev/ttyAMA3 is the PoE/board-control console and is not the Zigbee interface.)

dmesg | grep tty

Home Assistant ZHA

Install/patch the zigpy-espzb radio library (contact support@exaviz.com for the exact versions and patches we validated).
Go to Settings → Devices & Services → Add Integration
Select Zigbee Home Automation (ZHA)
Choose the EZSP/espzb (ZNSP) radio type and the serial device /dev/ttyAMA4 at 115200 baud
Follow the setup wizard

Updating Exaviz Firmware

Exaviz provides firmware images for the ESP32-C6 module, including the optional Zigbee coordinator image. Each board’s flash is encrypted with a per-unit key fused into the chip, so images are built per board - a generic image will not boot.

Requesting a firmware image

To switch firmware (for example, to the beta Zigbee coordinator image), email support@exaviz.com with your board serial number. The serial prints in the ESP32 boot banner (board serial: CRU-xxxxxx) and is also reported by info on /dev/pse. We’ll return an encrypted image keyed to your board plus flashing instructions.

Custom Firmware (Thread/Matter)

Not Supported by Exaviz Firmware

Thread, Matter, and 802.15.4 are not supported by Exaviz firmware. The Exaviz firmware provides WiFi and Bluetooth (default image) or Zigbee coordination (beta image) only.

If you need Thread, Matter, or 802.15.4 support, you can install your own custom firmware on the ESP32-C6. The GPIO Control and Flash Firmware with esptool sections below explain how to enter bootloader mode and flash firmware.

Disabling Firmware Encryption

The ESP32-C6 firmware is encrypted by default. To install custom firmware, you may need to disable encryption first.

Contact support@exaviz.com for assistance with disabling ESP32 firmware encryption.

Custom Firmware Warning

Installing custom firmware will disable Exaviz-provided features. If you flash custom firmware, Exaviz support may be limited to hardware-related issues only.

GPIO Control

The ESP32-C6 is controlled via CM5 GPIO pins for reset and firmware updates.

Install gpiod

sudo apt install gpiod

Pin Mapping

GPIO	Function	Description
GPIO16	EN (Enable)	Reset the ESP32 (active low)
GPIO17	BOOT	Enter bootloader mode (active low)

Reset the ESP32

gpioset gpiochip0 16=0 && sleep 0.5 && gpioset gpiochip0 16=1

Enter Boot Mode (Firmware Update)

To flash new firmware to the ESP32-C6:

# Hold BOOT low
gpioset gpiochip0 17=0

# Reset while BOOT is held
gpioset gpiochip0 16=0
sleep 0.5
gpioset gpiochip0 16=1

# Release BOOT after reset
sleep 0.5
gpioset gpiochip0 17=1

The ESP32 is now in bootloader mode, ready for esptool.py or similar.

Flash Firmware with esptool

# Install esptool
pip install esptool

# Flash firmware (example) — the ESP32 bootloader UART is /dev/ttyAMA3
esptool.py --chip esp32c6 --port /dev/ttyAMA3 write_flash 0x0 firmware.bin

Factory Firmware

The ESP32-C6 comes pre-flashed with the factory WiFi + Bluetooth firmware, which includes board control functions (PoE management, etc.). Only update firmware if specifically instructed by Exaviz support, if you are switching to the Zigbee coordinator firmware, or if you are installing custom firmware for unsupported protocols.

Troubleshooting

WiFi Not Working

If using CM5 built-in WiFi:

See WiFi Setup
Check wlan0 interface exists: ip link show wlan0
Verify wpa_supplicant configuration

If using ESP32 WiFi:

Verify ESP32 is running the latest Exaviz firmware
Check ESP32 status: dmesg | grep esp
Reset the ESP32 if needed
Ensure ESP32 isn’t stuck in boot mode (GPIO17 should be high)
Confirm the module is running the WiFi + Bluetooth firmware, not the Zigbee coordinator firmware (see Choosing a Firmware)

Bluetooth Not Found

Verify ESP32 is running the latest Exaviz firmware
Check hciconfig for Bluetooth adapter
Reset the ESP32 if needed
Ensure ESP32 isn’t stuck in boot mode (GPIO17 should be high)

Zigbee Coordinator Not Responding

Confirm the ESP32 is running the Zigbee coordinator firmware (beta) - the factory WiFi + Bluetooth image has no Zigbee coordinator
Verify your ZHA configuration points at /dev/ttyAMA4 (not /dev/ttyAMA3) at 115200 baud
Confirm you are using ZHA via zigpy-espzb - zigbee2mqtt and deCONZ do not support the ZNSP protocol
Reset the ESP32 if needed

ESP32 Unresponsive

If the ESP32 becomes completely unresponsive:

Try a normal reset (GPIO16 toggle)
If that fails, enter boot mode and reflash firmware
Check CM5 GPIO pins are configured correctly

# Verify GPIO state
gpioget gpiochip0 16 17
# Should return: 1 1 (both high)

Resources

ESP32-C6-MINI-1 Datasheet — Complete technical specifications from Espressif

Last modified August 31, 2026