From fadc71f7ed36890c09d538077f532537e0caaa6f Mon Sep 17 00:00:00 2001 From: "Earle F. Philhower, III" Date: Fri, 27 Sep 2019 07:51:16 -0700 Subject: [PATCH 1/3] Add info about installing python3 on Mac, Linux The Mac requires special handholding to allow SSL connections for get.py, so document those for end users. --- doc/installing.rst | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/installing.rst b/doc/installing.rst index 1c6317d2bd..6e4728aecf 100644 --- a/doc/installing.rst +++ b/doc/installing.rst @@ -12,6 +12,7 @@ Prerequisites - Arduino 1.6.8, get it from `Arduino website `__. - Internet connection +- Python 3 interpreter (Mac/Linux only, Windows installation supplies its own) Instructions ~~~~~~~~~~~~ @@ -186,9 +187,33 @@ Instructions - Other OS cd esp8266/tools python3 get.py + If you get an error message stating that python3 is not found, you will need to install it (most modern UNIX-like OSes provide Python 3 as + part of the default install). To install you will need to use ``sudo yum install python3``, ``sudo apt install python3``, or ``brew install python3`` + as appropriate. On the Mac you may get an error message like: + + .. code:: bash + + python3 get.py + Platform: x86_64-apple-darwin + Downloading python3-macosx-placeholder.tar.gz + Traceback (most recent call last): + File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/urllib/request.py", line 1317, in do_open + encode_chunked=req.has_header('Transfer-encoding')) + ... + File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/ssl.py", line 1117, in do_handshake + self._sslobj.do_handshake() + ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1056) + + This is because Homebrew on the Mac does not always install the required SSL certificates by default. Install them manually (adjust the Python 3.7 as needed) with: + + .. code:: bash + + cd "/Applications/Python 3.7/" && sudo "./Install Certificates.command" + + - Restart Arduino -- When later updating your local library, goto the esp8266 directory and do a git pull +- When later updating your local library, goto the esp8266 directory and do a git pull .. code:: bash From 3ba69e9491555fa3f1b1efaa6e73935736f79719 Mon Sep 17 00:00:00 2001 From: "Earle F. Philhower, III" Date: Fri, 27 Sep 2019 14:28:47 -0700 Subject: [PATCH 2/3] Add interrupt section to docs Adds a section on interrupts to the docs and lists the restrictions and warnings about running long tasks. Fixes #6428 --- doc/reference.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/doc/reference.rst b/doc/reference.rst index 29ae74e375..03f784f1aa 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -1,6 +1,27 @@ Reference ========= +Interrupts +---------- + +Interrupts can be used on the ESP8266, but they must be used with care +and have several limitations: + +* Interrupt callback functions must be in IRAM, because the flash may be + in the middle of other operations when they occur. Do this by adding + the ``ICACHE_RAM_ATTR`` attribute on the function definition. + +* Interrupts should not perform delay() or any long-running (>1ms) task. + WiFi and other portiong of the code can become unstable if interrupts + are blocked by a long-running interrupt. If you have much to do, you can + set a volatile global flag that your main ``loop()`` can check each pass + or use a scheduled function (which will be called by the OS when it is + safe, and not at IRQ level) to do the work. + +* Memory operations can be dangerous and avoided in interrupts. Calls to + ``new`` or ``malloc`` should be minimized, and calls to ``realloc`` and + ``free`` must NEVER be used. + Digital IO ---------- From 33d5f98f03e1d9f8914945b7782cd8648fbcbcdb Mon Sep 17 00:00:00 2001 From: "Earle F. Philhower, III" Date: Fri, 27 Sep 2019 16:47:55 -0700 Subject: [PATCH 3/3] Update per review comments --- doc/reference.rst | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index 03f784f1aa..db789128e6 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -9,18 +9,33 @@ and have several limitations: * Interrupt callback functions must be in IRAM, because the flash may be in the middle of other operations when they occur. Do this by adding - the ``ICACHE_RAM_ATTR`` attribute on the function definition. - -* Interrupts should not perform delay() or any long-running (>1ms) task. - WiFi and other portiong of the code can become unstable if interrupts + the ``ICACHE_RAM_ATTR`` attribute on the function definition. If this + attribute is not present, the sketch will crash when it attempts to + ``attachInterrupt`` with an error message. + +.. code:: cpp + + ICACHE_RAM_ATTR void gpio_change_handler(void *data) {... + +* Interrupts must not call ``delay()`` or ``yield()``, or call any routines + which internally use ``delay()`` or ``yield()`` either. + +* Long-running (>1ms) tasks in interrupts will cause instabilty or crashes. + WiFi and other portions of the core can become unstable if interrupts are blocked by a long-running interrupt. If you have much to do, you can set a volatile global flag that your main ``loop()`` can check each pass - or use a scheduled function (which will be called by the OS when it is - safe, and not at IRQ level) to do the work. - -* Memory operations can be dangerous and avoided in interrupts. Calls to - ``new`` or ``malloc`` should be minimized, and calls to ``realloc`` and - ``free`` must NEVER be used. + or use a scheduled function (which will be called outside of the interrupt + context when it is safe) to do long-running work. + +* Memory operations can be dangerous and should be avoided in interrupts. + Calls to ``new`` or ``malloc`` should be minimized because they may require + a long running time if memory is fragmented. Calls to ``realloc`` and + ``free`` must NEVER be called. Using any routines or objects which call + ``free`` or ``realloc`` themselves is also forbidden for the same reason. + This means that ``String``, ``std::string``, ``std::vector`` and other + classes which use contiguous memory that may be resized must be used with + extreme care (ensuring strings aren't changed, vector elements aren't + added, etc.). Digital IO ----------