ibex_bluesky_core.devices.block

bluesky devices and utilities for communicating with IBEX blocks.

Members

BlockMot	Create a new motor-record block.
BlockR	Device representing an IBEX readable block of arbitrary data type.
BlockRw	Device representing an IBEX read/write block of arbitrary data type.
BlockRwRbv	Device representing an IBEX read/write/setpoint readback block of arbitrary data type.
BlockWriteConfig	Configuration settings for writing to blocks.
RunControl	Subdevice for common run-control signals.
block_mot	Get a local block pointing at a motor record for the local instrument.
block_r	Get a local read-only block for the current instrument.
block_rw	Get a local read-write block for the current instrument.
block_rw_rbv	Get a local read/write/setpoint readback block for the current instrument.
block_w	Get a write-only block for the current instrument.

class ibex_bluesky_core.devices.block.BlockMot(prefix: str, block_name: str)

Bases: Motor, Movable[float], HasName

Create a new motor-record block.

The BlockMot object supports motion-specific functionality such as:

• Stopping if a scan is aborted (supports the bluesky Stoppable protocol)

• Limit checking (before a move starts - supports the bluesky Checkable protocol)

• Automatic calculation of move timeouts based on motor velocity

• Fly scanning

However, it generally relies on the underlying motor being “well-behaved”. For example, a motor which does many retries may exceed the simple default timeout based on velocity (it is possible to explicitly specify a timeout on set() to override this).

Blocks pointing at motors do not take a BlockWriteConfig parameter, as these parameters duplicate functionality which already exists in the motor record. The mapping is:

use_completion_callback:

Motors always use completion callbacks to check whether motion has completed. Whether to wait on that completion callback can be configured by the ‘wait’ keyword argument on set().

set_success_func:

Use .RDBD and .RTRY to control motor retries if the position has not been reached to within a specified tolerance. Note that motors which retry a lot may exceed the default motion timeout which is calculated based on velocity, distance and acceleration.

set_timeout_s:

A suitable timeout is calculated automatically based on velocity, distance and acceleration as defined on the motor record.

settle_time_s:

Use .DLY on the motor record to configure this.

use_global_moving_flag:

This is unnecessary for a single motor block, as a completion callback will always be used instead to detect when a single move has finished.

set(value: float, timeout: float | None | Literal['CALCULATE_TIMEOUT'] = CALCULATE_TIMEOUT) → WatchableAsyncStatus[float]

Pass through set to ophyd_async.epics.motor.Motor.set.

This is needed so that type-checker correctly understands the type of set.

This method will raise ophyd_async.epics.motor.MotorLimitsError if the requested position was outside the motor’s limits.

class ibex_bluesky_core.devices.block.BlockR(datatype: type[T], prefix: str, block_name: str)

Bases: StandardReadable, Triggerable, Generic[T]

Device representing an IBEX readable block of arbitrary data type.

Parameters:

• datatype – the type of data in this block (e.g. str, int, float)

• prefix – the current instrument’s PV prefix

• block_name – the name of the block

readback: SignalR[T]

Readback value. This is the hinted signal for a block.

run_control: RunControl

Run-control settings for this block.

trigger() → None

Blocks do not do anything when triggered.

This method implements bluesky.protocols.Triggerable, and should not be called directly.

This empty implementation is provided to allow using blocks in adaptive scans.

class ibex_bluesky_core.devices.block.BlockRw(datatype: type[T], prefix: str, block_name: str, *, write_config: BlockWriteConfig[T] | None = None, sp_suffix: str = ':SP')

Bases: BlockR[T], NamedMovable[T]

Device representing an IBEX read/write block of arbitrary data type.

The setpoint is not added to read() by default. For most cases where setpoint readback functionality is desired, BlockRwRbv is a more suitable type.

If you explicitly need to read the setpoint from a BlockRw, you can do so in a plan with:

import bluesky.plan_stubs as bps

def plan():
    block: BlockRw = ...
    yield from bps.rd(block.setpoint)

But note that this does not read back the setpoint from hardware, but rather the setpoint which was last sent by EPICS.

Parameters:

• datatype – the type of data in this block (e.g. str, int, float)

• prefix – the current instrument’s PV prefix

• block_name – the name of the block

• write_config – Settings which control how this device will set the underlying PVs

• sp_suffix – Suffix to append to PV for the setpoint. Defaults to “:SP” but can be set to empty string to read and write to exactly the same PV.

set(value: T) → None

Set the setpoint of this block.

This method implements bluesky.protocols.Movable, and should not be called directly.

From a plan, set a block using:

import bluesky.plan_stubs as bps

def my_plan():
    block = BlockRw(...)
    yield from bps.mv(block, value)

setpoint: SignalRW[T]

The setpoint for this block.

class ibex_bluesky_core.devices.block.BlockRwRbv(datatype: type[T], prefix: str, block_name: str, *, write_config: BlockWriteConfig[T] | None = None)

Bases: BlockRw[T], Locatable[T]

Device representing an IBEX read/write/setpoint readback block of arbitrary data type.

