Add samples and type hints for the idle_radio() feature

Author: Zack Yancey

samples/power_management/idle_polling/README.md

@@ -0,0 +1,94 @@
+Idle Radio Polling Sample Application
+======================================
+
+The `idle_radio()` function allows the MicroPython application to put the radio
+into an idle state, reducing current draw but preventing the radio from
+receiving transmissions (see the *Idle Radio* sample application).
+
+Zigbee networks allow a little bit more flexibility in this idle state. This
+state is actually the default state for end devices--whenever a message is sent
+to an end device it is held by a router until the end device enables the radio
+and polls for new messages. Normally this process happens automatically, but the
+`idle_radio()` function disables this polling, transferring the responsibility
+to do so to the application (using the `poll_now()` function).
+
+In this example an end device sleeps, waking every 5 seconds to take a sample
+from a sensor. Every 4 times the device wakes, it sends a message to the
+coordinator with the last 4 samples. When the device sends the samples it also
+polls for messages, allowing it to receive any messages that were sent while it
+was sleeping/idling.
+
+
+Requirements
+------------
+
+To run this example you need:
+
+* Two XBee 3 Zigbee modules with MicroPython support.
+* Carrier boards for each radio module (XBIB-U-DEV or XBIB-C board).
+
+
+Setup
+-----
+
+Set up a network with two modules:
+
+* One module is the *coordinator*, which will receive the sensor readings.
+  Configure the following AT commands on the coordinator:
+  * Set **AP** to 1 to enable API mode, making it easier to see transmissions
+    from the client using XCTU.
+  * Set **CE** to 1 to make the device a coordinator.
+  * Set **SP** to 0x7D0 (20 seconds). This indicates how long end devices will
+    go between polls, and is used to determine the timeout for transmissions.
+
+* The other module is the *end device* that will run the sample
+  application. Configure the following AT commands on the end device:
+  *  Set **SM** to 6 on the end device to allow MicroPython to control sleep.
+
+Allow the end device to join the network (wait until the associate LED on the
+end device is blinking and querying the **AI** command returns 0).
+
+
+Run
+---
+
+Open the coordinator in XCTU's API terminal so you can observe the frames output
+by the module, then compile and launch the application on the sensor module.
+
+Observe the output from MicroPython on the sensor module. The module will wake
+every 5 seconds, take a reading, and go back to sleep. Every 4th time the module
+wakes, it will send the last 4 samples to the coordinator. After 12 samples, the
+example will finish.
+
+The coordinator (or any other device on the network) can send a transmission to
+the end device at any time, and it will be received the next time the end device
+polls for data. It is recommended to send transmissions to the end device with
+transmit option bit six (0x40) set, to enable the extended timeout.
+
+Supported platforms
+-------------------
+
+* Digi XBee3 Zigbee 3 - minimum firmware version: 100B
+
+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/power_management/idle_polling/main.py

@@ -0,0 +1,88 @@
+# 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 xbee
+
+
+def read_sensor():
+    """This example uses ATTP to read the internal temperature sensor."""
+    return xbee.atcmd("TP")
+
+
+def handle_rx_packet(rx):
+    """Print out any received packets."""
+    print("Received:", rx["payload"])
+
+
+def main():
+    module = xbee.XBee()
+
+    # Wait until the module has joined a network before starting
+    ai = xbee.atcmd("AI")
+    while ai != 0:
+        print("Waiting to join a network, AI=%x" % ai)
+        time.sleep(1)
+        ai = xbee.atcmd("AI")
+
+    # Put the radio to sleep. Note that by doing so the MicroPython
+    # application assumes the responsibility of fequently calling poll_now()
+    # or data sent to this device may be lost.
+    xbee.idle_radio(True)
+
+    # register handle_rx_packet to be called whenever a packet is received.
+    xbee.receive_callback(handle_rx_packet)
+
+    samples = []
+    # Since this application spends most of its time asleep, stopping
+    # the application through the UART can be difficult. To make the
+    # example easier to work with, it will only run for about a minute
+    # instead of indefinitely.
+    for _ in range(12):
+        # Sleep for 5 seconds
+        module.sleep_now(5000)
+
+        # Upon waking, take a sample
+        sample = read_sensor()
+        samples.append(sample)
+        print("  Sample: {}".format(sample))
+
+        if len(samples) == 4:
+            # Once we have four samples, Send the samples to
+            # the coordinator. Note that we don't have to call
+            # xbee.idle_radio(True) to be able to do this--the radio is
+            # enabled just long enough to send the transmission.
+            print("Transmit samples: {}".format(samples))
+            xbee.transmit(xbee.ADDR_COORDINATOR, str(samples))
+
+            # Clear the stored samples
+            samples.clear()
+
+            # We need to call poll_now() periodically to check for incoming
+            # messages, so do that now.
+            xbee.poll_now()
+            # handle_rx_packet() is registered as the receive callback, so
+            # it will be called automatically if the poll comes back with
+            # any data.
+
+    print("Example complete, re-enabling radio")
+    xbee.idle_radio(False)
+
+
+main()

