`endaq.device`¶

Functions for detecting, identifying, and retrieving information about data-logging devices.

exception endaq.device.CommandError¶: Exception raised by a failure to process a command.

exception endaq.device.ConfigError¶: Exception raised when configuration data is invalid.

exception endaq.device.ConfigVersionError¶: Exception raised when configuration format doesn’t match the recorder hardware or firmware version.

exception endaq.device.DeviceError¶: Base class for device-related exceptions.

exception endaq.device.DeviceTimeout¶: Exception raised when a device fails to respond within an expected length of time.

class endaq.device.EndaqS(path, strict=True, devinfo=None, virtual=False)¶

An enDAQ S-series data recorder from Mide Technology Corporation.

A representation of an enDAQ/SlamStick data recorder. Typically, instantiation should be done indirectly, using functions such as endaq.device.getDevices() or endaq.device.fromRecording(). Explicitly instantiating a Recorder or Recorder subclass is rarely (if ever) necessary.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

class endaq.device.EndaqW(path, strict=True, devinfo=None, virtual=False)¶

An enDAQ W-series wireless-enabled data recorder from Mide Technology Corporation.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

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

Check the current state of the Wi-Fi (if present).

Note: This method is deprecated. Use recorder.command.queryWiFi() instead.

Parameters

timeout (int, 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)

Return type

Union[None, dict]

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?

Note: This method is deprecated. Use recorder.command.scanWiFi() instead.

Parameters

