Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions notecard/card.py
Original file line number Diff line number Diff line change
Expand Up @@ -404,7 +404,7 @@ def locationTrack(card, file=None, heartbeat=None, hours=None, payload=None, sta
Args:
card (Notecard): The current Notecard object.
file (str): The Notefile in which to store tracked location data. See the `_track.qo` Notefile's documentation for details on the format of the data captured.
heartbeat (bool): When `start` is `true`, set to `true` to capture a tracking Note on a fixed interval even when no motion has been detected. The interval is configured with the `hours` field below.
heartbeat (bool): When `start` is `true`, set to `true` to capture a tracking Note on a fixed interval even when no motion has been detected. The interval is configured with the `hours` field below. A heartbeat Note records the Notecard's last-known location without activating GPS to obtain a new fix.
hours (int): When `heartbeat` is `true`, the interval at which to capture a heartbeat tracking Note. A positive value sets the interval in hours (e.g. `2` captures a Note every two hours). To configure an interval shorter than one hour, pass a negative integer whose absolute value is the number of minutes (e.g. `-30` captures a Note every 30 minutes).
payload (str): A base64-encoded binary payload to be included in the next `_track.qo` Note. See the guide on Sampling at Predefined Intervals for more details.
start (bool): Set to `true` to start Notefile tracking.
Expand Down Expand Up @@ -752,7 +752,7 @@ def transport(card, allow=None, method=None, seconds=None, set=None, umin=None,
Args:
card (Notecard): The current Notecard object.
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.
method (str): The connectivity method to enable on the Notecard. See Connection Retry and Fallback Behaviors for when the Notecard falls back to the next transport and when it retries the preferred one.
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.
Expand Down
27 changes: 12 additions & 15 deletions notecard/hub.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ def log(card, alert=None, sync=None, text=None):

Args:
card (Notecard): The current Notecard object.
alert (bool): `true` if the message is urgent. This doesn't change any functionality, but rather `alert` is provided as a convenient flag to use in your program logic.
sync (bool): `true` if a sync should be initiated immediately. Setting `true` will also remove the Notecard from certain types of penalty boxes.
text (str): Text to log.
alert (bool): `true` if the message is urgent. This doesn't change how the Notecard handles the message. It adds `"alert":true` to the logged Note, so you can act on it after the Note reaches Notehub.
sync (bool): `true` to sync the log message to Notehub immediately. Setting `true` also removes the Notecard from certain types of penalty boxes.
text (str): Text to log. If omitted, nothing is logged.

Returns:
dict: The result of the Notecard request.
Expand All @@ -56,21 +56,21 @@ 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 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.
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":"00088B3700112233445566778899AABB"}` 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.
host (str): The hostname of the Notehub service, such as `a.notefile.net` (the default). Use `"-"` to reset to the default value.
inbound (int): The maximum wait time, in minutes, before syncing inbound data from Notehub. The default value of `0` disables automatic inbound syncing, meaning inbound data is only synced when explicitly requested, such as with `hub.sync`. Because of this, the `inbound` argument is required in `periodic` and `continuous` modes. Set to `-1` to restore the default value. The `_sync_inbound_mins` reserved environment variable and its variants override this setting when defined.
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. Ignored if the Notecard is already in `continuous` mode or if the Notecard is NOT performing a web transaction.
on (bool): If in `periodic` mode, used to temporarily switch the Notecard to `continuous` mode, typically to perform a web transaction. The Notecard stays in `continuous` mode until `seconds` pass without a web transaction, or until you send `off`, then returns to `periodic` mode. Ignored if the Notecard is already in `continuous` mode.
outbound (int): The maximum wait time, in minutes, before syncing outbound data from the Notecard. The default value of `0` disables automatic outbound syncing, meaning outbound data is only synced when explicitly requested, such as with `hub.sync`. Because of this, the `outbound` argument is required in `periodic` and `continuous` modes. Set to `-1` to restore the default value. The `_sync_outbound_mins` reserved environment variable and its variants override this setting when defined.
product (str): A Notehub-managed unique identifier that is used to match Devices with Projects. This string is used during a device's auto-provisioning to find the Notehub Project that, once provisioned, will securely manage the device and its data.
seconds (int): If in `periodic` mode and using `on` above, the number of seconds to run in continuous mode before switching back to periodic mode. If not set, a default of 300 seconds is used. Ignored if the Notecard is already in continuous mode.
seconds (int): If in `periodic` mode and using `on` above, the number of seconds the Notecard waits without a web transaction before switching back to periodic mode. Each web transaction restarts this wait. If not set, a default of 300 seconds is used. Ignored if the Notecard is already in continuous mode.
sn (str): The end product's serial number.
sync (bool): If in `continuous` mode, automatically and immediately sync each time an inbound Notefile change is detected on Notehub. NOTE: The `sync` argument is not supported when a Notecard is in NTN mode.
umin (bool): Set to `true` to use USB/line power variable sync behavior, enabling the Notecard to stay in `continuous` mode when connected to USB/line power and fallback to `minimum` mode when disconnected.
uoff (bool): Set to `true` to use USB/line power variable sync behavior, enabling the Notecard to stay in `continuous` mode when connected to USB/line power and fallback to `off` mode when disconnected.
uperiodic (bool): Set to `true` to use USB/line power variable sync behavior, enabling the Notecard to stay in `continuous` mode when connected to USB/line power and fallback to `periodic` mode when disconnected.
umin (bool): Set to `true` to use USB/line power variable sync behavior, enabling the Notecard to stay in `continuous` mode when connected to USB/line power and fall back to `minimum` mode when disconnected. Must be sent in the same request as `mode`. Any later `hub.set` that sets `mode` without this argument turns it off.
uoff (bool): Set to `true` to use USB/line power variable sync behavior, enabling the Notecard to stay in `continuous` mode when connected to USB/line power and fall back to `off` mode when disconnected. Must be sent in the same request as `mode`. Any later `hub.set` that sets `mode` without this argument turns it off.
uperiodic (bool): Set to `true` to use USB/line power variable sync behavior, enabling the Notecard to stay in `continuous` mode when connected to USB/line power and fall back to `periodic` mode when disconnected. Must be sent in the same request as `mode`. Any later `hub.set` that sets `mode` without this argument turns it off.
version (str): The version of your host firmware. The value provided will appear on your device in Notehub under the "Host Firmware" tab. You may pass a simple version number string (e.g. "1.0.0.0"), or an object with detailed information about the firmware image. 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"}` If your project uses Notecard Outboard Firmware Update, you can alternatively use the `dfu.status` request to set your host firmware version.
vinbound (str): Overrides `inbound` with a voltage-variable value. Use `"-"` to clear this value. NOTE: Setting voltage-variable values is not supported on Notecard XP.
voutbound (str): Overrides `outbound` with a voltage-variable value. Use `"-"` to clear this value. NOTE: Setting voltage-variable values is not supported on Notecard XP.
Expand Down Expand Up @@ -121,19 +121,16 @@ def set(card, align=None, details=None, duration=None, host=None, inbound=None,


@validate_card_object
def signal(card, seconds=None):
def signal(card):
"""Receive a Signal (a near-real-time Note) from Notehub. This request checks for an inbound signal from Notehub. If it finds a signal, this request returns the signal's body and deletes the signal. If there are multiple signals to receive, this request reads and deletes signals in FIFO (first in first out) order.

Args:
card (Notecard): The current Notecard object.
seconds (int): The number of seconds to wait before timing out the request.

Returns:
dict: The result of the Notecard request.
"""
req = {"req": "hub.signal"}
if seconds is not None:
req["seconds"] = seconds
return card.Transaction(req)


Expand Down Expand Up @@ -180,7 +177,7 @@ def syncStatus(card, sync=None):

Args:
card (Notecard): The current Notecard object.
sync (bool): `true` if this request should auto-initiate a sync pending outbound data.
sync (bool): `true` to start a sync if the Notecard has pending outbound data and no sync is already in progress.

Returns:
dict: The result of the Notecard request.
Expand Down
8 changes: 4 additions & 4 deletions notecard/note.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ def add(card, binary=None, body=None, file=None, full=None, key=None, limit=None
live (bool): If `true`, bypasses saving the Note to flash on the Notecard. Required to be set to `true` if also using `"binary":true`.
max (int): Defines the maximum number of queued Notes permitted in the specified Notefile (`"file"`). Any Notes added after this value will be rejected. When used with `"sync":true`, a sync will be triggered when the number of pending Notes matches the `max` value.
note (str): If the Notefile has a `.db/.dbs/.dbx` extension, specifies a unique Note ID. If `note` string is `"?"`, then a random unique Note ID is generated and returned as `{"note":"xxx"}`. If this argument is provided for a `.qo` Notefile, an error is returned.
payload (str): A base64-encoded binary payload. A Note must have either a `body` or a `payload`, and can have both. Payloads are limited to 256 bytes.
payload (str): A base64-encoded binary payload. A Note must have either a `body` or a `payload`, and can have both. Payloads are limited to 256 bytes, except in outbound Notefiles (`.qo`/`.qos`) that have a Note template.
sync (bool): Set to `true` to sync immediately. Only applies to outgoing Notecard requests, and only guarantees syncing the specified Notefile. Auto-syncing incoming Notes from Notehub is set on the Notecard with `{"req": "hub.set", "mode":"continuous", "sync": true}`.
verify (bool): If set to `true` and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.
verify (bool): If set to `true`, the Notefile is written to flash immediately, rather than being cached in RAM and written to flash later, so the Note survives a sudden power loss or restart before it syncs. Use it only for Notes you can't afford to lose, since frequent flash writes add time, power use, and flash wear.

Returns:
dict: The result of the Notecard request.
Expand Down Expand Up @@ -108,7 +108,7 @@ def delete(card, file, note, verify=None):
card (Notecard): The current Notecard object.
file (str): The Notefile from which to delete a Note. Must be a Notefile with a `.db` or `.dbx` extension.
note (str): The Note ID of the Note to delete.
verify (bool): If set to `true` and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.
verify (bool): If set to `true`, the Notefile is written to flash immediately, rather than being cached in RAM and written to flash later, so the deletion survives a sudden power loss or restart. Use it only for deletions you can't afford to lose, since frequent flash writes add time, power use, and flash wear.

Returns:
dict: The result of the Notecard request.
Expand Down Expand Up @@ -198,7 +198,7 @@ def update(card, file, note, body=None, payload=None, sync=None, verify=None):
note (str): The unique Note ID.
payload (str): A base64-encoded binary payload. A Note must have either a `body` or `payload`, and can have both.
sync (bool): Set to `true` to sync the Notefile immediately after updating the Note. Only the specified Notefile is guaranteed to sync.
verify (bool): If set to `true` and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.
verify (bool): If set to `true`, the Notefile is written to flash immediately, rather than being cached in RAM and written to flash later, so the update survives a sudden power loss or restart. Use it only for updates you can't afford to lose, such as stored settings, since frequent flash writes add time, power use, and flash wear.

Returns:
dict: The result of the Notecard request.
Expand Down
2 changes: 1 addition & 1 deletion test/fluent_api/test_hub.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@
(
hub.signal,
'hub.signal',
{'seconds': 30},
{},
None
),
(
Expand Down