The Recorder Class

Recorder is the class representing an enDAQ recording device. There are several subclasses (EndaqS, EndaqW, and legacy SlamStickX, SlamStickC, and SlamStickS), but nearly all functionality is implemented in Recorder. Devices that do not have a specific subclass associated with their product name will instantiate as Recorder.

Note

Some or all of the discrete product-specific subclasses may be deprecated in the near future (the legacy SlamStick classes excluded). Using isinstance() to determine Recorder subclasses is not recommended; consider using the properties partNumber and productName instead (see below).

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.

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

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.

previous

Finding Devices

next

Configuration and Control Interfaces