Auto-update: API changes from upstream

notecard/card.py

@@ -652,7 +652,7 @@ def restore(card, connected=None, delete=None):
     Args:
         card (Notecard): The current Notecard object.
         connected (bool): Set to `true` to reset the Notecard on Notehub. This will delete and deprovision the Notecard from Notehub the next time the Notecard connects. This also removes any Notefile templates used by this device. Conversely, if `connected` is `false` (or omitted), the Notecard's settings and data will be restored from Notehub the next time the Notecard connects to the previously used Notehub project.
-        delete (bool): Set to `true` to reset most Notecard configuration settings. Note that this does not reset stored Wi-Fi credentials or the alternate I2C address (if previously set) so the Notecard can still contact the network after a reset. The Notecard will be unable to sync with Notehub until the `ProductUID` is set again.
+        delete (bool): Set to `true` to reset most Notecard configuration settings. Note that this does not reset stored WiFi credentials or the alternate I2C address (if previously set) so the Notecard can still contact the network after a reset. The Notecard will be unable to sync with Notehub until the `ProductUID` is set again.
 
     Returns:
         dict: The result of the Notecard request.
@@ -764,16 +764,16 @@ def transport(card, allow=None, method=None, seconds=None, umin=None):
 
 @validate_card_object
 def triangulate(card, minutes=None, mode=None, on=None, set=None, text=None, time=None, usb=None):
-    """Enable or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or Wi-Fi access points with each new Notehub session.
+    """Enable or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or WiFi access points with each new Notehub session.
 
     Args:
         card (Notecard): The current Notecard object.
         minutes (int): Minimum delay, in minutes, between triangulation attempts. Use `0` for no time-based suppression.
-        mode (str): The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order. See Using Cell Tower & Wi-Fi Triangulation for more information.
+        mode (str): The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order. See Using Cell Tower & WiFi Triangulation for more information.
         on (bool): `true` to instruct the Notecard to triangulate even if the module has not moved. Only takes effect when `set` is `true`.
         set (bool): `true` to instruct the module to use the state of the `on` and `usb` arguments.
-        text (str): When using Wi-Fi triangulation, a newline-terminated list of Wi-Fi access points obtained by the external module. Format should follow the ESP32's AT+CWLAP command output.
-        time (int): When passed with `text`, records the time that the Wi-Fi access point scan was performed. If not provided, Notecard time is used.
+        text (str): When using WiFi triangulation, a newline-terminated list of WiFi access points obtained by the external module. Format should follow the ESP32's AT+CWLAP command output.
+        time (int): When passed with `text`, records the time that the WiFi access point scan was performed. If not provided, Notecard time is used.
         usb (bool): `true` to use perform triangulation only when the Notecard is connected to USB power. Only takes effect when `set` is `true`.
 
     Returns:
