OFFSPEC (spin-echo): DELFT RF IOC

[KathrynBaker]

Feature Description

As someone using OFFSPEC I want to be able to communicate with the Delft RF equipment in IBEX so that I can integrate it with my experiments.

Explanation

This was originally requested in 2022 in ticket #7493, but better requirements were needed and so this ticket is being produced having done the documentation of the existing system, which is the minimum we should aim for.
The UI specification has not been undertaken now, as that needs discussion with the users when picking up the ticket when we eventually undertake it.
Specific notes for each area will be in the comments of this ticket as there are a number of areas.
There are roughly 30 commands, at least one 150 value array, and at least 84 other process variables needed.

Acceptance Criteria

• The UI layout is discussed and agreed with the Scientists in order to engage them in the process of bringing this on line (expect to see in the comments below)
• An IOC exists which provides at least the same functionality as the LabVIEW code - this is what is specified in the following tickets.
• A LeWIS emulator exists for the device
• There are suitable system tests, especially for the behaviour of the profile moves (unless they are agreed to be deprecated by the scientists)
• There is a suitable UI available
• There is an appropriate page in the developers manual describing the device and the use of it
• Either the system has been tested with hardware, or a follow on ticket is created and scheduled to undertake the testing

How to Review

_{Before making a PR...}

• Provide verbose instructions for the reviewer to test your changes
• Describe how you have implemented testing for this feature
• Provide screenshots of the feature to help the reviewer if relevant

_{If not applicable, write "Not applicable"}

...

_{To the reviewer: Make sure to update submodules!}

[KathrynBaker]

Communications
This is a serial device.
The only macro required is the COM Port, it uses the typical 9600,8None,1 settings, has a carriage return only as the end of message, and a 1 second timeout. There's some interesting buffer flushing going on, so when testing with the device start with simple readbacks fairly directly to make sure that the comms is stable before looking at the more complicated values in the whole IOC.
In a more unusual move the end of the command to be sent gets * added to it, so it may be worth bearing in mind that this is needed, but is omitted from the list of commands which follow. There are some 10ms delays either side of the write, so there could be a need to throttle the information being sent and when you expect the readback to arrive.
The LabVIEW does some manual checking for the ; end of reply that is unlikely to be necessary using asyn/stream with a little care taken in the settings for readback compared to write.

[KathrynBaker]

Readbacks - Amplifiers

Section of System	Name of value to read	Command to read	Returned format	Notes
Amplifier 1	Gain	GN? 1	%f;
	Forward Power	PFW? 1	%f;
	Reverse Power	PRV? 1	%f;
	Status	STA? 1	%d;	This really is just given as a digit
	Frequency	FRQ? 1	%f;
	Correction	COR? 1	%f;
Amplifier 2	Gain	GN? 2	%f;
	Forward Power	PFW? 2	%f;
	Reverse Power	PRV? 2	%f;
	Status	STA? 2	%d;	This really is just given as a digit
	Frequency	FRQ? 2	%f;
	Correction	COR? 2	%f;

[KathrynBaker]

Readbacks - Coils

Section of System	Name of value to read	Command to read	Returned format	Notes
Coil 1	Current	I? 1	%f;	Divide this value by 100 for use
	Temperature	T? 1	%f;
Coil 2	Current	I? 2	%f;	Divide this value by 100 for use
	Temperature	T? 2	%f;
Coil 3	Current	I? 3	%f;	Divide this value by 100 for use
	Temperature	T? 3	%f;
Coil 4	Current	I? 4	%f;	Divide this value by 100 for use
	Temperature	T? 4	%f;

[KathrynBaker]

Readbacks - System Parameters

