typehints: Fixes for MicroPython v1.12 (Cellular x16, RF x0B)

Author: mikewadsten

typehints/common/sys.pyi

@@ -25,7 +25,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 argv: List[str] = ...
 byteorder: str = ...
-implementation: str = ...
+implementation: Tuple[str, Tuple[int, int, int], int] = ...
 maxsize: int = ...
 modules: Dict[str, Any] = ...  # technically [str, Module]
 path: List[str] = ...

typehints/common/ujson.pyi

@@ -18,7 +18,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from typing import Any
+from typing import Any, Union
 
 
 def dump(obj: Any, stream: Any) -> None:
@@ -56,11 +56,19 @@ def load(stream: Any) -> Any:
     """
     ...
 
-def loads(json_string: str) -> Any:
+def loads(json_string: Union[str, bytes, bytearray, memoryview]) -> Any:
     """
     Parses the given JSON string and returns a Python object. Raises
     ``ValueError`` if the string is not correctly formed.
 
+    **Note:** In MicroPython versions v1.11 and earlier, the ``json_string``
+    parameter is required to be of type ``str``. In newer version of
+    MicroPython, it must implement the buffer protocol (i.e. it must be
+    of type ``str``, ``bytes``, ``bytearray`` or ``memoryview``).
+    (The MicroPython version is visible in the banner displayed at the REPL,
+    using the **ATPYV** command, and as the second item in the
+    ``sys.implementation`` tuple.)
+
     :param json_string: String containing the JSON document to deserialise.
 
     :return: A Python object corresponding to the given JSON string.

typehints/common/umachine.pyi

@@ -372,12 +372,38 @@ class ADC(object):
 
     def read(self) -> int:
         """
-        Reads and returns a raw ADC sample. Use the following equation to
-        convert this value to mV::
+        Reads and returns a raw ADC sample with a range of 12 bits
+        (0 to 4095).
+
+        Use the following equation to convert this value to mV::
 
             sample mV = (A/D reading * Vref mV) / 4095
 
-        :return: A raw ADC sample
+        :return: A raw ADC sample in 12-bit range
+        """
+        ...
+
+    def read_u16(self) -> int:
+        """
+        Reads and returns a raw ADC sample with a range of 16 bits
+        (0 to 65535). This method is provided for compatibility with
+        other MicroPython implementations.
+
+        Since XBee devices only support 12-bit ADC readings,
+        readings from ``read_u16()`` will match those from ``read()``,
+        only scaled to a 16-bit range.
+
+        Use the following equation to convert this value to mV::
+
+            sample mV = (A/D reading * Vref mV) / 65535
+
+        **Note:**
+
+        The ``read_u16`` method is available on XBee Cellular and
+        XBee 3 Cellular products with version ending in 16 and newer,
+        and XBee 3 RF products with version ending in 0B and newer.
+
+        :return: A raw ADC sample in 16-bit range
         """
         ...