Release new typehints and samples for XBee (3) Cellular x16 firmware

samples/bluetooth/pairing/README.md

@@ -0,0 +1,83 @@
+Bluetooth Pairing Sample Application
+============================================================
+
+This example demonstrates performing pairing to secure the BLE
+connection to another BLE device. 
+
+Requirements
+------------
+
+To run this example you need:
+
+* One XBee3 radio module with MicroPython support.
+* One carrier board for the radio module (XBIB-U-DEV or XBIB-C board).
+* A peripheral BLE device to connect to which supports pairing.
+
+Setup
+-----
+
+Make sure the hardware is set up correctly:
+
+1. Plug the XBee3 radio module into the XBee adapter and connect it to your
+   computer's USB port.
+2. Find the BLE MAC address of the peripheral BLE device. It will be
+   used later in the example. The peripheral must support pairing with
+   MITM support. If it does not, edit the `ble.config` like to remove
+   that flag. If the flag is removed Just Works pairing may occur with
+   no callbacks.
+
+Run
+---
+
+Before launching the application, update the `REMOTE_ADDRESS` and `address_type`
+variables in `main.py` to match your BLE peripheral device.
+
+Compile and launch the MicroPython application. It prints information to the
+console.
+
+After connecting to the peripheral device, it will delay for a short
+period of time and then one of the `io_callback` methods will be
+called. The specific callback will depend on the capabilities of the
+BLE peripheral being paired against.
+
+Example session when connecting to a device with a keyboard and display.
+
+    Loading /flash/main.mpy...
+    Running bytecode...
+    Connecting
+    Connected
+    Wait for a bit before securing
+    Securing
+    Sleep forever
+    The passkey is 520308
+    Is this correct (y/n): y
+    Secured
+
+Supported platforms
+-------------------
+
+* Digi XBee3 Cellular LTE-M/NB-IoT - minimum firmware version: 11416
+* Digi XBee3 Cellular LTE Cat 1 - minimum firmware version: x16
+
+License
+-------
+
+Copyright (c) 2020, Digi International Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

samples/bluetooth/pairing/main.py

@@ -0,0 +1,103 @@
+# Copyright (c) 2020, Digi International Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# Change these two variables to your device's address and address type.
+# The address and address type can be discovered using ble.gap_scan().
+
+import binascii
+import time
+
+from digi import ble
+
+REMOTE_ADDRESS = "f2:bc:3c:06:01:0a"
+address_type = ble.ADDR_TYPE_PUBLIC
+
+# Put address into bytes (without colons)
+address = binascii.unhexlify(REMOTE_ADDRESS.replace(':', ''))
+
+
+# Present the passkey to the user
+def display_cb(passkey):
+    print("The passkey is {}".format(passkey))
+
+
+# Solicit the passkey from the user.
+# NOTE: `ble.passkey_enter()` does not need to be called from the
+# callback, this is done for simplicity here, but blocking the
+# callback for user activity in a real application may not be
+# desirable.
+def request_cb():
+    print("The passkey is being requested")
+    passkey = input("Passkey: ")
+    passkey = int(passkey)
+    ble.passkey_enter(passkey)
+
+
+# Ask the user to confirm the passkey
+# NOTE: As above `passkey_confirm` need not be called from the
+# callback.
+def confirm_cb(passkey):
+    print("The passkey is {}".format(passkey))
+    yn = input("Is this correct (y/n): ")
+    yn = yn.strip().lower()
+    ble.passkey_confirm(yn[0] == 'y')
+
+
+# Called when the `secure` operation completes
+def secure_cb(code):
+    if code == 0:
+        print("Secured")
+    else:
+        print("Pairing failed with error 0x{:x}".format(code))
+
+
+def main():
+    # io_callbacks must be called before `ble.config` to enable
+    # Require MITM.
+    ble.io_callbacks(display_cb=display_cb,
+                     request_cb=request_cb,
+                     confirm_cb=confirm_cb)
+    ble.config(security=ble.PAIRING_REQUIRE_MITM)
+    # Comment the line above, and uncomment the line below to use
+    # bonding. Once bonded the pairing activity will no longer be
+    # necessary on each connection as long as the keys are retained by
+    # the devices.
+    # ble.config(security=ble.PAIRING_REQUIRE_MITM | ble.PAIRING_REQUIRE_BONDING)
+
+
+    print("Connecting")
+    conn = ble.gap_connect(address_type, address)
+    print("Connected")
+
+    # The delay is not necessary, just here to easily observe the
+    # secured vs unsecured state.
+    print("Wait for a bit before securing")
+    time.sleep(5)
+
+    print("Securing")
+    conn.secure(secure_cb)
+
+    print("Sleep forever")
+    while True:
+        time.sleep(1)
+
+
+if __name__ == "__main__":
+    main()

