README.md
1# TWAI Network Example
2
3(See the README.md file in the upper level 'examples' directory for more information about examples.)
4
5This example demonstrates how to use the TWAI driver to program a target (ESP32, ESP32-S2, ESP32-S3 or ESP32-C3) as a TWAI node, and have the two nodes (Network Master and Network Slave) communicate on a TWAI network. The Listen Only node is optional and acts as a network monitor meaning that it only receives messages and does not influence the bus in any way (i.e. doesn't not acknowledge or send error frames).
6
7Note that concept of master/slave in this example refers to which node initiates
8and stops the transfer of a stream of data messages.
9
10## How to use example
11
12### Hardware Required
13
14This example requires at least two targets (e.g., an ESP32 or ESP32-S2) to act as the Network Master and Network Slave. The third target (Listen Only) is optional. Each target must be connected to an external transceiver (e.g., a SN65HVD23X transceiver). The transceivers must then be interconnected to form a TWAI network.
15
16The following diagram illustrates an example network:
17
18```
19 ---------- ---------- --------------
20 | Master | | Slave | | Listen Only |
21 | | | | | |
22 | TX RX | | TX RX | | TX RX |
23 ---------- ---------- --------------
24 | | | | | |
25 | | | | | |
26 ---------- ---------- ----------
27 | D R | | D R | | D R |
28 | | | | | |
29 | VP230 | | VP230 | | VP230 |
30 | | | | | |
31 | H L | | H L | | H L |
32 ---------- ---------- ----------
33 | | | | | |
34 | | | | | |
35 |--x------|-----x------|-----x------|--| H
36 | | |
37 |---------x------------x------------x--| L
38
39```
40
41Note: If you don't have an external transceiver, you can still run the [TWAI Self Test example](../twai_self_test/README.md)
42
43### Configure the project
44
45For each node in the TWAI network (i.e., Master, Slave, Listen Only)...
46
47* Set the target of the build (where `{IDF_TARGET}` stands for the target chip such as `eszp32` or `esp32s2`).
48* Then run `menuconfig` to configure the example.
49
50```
51idf.py set-target {IDF_TARGET}
52idf.py menuconfig
53```
54
55* Under `Example Configuration`, configure the pin assignments using the options `TX GPIO Number` and `RX GPIO Number` according to how the target was connected to the transceiver. By default, `TX GPIO Number` and `RX GPIO Number` are set to the following values:
56 * On the ESP32, `TX GPIO Number` and `RX GPIO Number` default to `21` and `22` respectively
57 * On the ESP32-S2, `TX GPIO Number` and `RX GPIO Number` default to `20` and `21` respectively
58 * On the ESP32-S3, `TX GPIO Number` and `RX GPIO Number` default to `4` and `5` respectively
59 * On the ESP32-C3, `TX GPIO Number` and `RX GPIO Number` default to `2` and `3` respectively
60
61
62### Build and Flash
63
64For each node, build the project and flash it to the board, then run monitor tool to view serial output:
65
66```
67idf.py -p PORT flash monitor
68```
69
70(Replace PORT with the name of the serial port to use.)
71
72(To exit the serial monitor, type ``Ctrl-]``.)
73
74See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
75
76## Example Output
77
78Network Master
79```
80I (345) TWAI Master: Driver installed
81I (345) TWAI Master: Driver started
82I (345) TWAI Master: Transmitting ping
83I (3105) TWAI Master: Transmitted start command
84I (3105) TWAI Master: Received data value 339
85...
86I (5545) TWAI Master: Received data value 584
87I (5545) TWAI Master: Transmitted stop command
88I (5595) TWAI Master: Driver stopped
89I (6595) TWAI Master: Driver started
90I (6595) TWAI Master: Transmitting ping
91I (7095) TWAI Master: Transmitted start command
92I (7095) TWAI Master: Received data value 738
93...
94I (9535) TWAI Master: Received data value 983
95I (9535) TWAI Master: Transmitted stop command
96I (9585) TWAI Master: Driver stopped
97I (10585) TWAI Master: Driver started
98I (10585) TWAI Master: Transmitting ping
99I (11085) TWAI Master: Transmitted start command
100I (11085) TWAI Master: Received data value 1137
101...
102I (13525) TWAI Master: Received data value 1382
103I (13525) TWAI Master: Transmitted stop command
104I (13575) TWAI Master: Driver stopped
105I (14575) TWAI Master: Driver uninstalled
106```
107
108Network Slave
109```
110Slave starting in 3
111Slave starting in 2
112Slave starting in 1
113I (6322) TWAI Slave: Driver installed
114I (6322) TWAI Slave: Driver started
115I (6462) TWAI Slave: Transmitted ping response
116I (6712) TWAI Slave: Start transmitting data
117I (6712) TWAI Slave: Transmitted data value 339
118...
119I (9162) TWAI Slave: Transmitted data value 584
120I (9212) TWAI Slave: Transmitted stop response
121I (9312) TWAI Slave: Driver stopped
122I (10312) TWAI Slave: Driver started
123I (10452) TWAI Slave: Transmitted ping response
124I (10702) TWAI Slave: Start transmitting data
125I (10702) TWAI Slave: Transmitted data value 738
126...
127I (13152) TWAI Slave: Transmitted data value 983
128I (13202) TWAI Slave: Transmitted stop response
129I (13302) TWAI Slave: Driver stopped
130I (14302) TWAI Slave: Driver started
131I (14442) TWAI Slave: Transmitted ping response
132I (14692) TWAI Slave: Start transmitting data
133I (14692) TWAI Slave: Transmitted data value 1137
134...
135I (17142) TWAI Slave: Transmitted data value 1382
136I (17192) TWAI Slave: Transmitted stop response
137I (17292) TWAI Slave: Driver stopped
138I (18292) TWAI Slave: Driver uninstalled
139```
140
141Network Listen Only
142```
143I (326) TWAI Listen Only: Driver installed
144I (326) TWAI Listen Only: Driver started
145I (366) TWAI Listen Only: Received master ping
146...
147I (1866) TWAI Listen Only: Received master ping
148I (1866) TWAI Listen Only: Received slave ping response
149I (2116) TWAI Listen Only: Received master start command
150I (2116) TWAI Listen Only: Received data value 329
151...
152I (4566) TWAI Listen Only: Received data value 574
153I (4566) TWAI Listen Only: Received master stop command
154I (4606) TWAI Listen Only: Received slave stop response
155I (5606) TWAI Listen Only: Received master ping
156I (5856) TWAI Listen Only: Received master ping
157I (5856) TWAI Listen Only: Received slave ping response
158I (6106) TWAI Listen Only: Received master start command
159I (6106) TWAI Listen Only: Received data value 728
160...
161I (8556) TWAI Listen Only: Received data value 973
162I (8556) TWAI Listen Only: Received master stop command
163I (8596) TWAI Listen Only: Received slave stop response
164I (9596) TWAI Listen Only: Received master ping
165I (9846) TWAI Listen Only: Received master ping
166I (9846) TWAI Listen Only: Received slave ping response
167I (10096) TWAI Listen Only: Received master start command
168I (10096) TWAI Listen Only: Received data value 1127
169...
170I (12546) TWAI Listen Only: Received data value 1372
171I (12546) TWAI Listen Only: Received master stop command
172I (12586) TWAI Listen Only: Received slave stop response
173I (12586) TWAI Listen Only: Driver stopped
174I (12586) TWAI Listen Only: Driver uninstalled
175
176```
177
178## Example Breakdown
179
180The communication between the Network Master and Network Slave execute the following steps over multiple iterations:
181
1821. Both master and slave go through install and start their TWAI drivers independently.
1832. The master repeatedly sends **PING** messages until it receives a **PING_RESP** (ping response message) from the slave. The slave will only send a **PING_RESP** message when it receives a **PING** message from the master.
1843. Once the master has received the **PING_RESP** from the slave, it will send a **START_CMD** message to the slave.
1854. Upon receiving the **START_CMD** message, the slave will start transmitting **DATA** messages until the master sends a **STOP_CMD**. The master will send the **STOP_CMD** after receiving N **DATA** messages from the slave (N = 50 by default).
1865. When the slave receives the **STOP_CMD**, it will confirm that it has stopped by sending a **STOP_RESP** message to the master.
187