Name of value to read	Command to read	Returned format	Notes
Alarm Code	ALM?	%d;	Convert into a Boolean array giving the following items in order: P Limit, I Limit, Amp 1, Amp 2, T4, T3, T2, T1
Operation Mode	MOD?	%[A-Za-z];%[A-Za-z];	if the first one is PNR the mode is given as NPR; if it is SESANS or any other value the mode is given as SESANS, this in turn is set as the Alarm Mode. The second is either low (0), medium(1), high(2), with low as the default, and the value is passed on as is for the Range, this in turn is set as the Alarm Range String
Alarm Operational Status	OPR?	String	returns one of PRFL, TRCW, CW, STOP, ALRM, SHDN, SCAN, LOCL, although Unknown is also allowed for the status that is displayed, this is then displayed as the alarm operational status
Coil Alarm Temperature	LIM?	%f;

[KathrynBaker]

Readbacks - Profile
This is only ever read on demand, not read regularly.
Start by setting the Profile Sample Pointer to 0, should any other number be provided it is kept to the range 0 to 149 using SPTR %d
Iterate 150 times and do the following (i = 0 indexed iterator):
- Send DNLD to get a %d,%d; response which gives values for the Sample Pointer and the Sample Value respectively.
- Create an X,Y point for the graph where:
- X = iterator x 0.5
- Y = Sample Value x (4.5/100)

• Those XY Values can then be displayed on a graph
• There is no source for the 4.5/100 magic numbers

[KathrynBaker]

Set Values - Profile
This is presently done for the whole 150 point array at once, although adapting it to change one value at a time should be possible, the existing interactions do not do that.
The Amplitude Profile is given as an array from the front panel
Set the Profile Sample Pointer to 0, should any other number be provided it is kept to the range 0 to 149 using SPTR %d
Iterate through the Amplitude profile to get an amplitude value until the end of the array is reached, or there have been 150 iterations, whichever is the smallest and do the following:
- Force the amplitude value in question to be between 10 and 180 inclusive
- Send UPLD %d where the variable is the amplitude value, this will return just a number which is the sample number written to, form this into an array - and do nothing with that array

[KathrynBaker]

Set Values - System

Name of value to set	Command to send	Notes
Mode	If the mode is NPR, or anything other than SESANS, send PNR %d where %d is the value for the Range. If the mode is SESANS, send SSNS %d where %d is the value for Range	The range maps as follows: 0 = Low, 1 = Medium, 2 = High
Alarm Temp	TLIM %.0f
Reset	RST
Stop RF	STOP	wait for 250ms after setting this value
Shutdown RF	SHDN
Scan RF	SCAN
Run Amplitude Profile	PROF
Send Command		This sends an arbitrary command entered into a string control

[KathrynBaker]

Set Values - RF

Part of System	Name of value to set	Command to send	Notes
RF1	CW Amplitude	CW1 %d	%d is the Amplitude x 10 and then ranged to be between 10 and 85 inclusive, wait for 250ms after setting this value
	TCW Amplitude	TCW1 %d	%d is the Amplitude x 10
	Frequency	FRQ1 %.0f
	Offset	COR1 %.0f
	Save Frequency	SVFR1
RF2	CW Amplitude	CW2 %d	%d is the Amplitude x 10 and then ranged to be between 10 and 85 inclusive, wait for 250ms after setting this value
	TCW Amplitude	TCW2 %d	%d is the Amplitude x 10
	Frequency	FRQ2 %.0f
	Offset	COR2 %.0f
	Save Frequency	SVFR2

[KathrynBaker]

Changes to the Profile
There are 5 things that can be made to the profile, note that nothing is currently automatically sent to the device

• Profile Up
  - For each entry in the profile array increment (+1) the Sample Amplitude
  • Profile Down
    • For each entry in the profile array decrement (-1) the Sample Amplitude
  • Profile Left
    • Delete the first entry in the profile array, and repeat the last entry by adding a copy at the end
  • Profile Right
    • Delete the last entry in the profile array, and repeat the first entry by adding a copy at the start of the array
  • Profile Filter
    • For each entry in the profile array set the sample amplitude to the average of the most recent three sample amplitudes (except for the first two which are the average of 1 and 2 samples respectively)