samples/bluetooth/xbee_connect/README.md

@@ -0,0 +1,78 @@
+XBee-to-XBee Bluetooth Connection Sample Application
+======================================
+
+This example demonstrates XBee to XBee communication by creating an
+authenticated and encrypted connection to the API service of a remote
+XBee 3 device.
+
+When run the example will connect to the specified XBee address with
+the provided password and periodically query the time and temperature
+of the remote XBee.
+
+Requirements
+------------
+
+To run this example you need:
+
+* Two XBee3 radio modules with MicroPython support.
+    * One will act as the MicroPython host, the other the target for
+      the API Service client.
+* Two carrier boards for the radio module (XBIB-U-DEV or XBIB-C board).
+
+Setup
+-----
+
+Make sure the hardware is set up correctly:
+
+1. Plug the XBee3 radio modules into the XBee adapters and connect to
+   your computer's USB port.
+2. On the XBee3 that will act as the API Service server
+   1. Enable Bluetooth
+   2. Configure a password and take note of the Bluetooth address and
+      password for customization of the MicroPython application.
+
+Run
+---
+
+The example must be configured prior to execution by providing the
+Bluetooth address and the password for the server XBee3. The example
+code should be modified to provide these values in the ADDRESS and
+PASSWORD variables at the top of the file.
+
+When run the script reports when it performs a query and provides
+interpreted response data for the time and temperature when it is
+received.
+
+Required libraries
+--------------------
+
+N/A
+
+Supported platforms
+-------------------
+
+* Digi XBee3 Cellular LTE-M/NB-IoT - minimum firmware version: 11416
+* Digi XBee3 Cellular LTE Cat 1 - minimum firmware version: x16
+
+License
+-------
+
+Copyright (c) 2020, Digi International, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

samples/bluetooth/xbee_connect/main.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2020, Digi International Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+import time
+import struct
+from binascii import unhexlify
+
+from digi import ble
+ble.active(True)
+
+# Replace these with the BL and password values for your XBee
+ADDRESS = "90FD9F7B764B"
+PASSWORD = "password"
+
+DT_request = unhexlify("7E000508014454015D")
+TP_request = unhexlify("7E00040801545052")
+
+
+def process_at_cmd_response(payload):
+    frame_id, at_cmd, status = struct.unpack(">B2sB", payload[:4])
+    value = payload[4:]
+    if at_cmd == b"DT":
+        print("Peer responded with time: {}".format(value))
+    elif at_cmd == b"TP":
+        (temp,) = struct.unpack(">H", value)
+        print("Peer responded with temperature: {}".format(temp))
+
+
+def process_frame(frame):
+    delim, len, cmd = struct.unpack(">BHB", frame[:4])  # Throw away initial delimiter
+    payload = frame[4:-1]  # Throw away CRC, checked by receive logic
+
+    if cmd == 0x88:
+        process_at_cmd_response(payload)
+
+
+def main():
+    conn = ble.gap_connect(ble.ADDR_TYPE_PUBLIC, unhexlify(ADDRESS))
+    xbeeconn = ble.xbee_connect(conn, process_frame, PASSWORD, timeout=10)
+
+    while True:
+        print("Querying DT & TP")
+        xbeeconn.send(DT_request)
+        xbeeconn.send(TP_request)
+        time.sleep(5)
+
+
+main()