architecture docs

Author: rerpha

doc/conf.py

@@ -104,5 +104,6 @@
 
 intersphinx_mapping = {
     "ibex_user_manual": ("https://isiscomputinggroup.github.io/ibex_user_manual/", None),
+    "EPICS": ("https://docs.epics-controls.org/en/latest/", None),
 }
 

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

@@ -1,8 +1,13 @@
-# Beckhoff IOC Architecture
-
-We have an EPICS motor record implementation which interfaces some intermediate PVs, spun up by AdsDriver and [The Beckhoff Motor Extensions](https://github.com/ISISComputingGroup/EPICS-motorExtensions/tree/master/beckhoffApp)
-
-This was originally done so we could drop-in [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) in place of another ADS EPICS module (`tcIOC`) and debug EPICS to ADS more easily by bypassing the motor modules if we saw a comms issue. In future, we could build [`AdsDriver`](https://github.com/ISISComputingGroup/adsDriver) into our motor module directly so we avoid this extra step. 
-
-This means that the EPICS motor record is essentially doing `dbgf` and `dbpf` to read and write to these PVs respectively, rather than just setting something on a device like a normal motion controller like a [Mclennan] or [Galil]. 
-
+# Beckhoff IOC Architecture
+
+[TC](https://github.com/ISISComputingGroup/EPICS-ioc/tree/master/TC) is the IOC responsible for communication with Beckhoff PLCs at ISIS.
+
+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.
+
+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 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`.

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

@@ -24,13 +24,14 @@ The IOC (`TC_01`) should in principle be able to talk via ADS at this point but
 - Number of axes (`NUM_AXES` macro)
 - the `IP` and `AMSnetID` of the controller
 
+{#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)
 - Axis description (`.DESC`) - [ticket to automatically populate](https://github.com/ISISComputingGroup/IBEX/issues/6860)
   - Note, if `stDescription` is actually filled out on a Beckhoff you can use the `FORWARD_DESC` macro set to `1` which will forward the PLC description to the corresponding motor record's `.DESC` field. 
-- Soft limits
+- Soft limits - [ticket to automatically populate](https://github.com/ISISComputingGroup/IBEX/issues/8763)
 
 These can be set via a `caput` and will be autosaved thereafter.
 
@@ -39,11 +40,11 @@ These are loaded in the usual way, you'll need to put your `axes.cmd` and `motio
 
 #### Jaws
 
-Jaws controlled by Beckhoffs don't actually require any logic to calculate gaps & centres, as this is done on the controller using virtual axes for the gaps and centres, so instead we load in a `$(JAWS)/db/jaws_alias.db` file instead of the usual `jaws.db`. This takes macros for the (virtual) axes to use as the gaps and centres.
+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. 
 
 #### 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`
+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

@@ -47,8 +47,47 @@ _When you have finished testing/reviewing a PR, it is best to run `unsettick.bat
 
 </details>
 
+## Simulate an Instrument
+
+To simulate an instrument's Beckhoff and make it virtual rather than driving physical motors etc. you need to: 
+
+1. Follow the above steps
+1. find the repo for that particular MCU within https://github.com/ISIS-Motion-Control 
+1. clone it and checkout master, then `git submodule update --init` in the cloned directory
+1. open up the solution in TwinCAT XAR
+1. change the `MCU_xxx` in the dropdown next to "solution" to `<local>`
+
+There are a few things we need to disable in XAR in order to get this instance entirely virtual. these are: 
+
+(under the "solution" in the solution explorer)
+
+License: 
+1. in SYSTEM -> License remove any dongles (these are normally physical USB sticks)
+1. generate a "7 days trial license" from the top-level screen
+
+I/O:
+
+in `I/O -> Devices`, disable all devices that show up by right-clicking and selecting "disable"
+
+Safety: 
+
+in `SAFETY`, disable all safety instances
+
+Motion:
+
+in `MOTION -> NC - Task 1 SVB` go to Axes and then expand all axes, then go to `Enc` and change the "type" to "Simulation encoder"
+
+
+After doing all of this you should be able to build the solution from "build" and then hit activate(icon that looks like stairs) and run it locally. 
+
+
+
 ### 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.
+```
+
 <details><summary>Jenkins</summary>