timeout (int, 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 take no arguments.

Returns

A list of dictionaries, described above.

Return type

Union[None, list]

setAP(ssid, password=None)¶

Quickly set the Wi-Fi access point (router) and password.

Parameters

ssid (str) – The SSID (name) of the wireless access point.
password (Optional[str], default: None) – The access point password.

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 may not support configuring multiple Wi-Fi AP. In most cases, only one should be specified, and it should be marked as selected.

Note: This method is deprecated. Use recorder.command.setWiFi() instead.

Parameters

wifi_data (dict) – The information about the Wi-Fi networks to be set on the device.
timeout (int, default: 10) – Time (in seconds) to wait for a response before raising a DeviceTimeout exception.
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 take no arguments.

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

Update the ESP32 firmware.

Note: This method is deprecated. Use recorder.command.updateESP32() instead.

Parameters

firmware (str) – The name of the ESP32 firmware package (.bin).
timeout (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 take no arguments.

Returns

class endaq.device.Recorder(path, strict=True, devinfo=None, virtual=False)¶

A representation of an enDAQ/SlamStick data recorder. Some devices will instantiate as a specialized subclass, but the interface remains the same.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

property available: bool¶: Is the device mounted and available as a drive? Note: if the device’s path or drive letter changed (e.g., after being rebooted or disconnected/reconnected), or the device’s firmware or manifest was updated, you may need to call update() first.

property birthday: Optional[datetime.datetime]¶: The recorder’s date of manufacture.

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

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

property channels: Dict[int, idelib.dataset.Channel]¶: The devices recording channels; a dictionary of Channel objects keyed by channel ID. For compatibility with idelib.dataset.Dataset; results are the same as Recorder.getChannels(mtype=None).

property chipId: Optional[int]¶: The recorder CPU/MCU unique chip ID.

property command: Union[None, endaq.device.command_interfaces.CommandInterface]¶: The device’s “command interface,” the means through which to directly control the device. Only applicable to non-virtual recorders (i.e., actual hardware, not instantiated from a recording).

property config: endaq.device.config.ConfigInterface¶: The device’s “configuration interface,” the means through which to read and/or write device config.

property firmware: Optional[str]¶: The recorder’s manufacturer-issued firmware version string or name.

property firmwareVersion: int¶: The recorder’s manufacturer-issued firmware version number.

classmethod fromRecording(dataset)¶

Create a ‘virtual’ recorder from the recorder description in a recording.

classmethod generateCalEbml(transforms, date=None, expires=None, calSerial=0)¶

Generate binary calibration data (EBML). For the keyword arguments, a value of False will simply not write the corresponding element.

Parameters

transforms (Union[List[Transform], Dict[int, Transform]]) – A dictionary or list of idelib.calibration objects.
date (Optional[int], default: None) – The date of calibration (epoch timestamp).
expires (Optional[int], default: None) – The calibration expiration date (epoch timestamp).
calSerial (int, default: 0) – The calibration serial number (integer). 0 is assumed to be user-created calibration.

getAccelAxisChannels()¶

Retrieve a list of all accelerometer axis subchannels, ordered alphabetically (X, Y, Z).

Returns: A dictionary of accelerometer subchannels, keyed by parent channel ID.
Return type: Dict[int, List[idelib.dataset.SubChannel]]

getAccelRange(channel=None, subchannel=None, rounded=True)¶

Get the range of the device’s acceleration measurement.

Parameters

channel (Optional[int], default: None) – The accelerometer’s channel ID.
subchannel (Optional[int], default: None) – The accelerometer axis’ subchannel ID.
rounded (bool, default: True) – If True, get the sensor’s acceleration range, ignoring any effect of the sensor’s resolution.

getCalDate(user=False, epoch=False)¶

Get the date of the recorder’s calibration. By default, the factory calibration date is returned, as user calibration typically has no date.

Parameters

user (bool, default: False) – If False (default), only return the factory-set calibration date. If True, return the date of the user-applied calibration (if any).
epoch (bool, default: False) – If False (default), return the calibration date as a Python datetime.datetime object. If False, return the calibration date as epoch time (i.e., a UNIX timestamp). For backwards compatibility with earlier software.

getCalExpiration(user=False, epoch=False)¶

Get the expiration date of the recorder’s calibration. Defaults to the expiration date of the factory calibration; user-supplied calibration typically has no expiration date.

Parameters

user – If False (default), only return the factory-set calibration expiration date. If True, return the expiration date of the user-applied calibration (if any).
epoch – If False (default), return the expiration date as a Python datetime.datetime object. If False, return the expiration date as epoch time (i.e., a UNIX timestamp). For backwards compatibility with earlier software.

getCalPolynomials(user=True)¶

Get the constructed Polynomial objects created from the device’s current calibration data, as a dictionary of idelib.transform.Transform subclass instances, keyed by ID. User-supplied calibration, if present, takes priority (as it is what will be applied in recordings).

Parameters: user (bool, default: True) – If False, ignore user calibration and return factory calibration.

getCalSerial(user=False)¶

Get the recorder’s factory calibration serial number. Defaults to the serial number of the factory calibration; the serial number of user-supplied calibration is typically zero or totally absent.

Parameters: user – If False (default), only return the factory-set calibration serial number. If True, return the serial number of the user-applied calibration (if any).

getCalibration(user=True)¶

Get the recorder’s current calibration information. User-supplied calibration, if present, takes priority (as it is what will be applied in recordings).

Parameters: user (bool, default: True) – If False, ignore user calibration and return factory calibration.

getChannels(mtype=None)¶

Get the recorder channel description data.

Parameters: mtype (Union[MeasurementType, str, None], default: None) – An optional measurement type, to filter results.
Returns: A dictionary of Channel objects, keyed by channel ID.
Return type: Dict[int, idelib.dataset.Channel]

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

getInfo(name=None, default=None)¶

Retrieve a recorder’s device information. Returns either a single item or a dictionary of all device information.

Parameters

name – The name of a specific device info item. None will return the entire dictionary of device information.
default – A value to return, if the device has no information, or, if name is used, the device does not have a specific item.

Returns

If no name is specified, a dictionary containing the device data. If a name is specified, the type returned will vary.

Return type

Any

getManifest()¶

Read the device’s manifest data. The data is a superset of the information returned by getInfo().

getProperties()¶

Get the raw Recording Properties from the device.

getSensors()¶

Get the recorder sensor description data.

getSubchannelRange(subchannel, rounded=True)¶

Get the range of one of the device’s subchannels. Note that the reported range (particularly for digital sensors) is that of the subchannel’s parser, and may exceed values actually produced by the sensor.

Parameters

subchannel (Channel) – An idelib.dataset.SubChannel instance, e.g., from the recorder’s channels dictionary.
rounded (bool, default: True) – If True, round the results to two significant digits (to remove floating point rounding errors).

getSubchannels(mtype=None)¶

Get the recorder subchannel description data.

Parameters: mtype (Union[MeasurementType, str, None], default: None) – An optional measurement type, to filter results. See endaq.device.measurement.
Returns: A list of SubChannel objects.
Return type: List[idelib.dataset.SubChannel]

getTime(epoch=True, timeout=3)¶

Read the date/time from the device.

Parameters

epoch – 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 successful completion before raising a TimeoutError. Not used by older devices/firmware.

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

getUserCalPolynomials(filename=None)¶

Get the recorder’s user-defined calibration data as a dictionary of idelib.transforms.Transform subclass instances, keyed by ID.

Parameters: filename (Union[AnyStr, Path, Drive, None], default: None) – The name of an alternative user calibration .dat file to read (as opposed to the device’s standard user calibration).

getUserCalibration(filename=None)¶

Get the recorder’s user-defined calibration data as a dictionary of parameters.

property hardwareVersion: str¶: The recorder’s manufacturer-issued hardware version number. Newer version numbers will be split into version, revision, and (optionally) a BOM version letter. Older versions will be a single number.

property hardwareVersionInt: int¶: The recorder’s manufacturer-issued hardware version number.

property hasCommandInterface: bool¶: Does the device have the ability to execute commands?

property hasConfigInterface: bool¶: Does the device have the ability to execute commands?

property hasWifi: Union[str, bool]¶: The name of the Wi-Fi hardware type, or False if none. The name will not be blank, so expressions like if dev.hasWifi: will work.

classmethod isRecorder(path, strict=True, **kwargs)¶

Test whether a given filesystem path refers to the root directory of a data recorder.

Parameters

path (Union[AnyStr, Path, Drive]) – The path to the possible recording device (e.g. a mount point under Linux/BSD/etc., or a drive letter under Windows)
strict (bool, default: True) – If False, only the directory structure is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

property isRemote¶: Is this device not directly connected to this computer?

property isVirtual¶: Is this actual hardware, or a virtual recorder?

property mcuType¶: The recorder’s CPU/MCU type.

property name: str¶: The recording device’s (user-assigned) name.

property notes: str¶: The recording device’s (user-assigned) description.

property partNumber¶: The recording device’s manufacturer-issued part number.

property path: Optional[str]¶: The recorder’s filesystem path (e.g., drive letter or mount point).

property postConfigMsg: str¶: The message to be displayed after configuration.

property productName: str¶: The recording device’s manufacturer-issued name.

refresh(force=False)¶

Clear cached device information, ensuring the data is up-to-date.

Parameters: force (bool, default: False) – If True, reread information from the device, rather than use cached data.

property sensors: Dict[int, idelib.dataset.Sensor]¶: The device’s sensors; a dictionary of Sensor objects keyed by sensor ID. For compatibility with idelib.dataset.Dataset; results are the same as Recorder.getSensors().

property serial: str¶: The recorder’s manufacturer-issued serial number (as string).

property serialInt: Optional[int]¶: The recorder’s manufacturer-issued serial number (as integer).

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. Random filesystem things can potentially cause hiccups.
timeout (Union[int, float], default: 3) – Seconds to wait for successful completion before raising a TimeoutError. Not used by older devices/firmware.

Returns

The time that was set, as integer seconds since the epoch.

Return type

Union[float, int]

startRecording(timeout=1, callback=None)¶

Start the device recording, if supported.

Parameters

timeout (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 take no arguments.

Returns

True if the command was successful.

Return type

bool

property timestamp: Optional[int]¶: The recorder’s date of manufacture, epoch time.

property transforms: Optional[Dict[int, idelib.transforms.Transform]]¶: The recorder’s calibration polynomials, a dictionary of idelib.transform.Transform subclass instances keyed by ID. For compatibility with idelib.dataset.Dataset; results are the same as Recorder.getCalPolynomials().

update(virtual=False, paths=None, strict=True)¶

Attempt to update the device’s information. Call this method if a device has had its firmware or manifest data updated. This method can also be used to attempt to find the actual hardware corresponding to a ‘virtual’ device (i.e., instantiated from an IDE recording file).

Parameters

virtual (bool, default: False) – If True and the recorder is a ‘virtual’ device, attempt to connect it to the actual hardware (if present).
paths (Optional[List[Union[AnyStr, Path, Drive]]], default: None) – A list of specific paths to recording devices. Defaults to all found devices (as returned by getDeviceList()).
strict (bool, default: True) – If False, only the directory structure is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

Returns

True if the device had its information updated, or False if the device is unchanged or the hardware could not be found.

Return type

bool

property volumeName¶: The recorder’s user-specified filesystem label.

writeUserCal(transforms, filename=None)¶

Write user calibration to the device.

Parameters

transforms (Union[List[Transform], Dict[int, Transform]]) – A dictionary or list of idelib.calibration objects.
filename (Union[str, Path, None], default: None) – An alternate file to which to write the data, instead of the standard user calibration file.

class endaq.device.SlamStickC(path, strict=True, devinfo=None, virtual=False)¶

A Slam Stick C data recorder from Mide Technology Corporation. Also sold as enDAQ Sx-D16.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

property path: Optional[str]¶: The recorder’s filesystem path (e.g., drive letter or mount point).

property serial: str¶: The recorder’s manufacturer-issued serial number (as string).

class endaq.device.SlamStickS(path, strict=True, devinfo=None, virtual=False)¶

A Slam Stick S data recorder from Mide Technology Corporation.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

class endaq.device.SlamStickX(path, strict=True, devinfo=None, virtual=False)¶

A Slam Stick X data recorder from Mide Technology Corporation.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

exception endaq.device.UnsupportedFeature¶

Exception raised when a device does not support a given feature (e.g., attempting to execute Wi-Fi commands on a device without Wi-Fi, or executing a command exclusive to the serial command interface over the file-based interface).

Intended to be instantiated with either a single argument (a message string) or with two (the object raising the exception, and the offending method).

endaq.device.deviceChanged(recordersOnly=True, clear=False)¶

Returns True if a drive has been connected or disconnected since the last call to deviceChanged().

Parameters

recordersOnly (bool, default: True) – If False, any change to the mounted drives is reported as a change. If True, the mounted drives are checked and True is only returned if the change occurred to a recorder. Checking for recorders only takes marginally more time.
clear (bool, default: False) – If True, clear the cache of previously-detected drives and devices.

endaq.device.findDevice(sn=None, chipId=None, paths=None, unmounted=False, update=False, strict=True)¶

Find a specific recorder by serial number or unique chip ID. One or the other must be provided, but not both. Note that early firmware versions do not report the device’s chip ID.

Parameters

sn (Union[str, int, None], default: None) – The serial number of the recorder to find. Cannot be used with chipId. It can be an integer or a formatted serial number string (e.g., 12345 or “S00012345”).
chipId (Union[str, int, None], default: None) – The chip ID of the recorder to find. Cannot be used with sn. It can be an integer or a hex string. Note that chipId cannot be used to find SlamStick and older enDAQ S devices (prior to hardware revision 2.0), as they do not report their chip ID.
paths (Optional[List[Union[AnyStr, Path, Drive]]], default: None) – A list of specific paths to recording devices. Defaults to all found devices (as returned by getDeviceList()).
unmounted (bool, default: False) – If True, include devices connected by USB and responsive to commands but not appearing as drives. Note: Not all devices/firmware versions support this.
update (bool, default: False) – If True, update the path of known devices if they have changed (e.g., their drive letter or mount point changed after a device reset).
strict (bool, default: True) – If False, only the directory structure is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

Returns

An instance of a Recorder subclass representing the device with the specified serial number or chip ID, or None if it cannot be found.

Return type

Optional[endaq.device.base.Recorder]

endaq.device.fromRecording(doc)¶

Create a ‘virtual’ recorder from the data contained in a recording file.

Parameters: doc (Dataset) – An imported IDE recording. Note that very old IDE files may not contain the metadata requires to create a virtual device.

endaq.device.getDevices(paths=None, unmounted=True, update=True, strict=True)¶

Get a list of data recorder objects.

Parameters

paths (Optional[List[Union[AnyStr, Path, Drive]]], default: None) – A list of specific paths to recording devices. Defaults to all found devices (as returned by getDeviceList()).
unmounted (bool, default: True) – If True, include devices connected by USB and responsive to commands but not appearing as drives. Note: Not all devices/firmware versions support this.
update (bool, default: True) – If True, update the path of known devices if they have changed (e.g., their drive letter or mount point changed after a device reset).
strict (bool, default: True) – If False, only the directory structure is used to identify a recorder. If True, non-FAT file systems and non-removable media will be automatically rejected.

Returns

A list of instances of Recorder subclasses.

Return type

List[endaq.device.base.Recorder]

endaq.device.getRecorder(path, update=False, strict=True)¶

Get a specific recorder by its path.

Parameters

path (Union[AnyStr, Path, Drive]) – The filesystem path to the recorder’s root directory.
update (bool, default: False) – If True, update the path of known devices if they have changed (e.g., their drive letter or mount point changed after a device reset).
strict (bool, default: True) – If False, only the directory structure within path is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

Returns

An instance of a Recorder subclass, or None if the path is not a recorder.

Return type

Optional[endaq.device.base.Recorder]

endaq.device.isRecorder(path, strict=True)¶

Determine if the given path is a recording device.

Parameters

path (Union[AnyStr, Path, Drive]) – The filesystem path to check.
strict (bool, default: True) – If False, only the directory structure within path is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

endaq.device.onRecorder(path, strict=True)¶

Returns the root directory of a recorder from a path to a directory or file on that recorder. It can be used to test whether a file is on a recorder. False is returned if the path is not on a recorder. The test is only whether the path refers to a recorder, not whether the path or file actually exists; if you need to know if the path is valid, perform your own checks first.

Parameters

path (Union[AnyStr, Path, Drive]) – The full path/name of a file.
strict (bool, default: True) – If False, only the directory structure within path is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

Returns

The path to the root directory of a recorder (e.g. the drive letter in Windows) if the path is to a subdirectory on a recording device, False if not.

Return type

bool

class endaq.device.base.Recorder(path, strict=True, devinfo=None, virtual=False)¶

A representation of an enDAQ/SlamStick data recorder. Some devices will instantiate as a specialized subclass, but the interface remains the same.

Parameters

path (Union[AnyStr, Path, Drive, None]) – The filesystem path to the recorder, or None if it is a ‘virtual’ or remote device.
strict (bool, default: True) – If True, only allow real device paths. If False, allow any path that contains a SYSTEM directory with the standard contents on a device. Primarily for testing.
devinfo (Optional[bytes], default: None) – The necessary data to instantiate a Recorder. For creating Recorder instances when the hardware isn’t physically present on the host computer. If None, the data will be read from the device.
virtual (bool, default: False) – True if the device is not actual hardware (e.g., constructed from data in a recording).

property available: bool¶: Is the device mounted and available as a drive? Note: if the device’s path or drive letter changed (e.g., after being rebooted or disconnected/reconnected), or the device’s firmware or manifest was updated, you may need to call update() first.

property birthday: Optional[datetime.datetime]¶: The recorder’s date of manufacture.

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

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

property channels: Dict[int, idelib.dataset.Channel]¶: The devices recording channels; a dictionary of Channel objects keyed by channel ID. For compatibility with idelib.dataset.Dataset; results are the same as Recorder.getChannels(mtype=None).

property chipId: Optional[int]¶: The recorder CPU/MCU unique chip ID.

property command: Union[None, endaq.device.command_interfaces.CommandInterface]¶: The device’s “command interface,” the means through which to directly control the device. Only applicable to non-virtual recorders (i.e., actual hardware, not instantiated from a recording).

property config: endaq.device.config.ConfigInterface¶: The device’s “configuration interface,” the means through which to read and/or write device config.

property firmware: Optional[str]¶: The recorder’s manufacturer-issued firmware version string or name.

property firmwareVersion: int¶: The recorder’s manufacturer-issued firmware version number.

classmethod fromRecording(dataset)¶

Create a ‘virtual’ recorder from the recorder description in a recording.

classmethod generateCalEbml(transforms, date=None, expires=None, calSerial=0)¶

Generate binary calibration data (EBML). For the keyword arguments, a value of False will simply not write the corresponding element.

Parameters

transforms (Union[List[Transform], Dict[int, Transform]]) – A dictionary or list of idelib.calibration objects.
date (Optional[int], default: None) – The date of calibration (epoch timestamp).
expires (Optional[int], default: None) – The calibration expiration date (epoch timestamp).
calSerial (int, default: 0) – The calibration serial number (integer). 0 is assumed to be user-created calibration.

getAccelAxisChannels()¶

Retrieve a list of all accelerometer axis subchannels, ordered alphabetically (X, Y, Z).

Returns: A dictionary of accelerometer subchannels, keyed by parent channel ID.
Return type: Dict[int, List[idelib.dataset.SubChannel]]

getAccelRange(channel=None, subchannel=None, rounded=True)¶

Get the range of the device’s acceleration measurement.

Parameters

channel (Optional[int], default: None) – The accelerometer’s channel ID.
subchannel (Optional[int], default: None) – The accelerometer axis’ subchannel ID.
rounded (bool, default: True) – If True, get the sensor’s acceleration range, ignoring any effect of the sensor’s resolution.

getCalDate(user=False, epoch=False)¶

Get the date of the recorder’s calibration. By default, the factory calibration date is returned, as user calibration typically has no date.

Parameters

user (bool, default: False) – If False (default), only return the factory-set calibration date. If True, return the date of the user-applied calibration (if any).
epoch (bool, default: False) – If False (default), return the calibration date as a Python datetime.datetime object. If False, return the calibration date as epoch time (i.e., a UNIX timestamp). For backwards compatibility with earlier software.

getCalExpiration(user=False, epoch=False)¶

Get the expiration date of the recorder’s calibration. Defaults to the expiration date of the factory calibration; user-supplied calibration typically has no expiration date.

Parameters

user – If False (default), only return the factory-set calibration expiration date. If True, return the expiration date of the user-applied calibration (if any).
epoch – If False (default), return the expiration date as a Python datetime.datetime object. If False, return the expiration date as epoch time (i.e., a UNIX timestamp). For backwards compatibility with earlier software.

getCalPolynomials(user=True)¶

Parameters: user (bool, default: True) – If False, ignore user calibration and return factory calibration.

getCalSerial(user=False)¶

Get the recorder’s factory calibration serial number. Defaults to the serial number of the factory calibration; the serial number of user-supplied calibration is typically zero or totally absent.

Parameters: user – If False (default), only return the factory-set calibration serial number. If True, return the serial number of the user-applied calibration (if any).

getCalibration(user=True)¶

Get the recorder’s current calibration information. User-supplied calibration, if present, takes priority (as it is what will be applied in recordings).

Parameters: user (bool, default: True) – If False, ignore user calibration and return factory calibration.

getChannels(mtype=None)¶

Get the recorder channel description data.

Parameters: mtype (Union[MeasurementType, str, None], default: None) – An optional measurement type, to filter results.
Returns: A dictionary of Channel objects, keyed by channel ID.
Return type: Dict[int, idelib.dataset.Channel]

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

getInfo(name=None, default=None)¶

Retrieve a recorder’s device information. Returns either a single item or a dictionary of all device information.

Parameters

name – The name of a specific device info item. None will return the entire dictionary of device information.
default – A value to return, if the device has no information, or, if name is used, the device does not have a specific item.

Returns

If no name is specified, a dictionary containing the device data. If a name is specified, the type returned will vary.

Return type

Any

getManifest()¶

Read the device’s manifest data. The data is a superset of the information returned by getInfo().

getProperties()¶

Get the raw Recording Properties from the device.

getSensors()¶

Get the recorder sensor description data.

getSubchannelRange(subchannel, rounded=True)¶

Parameters

subchannel (Channel) – An idelib.dataset.SubChannel instance, e.g., from the recorder’s channels dictionary.
rounded (bool, default: True) – If True, round the results to two significant digits (to remove floating point rounding errors).

getSubchannels(mtype=None)¶

Get the recorder subchannel description data.

Parameters: mtype (Union[MeasurementType, str, None], default: None) – An optional measurement type, to filter results. See endaq.device.measurement.
Returns: A list of SubChannel objects.
Return type: List[idelib.dataset.SubChannel]

getTime(epoch=True, timeout=3)¶

Read the date/time from the device.

Parameters

epoch – 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 successful completion before raising a TimeoutError. Not used by older devices/firmware.

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

getUserCalPolynomials(filename=None)¶

Get the recorder’s user-defined calibration data as a dictionary of idelib.transforms.Transform subclass instances, keyed by ID.

Parameters: filename (Union[AnyStr, Path, Drive, None], default: None) – The name of an alternative user calibration .dat file to read (as opposed to the device’s standard user calibration).

getUserCalibration(filename=None)¶

Get the recorder’s user-defined calibration data as a dictionary of parameters.

property hardwareVersion: str¶: The recorder’s manufacturer-issued hardware version number. Newer version numbers will be split into version, revision, and (optionally) a BOM version letter. Older versions will be a single number.

property hardwareVersionInt: int¶: The recorder’s manufacturer-issued hardware version number.

property hasCommandInterface: bool¶: Does the device have the ability to execute commands?

property hasConfigInterface: bool¶: Does the device have the ability to execute commands?

property hasWifi: Union[str, bool]¶: The name of the Wi-Fi hardware type, or False if none. The name will not be blank, so expressions like if dev.hasWifi: will work.

classmethod isRecorder(path, strict=True, **kwargs)¶

Test whether a given filesystem path refers to the root directory of a data recorder.

Parameters

path (Union[AnyStr, Path, Drive]) – The path to the possible recording device (e.g. a mount point under Linux/BSD/etc., or a drive letter under Windows)
strict (bool, default: True) – If False, only the directory structure is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

property isRemote¶: Is this device not directly connected to this computer?

property isVirtual¶: Is this actual hardware, or a virtual recorder?

property mcuType¶: The recorder’s CPU/MCU type.

property name: str¶: The recording device’s (user-assigned) name.

property notes: str¶: The recording device’s (user-assigned) description.

property partNumber¶: The recording device’s manufacturer-issued part number.

property path: Optional[str]¶: The recorder’s filesystem path (e.g., drive letter or mount point).

property postConfigMsg: str¶: The message to be displayed after configuration.

property productName: str¶: The recording device’s manufacturer-issued name.

refresh(force=False)¶

Clear cached device information, ensuring the data is up-to-date.

Parameters: force (bool, default: False) – If True, reread information from the device, rather than use cached data.

property sensors: Dict[int, idelib.dataset.Sensor]¶: The device’s sensors; a dictionary of Sensor objects keyed by sensor ID. For compatibility with idelib.dataset.Dataset; results are the same as Recorder.getSensors().

property serial: str¶: The recorder’s manufacturer-issued serial number (as string).

property serialInt: Optional[int]¶: The recorder’s manufacturer-issued serial number (as integer).

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. Random filesystem things can potentially cause hiccups.
timeout (Union[int, float], default: 3) – Seconds to wait for successful completion before raising a TimeoutError. Not used by older devices/firmware.

Returns

The time that was set, as integer seconds since the epoch.

Return type

Union[float, int]

startRecording(timeout=1, callback=None)¶

Start the device recording, if supported.

Parameters

timeout (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 take no arguments.

Returns

True if the command was successful.

Return type

bool

property timestamp: Optional[int]¶: The recorder’s date of manufacture, epoch time.

property transforms: Optional[Dict[int, idelib.transforms.Transform]]¶: The recorder’s calibration polynomials, a dictionary of idelib.transform.Transform subclass instances keyed by ID. For compatibility with idelib.dataset.Dataset; results are the same as Recorder.getCalPolynomials().

update(virtual=False, paths=None, strict=True)¶

Parameters

virtual (bool, default: False) – If True and the recorder is a ‘virtual’ device, attempt to connect it to the actual hardware (if present).
paths (Optional[List[Union[AnyStr, Path, Drive]]], default: None) – A list of specific paths to recording devices. Defaults to all found devices (as returned by getDeviceList()).
strict (bool, default: True) – If False, only the directory structure is used to identify a recorder. If True, non-FAT file systems will be automatically rejected.

Returns

True if the device had its information updated, or False if the device is unchanged or the hardware could not be found.

Return type

bool

property volumeName¶: The recorder’s user-specified filesystem label.

writeUserCal(transforms, filename=None)¶

Write user calibration to the device.

Parameters

transforms (Union[List[Transform], Dict[int, Transform]]) – A dictionary or list of idelib.calibration objects.
filename (Union[str, Path, None], default: None) – An alternate file to which to write the data, instead of the standard user calibration file.

enDAQ API Reference

endaq.device¶

`endaq.device`¶