Command Interface¶

Command interfaces: the mechanisms that communicate with and control the recording device.

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.
response – 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?

awaitDisconnect(timeout=None, callback=None)¶

Wait for the command interface to disconnect, indicating the device has rebooted, started recording, started a firmware update, etc.

Note: this is not related to the await keyword, coroutines, or the asyncio library.

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.
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

awaitDismount(timeout=None, callback=None)¶

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

Note: this is not related to the await keyword, coroutines, or the asyncio library.

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.
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

awaitReboot(timeout=None, callback=None)¶

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

Note: this is not related to the await keyword, coroutines, or the asyncio library.

Deprecated since version 4.0: Use either awaitDismount() or awaitDisconnect() instead.

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.
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

awaitReconnect(timeout=None, callback=None)¶

Wait for the command interface to reconnect.

Note: this is not related to the await keyword, coroutines, or the asyncio library.

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.
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.

Note: this is not related to the await keyword, coroutines, or the asyncio library.

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(duration=3, priority=0, a=7, b=0)¶

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?

property canStream: bool¶: Can the device stream data? Only applicable to wireless devices connected through an MQTT broker.

clearLockID(current=None, response=True, timeout=5, callback=None)¶

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.
response (bool, default: True) – If True (default), wait for the device to respond, acknowledging the change.
timeout (Union[int, float], default: 5) – Time (in seconds) to wait 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.

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).

Raises

UnsupportedFeature – Raised if the device does not support the command.

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.

Return type

bool

getClockDrift(pause=True, retries=1, timeout=3)¶

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.
timeout (Union[int, float], default: 3) – Seconds to wait for a successful read, when pause is True, before raising a TimeoutError.

Returns

The length of the drift, in seconds.

Return type

float

getLockID(timeout=5, callback=None)¶

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.
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 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]

getStatus(timeout=10, callback=None)¶

Get the device’s status.

Parameters

timeout (Union[int, float], default: 10) – 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

The device’s current status, as a tuple containing the timestamp of the status update, the status code, and the corresponding status message (if any).

Return type

Tuple[float, Optional[int], Optional[str]]

getTime(epoch=True, timeout=3)¶

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.
timeout (Union[int, float], default: 3) – Seconds to wait for a successful read before raising a TimeoutError. Not used by all interface types.

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

isLocked(timeout=5, callback=None)¶

Has the hardware been ‘claimed’ for exclusive use via setLockID()?

Parameters

timeout (Union[int, float], default: 5) – Time (in seconds) to wait 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 tuple of Booleans: whether the device has a lock set, and whether the lock belongs to this instance.

Return type

tuple[bool, 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, not larger than 30 bytes, 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 support the command.

Return type

bytes

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(wait=True, timeout=5, callback=None)¶

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

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond and/or disconnect, indicating the reset has started.
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. This is rarely (if ever) done by users in typical operation of the device.

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, response=True, timeout=5, callback=None)¶

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).
response (bool, default: True) – If True (default), wait for the device to respond, acknowledging the change.
response – If True (default), wait for the device to respond, acknowledging the change.
timeout (Union[int, float], default: 5) – Time (in seconds) to wait 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

The new lock ID.

Return type

Union[bytearray, bytes]

setTime(t=None, pause=True, retries=1, timeout=3)¶

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.
timeout (Union[int, float], default: 3) – Seconds to wait for a successful read before raising a TimeoutError. Not used by all interface types.

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(wait=True, timeout=5, callback=None)¶

Start the device recording, if supported.

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond and/or dismount, indicating the recording has started.
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

startStream(filename, wait=True, timeout=10, callback=None, streamCallback=None)¶

Start a device recording/streaming and save the data it sends to a file.

This command is only applicable to wireless devices (i.e., the enDAQ W-series) on an MQTT network running an enDAQ MQTT Device Manager.

Parameters

