From b10bb1002411a3d33d0416b7489b052d744c4a4b Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Tue, 9 Sep 2025 12:49:16 +0100 Subject: [PATCH 01/10] Oxford-Instruments-IPS.md: Added state-machine diagram as Mermaid script --- .../cryogenics/Oxford-Instruments-IPS.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md index ac34ca82e..f5f316dd1 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md +++ b/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
statemachine_pv=1 + set_psu_to_match_magnet: Set PSU to match magnet
statemachine_pv=2 + wait_for_voltage_to_stabilise: Wait for voltage to stabilise
statemachine_pv=3 + ensure_switch_heater_warm: Ensure switch heater warm
statemachine_pv=4 + set_psu_output: Set PSU output
statemachine_pv=5 + switch_off_heater: Switch off heater
statemachine_pv=6 + ramp_down_psu: Ramp down PSU
statemachine_pv=7 + initial --> at_field: field_setpoint_alarm == 0 + at_field --> set_psu_to_match_magnet: field_setpoint != field_setpoint_readback
&& field_setpoint_alarm == 0
&& (heater == 0 || heater == 2) + at_field --> set_psu_output: field_setpoint != field_setpoint_readback
&& field_setpoint_alarm == 0
&& heater == 1 + set_psu_to_match_magnet --> wait_for_voltage_to_stabilise: field_setpoint_readback == magnet_field
&& psu_field == magnet_field
"&& ((sweepmode == SWEEP_MODE)
|| (sweepmode == SWEEP_MODE_ALT))
&& (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
&& heater == 1
&& 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
&& (field_setpoint == psu_field
&& persistent == 1
&& (sweep_active == 0)
+ set_psu_output --> at_field: field_setpoint_readback == field_setpoint
&& field_setpoint == psu_field
&& persistent == 0
&& (sweep_active == 0)
+ set_psu_output --> set_psu_output: timeout 300s + switch_off_heater --> ramp_down_psu: heater == 0 || heater == 2
+ switch_off_heater --> switch_off_heater: timeout 30s + ramp_down_psu --> at_field: psu_field == 0
&& (sweep_active == 0)
+ ramp_down_psu --> ramp_down_psu: timeout 300s +``` + ## IOC notes - The IOC does not enter it's state machine until a setpoint is set. From 1a8fbcb2d1fdce45275f2e1e86238b8861646224 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Tue, 9 Sep 2025 12:50:13 +0100 Subject: [PATCH 02/10] Oxford-Instruments-Mercury-IPS.md: Added a new section concerning the SCPI protocol configuration. --- .../Oxford-Instruments-Mercury-IPS.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index 30398863c..2d50cfda5 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/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) \ No newline at end of file + * 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 Prorocol + +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 insterface 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 shoe-horning of the new interface to provide PV compatibility with the legacy mode. +There is now siginificantly more diagnostic information available, along with support for daughter-boards, such as He and N leve 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 assertain 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. + From 18e804aa5195d79f91b5c2c43863eebcd9b74caf Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Tue, 9 Sep 2025 13:52:07 +0100 Subject: [PATCH 03/10] Oxford-Instruments-Mercury-IPS.md: Spelling... --- .../cryogenics/Oxford-Instruments-Mercury-IPS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index 2d50cfda5..5dbeeddf4 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md @@ -11,18 +11,18 @@ The following faults can be seen when operating the magnet fully from the front * 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) -## SCPI Prorocol +## 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 insterface was was changed as little as possible. +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 shoe-horning of the new interface to provide PV compatibility with the legacy mode. -There is now siginificantly more diagnostic information available, along with support for daughter-boards, such as He and N leve meters, pressure measurement, etc., all of which have necessitated additions to the user interface in the IBEX client. +There is now significantly more diagnostic information available, along with support for daughter-boards, such as He and N leve 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 assertain that all the expected message strings are correct - they may need to be adjusted later on, if/when they arise. +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. From e25b500f9e7e7654dcc74becdfa9a301f0eac918 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Tue, 9 Sep 2025 13:55:11 +0100 Subject: [PATCH 04/10] Oxford-Instruments-Mercury-IPS.md: Spelling take 2... --- .../cryogenics/Oxford-Instruments-Mercury-IPS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index 5dbeeddf4..e9ca8e311 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md @@ -16,8 +16,8 @@ The following faults can be seen when operating the magnet fully from the front 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 shoe-horning 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 leve meters, pressure measurement, etc., all of which have necessitated additions to the user interface in the IBEX client. +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). From 413cb8aef3dadb2c1c650e05545a9a296b5b4b7b Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Wed, 17 Sep 2025 13:43:35 +0100 Subject: [PATCH 05/10] Oxford-Instruments-Mercury-IPS.md: Added useful information about the SCPI implementation --- .../Oxford-Instruments-Mercury-IPS.md | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index e9ca8e311..d8ad496bd 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md @@ -26,3 +26,147 @@ It has not been possible to test all alarm scenarios with the IPS unit and as su 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. +### CONTROL and CONTROL:SP +These records have been removed from the SCPI variant database +as the SCPI command set does not manage the panel lock in the same was as legacy and +Magnet Group advised to remove this feature, as they always want to be able to control +the IPS via the front panel. + +### SYSTEM:HWFAULT status is derived from the status bits via a calc record. +This collates the various possible hardware faults into a single record, +which in the legacy protocol is a single value (Xm bit 4). + +### SWEEPMODE:PARAMS and SWEEPMODE:SWEEP +These records have been removed as they are meaningless and underivable in SCPI protocol. + +### _SWEEPMODE:SWEEP +In the legacy version, this used to be the readback from n of Mmn part of Examine command return. +0 output constant, 1, 2, 3 output changing +The SCPI protocol doesn't directly offer this, so it has to be derived via the ACTIVITY record (DEV:GRPZ:PSU:ACTN) +Direction from Alex Jones: "A response of HOLD or CLMP would be equivalent to n=0 in the response of the X command +in the old protocol. Responses of RTOS or RTOZ would be equivalent to n=1. +There is no equivalent for the m=0,1 fast/slow ramps, but we do not use this feature anyway." + +### System Alarms +System alarms are derived by interrogating the IPS with the "READ:SYS:ALRM?" SCPI command. +This returns a comma-separated string of active alarms, or an empty string if no alarms are present. +The string is parsed by an aSub record, which sets the relevant bits in a binary register. +The bits are mapped to individual status records, which are then used to set the relevant alarms. +The precise protocol was determined empirically by sending the command and observing the response +directly from the instrument. +Discrete records are generated for each board type and each alarm by the +scpi_system_alarms_discrete.template and substitutions files. + +The base response is: READ:SYS:ALRM: which may (or may not) be followed by a board identifier, +a tab character (9) an alarm string and a semicolon. + +In ABNF:
+``` +response = "READ:SYS:ALRM:" *(error) +error = board_id TAB error_message SEMICOLON + +board_id = 1*(ALPHA / DIGIT / ".") ; e.g. MB1.T1 +error_message = 1*(ALPHA / DIGIT / ".") ; e.g. "Open circuit" +TAB = %x09 ; tab character +SEMICOLON = %x3B ; semicolon ";" +``` + +The board identifiers are provided as macros: + +| Macro | Default | +|-------|----------| +| BOARDID_MAG | MB1.T1 | +| BOARDID_10TMAG | DB8.T1 | +| BOARDID_PRESS | DB5.P1 | +| BOARDID_LEVEL | DB1.L1 | + +## Development Notes: +Alex Jones has looked at some of the differences between the SCPI and legacy command set and has summarised some useful information, as quoted below: +For the quench and overheat status, these (and many other issues) are dealt with by “Alarms” for the SCPI protocol. See the Magnet board section on p. 162 in Issue 20. These are read by “READ:DEV::PSU:STAT” in some undefined hex format for just the magnet-related alarms, and READ:SYS:ALRM for a list of everything. + +Some further information re UID naming: +The UIDs can be either the nickname for the card (which we can set to anything we want) or related to the slot number and signal type. +From the spreadsheet, the positional UID for the magnet temperature sensor will be MB1.T1, the UID for the level meter will be DB1.L1 and the UID for the magnet supply will be GRPZ for all 4 of the systems. +The 10T system will have an additional temperature sensor DB8.T1 and a pressure sensor DB5.P1. + +It appears that: +devices connected to the motherboard are prefixed: MB1\ +devices connected to a daughterboard are prefixed: DB + + +Conversation between Chris Lawson and Robert Grzyb at Oxford Instruments (18 Feb 2025) +SCPI Equivalents: +Yes we are looking for the equivalent between Mercury iPS and iPS-120 control syntax. It may be some things are missing/changed, but wondered if there was a table of all of this somewhere internally. +I do not think we have a document which succinctly summarises differences between Mercury iPS and the IPS-120 in the context of their remote command sets. + +Q: What are the new commands to use on the Mercury iPS which are equivalent to the commands from the old iPS-120 below?\ +F17 (Trip Current)\ +F19 (Trip Field)\ +Xmn\ +m = 1 quenched\ +m = 2 overheated + +Answer from Robert Grzyb at Oxford Instruments:\ +F17/F19\ +I assume that you mean legacy commands R17 (Trip Current) and R19 (Trip Field). +This functionality is preserved when Mercury iPS remote interface is set to use legacy command set. +But when using "SCPI-style" command set, this exact information cannot be retrieved directly from the iPS. +Under certain (limited) circumstances R17/R19 are equivalent to DEV::PSU:SIG:PCUR and DEV::PSU:SIG:PFLD (note that UID must be a group, not an individual PSU). + +Xmn +There is no equivalent for X (examine status) command in the "SCPI-style" command set. +As far as the first portion ("mn") of the reply to X command is concerned, certain "m" values correspond loosely to the bits of the status word in Mercury iPS group device (READ:DEV::PSU:STAT). +The "n" part is not applicable to the Mercury iPS at all. + + +Q: For Xmn, I note that these may be dealt with by alarms which can be read with READ:DEV::PSU:STAT in some hex format which is not defined in the manual (p. 162 in Issue 20). Could this be clarified?\ + +Asnwer from Robert Grzyb at Oxford Instruments:\ + +READ:DEV::PSU:STAT\ +It is important to note that the STATus word should be examined at the group device level, not the individual PSU level.\ +It is also very important to mask out (ignore) all other bits in this 32-bit word (i.e. ones not defined in the list given below):\ + + +| Status | Bit value | +| ------ | --------- | +| Switch Heater Mismatch | 00000001 | +| Over Temperature [Sense Resistor] | 00000004 | +| Over Temperature [Rundown Resistors] | 00000002 | +| Over Temperature [PCB] | 00000008 | +| Calibration Failure | 00000010 | +| MSP430 Firmware Error | 00000020 | +| Rundown Resistors Failed | 00000040 | +| MSP430 RS-485 Failure | 00000080 | +| Quench detected | 00000100 | +| Catch detected | 00000200 | +| Over Temperature [Sense Amplifier] | 00001000 | +| Over Temperature [Amplifier 1] | 00002000 | +| Over Temperature [Amplifier 2] | 00004000 | +| PWM Cutoff | 00008000 | +| Voltage ADC error | 00010000 | +| Current ADC error | 00020000 | + +Q: Also, is it possible to read if the Mercury iPS has tripped due to a low helium level signal from the level card (something like the X command on the old iLM200 which has a low level flag at bit 5 of S)? + +Answer:\ + +Low helium level + +There is no direct indication of the fact that iPS has run the magnet down as a result of helium level dropping below a set threshold.\ +It is possible to read both the helium level (DEV::LVL:SIG:HEL) and the configured threshold for low helium alarm (DEV::LVL:HEL:LOW). + + +## Compromises with SCPI command set and EPICS +STS:SYSTEM:LIMIT\ +Is an mbbi and has has 5 possible values:\ +- 0: "Normal" +- 1: "On +ve V Limit" +- 2: "On -ve V Limit" +- 4: "Current too -ve" +- 8: "Current too +ve" + +The limit flags came from the legacy command: Xmn +with the index denoted by the 'n' value. +SCPI does not provide this information. + From d3595b74732f66873ca9c310639891ef0fc2113f Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Wed, 17 Sep 2025 15:32:25 +0100 Subject: [PATCH 06/10] Fixed reported spelling issues --- .../Oxford-Instruments-Mercury-IPS.md | 156 +++++++++++------- doc/spelling_wordlist.txt | 4 + 2 files changed, 99 insertions(+), 61 deletions(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index d8ad496bd..80c6c2112 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md @@ -1,12 +1,13 @@ # Mercury IPS -The Oxford Instruments Mercury IPS is a superconducting magnet power supply. It is the successor to the [IPS](Oxford-Instruments-IPS). Much of the information on the IPS wiki page also applies to the Mercury IPS. +The Oxford Instruments Mercury IPS is a superconducting magnet power supply. It is the successor to +the [IPS](Oxford-Instruments-IPS). Much of the information on the IPS wiki page also applies to the Mercury IPS. -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 (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 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) @@ -14,17 +15,23 @@ The following faults can be seen when operating the magnet fully from the front ## 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. +SCPI mode keeps the same PV interface used by the older IPS units wherever possible, to minimise the +changes required to instrument python scripts when swapping between old & new controllers. +The SNL state machine logic is identical between SCPI & legacy mode. -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. +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. ### CONTROL and CONTROL:SP These records have been removed from the SCPI variant database @@ -34,30 +41,35 @@ the IPS via the front panel. ### SYSTEM:HWFAULT status is derived from the status bits via a calc record. This collates the various possible hardware faults into a single record, -which in the legacy protocol is a single value (Xm bit 4). +which in the legacy protocol is a single value (`Xm` bit 4). ### SWEEPMODE:PARAMS and SWEEPMODE:SWEEP These records have been removed as they are meaningless and underivable in SCPI protocol. ### _SWEEPMODE:SWEEP -In the legacy version, this used to be the readback from n of Mmn part of Examine command return. -0 output constant, 1, 2, 3 output changing -The SCPI protocol doesn't directly offer this, so it has to be derived via the ACTIVITY record (DEV:GRPZ:PSU:ACTN) -Direction from Alex Jones: "A response of HOLD or CLMP would be equivalent to n=0 in the response of the X command -in the old protocol. Responses of RTOS or RTOZ would be equivalent to n=1. -There is no equivalent for the m=0,1 fast/slow ramps, but we do not use this feature anyway." +In the legacy version, this used to be the readback from `n` of `Mmn` part of Examine command +return. +- 0 output constant +- 1, 2, 3 output changing + +The SCPI protocol doesn't directly offer this, so it has to be derived via the `ACTIVITY` record +(`DEV:GRPZ:PSU:ACTN`)\ +Direction from Alex Jones: "A response of `HOLD` or `CLMP` would be equivalent to `n=0` in the +response of the `X` command in the old protocol. Responses of `RTOS` or `RTOZ` would be equivalent to +`n=1`. +There is no equivalent for the `m=0,1` fast/slow ramps, but we do not use this feature anyway." ### System Alarms -System alarms are derived by interrogating the IPS with the "READ:SYS:ALRM?" SCPI command. +System alarms are derived by interrogating the IPS with the `READ:SYS:ALRM?` SCPI command. This returns a comma-separated string of active alarms, or an empty string if no alarms are present. The string is parsed by an aSub record, which sets the relevant bits in a binary register. The bits are mapped to individual status records, which are then used to set the relevant alarms. The precise protocol was determined empirically by sending the command and observing the response directly from the instrument. Discrete records are generated for each board type and each alarm by the -scpi_system_alarms_discrete.template and substitutions files. +`scpi_system_alarms_discrete.template` and substitutions files. -The base response is: READ:SYS:ALRM: which may (or may not) be followed by a board identifier, +The base response is: `READ:SYS:ALRM:` which may (or may not) be followed by a board identifier, a tab character (9) an alarm string and a semicolon. In ABNF:
@@ -81,51 +93,69 @@ The board identifiers are provided as macros: | BOARDID_LEVEL | DB1.L1 | ## Development Notes: -Alex Jones has looked at some of the differences between the SCPI and legacy command set and has summarised some useful information, as quoted below: -For the quench and overheat status, these (and many other issues) are dealt with by “Alarms” for the SCPI protocol. See the Magnet board section on p. 162 in Issue 20. These are read by “READ:DEV::PSU:STAT” in some undefined hex format for just the magnet-related alarms, and READ:SYS:ALRM for a list of everything. - -Some further information re UID naming: -The UIDs can be either the nickname for the card (which we can set to anything we want) or related to the slot number and signal type. -From the spreadsheet, the positional UID for the magnet temperature sensor will be MB1.T1, the UID for the level meter will be DB1.L1 and the UID for the magnet supply will be GRPZ for all 4 of the systems. -The 10T system will have an additional temperature sensor DB8.T1 and a pressure sensor DB5.P1. +Alex Jones has looked at some of the differences between the SCPI and legacy command set and has +summarised some useful information, as quoted below: +For the quench and overheat status, these (and many other issues) are dealt with by “Alarms” for +the SCPI protocol. See the Magnet board section on p. 162 in Issue 20. These are read by +`READ:DEV::PSU:STAT` in some undefined hex format for just the magnet-related alarms, and +`READ:SYS:ALRM` for a list of everything. + +### Some further information re UID naming: +The UIDs can be either the nickname for the card (which we can set to anything we want) or related +to the slot number and signal type. From the spreadsheet, the positional UID for the magnet +temperature sensor will be `MB1.T1`, the UID for the level meter will be `DB1.L1` and the UID for +the magnet supply will be `GRPZ` for all 4 of the systems. +The 10T system will have an additional temperature sensor `DB8.T1` and a pressure sensor `DB5.P1`. It appears that: -devices connected to the motherboard are prefixed: MB1\ -devices connected to a daughterboard are prefixed: DB +devices connected to the motherboard are prefixed: `MB1`\ +devices connected to a daughter-board are prefixed: `DB` -Conversation between Chris Lawson and Robert Grzyb at Oxford Instruments (18 Feb 2025) +Conversation between Chris Lawson and Oxford Instruments (18 Feb 2025) SCPI Equivalents: -Yes we are looking for the equivalent between Mercury iPS and iPS-120 control syntax. It may be some things are missing/changed, but wondered if there was a table of all of this somewhere internally. -I do not think we have a document which succinctly summarises differences between Mercury iPS and the IPS-120 in the context of their remote command sets. +Yes we are looking for the equivalent between Mercury iPS and iPS-120 control syntax. It may be +some things are missing/changed, but wondered if there was a table of all of this somewhere +internally. +I do not think we have a document which succinctly summarises differences between Mercury iPS and +the IPS-120 in the context of their remote command sets. -Q: What are the new commands to use on the Mercury iPS which are equivalent to the commands from the old iPS-120 below?\ -F17 (Trip Current)\ -F19 (Trip Field)\ -Xmn\ -m = 1 quenched\ -m = 2 overheated +Q: What are the new commands to use on the Mercury iPS which are equivalent to the commands from +the old iPS-120 below?\ +`F17` (Trip Current)\ +`F19` (Trip Field)\ +`Xmn`\ +`m = 1` quenched\ +`m = 2` overheated -Answer from Robert Grzyb at Oxford Instruments:\ -F17/F19\ -I assume that you mean legacy commands R17 (Trip Current) and R19 (Trip Field). +Answer from Oxford Instruments:\ +`F17/F19`\ +I assume that you mean legacy commands `R17` (Trip Current) and `R19` (Trip Field). This functionality is preserved when Mercury iPS remote interface is set to use legacy command set. -But when using "SCPI-style" command set, this exact information cannot be retrieved directly from the iPS. -Under certain (limited) circumstances R17/R19 are equivalent to DEV::PSU:SIG:PCUR and DEV::PSU:SIG:PFLD (note that UID must be a group, not an individual PSU). +But when using "SCPI-style" command set, this exact information cannot be retrieved directly from +the iPS. +Under certain (limited) circumstances `R17/R19` are equivalent to `DEV::PSU:SIG:PCUR` and +`DEV::PSU:SIG:PFLD` (note that UID must be a group, not an individual PSU). -Xmn -There is no equivalent for X (examine status) command in the "SCPI-style" command set. -As far as the first portion ("mn") of the reply to X command is concerned, certain "m" values correspond loosely to the bits of the status word in Mercury iPS group device (READ:DEV::PSU:STAT). -The "n" part is not applicable to the Mercury iPS at all. +`Xmn` +There is no equivalent for `X` (examine status) command in the "SCPI-style" command set. +As far as the first portion (`mn`) of the reply to `X` command is concerned, certain `m` values +correspond loosely to the bits of the status word in Mercury iPS group device +(`READ:DEV::PSU:STAT`). +The `n` part is not applicable to the Mercury iPS at all. -Q: For Xmn, I note that these may be dealt with by alarms which can be read with READ:DEV::PSU:STAT in some hex format which is not defined in the manual (p. 162 in Issue 20). Could this be clarified?\ +Q: For `Xmn`, I note that these may be dealt with by alarms which can be read with +`READ:DEV::PSU:STAT` in some hex format which is not defined in the manual +(p. 162 in Issue 20). Could this be clarified?\ -Asnwer from Robert Grzyb at Oxford Instruments:\ +Answer from Oxford Instruments:\ -READ:DEV::PSU:STAT\ -It is important to note that the STATus word should be examined at the group device level, not the individual PSU level.\ -It is also very important to mask out (ignore) all other bits in this 32-bit word (i.e. ones not defined in the list given below):\ +`READ:DEV::PSU:STAT`\ +It is important to note that the STATus word should be examined at the group device level, +not the individual PSU level.\ +It is also very important to mask out (ignore) all other bits in this 32-bit word (i.e. ones +not defined in the list given below):\ | Status | Bit value | @@ -147,26 +177,30 @@ It is also very important to mask out (ignore) all other bits in this 32-bit wor | Voltage ADC error | 00010000 | | Current ADC error | 00020000 | -Q: Also, is it possible to read if the Mercury iPS has tripped due to a low helium level signal from the level card (something like the X command on the old iLM200 which has a low level flag at bit 5 of S)? +Q: Also, is it possible to read if the Mercury iPS has tripped due to a low helium level signal +from the level card (something like the `X` command on the old `iLM200` which has a low level flag at +bit 5 of S)? Answer:\ Low helium level -There is no direct indication of the fact that iPS has run the magnet down as a result of helium level dropping below a set threshold.\ -It is possible to read both the helium level (DEV::LVL:SIG:HEL) and the configured threshold for low helium alarm (DEV::LVL:HEL:LOW). +There is no direct indication of the fact that iPS has run the magnet down as a result of helium +level dropping below a set threshold.\ +It is possible to read both the helium level (`DEV::LVL:SIG:HEL`) and the configured threshold +for low helium alarm (`DEV::LVL:HEL:LOW`). ## Compromises with SCPI command set and EPICS -STS:SYSTEM:LIMIT\ -Is an mbbi and has has 5 possible values:\ +`STS:SYSTEM:LIMIT`\ +Is an `mbbi` and has has 5 possible values:\ - 0: "Normal" - 1: "On +ve V Limit" - 2: "On -ve V Limit" - 4: "Current too -ve" - 8: "Current too +ve" -The limit flags came from the legacy command: Xmn -with the index denoted by the 'n' value. +The limit flags came from the legacy command: `Xmn` +with the index denoted by the `n` value. SCPI does not provide this information. diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt index 6e5b9a0c5..52a6449f5 100644 --- a/doc/spelling_wordlist.txt +++ b/doc/spelling_wordlist.txt @@ -348,6 +348,7 @@ idn ie IFR ilm +iLM200 ImageJ ini inits @@ -368,6 +369,7 @@ iocs iocsh ioLogik ip +iPS IPv ipython ish @@ -754,6 +756,7 @@ schedulable schemas ScriptUtil scrollbars +SCPI scsi sdk searchable @@ -882,6 +885,7 @@ uncheck unclamped uncomment uncommented +underivable unintuitive uno unpadded From 9f7fe00be78af78ed467dbcc6311d9e815122b39 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Wed, 17 Sep 2025 15:37:54 +0100 Subject: [PATCH 07/10] Removed duplicated SCPI from spelling_wordlist.txt --- doc/spelling_wordlist.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt index 52a6449f5..5c3b5ffda 100644 --- a/doc/spelling_wordlist.txt +++ b/doc/spelling_wordlist.txt @@ -756,7 +756,6 @@ schedulable schemas ScriptUtil scrollbars -SCPI scsi sdk searchable From 0732a9bba9fc3aa11fb6e6b0a6fbee75c12c9030 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Thu, 18 Sep 2025 11:02:27 +0100 Subject: [PATCH 08/10] Additional documentation on testing. --- .../Oxford-Instruments-Mercury-IPS.md | 105 ++++++++---------- 1 file changed, 47 insertions(+), 58 deletions(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index 80c6c2112..f8a91d576 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md @@ -29,6 +29,11 @@ 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. +Tested and verified to date: +- PSU board open circuit +- PSU board short circuit +- Temperature board open circuit +- Temperature board short circuit 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. @@ -107,56 +112,27 @@ temperature sensor will be `MB1.T1`, the UID for the level meter will be `DB1.L1 the magnet supply will be `GRPZ` for all 4 of the systems. The 10T system will have an additional temperature sensor `DB8.T1` and a pressure sensor `DB5.P1`. -It appears that: -devices connected to the motherboard are prefixed: `MB1`\ -devices connected to a daughter-board are prefixed: `DB` - - -Conversation between Chris Lawson and Oxford Instruments (18 Feb 2025) -SCPI Equivalents: -Yes we are looking for the equivalent between Mercury iPS and iPS-120 control syntax. It may be -some things are missing/changed, but wondered if there was a table of all of this somewhere -internally. -I do not think we have a document which succinctly summarises differences between Mercury iPS and -the IPS-120 in the context of their remote command sets. - -Q: What are the new commands to use on the Mercury iPS which are equivalent to the commands from -the old iPS-120 below?\ -`F17` (Trip Current)\ -`F19` (Trip Field)\ -`Xmn`\ -`m = 1` quenched\ -`m = 2` overheated +Devices connected to the motherboard are prefixed: `MB1`\ +Devices connected to a daughter-board are prefixed: `DB` + +### A comparison of availability of legacy vs SCPI features +| Function | Legacy | SCPI | +|---------------------------------|--------|---------------| +| Trip current readback | `F17` | Not available | +| Trip field readback | `F19` | Not available | +| Ramp mode reporting (fast/slow) | Yes | Not available | +| Status reporting | Yes | Detailed | +| He Level reporting | No | Yes | + | N2 Level reporting | No | Yes | -Answer from Oxford Instruments:\ -`F17/F19`\ -I assume that you mean legacy commands `R17` (Trip Current) and `R19` (Trip Field). -This functionality is preserved when Mercury iPS remote interface is set to use legacy command set. -But when using "SCPI-style" command set, this exact information cannot be retrieved directly from -the iPS. -Under certain (limited) circumstances `R17/R19` are equivalent to `DEV::PSU:SIG:PCUR` and -`DEV::PSU:SIG:PFLD` (note that UID must be a group, not an individual PSU). -`Xmn` -There is no equivalent for `X` (examine status) command in the "SCPI-style" command set. -As far as the first portion (`mn`) of the reply to `X` command is concerned, certain `m` values -correspond loosely to the bits of the status word in Mercury iPS group device -(`READ:DEV::PSU:STAT`). -The `n` part is not applicable to the Mercury iPS at all. - - -Q: For `Xmn`, I note that these may be dealt with by alarms which can be read with -`READ:DEV::PSU:STAT` in some hex format which is not defined in the manual -(p. 162 in Issue 20). Could this be clarified?\ - -Answer from Oxford Instruments:\ - -`READ:DEV::PSU:STAT`\ + +### PSU Status: +Using the SCPI command: `READ:DEV::PSU:STAT`\ It is important to note that the STATus word should be examined at the group device level, not the individual PSU level.\ It is also very important to mask out (ignore) all other bits in this 32-bit word (i.e. ones not defined in the list given below):\ - | Status | Bit value | | ------ | --------- | @@ -177,21 +153,8 @@ not defined in the list given below):\ | Voltage ADC error | 00010000 | | Current ADC error | 00020000 | -Q: Also, is it possible to read if the Mercury iPS has tripped due to a low helium level signal -from the level card (something like the `X` command on the old `iLM200` which has a low level flag at -bit 5 of S)? - -Answer:\ - -Low helium level - -There is no direct indication of the fact that iPS has run the magnet down as a result of helium -level dropping below a set threshold.\ -It is possible to read both the helium level (`DEV::LVL:SIG:HEL`) and the configured threshold -for low helium alarm (`DEV::LVL:HEL:LOW`). - -## Compromises with SCPI command set and EPICS +### Compromises with SCPI command set and EPICS `STS:SYSTEM:LIMIT`\ Is an `mbbi` and has has 5 possible values:\ - 0: "Normal" @@ -204,3 +167,29 @@ The limit flags came from the legacy command: `Xmn` with the index denoted by the `n` value. SCPI does not provide this information. +## IOC Test Framework: +With support for the new SCPI based IPS command set, there are now two sets of StreamDevice +protocols. The appropriate protocol is implemented by use of a macro (`PROTOCOL` = `SCPI` | `LEGACY`) defined +prior to running the IOC. + +The test framework has been adapted by splitting the existing legacy tests into common tests +and tests specific to either control interface. For instance, the legacy command set knows +nothing about cryogen levels, which the SCPI command set does. + +The IOC support provides two protocol files: +- Legacy: OxInstIPS.protocol +- SCPI: OxInstIPS_SCPI.protocol + +The lewis emulator and IOC test framework for the Mercury IPS is located within the IPS support +module. Manually running the tests is achievable using the following approach: +1. `cd` to `C:\Instrument\Apps\EPICS\support\IPS\master\system_tests` +2. `run_tests.bat -t ips_scpi -a -f` - this will run all the SCPI specific tests +3. `run_tests.bat -t ips -a -f` - this will run all the legacy specific tests +4. To run a specific test, use something like: `run_tests.bat -t ips_scpi.test_WHEN_inductance_set_via_backdoor_THEN_value_in_ioc_updates_0__0_12345 -a -f` +- Note that the -a flag simply prompts as to whether to run tests or simply run the emulator. +- The -f flag forces a fast fail on error and no further tests are run. + + +## Related Documentation: +[Oxford Instruments IPS](https://isiscomputinggroup.github.io/ibex_developers_manual/specific_iocs/cryogenics/Oxford-Instruments-IPS.html) + From bcfeddea2102399b13e4f9053915fb059686bae6 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Tue, 23 Sep 2025 08:46:51 +0100 Subject: [PATCH 09/10] Removed notes on legacy hardware quirks, as these should now be resolved with all units. --- .../Oxford-Instruments-Mercury-IPS.md | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md index f8a91d576..f96007aaa 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.md @@ -4,14 +4,6 @@ The Oxford Instruments Mercury IPS is a superconducting magnet power supply. It the [IPS](Oxford-Instruments-IPS). Much of the information on the IPS wiki page also applies to the Mercury IPS. -## 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) - ## SCPI Protocol The IPS IOC now supports the SCPI protocol, which is more feature rich than Legacy mode. @@ -26,9 +18,11 @@ documentation. The status strings are assumed to all conform to the "Directory o (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. +It has not been possible to test all alarm scenarios with the IPS unit. Some messages are +undocumented and were 'discovered'. Our best guess is that the IPS Manual presents some level of +truth, but as such it has not been possible to fully ascertain that all the expected message +strings are correct - they may need to be adjusted later on, if/when they arise. + Tested and verified to date: - PSU board open circuit - PSU board short circuit @@ -37,6 +31,7 @@ Tested and verified to date: 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. +See the section on [System Alarms](#system-alarms) below for more details. ### CONTROL and CONTROL:SP These records have been removed from the SCPI variant database @@ -123,7 +118,9 @@ Devices connected to a daughter-board are prefixed: `DB` | Ramp mode reporting (fast/slow) | Yes | Not available | | Status reporting | Yes | Detailed | | He Level reporting | No | Yes | - | N2 Level reporting | No | Yes | +| N2 Level reporting | No | Yes | +| Pressure reporting | No | Yes | +| Front panel control lock | Yes | No | @@ -169,8 +166,8 @@ SCPI does not provide this information. ## IOC Test Framework: With support for the new SCPI based IPS command set, there are now two sets of StreamDevice -protocols. The appropriate protocol is implemented by use of a macro (`PROTOCOL` = `SCPI` | `LEGACY`) defined -prior to running the IOC. +protocols. The appropriate protocol is implemented by use of a macro +(`PROTOCOL` = `SCPI` | `LEGACY`) defined prior to running the IOC. The test framework has been adapted by splitting the existing legacy tests into common tests and tests specific to either control interface. For instance, the legacy command set knows From 295f303c578a604b47aa2e20a09e72ca496f4370 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Tue, 23 Sep 2025 09:04:27 +0100 Subject: [PATCH 10/10] cryogenics/Oxford-Instruments-IPS.md: Added link to related documentation - Mercury IPS. --- doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md b/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md index f5f316dd1..1ae64fff6 100644 --- a/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md +++ b/doc/specific_iocs/cryogenics/Oxford-Instruments-IPS.md @@ -143,4 +143,7 @@ Check remote mode is enabled. ### Magnet system status reports something other than "normal" - e.g. "quenched" or "fault" -This indicates a hardware fault. Inform instrument scientists that the magnet has a problem and has likely gone to zero field (even if the IPS still claims to be producing a non-zero field). Consult cryogenics for help. \ No newline at end of file +This indicates a hardware fault. Inform instrument scientists that the magnet has a problem and has likely gone to zero field (even if the IPS still claims to be producing a non-zero field). Consult cryogenics for help. + +## Related Documentation: +[Oxford Instruments Mercury IPS](https://isiscomputinggroup.github.io/ibex_developers_manual/specific_iocs/cryogenics/Oxford-Instruments-Mercury-IPS.html)