add instrument specific information

Author: rerpha

doc/specific_iocs/motors/Beckhoff.md

@@ -18,16 +18,11 @@ Current Beckhoff installations are:
 
 
 ## Code on the controller
-Unlike most other devices (except the Galil) the computing group has some oversight over the PLC code written on the controller. It has been agreed that this code will mostly be written by IDD, with oversight from computing to guide good programming practices, assist in debugging etc. Code running on the PLC lives [here](https://github.com/ISIS-Motion-Control).
+Unlike most other devices (except the Galil) the computing group has some oversight over the PLC code written on the controller. It has been agreed that this code will mostly be written by IDD, with oversight from computing to guide good programming practices, assist in debugging etc. Code running on the PLC is kept in source control [here](https://github.com/ISIS-Motion-Control).
 
-### Documentation
-- [Axis and Controller Commissioning Guide](https://stfc365.sharepoint.com/:w:/s/ISISMechatronics/Ee_aMxb5CF1Dlz-NUGW3OVgB0K7vQjXXwZDwSl5DSHN48w?e=GjqNEb&isSPOFile=1) document describing setting up a controller and TwinCAT solution for a new system and configuring real and virtual axes within TwinCAT environment.
+The [Axis and Controller Commissioning Guide](https://stfc365.sharepoint.com/:w:/s/ISISMechatronics/Ee_aMxb5CF1Dlz-NUGW3OVgB0K7vQjXXwZDwSl5DSHN48w?e=GjqNEb&isSPOFile=1) document describing setting up a controller and TwinCAT solution for a new system and configuring real and virtual axes within TwinCAT environment.
 
-## Troubleshooting
-see [Beckhoff troubleshooting](beckhoff/Beckhoff-troubleshooting)
 
-## Testing
-See [Beckhoff testing](beckhoff/Beckhoff-testing)
 
 ## Commissioning a new Beckhoff on a beamline
 see [Beckhoff Commissioning](beckhoff/Beckhoff-commissioning)
@@ -38,18 +33,13 @@ see [Beckhoff Commissioning](beckhoff/Beckhoff-commissioning)
 we no longer use [tcIOC](https://github.com/ISISComputingGroup/EPICS-tcIoc) for numerous reasons, the most important being the dependence on the unreliable `.tpy` file format which was preventing us from integrating the new motion standard library code. We now use [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) in conjunction with [`TwincatMotor`](https://github.com/ISISComputingGroup/EPICS-TwincatMotor).**
 ```
 
-See [Beckhoff IOC Architecture](beckhoff/Beckhoff-architecture) for more information. 
-
-### Beckhoff config area
+See [Beckhoff IOC Architecture](beckhoff/Beckhoff-architecture) for more information.
 
-The config area contains a directory used for storing `.cmd` files for use with the `TC` IOC (in the same way as a galil or other motor controller). On an instrument it should look like this: `\instrument\apps\EPICS\support\motorExtensions\master\settings\<instname>\twincat\`. 
-
-### Quirks
+## Troubleshooting
+see [Beckhoff troubleshooting](beckhoff/Beckhoff-troubleshooting)
 
-- The main quirk with the way we interact with Beckhoffs is that we use [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) to spin up lots of intermediate PVs, in which our motor record uses with `dbpf` and `dbgf` instead of directly communicating with the device. In the future, we could integrate [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) within our motor record for a more standard approach.
-- The Beckhoff uses whether it has been homed to set `ATHM` in the motor record, rather than just using the raw datum switch. 
-- The "limits" shown on the table of motors summary view are not necessarily actual physical limit switches being engaged - the Beckhoff has more complex rules on whether motors can move back or forwards
-- The motor record sets `UEIP` (use encoder if present) to false to avoid using the encoder resolution to scale values. We have no control over whether to use or not use an encoder with a Beckhoff, the internal code handles it
+## Testing
+See [Beckhoff testing](beckhoff/Beckhoff-testing)
 
 ## Updating
 

doc/specific_iocs/motors/beckhoff/Beckhoff-architecture.md

@@ -4,10 +4,21 @@
 
 At IOC startup, it uses [a command](https://github.com/ISISComputingGroup/adsDriver/blob/main/adsApp/src/ioc_commands.cpp#L139) to get the number of motion axes. Note that this may be more than 8, in which case we have to use [some logic](https://github.com/ISISComputingGroup/EPICS-ioc/blob/master/TC/iocBoot/iocTC-IOC-01/st-common.lua#L51) to alias `MTR0109` to `MTR0201` so we can display it in the IBEX GUI's table of motors.  
 
-We have an EPICS motor record implementation which TC uses that interfaces some intermediate PVs, spun up [at runtime](https://github.com/ISISComputingGroup/EPICS-ioc/blob/97e2bd77c5909ff2f1b6c0cda7f175366b379102/TC/iocBoot/iocTC-IOC-01/st-common.lua#L30) per-axis by AdsDriver using [The Beckhoff Motor Extensions](https://github.com/ISISComputingGroup/EPICS-motorExtensions/tree/master/beckhoffApp)  `.db` files.
+We have an EPICS motor record implementation which TC uses that interfaces some intermediate PVs, spun up [at runtime](https://github.com/ISISComputingGroup/EPICS-ioc/blob/97e2bd77c5909ff2f1b6c0cda7f175366b379102/TC/iocBoot/iocTC-IOC-01/st-common.lua#L30) per-axis by AdsDriver using [the Beckhoff Motor Extensions](https://github.com/ISISComputingGroup/EPICS-motorExtensions/tree/master/beckhoffApp)  `.db` files.
 
-This was originally done so we could drop in [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) in place of another ADS EPICS module ([`tcIOC`](https://github.com/ISISComputingGroup/EPICS-tcIoc)) and debug EPICS to ADS communications more easily by bypassing the motor modules if we saw an issue. In the future, we could build [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) calls into our motor module directly so we avoid this extra step.
+This was originally done so we could drop in [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) in place of another ADS EPICS module ([`tcIOC`](https://github.com/ISISComputingGroup/EPICS-tcIoc)) and debug EPICS to ADS communications more easily by bypassing the motor modules if we saw an issue. In the future, we could build [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) calls into our motor module directly so we avoid this extra step. We still need to use `AdsDriver` to spin up extra, instrument-specific PVs - {ref}`beckhoff_arbitrary_fields`
 
 This means that the EPICS motor record is essentially doing `dbgf` and `dbpf` as documented in the {external+EPICS:doc}`EPICS IOC Test Facilities <appdevguide/IOCTestFacilities>` respectively to read and write to these PVs, rather than just setting something on a device like a normal motion controller like a {doc}`../McLennan-motors` or {doc}`../Galil`. 
 
 `TC` also does some things "outside" the motor record such as forwarding the device's velocities to the motor record. This is because the PLC is commissioned with a sensible velocity in most cases and we don't want to overwrite this information, and it may change on the PLC due to safety system overloads and so on. We also do the same for axis description (to the `.DESC` field) - see {ref}`beckhoff_manual_commission_step`.
+
+
+### Beckhoff config area
+
+The config area contains a directory used for storing `.cmd` files for use with the `TC` IOC (in the same way as a galil or other motor controller). On an instrument it should look like this: `\instrument\apps\EPICS\support\motorExtensions\master\settings\<instname>\twincat\`. 
+
+### Quirks
+- The Beckhoff uses whether it has been homed to set `ATHM` in the motor record, rather than just using the raw datum switch. This is different to a Galil which uses the datum switch.
+- The "limits" shown on the table of motors summary view are not necessarily actual physical limit switches being engaged - the Beckhoff has more complex rules on whether motors can move back or forwards.
+- The motor record sets `UEIP` (use encoder if present) to false to avoid using the encoder resolution to scale values. We have no control over whether to use or not use an encoder with a Beckhoff, the internal code handles it. As well as this, we do not retry (`.RCNT` and `.RDBD` fields of the motor record) as the motion control loop is handled by the PLC.
+- Some Beckhoff axes are virtual as the PLC can handle kinematics, for example many of the INTER axes. There isn't currently a way to differentiate real and virtual axes other than marking them with `v - ` in their `.DESC` fields.

doc/specific_iocs/motors/beckhoff/Beckhoff-commissioning.md

@@ -1,14 +1,17 @@
 # Beckhoff commissioning
 
 ## Commissioning steps
+
 These steps are for commissioning a Beckhoff on a beamline. 
 
 ### Networking
+
 Beckhoffs are connected to NDX machines via private networks, in much the same way as the Galils. By convention Beckhoffs live in the `192.168.1.22X` range, starting at 1 for the first controller (`192.168.1.221`) 
 
 ### ADS routes
+
 To actually communicate via the ADS transport layer you will need to set up a route on the instrument PC. To do so: 
-1. (**these are included in the windows 10 clone so should already be installed to instrument machines**) Install the XAR tools 
+1. (**these are included in the Windows 10 clone so should already be installed on instrument machines**) Install the XAR tools 
  A copy of these will be hosted on `<public share>\third_party_installers\special_drivers\beckhoff\`. All of the defaults are fine so this should be a case of just clicking through the wizard and installing the drivers that show up. 
 2. Set up an ADS route on the NDX: 
   - `Right-click TwinCAT icon in system tray -> Router -> Edit Routes -> Add...` with these settings:
@@ -18,6 +21,7 @@ To actually communicate via the ADS transport layer you will need to set up a ro
 3. To confirm that this has been set up remote into the controller itself on the aforementioned IP address and check that the route to the NDX has been added automatically. You should not need to manually add a route in the controller. 
 
 ### IOC setup
+
 The IOC (`TC_01`) should in principle be able to talk via ADS at this point but will need setting up in the respective configs. 
 - A `MTRCTRL` number will need to be given - this is the controller number as shown on the table of motors.
 - `Beckhoff_plc_code` should be specified as a macro, this may be removed in future releases, more information on this is available below however it should be set to `1` for instruments running the latest code. 
@@ -26,6 +30,7 @@ The IOC (`TC_01`) should in principle be able to talk via ADS at this point but
 
 {#beckhoff_manual_commission_step}
 #### Fields that aren't automatically populated
+
 Although commissioning a Beckhoff is far simpler than a Galil from an IBEX perspective, there are some fields that need to be set manually for each axis.  These are: 
 
 - Engineering units (`.EGU`) - [ticket to automatically populate](https://github.com/ISISComputingGroup/IBEX/issues/6855)
@@ -36,15 +41,18 @@ Although commissioning a Beckhoff is far simpler than a Galil from an IBEX persp
 These can be set via a `caput` and will be autosaved thereafter.
 
 #### Axes, motion setpoints, jaws
-These are loaded in the usual way, you'll need to put your `axes.cmd` and `motionSetpoints.cmd` files in the `twincat` config directory
+
+These are loaded in the usual way, you'll need to put your `axes.cmd` and `motionSetpoints.cmd` files in `motorExtensions\master\settings\NDX<inst>\twincat\`
 
 #### Jaws
 
 This is currently done in the same way as any other motion controller where IBEX works out gaps and centres. This logic may move to the controller eventually, in which case we will need to use [The Jaws alias `.db`](https://github.com/ISISComputingGroup/EPICS-jaws/blob/master/jawsApp/Db/jaws_alias.substitutions) 
 
 #### If a controller has more than 8 axes
+
 If a controller with more than 8 axes is going to be used, the TC IOC will alias records to the next controller number so they are shown in the GUI. For this to work you need to make sure that the next available controller number is not (and never will be, so long as the TC IOC uses it) used. 
 
+{#beckhoff_arbitrary_fields}
 #### Arbitrary fields 
 
 It was decided during [A meeting with the motion team](https://github.com/ISISComputingGroup/IBEX/issues/6916) that extra fields, for example LARMOR's air signals + bump strips will be exposed via a separate `PROG` file within the PLC. We should load these in from a `motorExtensions` `.cmd` file. Examples for LARMOR and SANS2D can be found in the settings directory of `motorExtensions\master\settings`

doc/specific_iocs/motors/beckhoff/Beckhoff-testing.md

@@ -85,7 +85,7 @@ After doing all of this you should be able to build the solution from "build" an
 ### Continuous Integration
 
 ```{warning}
-This is currently broken and this documentation will become out-of-date. https://github.com/ISISComputingGroup/IBEX/issues/7552 is to get them running again.
+This is currently broken and this documentation will become out-of-date until https://github.com/ISISComputingGroup/IBEX/issues/7552 is complete to get them running again.
 ```
 
 <details><summary>Jenkins</summary>

doc/specific_iocs/motors/beckhoff/Beckhoff-troubleshooting.md

@@ -29,3 +29,31 @@ See https://github.com/ISISComputingGroup/IBEX/issues/8339 for a detailed descri
 
 The solution is to set `.DLY` to 0.25 in the motor record (which causes a 250ms "settle time" after motions).
 
+## Instrument specific Beckhoff information
+
+### SANDALS - Jaws and Sample Changer
+
+SANDALS has a Beckhoff PLC which serves the Jaws permanently, and the Sample Changer when it is plugged in (over an ethercat network)
+
+Some of these axes are relatively-encoded, so need to be homed/calibrated before use after a power cycle. At the moment we use the `.ATHM` field to indicate this, so if the home icon is not shown on the Table of Motors the axes have not been calibrated and will error when a move is attempted.
+
+The Sample changer has some `pt100` sensors for temperature mounted on it, these are fed in through the beckhoff as extra fields. These are loaded by [this `.db`](https://github.com/ISISComputingGroup/EPICS-motorExtensions/blob/master/sandalsSampleChangerApp/Db/sandals_sample_changer_beckhoff_extras.substitutions)
+
+### INTER - Detector tank including Jaws 4
+
+This is currently the most complex implementation of using a Beckhoff PLC as it handles kinematics between physical axes and flight paths, traditionally "worked out" by the Reflectometry server. It has some custom routines which can be accessed from the PLC HMI or through the `INTER Beckhoff Diagnostics` device screen in IBEX.
+
+It also controls some Jaws on the front of the tank. 
+
+### LARMOR - Detector Bench
+
+This is a single axis. It lets IBEX know about an air PLC signal as it requires an air bearing to move. This is fed in by [this `.db`](https://github.com/ISISComputingGroup/EPICS-motorExtensions/blob/master/larmorBeckhoffExtrasApp/Db/larmor_beckhoff_extras.substitutions) and the bump strip signal is flipped and sent to the bump strip PV which is shown in the banner to indicate that motion has tripped.
+
+### IMAT - Rotation and Height stage
+
+This is currently just two axes, with no real quirks on our side. 
+
+### SURF - Cloche motion and jaws 1&2
+
+SURF's motion involves the tank, including the supermirror and frame-overlap mirror, as well as Jaws 1 and 2. This has had issues with encoder radiation in the past which has required a PLC power cycle, which in turn then requires a power restore. In order to get this properly working, [this ticket](https://github.com/ISISComputingGroup/IBEX/issues/8464) needs to be completed.
+