Control anything ESPHome can touch — switches, sensors, fans, lights — over long-range LoRa mesh, managed from MeshCore Companion.

XIAO nRF52840 only. This component has been developed and tested exclusively on the Seeed XIAO nRF52840 with SX1262 LoRa radio, running on ESPHome's Zephyr/nRF52 platform. It will not work on ESP32/ESP8266 boards without significant modifications to the HAL, SPI driver, and build system.

Prerequisites: ESPHome with nRF52 support (pip install esphome)

Create a YAML file — no need to clone this repo:

esphome:
  name: my-sensor

nrf52:
  board: xiao_ble
  bootloader: adafruit
  dfu:
    reset_pin: 18

logger:
  level: DEBUG

external_components:
  - source:
      type: git
      url: https://github.com/netmilk/esphome-meshcore
      ref: main
    components: [meshcore_sensor]

meshcore_sensor:
  name: "My Sensor"
  password: "mypassword"
  frequency: 869.432      # see Radio Presets below
  bandwidth: 62.5
  spreading_factor: 7
  coding_rate: 5
  tx_power: 22

  on_command:
    - command: "uptime"
      lambda: |-
        uint32_t s = millis() / 1000;
        char buf[32];
        snprintf(buf, sizeof(buf), "%ud %uh %um %us",
                 s/86400, (s/3600)%24, (s/60)%60, s%60);
        return std::string(buf);

Build and flash:

# First compile downloads libraries — run twice if it fails with missing headers
esphome compile my-sensor.yaml

# First flash: double-tap reset button, device mounts as XIAO-SENSE drive
cp .esphome/build/my-sensor/.pioenvs/my-sensor/zephyr/zephyr.uf2 /Volumes/XIAO-SENSE/

# After that, DFU is automatic:
esphome upload my-sensor.yaml

Open the Companion, tap Discover Sensors — your sensor should appear.

All devices on the mesh must use the same radio preset.

Define commands that users can send from the Companion. Each command has a prefix to match and a C++ lambda that returns a response string.

meshcore_sensor:
  id: meshcore
  # ... radio config ...

  on_command:
    - command: "led on"
      lambda: |-
        id(meshcore).set_led(true);
        return std::string("LED is ON");

    - command: "led off"
      lambda: |-
        id(meshcore).set_led(false);
        return std::string("LED is OFF");

Lambdas receive the full command string and can reference any ESPHome entity via id().

• MCU: Seeed XIAO nRF52840 (Sense or non-Sense)
• Radio: SX1262 LoRa module (MeshCore XIAO variant pinout)
• Companion: MeshCore Companion

D0 (P0.02) is the only pin free by default. D6/D7 are used by UART0 (serial console). To free up more pins, you can remap I2C or UART via config/overlays.

Not visible in Discover Sensors: Companion must use the same radio preset (frequency, bandwidth, SF, CR).

Login fails: Password must match the password config exactly.

Radio init fails (error -2): SPI issue. Check pin connections match the config.

DFU not working: First flash always requires double-tap reset. After that, esphome upload handles it automatically via 1200 baud touch.

git clone --recurse-submodules https://github.com/netmilk/esphome-meshcore.git
cd esphome-meshcore
esphome compile xiao-meshcore.yaml

MeshCore source is a git submodule at ./MeshCore, pinned to a known working commit. When used as an external component, the submodule is fetched automatically at build time.