1# TWAI Alert and Recovery 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 alert and bus recovery features of the TWAI driver. The alert feature allows the TWAI driver to notify the application layer of certain TWAI driver or bus events. The bus recovery feature is used to recover the TWAI driver after it has entered the Bus-Off state. See the TWAI driver reference for more details.
6
7## How to use example
8
9### Hardware Required
10
11This example requires only a single target (e.g., an ESP32 or ESP32-S2). The target must be connected to an external transceiver (e.g., a SN65HVD23X transceiver). This connection usually consists of a TX and an RX signal.
12
13Note: If you don't have an external transceiver, this example can still be run by simply connecting the TX GPIO and RX GPIO with a jumper.
14
15### Configure the project
16
17* Set the target of the build (where `{IDF_TARGET}` stands for the target chip such as `esp32`, `esp32s2`, `esp32s2` or `esp32c3`).
18* Then run `menuconfig` to configure the example.
19
20```
21idf.py set-target {IDF_TARGET}
22idf.py menuconfig
23```
24
25* 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:
26    * On the ESP32, `TX GPIO Number` and `RX GPIO Number` default to `21` and `22` respectively
27    * On the ESP32-S2, `TX GPIO Number` and `RX GPIO Number` default to `20` and `21` respectively
28    * On the ESP32-S3, `TX GPIO Number` and `RX GPIO Number` default to `4` and `5` respectively
29    * On the ESP32-C3, `TX GPIO Number` and `RX GPIO Number` default to `2` and `3` respectively
30
31### Build and Flash
32
33Build the project and flash it to the board, then run monitor tool to view serial output:
34
35```
36idf.py -p PORT flash monitor
37```
38
39(Replace PORT with the name of the serial port to use.)
40
41(To exit the serial monitor, type ``Ctrl-]``.)
42
43See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
44
45## Example Output
46
47```
48I (330) TWAI Alert and Recovery: Driver installed
49I (340) TWAI Alert and Recovery: Driver started
50I (340) TWAI Alert and Recovery: Starting transmissions
51W (350) TWAI Alert and Recovery: Trigger TX errors in 3
52W (1350) TWAI Alert and Recovery: Trigger TX errors in 2
53W (2350) TWAI Alert and Recovery: Trigger TX errors in 1
54I (3350) TWAI Alert and Recovery: Trigger errors
55I (3650) TWAI Alert and Recovery: Surpassed Error Warning Limit
56I (3650) TWAI Alert and Recovery: Entered Error Passive state
57I (4300) TWAI Alert and Recovery: Bus Off state
58W (4300) TWAI Alert and Recovery: Initiate bus recovery in 3
59W (5300) TWAI Alert and Recovery: Initiate bus recovery in 2
60W (6300) TWAI Alert and Recovery: Initiate bus recovery in 1
61I (7300) TWAI Alert and Recovery: Initiate bus recovery
62I (7350) TWAI Alert and Recovery: Bus Recovered
63I (7350) TWAI Alert and Recovery: Driver uninstalled
64```
65
66## Troubleshooting
67
68```
69I (3350) TWAI Alert and Recovery: Trigger errors
70```
71
72If the example does not progress pass triggering errors, check that the target is correctly connected to the transceiver.
73
74```
75I (3350) TWAI Alert and Recovery: Trigger errors
76I (3650) TWAI Alert and Recovery: Surpassed Error Warning Limit
77I (3650) TWAI Alert and Recovery: Entered Error Passive state
78```
79
80If the example is able to trigger errors but does not enter the bus off state (i.e., stays in the error passive state), check that the triggering of the bit error is properly set to the examples operating bit rate. By default, the example runs at a bit rate of 125kbits/sec, and the bit error should be triggered after the arbitration phase of each transmitted message.
81
82## Example Breakdown
83
84The TWAI Alert and Recovery Example will do the following...
85
861. Initialize the TWAI driver in No Acknowledgement mode (so that another node is not required).
872. Create a transmit task to handle message transmission, and a control task to handle alerts.
883. Control task starts the TWAI driver, then reconfigures the alerts to trigger when the error passive or bus off state is entered. The control task then waits for those alerts.
894. The transmit repeatedly transmits single shot messages (i.e., message won't be retried if an error occurs).
905. When a message is being transmitted, the transmit task will purposely invert the TX pin to trigger a bit error. **Note that the triggering of the bit error is timed to occur after the arbitration phase of the transmitted message**.
916. The triggering of a bit error on each transmitted message eventually puts the TWAI driver into the Bus-Off state.
927. Control tasks detects the Bus-Off state via an alert, and triggers the Bus-Off recovery process after a short delay. Alerts are also reconfigured to trigger on the completion of Bus-Off recovery.
938. Once the Bus-Off recovery completion alert is detected by the control task, the TWAI driver is stopped and uninstalled.
94