Draft: Add check_ref_clock-functions for SHF*, and HDAWG

[sebastiand-zi]

Description:

Fixes issue: #

Checklist:

• Add tests for the change to show correct behavior.
• Add or update relevant docs, code and examples.
• Update CHANGELOG.rst with relevant information and add the issue number.
• Add .. versionchanged:: where necessary.

[tobiasah]

question: Wouldn't it make more sense to return code and raise an error if its not or an error occurred?

[sebastiand-zi]

Andrea and I agree that raising an error probably makes sense.

We don't understand what you mean by "return code" however.

In any case this was taken over from an existing pqsc function.

[sebastiand-zi]

Feel free to add a proposal. Thanks.

[tobiasah]

something like this. #281 (comment)

... The "return code" was just a mixup in my head ... I meant return None and rais an error

[sebastiand-zi]

Suggested change

	shfsg.check_ref_clock()
	shfqa.check_ref_clock()
	# Verify if the ZSync connection is successful
	pqsc.check_zsync_connection([shfqa, shfsg])
	# Verify if the ZSync connection is successful
	shfsg.check_ref_clock()
	shfqa.check_ref_clock()
	pqsc.check_zsync_connection([shfqa, shfsg])

[tobiasah]

Suggested change

	def check_ref_clock(
	self, *, timeout: float = 30.0, sleep_time: float = 1.0
	) -> bool:
	"""Check if reference clock is locked successfully.
	Args:
	timeout: Maximum time in seconds the program waits
	(default: 30.0).
	sleep_time: Time in seconds to wait between
	requesting the reference clock status (default: 1)
	Raises:
	TimeoutError: If the process of locking to the reference clock
	exceeds the specified timeout.
	"""
	ref_clock_status = self.system.clocks.referenceclock.in_.status
	ref_clock = self.system.clocks.referenceclock.in_.source
	ref_clock_actual = self.system.clocks.referenceclock.in_.sourceactual
	try:
	ref_clock_status.wait_for_state_change(
	2, invert=True, timeout=timeout, sleep_time=sleep_time
	)
	except TimeoutError as error:
	raise TimeoutError(
	"Timeout during locking to reference clock signal"
	) from error
	if ref_clock_status() == 0:
	return True
	if ref_clock_status() == 1 and ref_clock_actual() != ref_clock():
	ref_clock("internal", deep=True)
	logger.error(
	f"There was an error locking the device({self.serial}) "
	f"onto reference clock signal. Automatically switching to internal "
	f"reference clock. Please try again."
	)
	return False
	def check_ref_clock(
	self, *, timeout: float = 30.0, sleep_time: float = 1.0
	) -> None:
	"""Check if reference clock is locked successfully.
	Args:
	timeout: Maximum time in seconds the program waits
	(default: 30.0).
	sleep_time: Time in seconds to wait between
	requesting the reference clock status (default: 1)
	Raises:
	ToolkitError: It the reference clock is not locked successfully or
	there was an error.
	TimeoutError: If the process of locking to the reference clock
	exceeds the specified timeout.
	"""
	ref_clock_status = self.system.clocks.referenceclock.in_.status
	ref_clock = self.system.clocks.referenceclock.in_.source
	ref_clock_actual = self.system.clocks.referenceclock.in_.sourceactual
	try:
	ref_clock_status.wait_for_state_change(
	2, invert=True, timeout=timeout, sleep_time=sleep_time
	)
	except TimeoutError as error:
	raise TimeoutError(
	"Timeout during locking to reference clock signal"
	) from error
	if ref_clock_status() == 0:
	return
	if ref_clock_status() == 1 and ref_clock_actual() != ref_clock():
	ref_clock("internal", deep=True)
	msg = (
	f"There was an error locking the device({self.serial}) "
	f"onto reference clock signal. Automatically switching to internal "
	f"reference clock. Please try again."
	)
	raise ToolkitError(msg)
	msg = "Reference clock is not locked sucessfully."
	raise ToolkitError(msg)