merge from upstream; working; includes debug_out code for debugging via Saleae for posterity

Author: dhalbert

.github/workflows/build.yml

@@ -36,7 +36,7 @@ jobs:
     - name: Install deps
       run: |
         sudo apt-get install -y eatmydata
-        sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64
+        sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64 latexmk texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra
         pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinx-autoapi sphinxcontrib-svg2pdfconverter polib pyyaml astroid isort black awscli
     - name: Versions
       run: |
@@ -73,12 +73,19 @@ jobs:
       with:
         name: stubs
         path: circuitpython-stubs*
-    - name: Docs
+    - name: Test Documentation Build (HTML)
       run: sphinx-build -E -W -b html -D version=${{ env.CP_VERSION }} -D release=${{ env.CP_VERSION }} . _build/html
     - uses: actions/upload-artifact@v2
       with:
         name: docs
         path: _build/html
+    - name: Test Documentation Build (LaTeX/PDF)
+      run: |
+        make latexpdf
+    - uses: actions/upload-artifact@v2
+      with:
+        name: docs
+        path: _build/latex
     - name: Translations
       run: make check-translate
     - name: New boards check
@@ -253,6 +260,7 @@ jobs:
         - "pca10100"
         - "pewpew10"
         - "pewpew_m4"
+        - "picoplanet"
         - "pirkey_m0"
         - "pitaya_go"
         - "pyb_nano_v2"

.gitignore

@@ -57,7 +57,7 @@ _build
 ######################
 genrst/
 /autoapi/
-/shared-bindings/**/*.rst
+/shared-bindings/*/**/*.rst
 
 # ctags and similar
 ###################
@@ -80,3 +80,8 @@ TAGS
 *.mo
 
 .vscode
+
+# Python Virtual Environments
+####################
+.venv
+.env

.gitmodules

@@ -147,3 +147,6 @@
 [submodule "ports/esp32s2/esp-idf"]
 	path = ports/esp32s2/esp-idf
 	url = https://github.com/tannewt/esp-idf.git
+[submodule "frozen/Adafruit_CircuitPython_RFM9x"]
+	path = frozen/Adafruit_CircuitPython_RFM9x
+	url = https://github.com/adafruit/Adafruit_CircuitPython_RFM9x.git

.readthedocs.yml

@@ -8,6 +8,13 @@
 
 version: 2
 
+submodules:
+    include:
+        - extmod/ulab
+
+formats:
+  - pdf
+
 python:
     version: 3
     install:

Makefile

@@ -245,6 +245,10 @@ stubs:
 	@$(PYTHON) tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR)
 	@$(PYTHON) setup.py -q sdist
 
+.PHONY: check-stubs
+check-stubs: stubs
+	MYPYPATH=$(STUBDIR) mypy --strict $(STUBDIR)
+
 update-frozen-libraries:
 	@echo "Updating all frozen libraries to latest tagged version."
 	cd frozen; for library in *; do cd $$library; ../../tools/git-checkout-latest-tag.sh; cd ..; done

conf.py

@@ -17,14 +17,17 @@
 #
 # SPDX-License-Identifier: MIT
 
-import json
 import logging
 import os
+import re
 import subprocess
 import sys
 import urllib.parse
 
 import recommonmark
+from sphinx.transforms import SphinxTransform
+from docutils import nodes
+from sphinx import addnodes
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -84,6 +87,7 @@
 autoapi_add_toctree_entry = False
 autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
 autoapi_template_dir = 'docs/autoapi/templates'
+autoapi_python_class_content = "both"
 autoapi_python_use_implicit_namespaces = True
 autoapi_root = "shared-bindings"
 
@@ -106,7 +110,25 @@
 #
 # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
 # breakdown, so use the same version identifier for both to avoid confusion.
-version = release = '0.0.0'
+
+final_version = ""
+git_describe = subprocess.run(
+    ["git", "describe", "--dirty", "--tags"],
+    stdout=subprocess.PIPE,
+    stderr=subprocess.STDOUT,
+    encoding="utf-8"
+)
+if git_describe.returncode == 0:
+    git_version = re.search(
+        r"^\d(?:\.\d){0,2}(?:\-(?:alpha|beta|rc)\.\d+){0,1}",
+        str(git_describe.stdout)
+    )
+    if git_version:
+        final_version = git_version[0]
+else:
+    print("Failed to retrieve git version:", git_describe.stdout)
+
+version = release = final_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -423,7 +445,38 @@ def generate_redirects(app):
             with open(redirected_filename, 'w') as f:
                 f.write(TEMPLATE % urllib.parse.quote(to_path, '#/'))
 
