Skip to content

Commit 65f811e

Browse files
geza-pycomgeza-pycom
committed
Update ESP-NOW documentation as per review findings
1 parent 3c4c862 commit 65f811e

3 files changed

Lines changed: 224 additions & 39 deletions

File tree

‎config.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,13 @@ theme = "doc-theme"
506506
parent = "tutorials@all"
507507
weight = 180
508508

509+
[[menu.main]]
510+
name = "ESP-NOW"
511+
url = "/tutorials/all/espnow/"
512+
identifier = "tutorials@all@espnow"
513+
parent = "tutorials@all"
514+
weight = 190
515+
509516
[[menu.main]]
510517
name = "LoRa Examples"
511518
url = "/tutorials/lora/"

‎content/firmwareapi/pycom/network/espnow.md‎

Lines changed: 10 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ aliases:
55
- firmwareapi/pycom/network/espnow.md
66
- chapter/firmwareapi/pycom/network/espnow
77
---
8-
This module implements interface to ESP-NOW protocol.
8+
This module implements interface to ESP-NOW protocol: https://www.espressif.com/en/products/software/esp-now/overview
99

1010
## Usage Example
1111

@@ -35,56 +35,27 @@ def espnow_rx(result):
3535
# "peer" is the Peer which the message has been received from. If message has been received from a not registered Peer this parameter is None
3636
# "msg" is the payload from the received message
3737
mac, peer, msg = result
38-
if(peer is None):
39-
print("Message received from an unknown Peer, registering...")
40-
peer = ESPNOW.add_peer(mac)
41-
print("Message received from %s with content: %s" % (binascii.hexlify(mac), msg))
42-
peer.send("Sending back an answer")
38+
if(peer is not None):
39+
print("Message received from %s with content: %s" % (binascii.hexlify(mac), msg))
40+
peer.send("Sending back an answer")
4341

4442
# The ESPNOW module needs that WLAN is initialized
4543
w = WLAN()
4644
# Initialize the ESPNOW module
4745
ESPNOW.init()
48-
print("ESP-NOW version: %s" % ESPNOW.version())
4946

5047
# Register the callback which will be called on TX
5148
ESPNOW.on_send(espnow_tx)
5249
# Register the callback which will be called on RX
5350
ESPNOW.on_recv(espnow_rx)
54-
# Configure the Primary Master Key which is used to encrypt the Local Master Key
55-
ESPNOW.pmk('0123456789abcdef')
5651

5752
# Add a dedicated Peer with MAC address: 11:22:33:44:55:66
58-
p1 = ESPNOW.add_peer("112233445566")
59-
# Add a dedicated Peer with MAC address: 66:55:44:33:22:11
60-
p2 = ESPNOW.add_peer("665544332211")
61-
# Set the Local Master Key of Peer p1
62-
p1.lmk(b'0123456789123456')
63-
# Do not set LMK for p2, traffic is not encrypted
64-
65-
# Get the number of registered Peers and how many is encrypted
66-
count = ESPNOW.peer_count()
67-
print("Number of Peers: %s, encrypted: %s" % (count[0], count[1]))
68-
69-
# Sending some messages to the Peers individually
70-
i = 0
71-
while i < 10:
72-
# The Peer p1 will only receive this message if the same LMK is configured for the Peer object created for this device on the other device also
73-
p1.send("%s" % (i))
74-
# Message to p2 is not encrypted, on the p2 device encryption for this current device's Peer object should not be configured
75-
p2.send("%s" % (i))
76-
i = i + 1
77-
time.sleep(1)
78-
53+
p = ESPNOW.add_peer("112233445566")
54+
# Send a message dedicated to the Peer
55+
p.send("My Message")
7956
# Sending 1 message to all Peers which are registered
8057
ESPNOW.send(None, "Hello all Peers!")
8158

