Espnow packet transport

content/components/packet_transport/_index.md

@@ -12,7 +12,7 @@ params:
 The purpose of this component is to allow ESPHome nodes to directly communicate with each over a communication channel.
 It permits the state of sensors and binary sensors to be transmitted from one node to another, without the need for a
 central server or broker. The actual transport channel is provided by another component. Currently the supported
-transports are {{< docref "/components/sx126x" >}}, {{< docref "/components/sx127x" >}}, {{< docref "/components/uart" >}} and {{< docref "/components/udp" >}}.
+transports are {{< docref "/components/espnow" >}}, {{< docref "/components/sx126x" >}}, {{< docref "/components/sx127x" >}}, {{< docref "/components/uart" >}} and {{< docref "/components/udp" >}}.
 
 Nodes may be *providers* which transmit or broadcast sensor data, or *consumers* which receive sensor data from one or more
 providers. A node may be both a provider and a consumer. Optional security is provided by one or more of:

content/components/packet_transport/espnow.md

@@ -0,0 +1,194 @@
+---
+description: "Instructions for setting up an ESP-NOW packet transport platform on ESPHome"
+title: "ESP-NOW Packet Transport Platform"
+params:
+  seo:
+    description: Instructions for setting up an ESP-NOW packet transport platform on ESPHome
+    image: espnow.svg
+---
+
+{{< anchor "espnow-packet-transport" >}}
+
+The [Packet Transport Component](#packet-transport) platform allows ESPHome nodes to directly communicate with each over a communication channel. The ESP-NOW implementation of the platform uses ESP-NOW as a communication medium. See the [Packet Transport Component](#packet-transport) and {{< docref "/components/espnow" >}} for more information.
+
+ESP-NOW provides low-latency, low-power wireless communication between ESP32 devices without requiring a Wi-Fi connection. This makes it ideal for battery-powered sensors or applications where Wi-Fi overhead would impact performance.
+
+> **Note:**  
+> ESP-NOW communication occurs independently of Wi-Fi. Devices can communicate via ESP-NOW even when Wi-Fi is disabled, making it suitable for power-sensitive applications.
+
+## Example Configuration
+
+```yaml
+# Example configuration entry
+espnow:
+  id: espnow_component
+
+packet_transport:
+  - platform: espnow
+    id: transport_unicast
+    espnow_id: espnow_component
+    peer_address: "AA:BB:CC:DD:EE:FF"
+    encryption:
+      key: "0123456789abcdef0123456789abcdef"
+    sensors:
+      - temp_sensor
+
+sensor:
+  - platform: internal_temperature
+    id: temp_sensor
+    name: "Test Temperature"
+```
+
+## Configuration Variables
+
+- **espnow_id** (**Required**, [ID](#config-id)): The esp-now ID to use for transport.
+- **peer_address** (*Optional*, MAC Address): MAC address to send packets to. This can be either a specific
+  peer address for point-to-point communication, or the broadcast address. Default FF:FF:FF:FF:FF:FF
+- All other options from the [Packet Transport Component](#packet-transport)
+
+> **Note:**  
+> Peers must be registered with the {{< docref "/components/espnow" >}} component before
+> they can receive packets. The `peer_address` only controls which peer(s) receive transmitted data;
+> incoming packets are accepted from all registered peers.
+
+## Broadcast vs Unicast
+
+The `peer_address` configuration determines the transmission mode.
+
+### Broadcast Mode (default)
+
+```yaml
+packet_transport:
+  - platform: espnow
+    sensors:
+      - sensor_id
+```
+
+All devices with the broadcast address (`FF:FF:FF:FF:FF:FF`) registered as a peer will receive the packets. This is useful for hub-and-spoke topologies where multiple devices monitor a single sensor source.
+
+> **Warning:**  
+> Using broadcast mode increases ESP-NOW traffic on the radio channel, which may impact performance of other ESP-NOW devices in range. Use specific peer addresses whenever possible to minimize interference.
+
+### Unicast Mode
+
+```yaml
+packet_transport:
+  - platform: espnow
+    peer_address: "AA:BB:CC:DD:EE:FF"
+    sensors:
+      - sensor_id
+```
+
+Only the specified peer receives the packets. This is more efficient for point-to-point communication and reduces radio channel congestion for neighboring ESP-NOW devices.
+
+## Simple Example
+
+This example shows two devices exchanging sensor data over ESP-NOW with encryption enabled.
+
+### Temperature Provider
+
+```yaml
+espnow:
+  peers:
+    - mac_address: "AA:BB:CC:DD:EE:01"  # Device 2
+
+packet_transport:
+  - platform: espnow
+    peer_address: "AA:BB:CC:DD:EE:01"  # Send to Device 2
+    encryption: "MySecretKey123"
+    sensors:
+      - outdoor_temp
+
+sensor:
+  - platform: ...
+    temperature:
+      name: "Outdoor Temperature"
+      id: outdoor_temp
+```
+
+### Temperature Consumer
+
+```yaml
+espnow:
+  peers:
+    - mac_address: "AA:BB:CC:DD:EE:00"  # Device 1
+
+packet_transport:
+  - platform: espnow
+    encryption: "MySecretKey123"
+    providers:
+      - name: temp-sensor
+
+sensor:
+  - platform: packet_transport
+    provider: temp-sensor
+    id: remote_temp
+    remote_id: outdoor_temp
+    name: "Remote Outdoor Temperature"
+```
+
+## Multi-Device Hub Example
+
+This example shows a central hub receiving sensor data from multiple remote devices.
+
+### Hub Device
+
+```yaml
+espnow:
+  peers:
+    - mac_address: "FF:FF:FF:FF:FF:FF"
+
+packet_transport:
+  - platform: espnow
+    encryption: "HubSecret123"
+    providers:
+      - name: room-sensor-1
+      - name: room-sensor-2
+      - name: outdoor-sensor
+
+sensor:
+  - platform: packet_transport
+    provider: room-sensor-1
+    remote_id: temperature
+    name: "Room 1 Temperature"
+
+  - platform: packet_transport
+    provider: room-sensor-2
+    remote_id: temperature
+    name: "Room 2 Temperature"
+
+  - platform: packet_transport
+    provider: outdoor-sensor
+    remote_id: temperature
+    name: "Outdoor Temperature"
+```
+
+### Remote Sensors
+
+```yaml
+espnow:
+  peers:
+    - mac_address: "FF:FF:FF:FF:FF:FF"
+
+packet_transport:
+  - platform: espnow
+    peer_address: "FF:FF:FF:FF:FF:FF"
+    encryption: "HubSecret123"
+    sensors:
+      - temperature
+
+sensor:
+  - platform: ...
+    temperature:
+      id: temperature
+```
+
+## See Also
+
+- [Packet Transport Component](#packet-transport)
+- {{< docref "/components/espnow" >}}
+- {{< docref "/components/binary_sensor/packet_transport" >}}
+- {{< docref "/components/sensor/packet_transport" >}}
+- [UDP Packet Transport](#udp-packet-transport)
+- [Automation](#automation)
+- {{< apiref "packet_transport/espnow_transport.h" "packet_transport/espnow_transport.h" >}}