diff --git a/notecard/card.py b/notecard/card.py index ac559a6..953e266 100644 --- a/notecard/card.py +++ b/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: diff --git a/notecard/hub.py b/notecard/hub.py index 0606529..b7e48a8 100644 --- a/notecard/hub.py +++ b/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.