The setpoint readback is added to read(), but not hints(), by default. If you do not have a setpoint readback, use BlockRw instead.

Parameters:

• datatype – the type of data in this block (e.g. str, int, float)

• prefix – the current instrument’s PV prefix

• block_name – the name of the block

• write_config – Settings which control how this device will set the underlying PVs

async locate() → Location[T]

Get the current Location of this block.

This method implements bluesky.protocols.Locatable, and should not be called directly.

From a plan, locate a block using:

import bluesky.plan_stubs as bps

def my_plan():
    block: BlockRwRbv = ...
    location = yield from bps.locate(block)

If you only need the current value, rather than the value and the setpoint-readback, use:

import bluesky.plan_stubs as bps

def my_plan():
    block: BlockRwRbv = ...
    value = yield from bps.rd(block)

setpoint_readback: SignalR[T]

The setpoint-readback for this block.

class ibex_bluesky_core.devices.block.BlockWriteConfig(*, use_completion_callback: bool = True, set_success_func: Callable[[T, T], bool] | None = None, set_timeout_s: float | None = None, settle_time_s: float = 0.0, use_global_moving_flag: bool = False, timeout_is_error: bool = True)

Bases: Generic[T]

Configuration settings for writing to blocks.

These settings control how a block write is determined to be ‘complete’. A block write should only be marked as complete when the equipment has physically reached the correct state, not just when the equipment has been told to move to the correct state.

For example, during a scan of a block against a detector, the detector will be read as soon as the block declares the write as ‘complete’.

set_success_func: Callable[[T, T], bool] | None = None

An arbitrary function which is called to decide whether the block has set successfully yet or not. The function takes (setpoint, actual) as arguments and should return True if the value has successfully set and is “ready”, or False otherwise.

This can be used to implement arbitrary tolerance behaviour. For example:

def check(setpoint: T, actual: T) -> bool:
    return setpoint - 0.1 <= actual <= setpoint + 0.1

If use_completion_callback is True, the completion callback must complete before set_success_func is ever called.

Executing this function should be “fast” (i.e. the function should not sleep), and it should not do any external I/O.

Defaults to None, which means no check is applied.

set_timeout_s: float | None = None

A timeout, in seconds, on the value being set successfully. The timeout applies to the EPICS completion callback (if enabled) and the set success function (if provided), and excludes any configured settle time.

Defaults to None, which means no timeout.

settle_time_s: float = 0.0

A wait time, in seconds, which is unconditionally applied just before the set status is marked as complete. Defaults to zero.

timeout_is_error: bool = True

Whether a write timeout is considered an error. Defaults to True. If False, a set will be marked as complete without error even if the block has not given a completion callback or satisfied set_success_func within settle_time_s.

use_completion_callback: bool = True

Whether to wait for an EPICS completion callback while setting this block. Defaults to True, which is appropriate for most blocks.

use_global_moving_flag: bool = False

Whether to wait for the IBEX global moving indicator to return “stationary”. This is useful for compound moves, where changing a single block may cause multiple underlying axes to move, and all movement needs to be complete before the set is considered complete.

class ibex_bluesky_core.devices.block.RunControl(prefix: str, name: str = '')

Bases: StandardReadable

Subdevice for common run-control signals.

Note

Run control should be accessed via the run_control property on a block, rather than by constructing an instance of this class directly.

Parameters:

• prefix – the run-control prefix, e.g. IN:INSTRUMENT:CS:SB:blockname:RC:

• name – ophyd device name

enabled: SignalRW[bool]

Run-control enabled.

high_limit: SignalRW[float]

Run-control high limit.

in_range: SignalR[bool]

Whether run-control is currently in-range.

in_time: SignalR[float]

Run-control time inside limits.

low_limit: SignalRW[float]

Run-control low limit.

out_time: SignalR[float]

Run-control time outside limits.

suspend_if_invalid: SignalRW[bool]

Whether run-control should suspend data collection on invalid values.

ibex_bluesky_core.devices.block.block_mot(block_name: str) → BlockMot

Get a local block pointing at a motor record for the local instrument.

See documentation of BlockMot for more information.

ibex_bluesky_core.devices.block.block_r(datatype: type[T], block_name: str) → BlockR[T]

Get a local read-only block for the current instrument.

See documentation of BlockR for more information.

ibex_bluesky_core.devices.block.block_rw(datatype: type[T], block_name: str, *, write_config: BlockWriteConfig[T] | None = None, sp_suffix: str = ':SP') → BlockRw[T]

Get a local read-write block for the current instrument.

See documentation of BlockRw for more information.

ibex_bluesky_core.devices.block.block_rw_rbv(datatype: type[T], block_name: str, *, write_config: BlockWriteConfig[T] | None = None) → BlockRwRbv[T]

Get a local read/write/setpoint readback block for the current instrument.

See documentation of BlockRwRbv for more information.

ibex_bluesky_core.devices.block.block_w(datatype: type[T], block_name: str, *, write_config: BlockWriteConfig[T] | None = None) → BlockRw[T]

Get a write-only block for the current instrument.

This is a BlockRw instance with no SP suffix.