@@ -799,7 +799,7 @@ def triangulate(card, minutes=None, mode=None, on=None, set=None, text=None, tim
 
 @validate_card_object
 def usageGet(card, mode=None, offset=None):
-    """Return the Notecard's network usage statistics for cellular and Wi-Fi transmissions.
+    """Return the Notecard's network usage statistics for cellular and WiFi transmissions.
 
     Args:
         card (Notecard): The current Notecard object.
@@ -967,14 +967,14 @@ def wireless(card, apn=None, hours=None, method=None, mode=None):
 
 @validate_card_object
 def wifi(card, name=None, org=None, password=None, ssid=None, start=None, text=None):
-    r"""Set up a Notecard WiFi to connect to a Wi-Fi access point.
+    r"""Set up a Notecard WiFi to connect to a WiFi access point.
 
     Args:
         card (Notecard): The current Notecard object.
         name (str): By default, the Notecard creates a SoftAP (software enabled access point) under the name "Notecard". You can use the `name` argument to change the name of the SoftAP to a custom name. If you include a `-` at the end of the `name` (for example `"name": "acme-"`), the Notecard will append the last four digits of the network's MAC address (for example `acme-025c`). This allows you to distinguish between multiple Notecards in SoftAP mode.
         org (str): If specified, replaces the Blues logo on the SoftAP page with the provided name.
-        password (str): The network password of the Wi-Fi access point. Alternatively, use `-` to clear an already set password or to connect to an open access point.
-        ssid (str): The SSID of the Wi-Fi access point. Alternatively, use `-` to clear an already set SSID.
+        password (str): The network password of the WiFi access point. Alternatively, use `-` to clear an already set password or to connect to an open access point.
+        ssid (str): The SSID of the WiFi access point. Alternatively, use `-` to clear an already set SSID.
         start (bool): Specify `true` to activate SoftAP mode on the Notecard programmatically.
         text (str): A string containing an array of access points the Notecard should attempt to use. The access points should be provided in the following format: `["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"]`. You may need to escape any quotes used in this argument before passing it to the Notecard. For example, the following is a valid request to pass to a Notecard through the In-Browser Terminal. `{"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"]"}`
 

notecard/dfu.py

@@ -13,18 +13,21 @@
 
 
 @validate_card_object
-def get(card, length=None, offset=None):
+def get(card, binary=None, length=None, offset=None):
     """Retrieve downloaded firmware data from the Notecard for use with IAP host MCU firmware updates.
 
     Args:
         card (Notecard): The current Notecard object.
+        binary (bool): If `true`, the Notecard will return firmware data in the binary I/O buffer instead of the response `payload` field. This allows for larger data transfers and more efficient processing. When `true`, the response will include `cobs`, `length`, and `status` (MD5 hash) fields instead of `payload`. Learn more in this guide on Sending and Receiving Large Binary Objects.
         length (int): The number of bytes of firmware data to read and return to the host. Set to `0` to verify that the Notecard is in DFU mode without attempting to retrieve data.
         offset (int): The offset to use before performing a read of firmware data.
 
     Returns:
         dict: The result of the Notecard request.
     """
     req = {"req": "dfu.get"}
+    if binary is not None:
+        req["binary"] = binary
     if length is not None:
         req["length"] = length
     if offset is not None:

notecard/hub.py

@@ -60,7 +60,7 @@ def set(card, align=None, details=None, duration=None, host=None, inbound=None,
         duration (int): When in `continuous` mode, the amount of time, in minutes, of each session (the minimum allowed value is `15`). When this time elapses, the Notecard gracefully ends the current session and starts a new one in order to sync session-specific data to Notehub.
         host (str): The URL of the Notehub service. Use `"-"` to reset to the default value.
         inbound (int): The max wait time, in minutes, to sync inbound data from Notehub. Explicit syncs (e.g. using `hub.sync`) do not affect this cadence. When in `periodic` or `continuous` mode this argument is required, otherwise the Notecard will function as if it is in `minimum` mode as it pertains to syncing behavior. Use `-1` to reset the value back to its default of `0`. A value of `0` means that the Notecard will never sync inbound data unless explicitly told to do so (e.g. using `hub.sync`).
-        mode (str): The Notecard's synchronization mode.
+        mode (str): The Notecard's synchronization mode. NOTE: The Notecard must be in `periodic` or `continuous` mode to use the onboard GPS module.
         off (bool): Set to `true` to manually instruct the Notecard to resume periodic mode after a web transaction has completed.
         on (bool): If in `periodic` mode, used to temporarily switch the Notecard to `continuous` mode to perform a web transaction.\n\nIgnored if the Notecard is already in `continuous` mode or if the Notecard is NOT performing a web transaction.
         outbound (int): The max wait time, in minutes, to sync outbound data from the Notecard. Explicit syncs (e.g. using `hub.sync`) do not affect this cadence. When in `periodic` or `continuous` mode this argument is required, otherwise the Notecard will function as if it is in `minimum` mode as it pertains to syncing behavior. Use `-1` to reset the value back to its default of `0`. A value of `0` means that the Notecard will never sync outbound data unless explicitly told to do so (e.g. using `hub.sync`).

notecard/note.py

@@ -159,7 +159,7 @@ def template(card, file, body=None, delete=None, format=None, length=None, port=
     Args:
         card (Notecard): The current Notecard object.
         body (dict): A sample JSON body that specifies field names and values as "hints" for the data type. Possible data types are: boolean, integer, float, and string. See Understanding Template Data Types for an explanation of type hints and explanations.
-        delete (bool): Set to `true` to delete all pending Notes using the template if one of the following scenarios is also true: Connecting via non-NTN (e.g. cellular or Wi-Fi) communications, but attempting to sync NTN-compatible Notefiles. or Connecting via NTN (e.g. satellite) communications, but attempting to sync non-NTN-compatible Notefiles. Read more about this feature in Starnote Best Practices.
+        delete (bool): Set to `true` to delete all pending Notes using the template if one of the following scenarios is also true: Connecting via non-NTN (e.g. cellular or WiFi) communications, but attempting to sync NTN-compatible Notefiles. or Connecting via NTN (e.g. satellite) communications, but attempting to sync non-NTN-compatible Notefiles. Read more about this feature in Starnote Best Practices.
         file (str): The name of the Notefile to which the template will be applied.
         format (str): By default all Note templates automatically include metadata, including a timestamp for when the Note was created, various fields about a device's location, as well as a timestamp for when the device's location was determined. By providing a `format` of `"compact"` you tell the Notecard to omit this additional metadata to save on storage and bandwidth. The use of `format: "compact"` is required for Notecard LoRa and a Notecard paired with Starnote. When using `"compact"` templates, you may include the following keywords in your template to add in fields that would otherwise be omitted: `lat`, `lon`, `ltime`, `time`. See Creating Compact Templates to learn more.
         length (int): The maximum length of a `payload` (in bytes) that can be sent in Notes for the template Notefile. As of v3.2.1 `length` is not required, and payloads can be added to any template-based Note without specifying the payload length.

notecard/ntn.py

@@ -34,7 +34,7 @@ def gps(card, off=None, on=None):
 
 @validate_card_object
 def reset(card):
-    """Once a Notecard is connected to a Starnote device, the presence of a physical Starnote is stored in a permanent configuration that is not affected by a `card.restore` request. This request clears this configuration and allows you to return to testing NTN mode over cellular or Wi-Fi.
+    """Once a Notecard is connected to a Starnote device, the presence of a physical Starnote is stored in a permanent configuration that is not affected by a `card.restore` request. This request clears this configuration and allows you to return to testing NTN mode over cellular or WiFi.
 
     Args:
         card (Notecard): The current Notecard object.