Ticket8614 mercury ips magnet supply

doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md

@@ -64,6 +64,40 @@ The IOC implements the following state machine in SNL:
   * Set the IPS activity to "Ramp to Zero" and wait for the supplied current to drop to zero
   * At the end of this state, the magnet is set to "persistent" mode.
 
+The SNL state machine is also described in the following diagram:
+```{mermaid}
+---
+title: IPS State Machine
+---
+stateDiagram-v2
+    direction TB
+    [*] --> initial
+    at_field: At Field<br>statemachine_pv=1
+    set_psu_to_match_magnet: Set PSU to match magnet<br>statemachine_pv=2
+    wait_for_voltage_to_stabilise: Wait for voltage to stabilise<br>statemachine_pv=3
+    ensure_switch_heater_warm: Ensure switch heater warm<br>statemachine_pv=4
+    set_psu_output: Set PSU output<br>statemachine_pv=5
+    switch_off_heater: Switch off heater<br>statemachine_pv=6
+    ramp_down_psu: Ramp down PSU<br>statemachine_pv=7
+    initial --> at_field: field_setpoint_alarm == 0
+    at_field --> set_psu_to_match_magnet: field_setpoint != field_setpoint_readback<br>&& field_setpoint_alarm == 0<br> && (heater == 0 || heater == 2)
+    at_field --> set_psu_output: field_setpoint != field_setpoint_readback<br>&& field_setpoint_alarm == 0<br>&& heater == 1
+    set_psu_to_match_magnet --> wait_for_voltage_to_stabilise: field_setpoint_readback == magnet_field<br>&& psu_field == magnet_field<br>"&& ((sweepmode == SWEEP_MODE)<br> || (sweepmode == SWEEP_MODE_ALT))<br>&& (sweep_active == 0)
+    set_psu_to_match_magnet --> set_psu_to_match_magnet: timeout 300s
+    wait_for_voltage_to_stabilise --> ensure_switch_heater_warm: supplyvoltage_stable == 1
+    wait_for_voltage_to_stabilise --> set_psu_to_match_magnet: field_setpoint_readback != field_setpoint_raw
+    wait_for_voltage_to_stabilise --> set_psu_to_match_magnet: timeout 300s
+    ensure_switch_heater_warm --> set_psu_output: activity == ACTIVITY_HOLD<br>&& heater == 1<br> && heater_ontime_ok == 1
+    ensure_switch_heater_warm --> ensure_switch_heater_warm: timeout heater_wait_time + 30.0s
+    set_psu_output --> switch_off_heater: field_setpoint_readback == field_setpoint<br>&& (field_setpoint == psu_field<br>&& persistent == 1<br>&& (sweep_active == 0)<br>
+    set_psu_output --> at_field: field_setpoint_readback == field_setpoint<br>&& field_setpoint == psu_field<br>&& persistent == 0<br>&& (sweep_active == 0)<br>
+    set_psu_output --> set_psu_output: timeout 300s
+    switch_off_heater --> ramp_down_psu: heater == 0 || heater == 2<br>
+    switch_off_heater --> switch_off_heater: timeout 30s
+    ramp_down_psu --> at_field: psu_field == 0<br>&& (sweep_active == 0) <br>
+    ramp_down_psu --> ramp_down_psu: timeout 300s
+```
+
 ## IOC notes
 
 - The IOC does not enter it's state machine until a setpoint is set.

doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md

@@ -4,9 +4,25 @@ The Oxford Instruments Mercury IPS is a superconducting magnet power supply. It
 
 Note: although the Mercury IPS is the successor to the "old" IPS, cryogenics prefer to run the older IPS units as they are more reliable.
 
-## Hardware quirks
+## Hardware quirks (Legacy mode)
 
 The following faults can be seen when operating the magnet fully from the front panel, but it is likely that software will also run into the same conditions:
   * The firmware will sometimes crash/freeze. To reset it, the whole power supply needs to be power-cycled. This is obviously undesirable for a magnet power supply, and cryogenics are chasing OI about this issue. It's not clear whether this issue is general to all Mercury IPS units or whether we have one faulty unit.
   * The switch heater occasionally reports that it's ON when it's actually OFF
-  * The power supply reports a voltage of ~9000V which is incorrect (a sensible voltage for this power supply would be around ~8V while ramping)
+  * The power supply reports a voltage of ~9000V which is incorrect (a sensible voltage for this power supply would be around ~8V while ramping)
+
+## SCPI Protocol
+
+The IPS IOC now supports the SCPI protocol, which is more feature rich than Legacy mode.
+Effort was made to ensure that the top level EPICS interface was was changed as little as possible.
+It was particularly important that the SNL state-machine logic was not altered.
+This all required some careful designing of the new interface to provide PV compatibility with the legacy mode.
+There is now significantly more diagnostic information available, along with support for daughter-boards, such as He and N level meters, pressure measurement, etc., all of which have necessitated additions to the user interface in the IBEX client.
+The IOC can be configured to run with either legacy or SCPI protocols via a STREAMPROTOCOL macro ("SCPI" | "LEGACY"). The IOC publishes a new PV $(P)PROTOCOL, which reflects the configuration mode, allowing the user interface to hide or show attributes and controls relevant to SCPI or LEGACY modes.
+
+As already mentioned, SCPI mode provides additional status reporting, much of which is based on the return string from the "READ:SYS:ALRM" command, which is poorly documented in the supplier's documentation. The status strings are assumed to all conform to the "Directory of Alarms" section (17.3) of the Operator's Manual (Issue 20, July 2018).
+Whilst many of the system alarms that we could test, mostly conformed, some differences were noticed, along with additional, undocumented status, such as "Magnet Safety".
+It has not been possible to test all alarm scenarios with the IPS unit and as such unable to fully ascertain that all the expected message strings are correct - they may need to be adjusted later on, if/when they arise.
+
+The support module exports an aSub record subroutine to facilitate handling of the responses to READ:SYS:ALRM, which is not feasible with a StreamDevice protocol handler.
+