LTE PSM: move example to tutorial

Author: peter-pycom

config.toml

@@ -569,6 +569,13 @@ theme = "doc-theme"
     parent = "tutorials@lte"
     weight = 20
 
+[[menu.main]]
+    name = "Power consumption"
+    url = "/tutorials/lte/power/"
+    identifier = "tutorials@lte@power"
+    parent = "tutorials@lte"
+    weight = 20
+
 [[menu.main]]
     name = "Module IMEI"
     url = "/tutorials/lte/imei/"

content/firmwareapi/pycom/network/lte.md

@@ -54,76 +54,21 @@ lte = LTE()
 
 ## Methods
 
-#### lte.init(\*, carrier=None)
+#### lte.init(\*, carrier=None, psm_period_value=0, psm_period_unit=LTE.PSM_PERIOD_DISABLED, psm_active_value=0, psm_active_unit=LTE.PSM_ACTIVE_DISABLED )
 
-This method is used to set up the LTE subsystem. After a `deinit()` this method can take several seconds to return waiting for the LTE modem to start-up. Optionally specify a carrier name. The available options are: `verizon, at&t, standard`. `standard` is generic for any carrier, and it's also the option used when no arguments are given.
+This method is used to set up the LTE subsystem. After a `deinit()` this method can take several seconds to return waiting for the LTE modem to start-up.
 
-**Power Saving Mode**
+Optionally you can specify a carrier name. The available options are: `verizon, at&t, standard`. `standard` is generic for any carrier, and it's also the option used when no arguments are given.
 
-The _Power Saving Mode_ allows a user to configure how often a device will connect and how long it will stay connected. Upon `attach()` this configuration is then requested from the network. Ultimately it is up to the network to decide the PSM configuration. After a successful PSM configuration,
-
-- the LTE modem will go into a low power state during deep sleep, but
-- it will stay attached to the network, thus no time is spent for `attach()` after waking up.
-
-The configuration is done with these four parameters:
+For *Power Saving Mode* (PSM), you can use the following four arguments:
 
 - `psm_period_value` : Configure at which period the device will connect to the network. Values from 0 to 31 are allowed.
 - `psm_period_unit` : Specify the _unit_ to be used for `psm_period_value`.
 - `psm_active_value` : Configure how long the device will be connected. Values from 0 to 31 are allowed.
 - `psm_active_unit` : Specify the _unit_ for `psm_active_value`.
 
-The LTE specification prescribes certain _units_ for configuring PSM. See the constants below.
-
-For the following example, assume you want to wake up once per hour, connect and do some processing, then go to deepsleep for 55 minutes:
-
-```python
+The LTE specification defines the _units_ for configuring PSM. See the [constants](#constants) below. Also see the [PSM example](/tutorials/lte/power) in the tutorials.
 
-from network import LTE
-import time
-import socket
-import machine
-import pycom
-
-def attach():
-    start = time.time()
-    if lte.isattached():
-        print("already attached")
-    else:
-        print("attach")
-        lte.attach(band=20, apn="spe.inetd.vodafone.nbiot")
-        while not lte.isattached():
-            time.sleep(1)
-    print("attached after", time.time() - start, "seconds")
-    print(lte.psm())
-
-def connect():
-    print("connect")
-    start = time.time()
-    lte.connect()
-    while not lte.isconnected():
-        time.sleep(0.5)
-    print("connected after", time.time() - start, "seconds")
-
-def http_get(url = 'http://detectportal.firefox.com/'):
-    _, _, host, path = url.split('/', 3)
-    addr = socket.getaddrinfo(host, 80)[0][-1]
-    s = socket.socket()
-    s.connect(addr)
-    s.send(bytes('GET /%s HTTP/1.0\r\nHost: %s\r\n\r\n' % (path, host), 'utf8'))
-    s.close()
-
-# period 1h, active 10s
-lte = LTE(psm_period_value=1, psm_period_unit=LTE.PSM_PERIOD_1H,
-          psm_active_value=5, psm_active_unit=LTE.PSM_ACTIVE_2S )
-print(lte.psm())
-attach()
-connect()
-http_get()
-print("deinit")
-lte.deinit(detach=False, reset=False)
-print("deepsleep")
-machine.deepsleep(55 * 60 * 1000) # 55m
-```
 
 #### lte.deinit(detach=True, reset = False)
 
@@ -133,6 +78,10 @@ Disables LTE modem completely. This reduces the power consumption to the minimum
 
 - `reset` : reset LTE modem.
 
+#### lte.psm()
+
+Query the PSM timers. The return value is a 5-tuple with the following structure: `(enabled, period_value, period_unit, active_value, active_unit)`.
+
 #### lte.attach(\*, band=None, apn=None, cid=None, type=LTE.IP, legacyattach=True)
 
 Enable radio functionality and attach to the LTE network authorised by the inserted SIM card. Optionally specify:
@@ -271,13 +220,13 @@ Check Network Coverage for UE device (i.e LTE modem).
 `False`: No Netwok Coverage.
 
 