+
+class CoreModuleTransform(SphinxTransform):
+    default_priority = 870
+
+    def _convert_first_paragraph_into_title(self):
+        title = self.document.next_node(nodes.title)
+        paragraph = self.document.next_node(nodes.paragraph)
+        if not title or not paragraph:
+            return
+        if isinstance(paragraph[0], nodes.paragraph):
+            paragraph = paragraph[0]
+        if all(isinstance(child, nodes.Text) for child in paragraph.children):
+            for child in paragraph.children:
+                title.append(nodes.Text(" \u2013 "))
+                title.append(child)
+            paragraph.parent.remove(paragraph)
+
+    def _enable_linking_to_nonclass_targets(self):
+        for desc in self.document.traverse(addnodes.desc):
+            for xref in desc.traverse(addnodes.pending_xref):
+                if xref.attributes.get("reftype") == "class":
+                    xref.attributes.pop("refspecific", None)
+
+    def apply(self, **kwargs):
+        docname = self.env.docname
+        if docname.startswith(autoapi_root) and docname.endswith("/index"):
+            self._convert_first_paragraph_into_title()
+            self._enable_linking_to_nonclass_targets()
+
+
 def setup(app):
     app.add_css_file("customstyle.css")
     app.add_config_value('redirects_file', 'redirects', 'env')
     app.connect('builder-inited', generate_redirects)
+    app.add_transform(CoreModuleTransform)

devices/ble_hci/common-hal/_bleio/Adapter.c