samples/power_management/idle_radio/README.md

@@ -0,0 +1,86 @@
+Idle Radio Sample Application
+======================================
+
+By default, whenever an XBee module is awake, the radio is active and available
+to receive RF transmissions. If the application does not always need to receive
+transmissions while it is awake (for example, if a MicroPython application is
+waking only to sample some data and go back to sleep), the radio can be disabled
+to save power.
+
+In this example an end device sleeps, waking every 5 seconds to take a sample
+from a sensor. Every 4 times the device wakes, it sends a message to an
+aggregator with the last 4 samples. When the device isn't actively transmitting
+or receiving, the radio is kept in the idle state to minimize current draw.
+
+
+**Note** if using XBee 3 Zigbee: This sample application will run, but on a
+Zigbee network additional functionality is available to further reduce power
+usage. See the *Idle Radio Polling* sample application for more information.
+
+
+Requirements
+------------
+
+To run this example you need:
+
+* Two XBee 3 modules with MicroPython support.
+* Carrier boards for each radio module (XBIB-U-DEV or XBIB-C board).
+
+
+Setup
+-----
+
+Set up a network with two modules:
+
+* One module is the *aggregator*, which will receive the sensor readings.
+
+* The other module is the *sensor module* that will run the sample
+  application. Configure the following AT commands:
+  * **SM** 6
+  * **DH**/**DL**: Set to the 64-bit address (**SH**/**SL**) of the aggregator.
+
+
+Run
+---
+
+Open the aggregator in XCTU's API terminal so you can observe the frames output
+by the module, then compile and launch the application on the sensor module.
+
+Observe the output from MicroPython on the sensor module. The module will wake
+every 5 seconds, take a reading, and go back to sleep. Every 4th time the module
+wakes, it will send the last 4 samples to the aggregator. After 12 samples, the
+example will finish.
+
+To send a message to the sensor module, the aggregator will need to wait until
+it receives a packet from the sensor module, then send its message during the 1
+second that the sensor module application activates the radio after sending its
+samples.
+
+Supported platforms
+-------------------
+
+* Digi XBee3 Zigbee 3 - minimum firmware version: 100B
+* Digi XBee3 DigiMesh 2.4 - minimum firmware version: 300B
+
+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/power_management/idle_radio/main.py

@@ -0,0 +1,91 @@
+# 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 xbee
+
+
+def read_sensor():
+    """This example uses ATTP to read the internal temperature sensor."""
+    return xbee.atcmd("TP")
+
+
+def handle_rx_packet(rx):
+    """Print out any received packets."""
+    print("Received:", rx["payload"])
+
+
+def main():
+    module = xbee.XBee()
+
+    # Idle the radio. While the radio is idled, the radio cannot receive
+    # transmissions and current draw is reduced.
+    xbee.idle_radio(True)
+
+    # register handle_rx_packet to be called whenever a packet is received.
+    xbee.receive_callback(handle_rx_packet)
+
+    # Send transmissions to the address configured by DH/DL
+    dest_addr = xbee.atcmd("DH") + xbee.atcmd("DL")
+
+    samples = []
+    # Since this application spends most of its time asleep, stopping
+    # the application through the UART can be difficult. To make the
+    # example easier to work with, it will only run for about a minute
+    # instead of indefinitely.
+    for _ in range(12):
+        # Sleep for 5 seconds
+        module.sleep_now(5000)
+
+        # Upon waking, take a sample
+        sample = read_sensor()
+        samples.append(sample)
+        print("  Sample: {}".format(sample))
+
+        if len(samples) == 4:
+            # Once we have four samples, Send the samples to
+            # the coordinator. Note that we don't have to call
+            # xbee.idle_radio(True) to be able to do this--the radio is
+            # enabled just long enough to send the transmission.
+            print("Transmit samples: {}".format(samples))
+            xbee.transmit(dest_addr, str(samples))
+
+            # Clear the stored samples
+            samples.clear()
+
+            # If the server is ever going to send transmissions to the
+            # end device, the end device needs to enable the radio at
+            # some point, and the server needs to know when that is. For
+            # this example, that is achieved by leaving the radio on for
+            # 1 second after transmitting a sample. If this end device
+            # never needs to receive transmissions, this can be left
+            # out.
+            print("Enable the radio for a bit to receive transmissions...")
+            xbee.idle_radio(False)
+            # Wait 1 second with the radio enabled. This is the only
+            # time the radio can receive transmissions.
+            time.sleep(1)
+            print("Disable the radio again")
+            xbee.idle_radio(True)
+
+    print("Example complete, re-enabling radio")
+    xbee.idle_radio(False)
+
+
+main()