Update Notecard API from upstream schema changes (6fa7ea71ba950aeb8c45e8241d8689eb1203566f) (#184)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

notecard/card.py

@@ -352,7 +352,7 @@ def locationMode(card, delete=None, lat=None, lon=None, max=None, minutes=None,
         lat (float): When in periodic or continuous mode, providing this value enables geofencing. The value you provide for this argument should be the latitude of the center of the geofence, in degrees. When in fixed mode, the value you provide for this argument should be the latitude location of the device itself, in degrees.
         lon (float): When in periodic or continuous mode, providing this value enables geofencing. The value you provide for this argument should be the longitude of the center of the geofence, in degrees. When in fixed mode, the value you provide for this argument should be the longitude location of the device itself, in degrees.
         max (int): Meters from a geofence center. Used to enable geofence location tracking.
-        minutes (int): When geofence is enabled, the number of minutes the device should be outside the geofence before the Notecard location is tracked.
+        minutes (int): When geofence is enabled, the debounce period in minutes for transitions across the geofence boundary. The Notecard reports a transition the first time a GPS fix lands on the opposite side of the boundary from the previous one, then ignores further transitions for this many minutes.
         mode (str): Sets the location mode.
         seconds (int): When in `periodic` mode, location will be sampled at this interval, if the Notecard detects motion. If seconds is < 300, during periods of sustained movement the Notecard will leave its onboard GPS/GNSS on continuously to avoid powering the module on and off repeatedly.
         threshold (int): When in `periodic` mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.
@@ -399,7 +399,7 @@ def location(card):
 
 @validate_card_object
 def locationTrack(card, file=None, heartbeat=None, hours=None, payload=None, start=None, stop=None, sync=None):
-    """Store location data in a Notefile at the `periodic` interval, or using a specified `heartbeat`. This request is only available when the `card.location.mode` request has been set to `periodic`—e.g. `{"req":"card.location.mode","mode":"periodic","seconds":300}`. If you want to track and transmit data simultaneously consider using an external GPS/GNSS module with the Notecard. If you connect a BME280 sensor on the I2C bus, Notecard will include a temperature, humidity, and pressure reading with each captured Note. If you connect an ENS210 sensor on the I2C bus, Notecard will include a temperature and pressure reading with each captured Note. Learn more in _track.qo.
+    """Store location data in a Notefile at the `periodic` interval, or using a specified `heartbeat`. This request is only available when the `card.location.mode` request has been set to `periodic`—e.g. `{"req":"card.location.mode","mode":"periodic","seconds":300}`. If you want to track and transmit data simultaneously consider using an external GPS/GNSS module with the Notecard. If you connect a BME280 sensor on the I2C bus, Notecard will include a temperature, humidity, and pressure reading with each captured Note. If you connect an ENS210 sensor on the I2C bus, Notecard will include a temperature and humidity reading with each captured Note. Learn more in _track.qo.
 
     Args:
         card (Notecard): The current Notecard object.
@@ -586,18 +586,21 @@ def random(card, count=None, mode=None):
 
 
 @validate_card_object
-def power(card, minutes=None, reset=None):
+def power(card, hours=None, minutes=None, reset=None):
     """Use `card.power` API is used to configure a connected Mojo device or to manually request power consumption readings in firmware.
 
     Args:
         card (Notecard): The current Notecard object.
-        minutes (int): How often, in minutes, Notecard should log power consumption in a `_log.qo` Note. The default value is `720` (12 hours).
+        hours (int): How often, in hours, Notecard should log power consumption in a `_log.qo` Note. Provided as a convenience alternative to `minutes`. If both `hours` and `minutes` are provided, the resulting cadence is the sum of the two.
+        minutes (int): How often, in minutes, Notecard should log power consumption in a `_log.qo` Note. The default value is `720` (12 hours). May be combined with `hours`, in which case the two values are added together.
         reset (bool): Set to `true` to reset the power consumption counters back to 0.
 
     Returns:
         dict: The result of the Notecard request.
     """
     req = {"req": "card.power"}
+    if hours is not None:
+        req["hours"] = hours
     if minutes is not None:
         req["minutes"] = minutes
     if reset is not None:
@@ -681,7 +684,7 @@ def status(card):
 
 @validate_card_object
 def temp(card, minutes=None, status=None, stop=None, sync=None):
-    """Get the current temperature from the Notecard's onboard calibrated temperature sensor. When using a Notecard Cellular or Notecard Cell+WiFi, if you connect a BME280 sensor on the I2C bus the Notecard will add `temperature`, `pressure`, and `humidity` fields to the response. If you connect an ENS210 sensor on the I2C bus the Notecard will add `temperature` and `pressure` fields to the response.
+    """Get the current temperature from the Notecard's onboard calibrated temperature sensor.
 
     Args:
         card (Notecard): The current Notecard object.
@@ -737,14 +740,15 @@ def trace(card, mode=None):
 
 
 @validate_card_object
-def transport(card, allow=None, method=None, seconds=None, umin=None):
+def transport(card, allow=None, method=None, seconds=None, set=None, umin=None):
     """Specify the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard.
 
     Args:
         card (Notecard): The current Notecard object.
-        allow (bool): Set to `true` to allow adding Notes to non-compact Notefiles while connected over a non-terrestrial network. See Define NTN vs non-NTN Templates.
+        allow (bool): Set to `true` to allow adding Notes to templated Notefiles that have no `port` while connected over a non-terrestrial network. See Define NTN vs non-NTN Templates.
         method (str): The connectivity method to enable on the Notecard.
         seconds (int): The amount of time (in seconds) a Notecard will spend on any fallback transport before retrying the first transport specified in the `method`. The default is `3600` or 60 minutes.
+        set (bool): Set to `true` to apply the `allow` argument without also changing the transport `method`.
         umin (bool): Set to `true` to force a longer network transport timeout when using Wideband Notecards.
 
     Returns:
@@ -757,6 +761,8 @@ def transport(card, allow=None, method=None, seconds=None, umin=None):
         req["method"] = method
     if seconds is not None:
         req["seconds"] = seconds
+    if set is not None:
+        req["set"] = set
     if umin is not None:
         req["umin"] = umin
     return card.Transaction(req)
@@ -855,7 +861,7 @@ def version(card):
 
 
 @validate_card_object
-def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None, off=None, offset=None, on=None, set=None, sync=None, usb=None, vmax=None, vmin=None):
+def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None, now=None, off=None, offset=None, on=None, set=None, sync=None, usb=None, vmax=None, vmin=None):
     """Provide the current VMODEM_P voltage level on the Notecard, and provides information about historical voltage trends. When used with the mode argument, configures voltage thresholds based on how the device is powered.
 
     Args:
@@ -865,14 +871,15 @@ def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None
         hours (int): The number of hours to analyze, up to 720 (30 days).
         mode (str): Used to set voltage thresholds based on how the Notecard will be powered, and which can be used to configure voltage-variable Notecard behavior. Each value is shorthand that assigns a battery voltage reading to a given device state like `high`, `normal`, `low`, and `dead`. In addition to the named presets below, a custom semicolon-separated shorthand string may be provided using any combination of the `usb`, `high`, `normal`, `low`, and `dead` states (e.g. `"usb:4.6;high:4.2;normal:3.6;low:0"`). NOTE: Setting voltage thresholds is not supported on the Notecard XP.
         name (str): Specifies an environment variable to override application default timing values.
+        now (bool): By default, the returned `value` is an average of the voltage readings taken over the previous 15 minutes, which smooths out momentary fluctuations. Set to `true` to return the instantaneous voltage reading instead.
         off (bool): Disable historic voltage trend calculations.
         offset (int): Number of hours to move into the past before starting analysis.
         on (bool): Enable historic voltage trend calculations.
         set (bool): Used along with `calibration`, set to `true` to specify a new calibration value.
         sync (bool): When enabled and the `usb` argument is set to `true`, the Notecard will perform a sync when USB power is connected or disconnected.
         usb (bool): When enabled, the Notecard will monitor for changes to USB power state.
-        vmax (float): Ignore voltage readings above this level when performing calculations.
-        vmin (float): Ignore voltage readings below this level when performing calculations.
+        vmax (float): Ignore voltage readings above this level when performing calculations. Defaults to the maximum voltage the Notecard's components are rated for.
+        vmin (float): Ignore voltage readings below this level when performing calculations. Defaults to the minimum voltage the Notecard's components are rated for.
 
     Returns:
         dict: The result of the Notecard request.
@@ -888,6 +895,8 @@ def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None
         req["mode"] = mode
     if name:
         req["name"] = name
+    if now is not None:
+        req["now"] = now
     if off is not None:
         req["off"] = off
     if offset is not None:

notecard/dfu.py

@@ -18,8 +18,8 @@ def get(card, binary=None, length=None, offset=None):
 
     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.
+        binary (bool): If `true`, the Notecard places the firmware data in the binary storage area instead of the response `payload` field, and returns `cobs`, `length`, and `status` fields instead. Read it out with card.binary.get, then clear the area with a `card.binary` request and `delete` set to `true`. 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, up to a maximum of 8192 per request. Set to `0` to verify that the Notecard is ready to serve firmware data without retrieving any.
         offset (int): The offset to use before performing a read of firmware data.
 
     Returns:
@@ -43,12 +43,12 @@ def status(card, err=None, name=None, off=None, on=None, status=None, stop=None,
         card (Notecard): The current Notecard object.
         err (str): If `err` text is provided along with `"stop":true`, this sets the host DFU to an error state with the specified string.
         name (str): Determines which type of firmware update status to view. The value can be `"user"` (default), which gets the status of MCU host firmware updates, or `"card"`, which gets the status of Notecard firmware updates.
-        off (bool): `true` to disable firmware downloads from Notehub.
-        on (bool): `true` to allow firmware downloads from Notehub.
-        status (str): When setting `stop` to `true`, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes.
-        stop (bool): `true` to clear DFU state and delete the local firmware image from the Notecard.
+        off (bool): `true` to disable firmware downloads from Notehub. This setting persists across Notecard restarts. If both `on` and `off` are provided in the same request, `off` takes precedence.
+        on (bool): `true` to allow firmware downloads from Notehub. Downloads are enabled by default, and this setting persists across Notecard restarts. Enabling downloads here does not guarantee that a download will proceed. It can still be deferred by the `_fw_download_disabled` and `_fw_download_window_mins` environment variables, or by the `vvalue` voltage gate below.
+        status (str): When setting `stop` to `true`, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes. If `stop` is `true` and no `status` is provided, the Notecard reports `successful firmware update`.
+        stop (bool): `true` to end the current DFU. The Notecard exits DFU operating mode and marks the update `completed`, or `error` if an `err` string is also provided.
         version (str): Version information on the host firmware to pass to Notehub. You may pass a simple version number string (e.g. `"1.0.0.0"`), or an object with detailed information about the firmware image (recommended). If you provide an object it must take the following form. `{"org":"my-organization","product":"My Product","description":"A description of the image","version":"1.2.4","built":"Jan 01 2025 01:02:03","ver_major":1,"ver_minor":2,"ver_patch":4,"ver_build": 5,"builder":"The Builder"}` Code to help you generate a version with the correct formatting is available in Enabling Notecard Outboard Firmware Update.
-        vvalue (str): A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled. Use a boolean `1` (on) or `0` (off) for each source/voltage level: `usb:<1/0>;high:<1/0>;normal:<1/0>;low:<1/0>;dead:0`.
+        vvalue (str): A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled. Use a boolean `1` (on) or `0` (off) for each source/voltage level: `usb:<1/0>;high:<1/0>;normal:<1/0>;low:<1/0>;dead:0`. The default is `usb:1;high:1;normal:1;low:0;dead:0`.
 
     Returns:
         dict: The result of the Notecard request.

notecard/file.py

@@ -13,16 +13,19 @@
 
 
 @validate_card_object
-def changesPending(card):
+def changesPending(card, files=None):
     """Return info about file changes that are pending upload to Notehub.
 
     Args:
         card (Notecard): The current Notecard object.
+        files (list): One or more files to obtain pending change information from. Omit to return pending changes for all Notefiles.
 
     Returns:
         dict: The result of the Notecard request.
     """
     req = {"req": "file.changes.pending"}
+    if files:
+        req["files"] = files
     return card.Transaction(req)
 
 
@@ -33,7 +36,7 @@ def changes(card, files=None, tracker=None):
     Args:
         card (Notecard): The current Notecard object.
         files (list): One or more files to obtain change information from. Omit to return changes for all Notefiles.
-        tracker (str): ID of a change tracker to use to determine changes to Notefiles.
+        tracker (str): ID of a change tracker to use to determine changes to Notefiles. Must be accompanied by a `files` argument.
 
     Returns:
         dict: The result of the Notecard request.

notecard/hub.py

@@ -55,7 +55,7 @@ def set(card, align=None, details=None, duration=None, host=None, inbound=None,
 
     Args:
         card (Notecard): The current Notecard object.
-        align (bool): Use `true` to align syncs on a regular time-periodic cycle.
+        align (bool): Use `true` to align syncs on a regular time-periodic cycle. The cycle is anchored to the Notecard's boot time, not to a wall-clock time.
         details (str): When using Notecard LoRa you can use this argument to provide information about an alternative LoRaWAN server or service you would like the Notecard to use. The argument you provide must be a JSON object with three keys, "deveui", "appeui", and "appkey", all of which are hexadecimal strings with no leading 0x. For example: `{"deveui":"0080E11500088B37","appeui":"6E6F746563617264","appkey":"00088B37"}` The LoRaWAN details you send to a Notecard become part of its permanent configuration, and survive factory resets. You can reset a Notecard's LoRaWAN details to its default values by providing a `"-"` for the details argument.
         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.

notecard/ntn.py

@@ -12,6 +12,20 @@
 from notecard.validators import validate_card_object
 
 
+@validate_card_object
+def config(card):
+    """Return the configuration and identity of the satellite (NTN) module: the network it is provisioned for, its modem, its SKU and ordering code, and the firmware it is running.
+
+    Args:
+        card (Notecard): The current Notecard object.
+
+    Returns:
+        dict: The result of the Notecard request.
+    """
+    req = {"req": "ntn.config"}
+    return card.Transaction(req)
+
+
 @validate_card_object
 def gps(card, off=None, on=None):
     """On a Notecard paired with a Starnote, this controls whether the Starnote uses a location known to the paired Notecard instead of acquiring one with its own GPS/GNSS module. It does not, by default. On Notecard for Skylo, the satellite radio and the GPS/GNSS are part of the same module. This request controls whether the Notecard uses a known location (typically a fixed location set with `card.location.mode`), instead of acquiring a new location for NTN use.