@@ -280,7 +280,7 @@ STATIC void bleio_adapter_hci_init(bleio_adapter_obj_t *self) {
     const size_t len = sizeof(default_ble_name);
 
     bt_addr_t addr;
-    check_hci_error(hci_read_bd_addr(&addr));
+    hci_check_error(hci_read_bd_addr(&addr));
 
     default_ble_name[len - 4] = nibble_to_hex_lower[addr.val[1] >> 4 & 0xf];
     default_ble_name[len - 3] = nibble_to_hex_lower[addr.val[1] & 0xf];
@@ -373,7 +373,7 @@ void common_hal_bleio_adapter_set_enabled(bleio_adapter_obj_t *self, bool enable
     }
 
     // Enabling or disabling: stop any current activity; reset to known state.
-    check_hci_error(hci_reset());
+    hci_reset();
     self->now_advertising = false;
     self->extended_advertising = false;
     self->circuitpython_advertising = false;
@@ -397,7 +397,7 @@ bleio_address_obj_t *common_hal_bleio_adapter_get_address(bleio_adapter_obj_t *s
     check_enabled(self);
 
     bt_addr_t addr;
-    check_hci_error(hci_read_bd_addr(&addr));
+    hci_check_error(hci_read_bd_addr(&addr));
 
     bleio_address_obj_t *address = m_new_obj(bleio_address_obj_t);
     address->base.type = &bleio_address_type;
@@ -406,6 +406,14 @@ bleio_address_obj_t *common_hal_bleio_adapter_get_address(bleio_adapter_obj_t *s
     return address;
 }
 
+bool common_hal_bleio_adapter_set_address(bleio_adapter_obj_t *self, bleio_address_obj_t *address) {
+    mp_buffer_info_t bufinfo;
+    if (!mp_get_buffer(address->bytes, &bufinfo, MP_BUFFER_READ)) {
+        return false;
+    }
+    return hci_le_set_random_address(bufinfo.buf) == HCI_OK;
+}
+
 mp_obj_str_t* common_hal_bleio_adapter_get_name(bleio_adapter_obj_t *self) {
     return self->name;
 }
@@ -673,7 +681,7 @@ uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
         // Advertising interval.
         uint32_t interval_units = SEC_TO_UNITS(interval, UNIT_0_625_MS);
 
-        check_hci_error(
+        hci_check_error(
             hci_le_set_extended_advertising_parameters(
                 0,              // handle
                 props,          // adv properties
@@ -697,7 +705,7 @@ uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
         uint8_t handle[1] = { 0 };
         uint16_t duration_10msec[1] = { timeout * 100 };
         uint8_t max_ext_adv_evts[1] =  { 0 };
-        check_hci_error(
+        hci_check_error(
             hci_le_set_extended_advertising_enable(
                 BT_HCI_LE_ADV_ENABLE,
                 1,                // one advertising set.
@@ -725,7 +733,7 @@ uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
         // Advertising interval.
         uint16_t interval_units = SEC_TO_UNITS(interval, UNIT_0_625_MS);
 
-        check_hci_error(
+        hci_check_error(
             hci_le_set_advertising_parameters(
                 interval_units, // min interval
                 interval_units, // max interval
@@ -740,19 +748,19 @@ uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
         // even though the actual data length may be shorter.
         uint8_t full_data[MAX_ADVERTISEMENT_SIZE] = { 0 };
         memcpy(full_data, advertising_data, MIN(sizeof(full_data), advertising_data_len));
-        check_hci_error(hci_le_set_advertising_data(advertising_data_len, full_data));
+        hci_check_error(hci_le_set_advertising_data(advertising_data_len, full_data));
         memset(full_data, 0, sizeof(full_data));
         if (scan_response_data_len > 0) {
             memcpy(full_data, scan_response_data, MIN(sizeof(full_data), scan_response_data_len));
-            check_hci_error(hci_le_set_scan_response_data(scan_response_data_len, full_data));
+            hci_check_error(hci_le_set_scan_response_data(scan_response_data_len, full_data));
         }
 
         // No duration mechanism is provided for legacy advertising, so we need to do our own.
         self->advertising_timeout_msecs = timeout * 1000;
         self->advertising_start_ticks = supervisor_ticks_ms64();
 
         // Start advertising.
-        check_hci_error(hci_le_set_advertising_enable(BT_HCI_LE_ADV_ENABLE));
+        hci_check_error(hci_le_set_advertising_enable(BT_HCI_LE_ADV_ENABLE));
         self->extended_advertising = false;
     } // end legacy advertising setup
 
@@ -809,7 +817,7 @@ void common_hal_bleio_adapter_stop_advertising(bleio_adapter_obj_t *self) {
     // OK if we're already stopped. There seems to be an ESP32 HCI bug:
     // If advertising is already off, then LE_SET_ADV_ENABLE does not return a response.
     if (result != HCI_RESPONSE_TIMEOUT) {
-        check_hci_error(result);
+        hci_check_error(result);
     }
 
     //TODO startup CircuitPython advertising again.
@@ -942,5 +950,8 @@ void bleio_adapter_background(bleio_adapter_obj_t* adapter) {
         common_hal_bleio_adapter_stop_advertising(adapter);
     }
 
-    hci_poll_for_incoming_pkt();
+    hci_result_t result = hci_poll_for_incoming_pkt();
+    if (result != HCI_OK) {
+        mp_printf(&mp_plat_print, "bad hci_poll_for_incoming_pkt() result in background: %d\n", result);
+    }
 }

devices/ble_hci/common-hal/_bleio/__init__.c

@@ -43,43 +43,6 @@ bleio_uuid_obj_t cccd_uuid;
 
 bool vm_used_ble;
 
-void check_hci_error(hci_result_t result) {
-    switch (result) {
-        case HCI_OK:
-            return;
-
-        case HCI_RESPONSE_TIMEOUT:
-            mp_raise_bleio_BluetoothError(translate("Timeout waiting for HCI response"));
-            return;
-
-        case HCI_WRITE_TIMEOUT:
-            mp_raise_bleio_BluetoothError(translate("Timeout waiting to write HCI request"));
-            return;
-
-        case HCI_READ_ERROR:
-            mp_raise_bleio_BluetoothError(translate("Error reading from HCI adapter"));
-            return;
-
-        case HCI_WRITE_ERROR:
-            mp_raise_bleio_BluetoothError(translate("Error writing to HCI adapter"));
-            return;
-
-        case HCI_ATT_ERROR:
-            mp_raise_RuntimeError(translate("Error in ATT protocol code"));
-            return;
-
-        default:
-            // Should be an HCI status error, > 0.
-            if (result > 0) {
-                mp_raise_bleio_BluetoothError(translate("HCI status error: %02x"), result);
-            } else {
-                mp_raise_bleio_BluetoothError(translate("Unknown hci_result_t: %d"), result);
-            }
-            return;
-    }
-}
-
-
 // void check_sec_status(uint8_t sec_status) {
 //     if (sec_status == BLE_GAP_SEC_STATUS_SUCCESS) {
 //         return;

devices/ble_hci/common-hal/_bleio/__init__.h

@@ -53,12 +53,6 @@ typedef struct {
 #define BLE_GATTS_FIX_ATTR_LEN_MAX (510)  /**< Maximum length for fixed length Attribute Values. */
 #define BLE_GATTS_VAR_ATTR_LEN_MAX (512)  /**< Maximum length for variable length Attribute Values. */
 
-
-// These helpers raise the appropriate exceptions if the code doesn't equal success.
-void check_hci_error(hci_result_t result);
-void check_gatt_status(uint16_t gatt_status);
-void check_sec_status(uint8_t sec_status);
-
 // Track if the user code modified the BLE state to know if we need to undo it on reload.
 extern bool vm_used_ble;