82-
# Remove 1 Peer
83-
ESPNOW.del_peer(p1)
84-
85-
# Deinit the module
86-
ESPNOW.deinit()
87-
8859
```
8960

9061
## Initialization
@@ -105,7 +76,7 @@ Configures the Primary Master Key which is used to encrypt the Local Master Key.
10576

10677
* `pmk` is the Primary Master Key to be configured.
10778

108-
The PMK specified by `pmk` is accepted in format of Byte array with length 16.
79+
The PMK specified by `pmk` is accepted in format of string with length 16.
10980

11081
#### ESPNOW.send(addr, msg)
11182

@@ -147,7 +118,7 @@ Creates a new Peer object and registers it into ESP-NOW module.
147118
* `addr` is the MAC address of the Peer to be created. MAC address is accepted in either String format or as a Byte array.
148119
* `lmk` is the Local Master Key to be used when communicating with the Peer. By default it is None which means the communication will not be encrypted.
149120

150-
The LMK specified by `lmk` is accepted in format of Byte array with length 16.
121+
The LMK specified by `lmk` is accepted in format of string with length 16.
151122

152123
This function returns with an `ESPNOW_Peer` object.
153124

@@ -171,7 +142,7 @@ Configures or returns the Local Master Key of the Peer.
171142
* `lmk` is the new LMK to be set to this Peer.
172143

173144
If `lmk` is not used then this functions returns the LMK of the Peer.
174-
The LMK specified by `lmk` is accepted in format of Byte array with length 16.
145+
The LMK specified by `lmk` is accepted in format of string with length 16.
175146

176147
#### ESPNOW_Peer.send(msg)
177148

‎content/tutorials/all/espnow.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: ""
3+
aliases:
4+
- tutorials/all/ESP-NOW.html
5+
- tutorials/all/espnow.md
6+
---
7+
8+
Detailed information about this class can be found in [espnow](/firmwareapi/pycom/network/espnow).
9+
10+
### Sending and receiving messages to/from 2 remote devices: Peer 1 and Peer 2
11+
12+
The following example sets up a device which communicates with 2 remote Peers. Message exchange with Peer 1 is encrypted while with Peer 2 it is not.
13+
14+
```python
15+
16+
from network import WLAN
17+
from network import ESPNOW
18+
import binascii
19+
import time
20+
21+
# Modify this variable to change the PMK to be used
22+
# Note: This must match with the value of ESPNOW_PMK from the next example.
23+
ESPNOW_PMK = "0123456789abcdef"
24+
# Modify this variable to change the MAC address of the remote Peer 1
25+
# Note: This must match with the MAC address of the Peer 1 from the next example.
26+
ESPNOW_PEER_1_MAC = "112233445566"
27+
# Modify this variable to change the LMK to be used when communicating with remote Peer 1
28+
# Note: This must match with the value of ESPNOW_PEER_LMK from the next example.
29+
ESPNOW_PEER_1_LMK = "0123456789123456"
30+
# Modify this variable to change the MAC address of the remote Peer 2
31+
# Note: This must match with the MAC address of the Peer 2 from the next example.
32+
ESPNOW_PEER_2_MAC = "AABBCCDDEEFF"
33+
34+
35+
# The callback to be registered when a message has been sent to a Peer
36+
def espnow_tx(result):
37+
# "result" is the parameter in form of 2 element long tuple
38+
# "peer" is the Peer which the message has been sent to
39+
# "sent" is a boolean showing whether the message could be sent
40+
peer, sent = result
41+
mac = peer.addr()
42+
if(sent == False):
43+
print("Sending message to %s failed!" % binascii.hexlify(mac))
44+
else:
45+
print("Message sent to: %s" % (binascii.hexlify(mac)))
46+
47+
# The callback to be registered when a message has been received
48+
def espnow_rx(result):
49+
# "result" is the parameter in form of 3 element long tuple
50+
# "mac" is the MAC address of the sender
51+
# "peer" is the Peer which the message has been received from. If message has been received from a not registered Peer this parameter is None
52+
# "msg" is the payload from the received message
53+
mac, peer, msg = result
54+
# Accept and handle messages only from the registered Peers
55+
if(peer is not None):
56+
# Do something with the received message
57+
print("Message received from %s with content: %s" % (binascii.hexlify(mac), msg))
58+
59+
# The ESPNOW module needs that WLAN is initialized
60+
w = WLAN()
61+
# Initialize the ESPNOW module
62+
ESPNOW.init()
63+
print("ESP-NOW version: %s" % ESPNOW.version())
64+
65+
# Register the callback which will be called on TX
66+
ESPNOW.on_send(espnow_tx)
67+
# Register the callback which will be called on RX
68+
ESPNOW.on_recv(espnow_rx)
69+
# Configure the Primary Master Key which is used to encrypt the Local Master Key
70+
ESPNOW.pmk(ESPNOW_PMK)
71+
72+
# Add Peer 1
73+
p1 = ESPNOW.add_peer(ESPNOW_PEER_1_MAC)
74+
# Add Peer 2
75+
p2 = ESPNOW.add_peer(ESPNOW_PEER_2_MAC)
76+
# Set the Local Master Key of Peer p1
77+
p1.lmk(ESPNOW_PEER_1_LMK)
78+
# Do not set LMK for Peer 2, traffic is not encrypted
79+
80+
# Get the number of registered Peers and how many is encrypted
81+
count = ESPNOW.peer_count()
82+
print("Number of Peers: %s, encrypted: %s" % (count[0], count[1]))
83+
84+
# Sending some messages to the Peers individually
85+
i = 0
86+
while i < 10:
87+
# The Peer 1 will only receive this message if the same PMK and LMK is configured for the Peer object created for this device on the other device also. Check the next examples.
88+
p1.send("%s" % (i))
89+
# Message to Peer 2 is not encrypted, on the Peer 2 device encryption for this current device's Peer object should not be configured. Check the next examples.
90+
p2.send("%s" % (i))
91+
i = i + 1
92+
time.sleep(1)
93+
94+
# Sending 1 message to all Peers which are registered
95+
ESPNOW.send(None, "Hello all Peers!")
96+
97+
# Remove Peer 1
98+
ESPNOW.del_peer(p1)
99+
100+
# Deinit the module
101+
ESPNOW.deinit()
102+
103+
```
104+
105+
### Example code for Peer 1
106+
This example code implements Peer 1 device from the previous example.
107+
108+
```python
109+
from network import WLAN
110+
from network import ESPNOW
111+
import binascii
112+
import time
113+
114+
# Modify this variable to change the PMK to be used
115+
# Note: This must match with the value of ESPNOW_PMK from the first example.
116+
ESPNOW_PMK = "0123456789abcdef"
117+
# Modify this variable to change the MAC address of the remote Peer.
118+
# Note: This must match with the MAC address of the Peer from the first example.
119+
ESPNOW_PEER_MAC = "665544332211"
120+
# Modify this variable to change the LMK to be used when communicating with the remote Peer
121+
# Note: This must match with the value of ESPNOW_PEER_1_LMK from the first example.
122+
ESPNOW_PEER_LMK = "0123456789123456"
123+
124+
def tx(result):
125+
peer, sent = result
126+
mac = peer.addr()
127+
print("Sending to: %s - %r" % (binascii.hexlify(mac),sent))
128+
129+
def rx(result):
130+
print("Message received:")
131+
mac, peer, msg = result
132+
# Accept messages only from the registered Peer
133+
if(peer is not None):
134+
print("Received: %s - %s" % (binascii.hexlify(mac),msg))
135+
# Send back a response
136+
peer.send("Message received: %s" % msg)
137+
138+
w = WLAN()
139+
ESPNOW.init()
140+
ESPNOW.on_send(tx)
141+
ESPNOW.on_recv(rx)
142+
ESPNOW.pmk(ESPNOW_PMK)
143+
144+
# Add the Peer
145+
p = ESPNOW.add_peer(ESPNOW_PEER_MAC)
146+
# Configure the LMK to be used during communication.
147+
p.lmk(ESPNOW_PEER_LMK)
148+
149+
```
150+
151+
### Example code for Peer 2
152+
This example code implements Peer 2 device from the first example.
153+
154+
```python
155+
from network import WLAN
156+
from network import ESPNOW
157+
import binascii
158+
import time
159+
160+
# Modify this variable to change the MAC address of the remote Peer.
161+
# Note: This must match with the MAC address of the Peer from the first example.
162+
ESPNOW_PEER_MAC = "665544332211"
163+
164+
def tx(result):
165+
peer, sent = result
166+
mac = peer.addr()
167+
print("Sending to: %s - %r" % (binascii.hexlify(mac),sent))
168+
169+
def rx(result):
170+
print("Message received:")
171+
mac, peer, msg = result
172+
# Accept messages only from the registered Peer
173+
if(peer is not None):
174+
print("Received: %s - %s" % (binascii.hexlify(mac),msg))
175+
# Send back a response
176+
peer.send("Message received: %s" % msg)
177+
178+
w = WLAN()
179+
# Init ESP-NOW, no PMK is configured.
180+
ESPNOW.init()
181+
ESPNOW.on_send(tx)
182+
ESPNOW.on_recv(rx)
183+
184+
# Add the Peer. No LMK will be configured for it.
185+
p = ESPNOW.add_peer(ESPNOW_PEER_MAC)
186+
187+
```
188+
189+
### Example snippet for RX callback
190+
This example snippet shows how it may be handled when the device receives a message from a previously not registered Peer.
191+
192+
```python
193+
194+
# The callback to be registered when a message has been received
195+
def espnow_rx(result):
196+
# "result" is the parameter in form of 3 element long tuple
197+
# "mac" is the MAC address of the sender
198+
# "peer" is the Peer which the message has been received from. If message has been received from a not registered Peer this parameter is None
199+
# "msg" is the payload from the received message
200+
mac, peer, msg = result
201+
if(peer is None):
202+
print("Message received from an unknown Peer, registering...")
203+
peer = ESPNOW.add_peer(mac)
204+
print("Message received from %s with content: %s" % (binascii.hexlify(mac), msg))
205+
peer.send("Sending back an answer...")
206+
207+
```

0 commit comments

Comments
 (0)