-## Constants
+## Constants<a id="constants"></a>
 
 - `LTE.IP` : Internet Protocol IP
 
 - `LTE.IPV4V6` : Internet protocol ver. 4/6
 
 - `PSM_PERIOD_2S`, `PSM_PERIOD_30S`, `PSM_PERIOD_1M`, `PSM_PERIOD_10M`, `PSM_PERIOD_1H`, `PSM_PERIOD_10H`, `PSM_PERIOD_320H`: Specify the unit for the PSM period to be 2 seconds, 30 seconds, 1 minute, 10 minutes, 1 hour, 10 hours, or 320 hours, respectively.
-- `PSM_PERIOD_DISABLED`: Specifying the unit for PSM period of `PSM_PERIOD_DISABLED` means turning PSM off. This is the default.
+- `PSM_PERIOD_DISABLED`: Specifying the unit for PSM period of `PSM_PERIOD_DISABLED` means turning PSM off.
 - `PSM_ACTIVE_2S`, `PSM_ACTIVE_1M`, `PSM_ACTIVE_6M`: Specify the unit for the PSM active duration to be 2 seconds, 1 minute, or 6 minutes, respectively.
-- `PSM_ACTIVE_DISABLED`: Specifying the active duration unit of `PSM_ACTIVE_DISABLED` means turning PSM off. This is the default.
+- `PSM_ACTIVE_DISABLED`: Specifying the active duration unit of `PSM_ACTIVE_DISABLED` means turning PSM off.

content/tutorials/lte/power.md

@@ -0,0 +1,100 @@
+---
+title: "LTE power consumption"
+aliases:
+    - tutorials/lte/power.html
+    - tutorials/lte/power.md
+    - chapter/tutorials/power
+---
+
+There are some trade offs one can do to reduce power consumption of the LTE modem. You can limit connectivity in exchange for saving power consumption.
+
+Let's start with the simplest choice: Turn off or not. It's not very sophisticated, but for completeness, let's start with this:
+
+
+## Turn LTE modem off <a id="lte-power-off" ></a>
+
+```python
+
+from network import LTE
+import time
+import socket
+import machine
+import pycom
+
+def attach():
+    start = time.time()
+    if lte.isattached():
+        print("already attached")
+    else:
+        print("attach")
+        lte.attach(band=20, apn="the.apn.to.be.used.with.your.simcard")
+        while not lte.isattached():
+            time.sleep(1)
+    print("attached after", time.time() - start, "seconds")
+    print(lte.psm())
+
+def connect():
+    print("connect")
+    start = time.time()
+    lte.connect()
+    while not lte.isconnected():
+        time.sleep(0.5)
+    print("connected after", time.time() - start, "seconds")
+
+def http_get(url = 'http://detectportal.firefox.com/'):
+    _, _, host, path = url.split('/', 3)
+    addr = socket.getaddrinfo(host, 80)[0][-1]
+    s = socket.socket()
+    s.connect(addr)
+    s.send(bytes('GET /%s HTTP/1.0\r\nHost: %s\r\n\r\n' % (path, host), 'utf8'))
+    s.close()
+
+# main
+lte = LTE()
+attach()
+connect()
+http_get()
+print("deinit")
+lte.deinit()
+print("deepsleep")
+machine.deepsleep(55 * 60 * 1000) # 55m
+```
+
+The example above is the simple case where we attach, connect, communicate and then turn the LTE modem off: `lte.deinit()`. This will make sure the LTE modem uses minimal power after the deinit. However, it means that the subsequent attach procedure after waking up will take some seconds. During this attach time the modem already consumes power.
+
+## Leave LTE modem on
+
+Depending on your use case, you may want to save the time (and energy) for reattching that you get after [turning the modem off](#lte-power-off).
+If your device communicates a lot, then you can choose to not turn it off at all, save the time for the reattach. However, you then trade the higher power consumption during any idle time. For this, simply remove the deinit from the example:
+
+
+```python
+# lte.deinit()
+```
+
+## Power Saving Mode
+
+A more sophisticated configuration, is the _Power Saving Mode_. PSM allows you to configure the period how often the device will connect and how long it will stay actively connected. During the sleep
+- the LTE modem will go into a low power state, but
+- it will stay attached to the network, thus no time is spent for `attach()` after waking up.
+
+Note that the network needs to cooperate in this, so first there is a negotiation where you propose timers. Then you attach and the network will decide which timers to actually apply. Afterwards you can query the effective values.
+
+So you see, here you not only need to make the trade off what is best for your application, but you will also need to do some testing to see which values your provider offers you and how this works out in your application in practise.
+
+For the following example, assume you want to wake up once per hour, connect and do some processing, then go to deepsleep for 55 minutes. We would adjust the main part of the example as follows:
+
+```python
+# main
+# period 1h, active 10s
+lte = LTE(psm_period_value=1, psm_period_unit=LTE.PSM_PERIOD_1H,
+          psm_active_value=5, psm_active_unit=LTE.PSM_ACTIVE_2S )
+print(lte.psm())
+attach()
+connect()
+http_get()
+print("deinit")
+lte.deinit(detach=False, reset=False)
+print("deepsleep")
+machine.deepsleep(55 * 60 * 1000) # 55m
+```