Decide the interface between `StandardDetector` and `DetectorController` w.r.t. the `TriggerInfo` that is passed down in `prepare`

[coretl]

As mentioned in https://github.com/bluesky/ophyd-async/pull/401#discussion_r1644527435 and https://github.com/bluesky/ophyd-async/pull/401#discussion_r1644506670, we need to decide what StandardDetector does with the TriggerInfo passed down to prepare. We should also consider #162 and #357 while we're at it. I propose:

• async def DetectorController.arm(num, trigger, exposure) -> Status -> async def DetectorController.arm(trigger_info) -> None, where the return value for acquire.set(True) is stored locally rather than returned
• Add a new async def DetectorController.wait_for_disarmed(timeout=DEFAULT_TIMEOUT) that waits for aquire to be False and does the successful completion check that will fail if the detector did anything apart from normal completion or manual disarming
• async def DetectorController.disarm() -> async def DetectorController.start_disarm() as it doesn't wait for completion

We should also document the various permutations of TriggerInfo and provide any common helpers like the one defined in #401. The cases we need to document:

• trigger=internal, livetime=deadtime=None: Internal trigger mode, with exposure and period untouched. The default for trigger() if prepare() not called
• trigger=any, livetime=float: Exposure set to livetime and period set to livetime+get_deadtime(livetime)
• trigger=any, livetime=float, deadtime=float: Exposure set to livetime and period set to deadtime
• num=0: Go until disarmed, if detector supports it
• num=+ve: Arm for this many frames

We still need to work out if we should provide things like min_exposure and max_framerate as well as get_deadtime(exposure), but this will we tackled in a different issue

[coretl]

@callumforrester @abbiemery @evalott100 @DiamondJoseph thoughts?

[callumforrester]

I think there is a use case for keeping the detector to minimum deadtime while the system as a whole has a longer deadtime, which is what this diagram covers. Do any your permutations cover that?

[coretl]

Yes, as this is a property of the trigger generation system, rather than the detector. In the case above the TriggerInfo.deadtime (which the docstring describes as the minimum deadtime) will be the output of get_deadtime(exposure), while the trigger system will actually provide a bigger gap between triggers as shown by your diagram

[coretl]

Need a discussion with @jwlodek and @tomtrafford

[ZohebShaikh]

After future discussion,

We have decide to have

StandardDetector.prepare() -> DetectorController.prepare()

StandardDetector.kickoff() -> DetectorController.arm()

StandardDetector.trigger() -> DetectorController.arm()