diff --git a/notecard/card.py b/notecard/card.py index 8e37881..b1643e1 100644 --- a/notecard/card.py +++ b/notecard/card.py @@ -325,7 +325,7 @@ def led(card, mode=None, off=None, on=None): Args: card (Notecard): The current Notecard object. - mode (str): Used to specify the color of the LED to turn on or off. Note: Notecard LoRa does not support monochromatic LED or RGB modes, only NeoPixels. + mode (str): Used to specify the color of the LED to turn on or off. Note: Notecard for LoRa does not support monochromatic LED or RGB modes, only NeoPixels. off (bool): Set to `true` to turn the specified LED or NeoPixel off. on (bool): Set to `true` to turn the specified LED or NeoPixel on. @@ -385,7 +385,7 @@ def locationMode(card, delete=None, lat=None, lon=None, max=None, minutes=None, @validate_card_object def location(card): - """Retrieve the last known location of the Notecard and the time at which it was acquired. Use card.location.mode to configure location settings. This request will return the cell tower location or triangulated location of the most recent session if a GPS/GNSS location is not available. On Notecard LoRa this request can only return a location set through the card.location.mode request's `"fixed"` mode. + """Retrieve the last known location of the Notecard and the time at which it was acquired. Use card.location.mode to configure location settings. This request will return the cell tower location or triangulated location of the most recent session if a GPS/GNSS location is not available. On Notecard for LoRa this request can only return a location set through the card.location.mode request's `"fixed"` mode. Args: card (Notecard): The current Notecard object. @@ -656,7 +656,7 @@ def sleep(card, mode=None, off=None, on=None, seconds=None): @validate_card_object def restore(card, connected=None, delete=None): - """Perform a factory reset on the Notecard and restarts. Sending this request without either of the optional arguments below will only reset the Notecard's file system, thus forcing a re-sync of all Notefiles from Notehub. On Notecard LoRa there is no option to retain configuration settings, and providing `"delete": true` is required. The Notecard LoRa retains LoRaWAN configuration after factory resets. + """Perform a factory reset on the Notecard and restarts. Sending this request without either of the optional arguments below will only reset the Notecard's file system, thus forcing a re-sync of all Notefiles from Notehub. On Notecard for LoRa there is no option to retain configuration settings, and providing `"delete": true` is required. The Notecard for LoRa retains LoRaWAN configuration after factory resets. Args: card (Notecard): The current Notecard object. @@ -746,7 +746,7 @@ def trace(card, mode=None): @validate_card_object -def transport(card, allow=None, method=None, seconds=None, set=None, umin=None): +def transport(card, allow=None, method=None, seconds=None, set=None, umin=None, uoff=None): """Specify the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard. Args: @@ -756,6 +756,7 @@ def transport(card, allow=None, method=None, seconds=None, set=None, umin=None): 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. + uoff (bool): Set to `true` to turn off the longer network transport timeout set with `umin`. Returns: dict: The result of the Notecard request. @@ -771,6 +772,8 @@ def transport(card, allow=None, method=None, seconds=None, set=None, umin=None): req["set"] = set if umin is not None: req["umin"] = umin + if uoff is not None: + req["uoff"] = uoff return card.Transaction(req) @@ -867,7 +870,7 @@ def version(card): @validate_card_object -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): +def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None, now=None, off=None, offset=None, on=None, reset=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: @@ -881,6 +884,7 @@ def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None 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. + reset (bool): Set to `true` to clear a calibration value previously set with `set` and `calibration`, restoring the default calibration. 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. @@ -909,6 +913,8 @@ def voltage(card, alert=None, calibration=None, hours=None, mode=None, name=None req["offset"] = offset if on is not None: req["on"] = on + if reset is not None: + req["reset"] = reset if set is not None: req["set"] = set if sync is not None: diff --git a/notecard/hub.py b/notecard/hub.py index c8b13a1..5086e5a 100644 --- a/notecard/hub.py +++ b/notecard/hub.py @@ -56,7 +56,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. The cycle is anchored to the moment the Notecard first obtained valid time after booting, 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. + details (str): When using Notecard for 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. 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`). diff --git a/notecard/note.py b/notecard/note.py index 26b2ed1..ef05faa 100644 --- a/notecard/note.py +++ b/notecard/note.py @@ -20,7 +20,7 @@ def add(card, binary=None, body=None, file=None, full=None, key=None, limit=None card (Notecard): The current Notecard object. binary (bool): If `true`, the Notecard will send all the data in the binary buffer to Notehub. Learn more in this guide on Sending and Receiving Large Binary Objects. body (dict): A JSON object to be enqueued. A Note must have either a `body` or a `payload`, and can have both. - file (str): The name of the Notefile. On Notecard LoRa this argument is required. On all other Notecards this field is optional and defaults to `data.qo` if not provided. When using this request on the Notecard the Notefile name must end in one of: `.qo` for a queue outgoing (Notecard to Notehub) with plaintext transport `.qos` for a queue outgoing with encrypted transport `.db` for a bidirectionally synchronized database with plaintext transport `.dbs` for a bidirectionally synchronized database with encrypted transport `.dbx` for a local-only database + file (str): The name of the Notefile. On Notecard for LoRa this argument is required. On all other Notecards this field is optional and defaults to `data.qo` if not provided. When using this request on the Notecard the Notefile name must end in one of: `.qo` for a queue outgoing (Notecard to Notehub) with plaintext transport `.qos` for a queue outgoing with encrypted transport `.db` for a bidirectionally synchronized database with plaintext transport `.dbs` for a bidirectionally synchronized database with encrypted transport `.dbx` for a local-only database full (bool): If set to `true`, and the Note is using a Notefile Template, the Note will bypass usage of omitempty and retain `null`, `0`, `false`, and empty string `""` values. key (str): The name of an environment variable in your Notehub project that contains the contents of a public key. Used when encrypting the Note body for transport. Note body encryption is not supported on Notecard for LoRa. limit (bool): If set to `true`, the Note will not be created if Notecard is in a penalty box. @@ -161,9 +161,9 @@ def template(card, file, body=None, delete=None, format=None, length=None, port= 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 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. + 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 for 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. - port (int): This argument is required on Notecard LoRa and a Notecard paired with Starnote, but ignored on all other Notecards. A port is a unique integer in the range 1–100, where each unique number represents one Notefile. This argument allows the Notecard to send a numerical reference to the Notefile over the air, rather than the full Notefile name. The port you provide is also used in the "frame port" field on LoRaWAN gateways. + port (int): This argument is required on Notecard for LoRa and a Notecard paired with Starnote, but ignored on all other Notecards. A port is a unique integer in the range 1–100, where each unique number represents one Notefile. This argument allows the Notecard to send a numerical reference to the Notefile over the air, rather than the full Notefile name. The port you provide is also used in the "frame port" field on LoRaWAN gateways. verify (bool): If `true`, returns the current template set on a given Notefile. Returns: