From 56310513788f3f27f5a77a6a20c64ebd34e5dee8 Mon Sep 17 00:00:00 2001 From: Martin Berka Date: Wed, 2 Dec 2020 01:14:14 -0800 Subject: [PATCH] Update a02-my-esp-crashes.rst (#7739) Fixes formatting of bulleted list in Stack section, and misc typos/wording. --- doc/faq/a02-my-esp-crashes.rst | 58 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/doc/faq/a02-my-esp-crashes.rst b/doc/faq/a02-my-esp-crashes.rst index aeedc8d5e2..c2433b5931 100644 --- a/doc/faq/a02-my-esp-crashes.rst +++ b/doc/faq/a02-my-esp-crashes.rst @@ -65,12 +65,12 @@ If you are using generic ESP modules, please follow `recommendations `__ on power supply and boot strapping resistors. -For boards with integrated USB to serial converter and power supply, +For boards with integrated USB-to-serial converter and power supply, usually it is enough to connect it to an USB hub that provides standard 0.5A and is not shared with other USB devices. -In any case make sure that your module is able to stable run standard -example sketches that establish Wi-Fi connection like e.g. +In any case, make sure that your module is able to stably run standard +example sketches that establish Wi-Fi connection like, e.g., `HelloServer.ino `__. What is the Cause of Restart? @@ -82,13 +82,13 @@ is wrong, it restarts itself to tell you about it. There are two typical scenarios that trigger ESP restarts: -- **Exception** - when code is performing `illegal +- **Exception** - when the code attempts an `illegal operation <../exception_causes.rst>`__, like trying to write to non-existent memory location. -- **Watchdog** - if code is `locked - up `__ staying too long - in a loop or processing some task, so vital processes like Wi-Fi - communication are not able to run. +- **Watchdog** - if the code `locks + up `__, staying too long + in a loop or processing any other task without any pauses, which would + prevent vital processes like Wi-Fi communication from running. Please check below how to recognize `exception <#exception>`__ and `watchdog <#watchdog>`__ scenarios and what to do about it. @@ -127,7 +127,7 @@ up. `SDK `__, that is part of `esp8266 / arduino `__ core loaded to module together with your application. -- **Hardware Watchdog** - build in ESP8266 hardware and acting if +- **Hardware Watchdog** - built-in ESP8266 hardware, acting if the software watchdog is disabled for too long, in case it fails, or if it is not provided at all. @@ -312,9 +312,10 @@ Memory, memory, memory Stack   The amount of stack in the ESP is tiny at only 4KB. For normal development in large systems, it is good practice to use and abuse the stack, because it is faster for allocation/deallocation, the scope of the object is well defined, and deallocation automatically happens in reverse order as allocation, which means no mem fragmentation. However, with the tiny amount of stack available in the ESP, that practice is not really viable, at least not for big objects. + * Large objects that have internally managed memory, such as String, std::string, std::vector, etc, are ok on the stack, because they internally allocate their buffers on the heap. - * Large arrays on the stack, such as uint8_t buffer[2048] should be avoided on the stack and be dynamically allocated (consider smart pointers). - * Objects that have large data members, such as large arrays, should be avoided on the stack, and be dynamically allocated (consider smart pointers). + * Large arrays on the stack, such as uint8_t buffer[2048] should be avoided on the stack and should be dynamically allocated instead (consider smart pointers). + * Objects that have large data members, such as large arrays, should also be avoided on the stack, and should be dynamically allocated (consider smart pointers). If at the Wall, Enter an Issue Report @@ -330,37 +331,38 @@ author of code in his / her repository. If there are no guidelines, include in your report the following: -- [ ] Exact steps by step instructions to reproduce the issue +- [ ] Exact step-by-step instructions to reproduce the issue - [ ] Your exact hardware configuration including the schematic -- [ ] If the issue concerns standard, commercially available ESP board +- [ ] If the issue concerns a standard, commercially available ESP board with power supply and USB interface, without extra h/w attached, then - provide just the board type or link to description + provide just the board type or a link to its description - [ ] Configuration settings in Arduino IDE used to upload the application - [ ] Error log & messages produced by the application (enable debugging for more details) - [ ] Decoded stack trace - [ ] Copy of your sketch -- [ ] Copy of all the libraries used by the sketch -- [ ] If you are using standard libraries available in Library Manager, - then provide just version numbers +- [ ] Copy of all the libraries used by the sketch (if you are using + standard libraries available in the Arduino Library Manager, + then provide just version numbers) - [ ] Version of `esp8266 / Arduino `__ core - [ ] Name and version of your programming IDE and O/S With plenty of ESP module types available, several versions of libraries or `esp8266 / Arduino `__ core, -types and versions of O/S, you need to provide exact information what -your application is about. Only then people willing to look into your -issue may be able to refer it to configuration they have. If you are -lucky, they may even attempt to reproduce your issue on their equipment. -This will be far more difficult if you are providing only vague details, +types and versions of O/S, you need to provide exact information on what +your application is about. Only then, people willing to look into your +issue may be able to compare it to a configuration they are familiar with. +If you are lucky, they may even attempt to reproduce your issue on their +own equipment! +This will be far more difficult if you provide only vague details, so somebody would need to ask you to find out what is really happening. -On the other hand if you flood your issue report with hundreds lines of -code, you may also have difficulty to find somebody willing to analyze -it. Therefore reduce your code to the bare minimum that is still causing -the issue. It will help you as well to isolate the issue and pin done +On the other hand, if you flood your issue report with hundreds lines of +code, you may also have difficulty finding somebody willing to analyze +it. Therefore, reduce your code to the bare minimum that is still causing +the issue. This will also help to isolate the issue and pin down the root cause. Conclusion @@ -371,8 +373,8 @@ Do not be afraid to troubleshoot ESP exception and watchdog restarts. detailed diagnostics that will help you pin down the issue. Before checking the s/w, get your h/w right. Use `ESP Exception Decoder `__ to find -out where the code fails. If you do you homework and still unable to -identify the root cause, enter the issue report. Provide enough details. +out where the code fails. If you do you homework and are still unable to +identify the root cause, submit an issue report. Provide enough details. Be specific and isolate the issue. Then ask community for support. There are plenty of people that like to work with ESP and willing to help with your problem.