filename (Union[str, Path]) – The name of the file to which to write the streamed data (e.g., an .IDE).
wait (bool, default: True) – If True, wait for the recorer to respond and/or disconnect, indicating the streaming has started.
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. Note that this only applies while starting the stream; use stopStreaming() to stop an active stream.
streamCallback (Optional[Callable], default: None) – A function to call each time a ‘chunk’ of streamed data arrives. It should take two parameters: the Recorder instance, and the number of bytes in the chunk. Note: Unlike other callback functions, its return value is ignored, so returning False does not cancel the operation.

Returns

True if the command was successful.

Return type

bool

stopRecording(wait=True, timeout=5, callback=None)¶

Stop a device that is recording, if supported.

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond and/or remount, indicating the recording has stopped.
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.

stopStream(wait=True, timeout=5, callback=None)¶

Stop a device that is streaming data.

This command is only applicable to wireless devices (i.e., the enDAQ W-series) on an MQTT network running an enDAQ MQTT Device Manager.

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond indicating the streaming has stopped.
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.

Return type

bool

streaming()¶

Is this instance receiving and recording data streamed from the device? Note: Only applicable to wireless devices connected through an MQTT broker.

updateDevice(firmware=None, userpage=None, validate=True, 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!
validate (bool, default: True) – If True, verify the update is compatible with the 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.

class endaq.device.command_interfaces.FileCommandInterface(device)¶

A mechanism for sending commands to a recorder via the COMMAND file.

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

property available: bool¶: Is the command interface available and able to accept commands?

classmethod hasInterface(device)¶

Determine if a device supports this CommandInterface type.

Parameters: device – The recorder to check.
Returns: True if the device supports the interface.
Return type: bool

reset(wait=True, timeout=10, callback=None)¶

Reset (reboot) the recorder.

Parameters

wait (bool, default: True) – If True, wait for the recorer to dismount, indicating the reset has taken effect.
timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. 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

startRecording(wait=True, timeout=10, callback=None)¶

Start the device recording, if supported.

Parameters

wait (bool, default: True) – If True, wait for the recorer to dismount, indicating the recording has started.
timeout (Union[int, float], default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception. 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

class endaq.device.command_interfaces.LegacyFileCommandInterface(device)¶

A mechanism for sending commands to a recorder via the COMMAND file. For devices using old firmware that supports only a subset of commands.

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

property canCopyFirmware: bool¶: Can the device get new firmware/userpage from a file?

property canRecord: bool¶: Can the device record on command?

classmethod hasInterface(device)¶

Determine if a device supports this CommandInterface type.

Parameters: device – The recorder to check.
Returns: True if the device supports the interface.
Return type: bool

setKeys(*args, **kwargs)¶: Update the device’s key bundle. Not supported on this device.

updateDevice(*args, **kwargs)¶

Apply a firmware package and/or device description data update. Not supported on this device; serial bootloader connection required.

class endaq.device.command_interfaces.SerialCommandInterface(device, make_crc=True, ignore_crc=False, **serial_kwargs)¶

A mechanism for sending commands to a recorder via a serial port.

Variables

response – The last reported device status. Not available on all interface types.
make_crc – If True, generate CRCs for outgoing packets.
ignore_crc – If True, ignore the CRC on response packets.

Constructor.

Parameters

device (Recorder) – The Recorder to which to interface.
make_crc (bool, default: True) – If True, generate CRCs for outgoing packets.
ignore_crc (bool, default: False) – If True, ignore the CRC on response packets.

If additional keyword arguments are provided, they will be used when opening the serial port.

property available: bool¶: Is the command interface available and able to accept commands?

awaitDisconnect(timeout=None, callback=None)¶

Wait for the command interface to disconnect, indicating the device has rebooted, started recording, started a firmware update, etc.

Note: this is not related to the await keyword, coroutines, or the asyncio library.

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.
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

awaitReconnect(timeout=None, callback=None)¶

Wait for the command interface to reconnect.

Note: this is not related to the await keyword, coroutines, or the asyncio library.

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.
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

blink(duration=3, priority=0, a=7, b=0)¶

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.

Bit 0 (LSB): Green

Bit 1: Red

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’.

clearLockID(current=None, response=True, timeout=5, callback=None)¶

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, but one can be supplied to force a device with a different ID to clear it.
response (bool, default: True) – If True (default), wait for the device to respond, acknowledging the change.
timeout (Union[int, float], default: 5) – Time (in seconds) to wait 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.

close()¶

Close the serial connection.

Returns: True if the interface connection has closed, or was already closed.
Return type: bool

classmethod findSerialPort(device, strict=True)¶

Find the path/name/number of a serial port corresponding to a given serial number.

Parameters

device (Union[Recorder, int, str]) – The Recorder to check, or a recorder serial number.
strict (bool, default: True) – If True, check the USB serial port VID and PID to see if they belong to a known type of device. If False, only the serial number is checked.

Returns

The corresponding serial port path/name/number, or None if no matching port is found.

Return type

Union[None, str]

getBatteryStatus(timeout=1, callback=None)¶

Get the status of the recorder’s battery. Not supported on all devices.

Parameters

timeout (Union[int, float], default: 1) – 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

A dictionary with the parsed battery status. It will always contain the key “hasBattery”, and if that is True, it will contain other keys:

”charging”: (bool)
”percentage”: (bool) True if the reported charge
level is a percentage, or 3 states (0 = empty, 255 = full, anything else is ‘some’ charge).
”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).

Return type

Optional[dict]

getLockID(timeout=5, callback=None)¶

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.
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 device’s current lock ID, if any.

Return type

Optional[Union[bytearray, bytes]]

getSerialPort(reset=False, timeout=1, kwargs=None)¶

Connect to a device’s serial port.

Parameters

reset (bool, default: False) – If True, reset the serial connection if already open. Use if the path/number to the device’s serial port has changed.
timeout (Union[int, float], default: 1) – Time (in seconds) to get the serial port.
kwargs (Optional[Dict[str, Any]], default: None) – Additional keyword arguments to be used when opening the port. Note: these will be ignored if the port has already been created and reset is False.

Returns

A serial.Serial instance, or None if no port matching the device can be found.

Return type

Union[None, serial.serialposix.Serial]

getStatus(timeout=10, callback=None)¶

Get the device’s status.

Parameters

timeout (Union[int, float], default: 10) – 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

The device’s current status, as a tuple containing the timestamp of the status update, the status code, and the corresponding status message (if any).

Return type

Tuple[float, Optional[int], Optional[str]]

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

isLocked(timeout=5, callback=None)¶

Has the hardware been ‘claimed’ for exclusive use via setLockID()?

Parameters

timeout (Union[int, float], default: 5) – Time (in seconds) to wait 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 tuple of Booleans: whether the device has a lock set, and whether the lock belongs to this instance.

Return type

tuple[bool, bool]

ping(data=None, timeout=10, interval=0.25, 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, not larger than 30 bytes, returned by the recorder verbatim.
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

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

Return type

dict

reset(wait=True, timeout=5, callback=None)¶

Reset (reboot) the recorder.

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond and/or disconnect, indicating the reset has started.
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.

Return type

bool

resetConnection()¶

Reset the serial connection.

Returns: True if the interface connection was reset.
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.

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 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?

Return type

Union[None, list]

setLockID(current=None, new=None, response=True, timeout=5, callback=None)¶

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).
response (bool, default: True) – If True (default), wait for the device to respond, acknowledging the change.
timeout (Union[int, float], default: 5) – Time (in seconds) to wait 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

The new lock ID.

Return type

bool

startRecording(wait=True, timeout=5, callback=None)¶

Start the device recording.

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond and/or dismount, indicating the recording has started.
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.

Return type

bool

stopRecording(wait=True, timeout=5, callback=None)¶

Stop a device that is recording.

Parameters

wait (bool, default: True) – If True, wait for the recorer to respond and/or remount, indicating the recording has stopped.
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.

endaq.device

Configuration