Configuration and Control Interfaces

Device configuration and control is done through ‘interfaces,’ objects that encapsulate the processes. Typically, neither of these interfaces are explicitly created; accessing Recorder.config and Recorder.command will automatically instantiate a ConfigInterface or CommandInterface subclass appropriate for the given device.

There is some overlap between the configuration and command interfaces; for example, configuring Wi-Fi or setting a device’s clock are handled through the command interface. As a rule, changes that happen immediately are commands, and changes that apply after the recorder restarts (e.g., being reset, starting a recording, being disconnected) are handled by the configuration interface.

Configuration

class endaq.device.config.ConfigInterface(device)

Base class for mechanisms to access/modify device configuration.

Variables

  • config – Device configuration data (e.g., data read from the config file). This may be set manually to override defaults and/or existing configuration data. Manual setting must be done after instantiation and before accessing config elements via the interface’s item attribute.

  • configUi – Device configuration UI information. May be set manually to override defaults. Manual setting must be done after instantiation and before accessing config elements via item.

  • unknownConfig – A dictionary of configuration item types and values, keyed by Config ID. Items read from the configuration file that do not match items in the ConfigUI data go into the dictionary. These will (by default) be written back to the config file verbatim. unknownConfig may also be used to manually add arbitrary items to the config file.

ConfigInterface instances are rarely (if ever) explicitly created; the parent Recorder object will create the appropriate ConfigInterface when its config property is first accessed.

Parameters

device (Recorder) – The Recorder to configure.

applyConfig(unknown=True, version=None)

Apply (save) configuration data to the device.

Parameters

  • unknown (bool, default: True) – If True, include values that do not correspond to known configuration items (e.g., originally read from the config file).

  • version (Optional[int], default: None) – The version of configuration data to use, if the device supports more than one. Defaults to the latest version supported.

property available: bool

Is the device currently ready for configuration?

Note: This is intended for future configuration systems. Since configuration is currently applied via the filesystem, it is functionally the same as Recorder.available.

property buttonMode: Optional[int]

The ID of the device’s ‘button mode’ (what happens when the device’s primary button is pressed).

property buttonModes: Dict[int, str]

The IDs and descriptions of all known Button Mode options. Read only.

close()

Close the interface. Only applicable to subclasses with a persistent connection. Fails silently.

Returns

True if the connection was reset (or the interface type has no persistent connection).

Return type

bool

enableChannel(channel, enabled=True)

Enable or disable a Channel or SubChannel.

Due to the way in which they operate, some sensor’s SubChannels cannot be individually configured, and changes must be made to the parent Channel. The opposite is true for other sensors - primarily the analog ones - which can only be configured at the SubChannel level. Attempting to configure at the wrong ‘level’ will raise a ConfigError.

Parameters

  • channel (Union[Channel, SubChannel]) – The channel or subchannel to enable/disable.

  • enabled (bool, default: True) – True to enable the channel/subchannel recording.

getChanges()

Has the configuration data been modified?

getConfig()

Low-level method that retrieves the device’s config EBML (e.g., the contents of a real device’s config.cfg file), if any.

getConfigUI()

Get the device’s ConfigUI data.

getConfigValues(original=False, defaults=False, none=False, unknown=True)

Get the device configuration as a simple dictionary of values keyed by config ID.

Parameters

  • original (bool, default: False) – If True, return only the values read from the device configuration. Overrides the other parameters.

  • defaults (bool, default: False) – If True, include items with their default values, not only those explicitly set or read from a file.

  • none (bool, default: False) – If False, exclude items with values of None.

  • unknown (bool, default: True) – If True, include values read from the config file that do not correspond to know configuration items.

getSampleRate(channel)

Get the sample rate of a Channel.

Parameters

channel (Channel) – The Channel to get.

Returns

The sampling rate, in hertz.

Return type

float

getTrigger(channel)

Get the trigger information for a Channel or SubChannel.

Parameters

channel (Union[Channel, SubChannel]) – The Channel or SubChannel to get.

Returns

A dict of trigger parameters, usable as keyword arguments for setTrigger().

Return type

dict

getTriggers()

Get all settable triggers (threshold, high, and/or low).

Returns

A list of all trigger configuration items.

Return type

List[endaq.device.config.ConfigItem]

classmethod hasInterface(device)

Determine if a device supports this ConfigInterface type.

Parameters

device (Recorder) – The Recorder to check.

Returns

True if the device supports the interface.

Return type

bool

isEnabled(channel)

Is the Channel or SubChannel enabled?

Due to the way in which they operate, some sensor’s SubChannels cannot be individually configured, and changes must be made to the parent Channel. The opposite is true for other sensors - primarily the analog ones - which can only be configured at the SubChannel level. Attempting to configure at the wrong ‘level’ will raise a ConfigError.

Parameters

channel (Union[Channel, SubChannel]) – The Channel or SubChannel to check.

Returns

True if configured to record.

Return type

bool

property items: Dict[int, endaq.device.config.ConfigItem]

All defined configuration items for the device, keyed by Config ID.

loadConfig(config=None)

Process a device’s configuration data.

Parameters

config (Optional[MasterElement], default: None) – Optional, explicit configuration EBML data to process. If none is provided, the data retrieved by getConfig() will be used.

property name: Optional[str]

User-entered name of the device.

property notes: Optional[str]

User-entered notes/description of the device.

parseConfigUI(configUi)

Recursively process CONFIG.UI data to populate the interface’s dictionaries of configuration items.

Parameters

configUi (Union[Document, Element]) – A parsed CONFIG.UI EBML document or element.

property pluginAction: Optional[int]

The ID of the device’s Plug-In Action (what happens when attached by USB).

property pluginActions: Dict[int, str]

The IDs and descriptions of all known Plug-In Action options. Read only.

property recordingDir: Optional[str]

The name of the directory (on the device) where recordings are saved.

property recordingPrefix: Optional[str]

Prefix string for all recording filenames.

revert()

Reset all configuration values to what was originally read from the configuration file, or None if the value was never read from the file.

saveAs(filename, unknown=True, version=None)

Save the raw configuration data to a file (e.g., config.cfg). The file saved is the equivalent of the recorder’s native config data, and can only be applied to the original recorder (or one of the same model). To export configuration data for use on another device, use endaq.device.configio.exportConfig().

Parameters

  • filename (Union[str, Path]) – The name of the output file. By convention, the extension is .cfg, but this is not enforced.

  • unknown (bool, default: True) – If True, include values that do not correspond to known configuration items (e.g., originally read from the config file).

  • version (Optional[int], default: None) – The version of configuration data to use, if the device supports more than one. Defaults to the latest version supported.

setSampleRate(channel, sampleRate)

Set the sample rate of a Channel.

Parameters

  • channel (Channel) – The Channel to set.

  • sampleRate (float) – The new sampling rate, in hertz.

setTrigger(channel, **kwargs)

Set the trigger for a Channel or Subchannel.

Parameters

  • channel (Union[Channel, SubChannel]) – The channel or subchannel to configure.

  • low – The trigger’s low threshold value (if applicable).

  • high – The trigger’s high threshold value (if applicable). Also used for sensors that have only an absolute threshold trigger (e.g., a shock trigger).

  • enabled – True to enable the channel/subchannel trigger. Threshold arguments are Values of high and low are optional if False.

property supportedConfigVersions

A tuple of configuration data format versions supported by the interface. 1 is the original SlamStick version, only supported on old hardware/firmware. The current version is 2.

property tags: Optional[str]

The device’s recording tags (comma-separated string), stored in each recording. Primarily used for organization on enDAQ Cloud.

property utcOffset: Optional[Union[float, int]]

The recorder’s local offset from UTC, in minutes.

Control

class endaq.device.command_interfaces.CommandInterface(device)

Base class for command interfaces, the mechanism that communicates with and controls the recording device.

Variables

  • timeout – The underlying communication medium’s response timeout (in seconds). This is not the same as the timeout for individual commands. Not used by all interface types.

  • status – The last reported device status. Not available on all interface types. A tuple containing the status code and a status message string (optional).

CommandInterface instances are rarely (if ever) explicitly created; the parent Recorder object will create an instance of the appropriate CommandInterface subclass when its command property is first accessed.

Parameters

device (Recorder) – The Recorder to which to interface.

property available: bool

Is the command interface available and able to accept commands?

awaitReboot(timeout=None, timeoutMsg=None, callback=None)

Wait for the device to dismount as a drive, indicating it has rebooted, started recording, started firmware application, etc.

Parameters

  • timeout (Union[int, float, None], default: None) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately; None or -1 will wait indefinitely.

  • timeoutMsg (Optional[str], default: None) – A command-specific message to use when raising a DeviceTimeout exception.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

True if the device unmounted. False if it is a virtual device, or the wait was cancelled by the callback.

Return type

bool

awaitRemount(update=False, paths=None, strict=True, timeout=None, interval=0.125, callback=None)

Wait for the device to reappear as a drive, indicating it has been reconnected, completed a recording, finished firmware application, etc.

Parameters

  • update (bool, default: False) – If True, attempt to update the device’s information. This may be required if the device has had its firmware or userpage updated.

  • paths (Optional[List[Union[AnyStr, Path, Drive]]], default: None) – For use with update. A list of specific paths to search for the updated recording device.

  • strict (bool, default: True) – For use with update. If True, non-FAT file systems will be automatically rejected when searching for the updated recording device.

  • timeout (Union[int, float, None], default: None) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately; None or -1 will wait indefinitely.

  • interval (float, default: 0.125) – Time (in seconds) between checks for the remounted device.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

True if the device reappeared. False if it is a virtual device, or the wait was cancelled by the callback.

Return type

bool

Blink the device’s LEDs. This is intended for identifying a specific recorder when multiple are plugged into one computer. Not supported on all devices.

Blinking will alternate between patterns a and b every 0.5 seconds, continuing for the specified duration. a and b are unsigned 8 bit integers, in which each bit represents one of the recorder’s LEDs:

  • Bit 0 (LSB): Red

  • Bit 1: Green

  • Bit 2: Blue

  • Bits 3-7: Reserved for future use.

Parameters

  • duration (int, default: 3) – The total duration (in seconds) of the blinking, maximum 255. 0 will blink without time limit, stopping when the device is disconnected from USB, or when a recording is started (trigger or button press).

  • priority (int, default: 0) – If 1, the Blink command should take precedence over all other device LED sequences. If 0, the Blink command should not take precedence over Wi-Fi indications including Provisioning, Connecting, and Success/Failure indications, but it should take precedence over battery indications.

  • a (int, default: 7) – LED pattern ‘A’.

  • b (int, default: 0) – LED pattern ‘B’.

property canCopyFirmware: bool

Can the device get new firmware/userpage from a file?

property canRecord: bool

Can the device record on command?

clearLockID(current=None, timeout=5)

Clear the lock ID on the device.

Lock IDs are a weakly-enforced means of requesting exclusive use of a device. If a device has a lock ID set, commands sent without that ID will generate an error.

Parameters

  • current (Union[bytearray, bytes, None], default: None) – The lock ID currently on the device. Defaults to this command interface’s current lock ID (if any), but one can be supplied to force a device with a different ID to clear it.

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for a response.

close()

Close the interface. Only applicable to subclasses with a persistent connection (e.g., SerialCommandInterface). Fails silently.

Returns

True if the connection was reset (or the interface type has no persistent connection).

Return type

bool

getBatteryStatus(timeout=1, callback=None)

Get the status of the recorder’s battery. Not supported on all devices. Status is returned as a dictionary. The dictionary will always contain the key “hasBattery”, and if that is True, it will contain other keys:

  • “charging”: (bool) True if the battery is charging.

  • “percentage”: (bool) True if the reported charge level is a percentage, or 3 states (0 = empty, 255 = full, anything else is ‘some’ charge) of False.

  • “level”: (int) The current battery charge level.

If the device is capable of reporting if it is receiving external power, the dict will contain “externalPower” (bool).

Parameters

  • timeout (Union[int, float], default: 1) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately; None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

A dictionary with the parsed battery status.

Raises

UnsupportedFeature – Raised if the device does not

Return type

bool

support the command.

getClockDrift(pause=True, retries=1)

Calculate how far the recorder’s clock has drifted from the system time.

Parameters

  • pause (bool, default: True) – If True (default), the system waits until a whole-numbered second before reading the device’s clock. This may improve accuracy since the device’s realtime clock is in integer seconds.

  • retries (int, default: 1) – The number of attempts to make, should the first fail. Random filesystem things can potentially cause hiccups.

Returns

The length of the drift, in seconds.

Return type

float

getLockID(timeout=5)

Get the device’s current lock ID, if any. Not supported by all device types or firmware versions.

Lock IDs are a weakly-enforced means of requesting exclusive use of a device. If a device has a lock ID set, commands sent without that ID will generate an error.

Parameters

timeout (Union[int, float], default: 5) – Time (in seconds) to wait for a response.

Returns

The device’s current lock ID, if any.

Return type

Optional[Union[bytearray, bytes]]

getNetworkAddress(timeout=10, interval=0.25, callback=None)

Get the device’s unique MAC address and its assigned IPv4 address as a tuple of human-readable strings (e.g., ("89:ab:cd:ef", "192.168.1.10")). If the device is not connected, the IP (the second item in the tuple) will be None. If the device does not have network hardware (Wi-Fi, etc.), both the MAC and IP will be None; unlike the other network related methods, it does not raise an exception if the device does not have network hardware.

Raises

DeviceTimeout – Raised if ‘timeout’ seconds have gone by without getting a response

Parameters

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. None or -1 will wait indefinitely.

  • interval (float, default: 0.25) – Time (in seconds) between checks for a response.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

A two-item tuple containing the device’s MAC address and IP address. One or both may be None, as described above.

Return type

Tuple[Optional[str], Optional[str]]

getNetworkStatus(timeout=10, interval=0.25, callback=None)

Check the device’s networking hardware. The response is less specific to one interface type (i.e., the results of queryWiFi()).

The resluts is a dictionary, with keys:

  • MACAddress (bytes): The unique hardware address of the

    device’s network interface (does not change).

  • IPV4Address (bytes): The device’s IP address (typically

    set by the router when the device connects). This will not be present if the device is not connected.

  • CurrentWiFiStatus (int, optional): The Wi-Fi connection

    status. May not be present. Note: this is not the same as the WiFiConnectionStatus in the response returned by queryWifi().

Raises

  • DeviceTimeout – Raised if ‘timeout’ seconds have gone by without getting a response

  • UnsupportedFeature – Raised if the device does not support Wi-Fi.

Parameters

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. None or -1 will wait indefinitely

  • interval (float, default: 0.25) – Time (in seconds) between checks for a response.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

A list of dictionaries, described above.

Return type

Union[None, dict]

getTime(epoch=True)

Read the date/time from the device. Also returns the current system time for comparison.

Parameters

epoch (bool, default: True) – If True, return the date/time as integer seconds since the epoch (‘Unix time’). If False, return a Python datetime.datetime object.

Returns

The system time and the device time. Both are UTC.

Return type

Union[Tuple[datetime.datetime, datetime.datetime], Tuple[Union[float, int], Union[float, int]]]

classmethod hasInterface(device)

Determine if a device supports this CommandInterface type.

Parameters

device (Recorder) – The recorder to check.

Returns

True if the device supports the interface.

Return type

bool

ping(data=None, timeout=5, callback=None)

Verify the recorder is present and responding. Not supported on all devices.

Parameters

  • data (Union[bytearray, bytes, None], default: None) – An optional binary payload, returned by the recorder verbatim.

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately; None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

The received data, which should be identical to the data sent.

Raises

UnsupportedFeature – Raised if the device does not

Return type

bytes

support the command.

queryWifi(timeout=10, interval=0.25, callback=None)

Check the current state of the Wi-Fi (if present). Applicable only to devices with Wi-Fi hardware.

Parameters

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception.

  • interval (float, default: 0.25) – Time (in seconds) between checks for a response.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

None if no information was recieved, else it will return the information from the QueryWiFiResponse command (this return statement is not used anywhere)

Raises

  • UnsupportedFeature – Raised if the device does not support Wi-Fi.

  • DeviceTimeout – Raised if ‘timeout’ seconds have gone by without getting a response

Return type

Union[None, dict]

reset(timeout=5, callback=None)

Reset (reboot) the recorder. Must be implemented in every subclass.

Parameters

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately; None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

True if the command was successful.

Return type

bool

resetConnection()

Reset the interface. Only applicable to subclasses with a persistent connection. Fails silently.

Returns

True if the connection was reset (or the interface type has no persistent connection).

Return type

bool

scanWifi(timeout=10, interval=0.25, callback=None)

Initiate a scan for Wi-Fi access points (APs). Applicable only to devices with Wi-Fi hardware.

The resluts are returned as a list of dictionaries, one for each access point, with keys:

  • SSID (str): The access point name.

  • RSSI (int): The AP’s signal strength.

  • AuthType (int): The authentication (security) type. Currently, this is either 0 (no authentication) or 1 (any authentication).

  • Known (bool): Is this access point known (i.e. has a stored password on the device)?

  • Selected (bool): Is this the currently selected AP?

Raises

  • DeviceTimeout – Raised if ‘timeout’ seconds have gone by without getting a response

  • UnsupportedFeature – Raised if the device does not support Wi-Fi.

Parameters

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception.

  • interval (float, default: 0.25) – Time (in seconds) between checks for a response.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

A list of dictionaries, described above.

Return type

Union[None, list]

setAP(ssid, password=None, wait=False, timeout=10, callback=None)

Quickly set the Wi-Fi access point (router) and password. Applicable only to devices with Wi-Fi hardware.

Parameters

  • ssid (str) – The SSID (name) of the wireless access point.

  • password (Optional[str], default: None) – The access point password.

  • wait (bool, default: False) – If True, wait until the device reports it is connected before returning.

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments. The callback will not be called if wait is False.

setKeys(keys, timeout=5, callback=None)

Update the device’s key bundle

Parameters

  • keys (Union[bytearray, bytes]) – The key data.

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately. None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

setLockID(current=None, new=None, timeout=5)

Set a unique ‘lock’ ID on the device, requesting exclusive use of the device. Not supported by all devices/firmware.

Lock IDs are a weakly-enforced means of requesting exclusive use of a device. If a device has a lock ID set, commands sent without that ID will generate an error.

Parameters

  • current (Union[bytearray, bytes, None], default: None) – The lock ID currently on the device; for use if the device already has a lock ID set.

  • new (Union[bytearray, bytes, None], default: None) – The new lock ID. It defaults to the command interface’s lockId (generated when the CommandInterface was instantiated, and unique to this instance).

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for a response.

Returns

The new lock ID.

Return type

Union[bytearray, bytes]

setTime(t=None, pause=True, retries=1)

Set a recorder’s date/time. A variety of standard time types are accepted. Note that the minimum unit of time is the whole second.

Parameters

  • t (Union[float, int, datetime, struct_time, tuple, None], default: None) – The time to write, as either seconds since the epoch (i.e. ‘Unix time’), datetime.datetime or a UTC time.struct_time. The current time (from the host) is used if None (default).

  • pause (bool, default: True) – If True (default), the system waits until a whole-numbered second before setting the clock. This may improve accuracy across multiple recorders, but may take up to a second to run. Not applicable if a specific time is provided (i.e. t is not None).

  • retries (int, default: 1) – The number of attempts to make, should the first fail. Although rare, random filesystem things can potentially cause hiccups.

Returns

The system time (float) and time that was set (integer). Both are UNIX epoch time (seconds since 1970-01-01T00:00:00).

Return type

Tuple[Union[float, int], Union[float, int]]

setWifi(wifi_data, timeout=10, interval=1.25, callback=None)

Configure all known Wi-Fi access points. Applicable only to devices with Wi-Fi hardware. The data is in the form of a list of dictionaries with the following keys:

  • "SSID": The Wi-Fi access point name (string)

  • "Password": The access point’s password (string, optional)

  • "Selected": 1 if the device should use this AP, 0 if not

Note that devices (as of firmware 3.0.17) do not support configuring multiple Wi-Fi AP. Consider using setAP() instead.

Parameters

  • wifi_data (dict) – The information about the Wi-Fi networks to be set on the device.

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. None or -1 will wait indefinitely.

  • interval (float, default: 1.25) – Time (in seconds) between checks for a response.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Raises

UnsupportedFeature – Raised if the device does not support Wi-Fi.

startRecording(timeout=5, callback=None)

Start the device recording, if supported.

Parameters

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

True if the command was successful.

Return type

bool

stopRecording(timeout=5, callback=None)

Stop a device that is recording, if supported.

Parameters

  • timeout (Union[int, float], default: 5) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

True if the command was successful.

updateDevice(firmware=None, userpage=None, clean=False, timeout=10.0, callback=None)

Apply a firmware package and/or device description data update to the device. If no filenames are supplied, it will be assumed that one or both of the update files have been manually copied to the recorder; a FileNotFound exception will be raised if neither exist on the device.

Parameters

  • firmware (Optional[str], default: None) – The name of the firmware file (typically “.pkg”, or “.bin” on older devices). If provided, any existing firmware update files already on the device will be overwritten.

  • userpage (Optional[str], default: None) – The name of the “userpage” device description file (typically “.bin”). If provided, any existing userpage update files already on the device will be overwritten. Warning: userpage data is specific to an individual recorder. Do not install a userpage file created for a different device!

  • clean (bool, default: False) – If True, any existing firmware or userpage update files will be removed from the device. Used if either firmware or userpage is supplied (but not both).

  • timeout (Union[int, float], default: 10.0) – Time (in seconds) to wait for the recorder to dismount, implying the updates are being applied. 0 will return immediately; None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Returns

True if the device rebooted. Note: this does not indicate that the updates were successfully applied.

Return type

bool

updateESP32(firmware, timeout=10, callback=None)

Update the ESP32 firmware. Applicable only to devices with ESP32 Wi-Fi hardware.

Note: Updating the ESP32 is a long process, typically taking up to 4 minutes after calling the function to complete. This is normal.

Parameters

  • firmware (str) – The name of the ESP32 firmware package (.bin).

  • timeout (Union[int, float], default: 10) – Time (in seconds) to wait for the recorder to respond. 0 will return immediately; None or -1 will wait indefinitely.

  • callback (Optional[Callable], default: None) – A function to call each response-checking cycle. If the callback returns True, the wait for a response will be cancelled. The callback function should require no arguments.

Raises

UnsupportedFeature – Raised if the device does not support Wi-Fi via ESP32 hardware.

Special Notes

Callback Functions

Several commands feature a parameter for a callback function, which will be called periodically during potentially long-running functions. Callbacks are primarily intended for use with GUIs. If the function returns True, the command will be cancelled. Also, in cases in which the command is executing in the foreground thread, the callback creates an opportunity to update the UI.

Callback functions require no arguments, but for the sake of future-proofing, it is recommended that the functions accept them. In the future, commands may provide information via arguments (e.g., the percentage completed, elapsed time, etc.).

def my_callback(*args, **kwargs):
    """ Fake example callback function. Accepts any positional or keyword arguments,
        but ignores them. Setting the global variable `keep_going` to `True` will
        make the function return `True`, cancelling the command to which the callback
        function was provided.
    """
    # Something could happen here, like yielding some cycles to the GUI.
    # ...
    if keep_going:
        return False
    else:
        return True

previous

The Recorder Class

next

Special Topics and How-Tos