From a85fb6a1cf50df1cb696ec22a34d30d56ef0535a Mon Sep 17 00:00:00 2001
From: "Irene Siu (Apple)" <irene_siu@apple.com>
Date: Fri, 29 Apr 2022 11:29:27 -0700
Subject: [PATCH] [chip-tool] Update chip-tool documentation to add info on
 interactive mode and timeout (#17874)

* Update chip-tool documentation to add info on interactive mode and timeout.

* Update actual node id value in example command to ${NODE_ID}

* Add --timeout to the documentation.

* Fix typo: bu -> by
---
 docs/guides/chip_tool_guide.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md
index 461d7322864724..d81c35c8dcb793 100644
--- a/docs/guides/chip_tool_guide.md
+++ b/docs/guides/chip_tool_guide.md
@@ -391,6 +391,40 @@ $ ./chip-tool basic
 This section contains a general list of various CHIP Tool commands and options,
 not limited to commissioning procedure and cluster interaction.
 
+### Interactive mode versus single command mode
+
+By default, chip-tool runs in single command mode where if any single command
+does not complete within a certain timeout period, chip-tool will exit with a
+timeout error.
+
+Example of error:
+
+```
+[1650992689511] [32397:1415601] CHIP: [TOO] Run command failure: ../../../examples/chip-tool/commands/common/CHIPCommand.cpp:392: CHIP Error 0x00000032: Timeout
+```
+
+This timeout can be modified for any command execution by supplying the optional
+`--timeout` parameter, which takes a value in seconds, with the maximum being
+65535 seconds.
+
+Example of command:
+
+```
+$ ./chip-tool otasoftwareupdaterequestor subscribe-event state-transition 5 10 0x1234567890 0 --timeout 65535
+```
+
+For commands such as event subscriptions that need to run for an extended period
+of time, chip-tool can be started in interactive mode first before running the
+command. In interactive mode, there will be no timeout and multiple commands can
+be issued.
+
+Example of command:
+
+```
+$ ./chip-tool interactive start
+otasoftwareupdaterequestor subscribe-event state-transition 5 10 ${NODE_ID} 0
+```
+
 ### Printing all supported clusters
 
 To print all clusters supported by the CHIP Tool, run the following command: