Add purchasing devices guide

Author: Tom-Willemsen

doc/Glossary.md

@@ -233,7 +233,11 @@ The version of [IBEX](#ibex) to be deployed.
 
 ## SECI
 
-**Sample Environment Control Interface. An old instrument control system, used before IBEX. No longer in use on any instruments. Written in C# and incorporating [LabVIEW](#labview) drivers for the sample environment equipment.
+**Sample Environment Control Interface**. An old instrument control system, used before IBEX. No longer in use on any instruments. Written in C# and incorporating [LabVIEW](#labview) drivers for the sample environment equipment.
+
+## SECoP
+
+**Sample Environment Communication Protocol**. See {external+secop:doc}`SECoP docs <index>` for details.
 
 ## Sequencer
 

doc/IOCs.md

@@ -80,7 +80,6 @@ If you're not creating a StreamDevice IOC or you would like to know how an IOC c
 * [IOC Testing framework](iocs/testing/IOC-Testing-Framework)
 * [Complexity of LabVIEW Drivers](system_components/labview/Complexity-of-LabVIEW-Drivers)
 * [Typical start up log for an ioc](iocs/troubleshooting/IOC-Start-Example)
-* [Some Design thoughts for a serial/Ethernet IOC](iocs/tips_tricks/Some-Design-thoughts-for-a-serial-or-Ethernet-IOC)
 * [Reducing build dependencies for older iocs](iocs/compiling/Reducing-Build-Dependencies)
 * [Template Substitutions](iocs/tools/Template-Substitutions)
 * [Creating a State Machine](iocs/tools/Creating-a-State-Machine-(Sequencer))

doc/conf.py

@@ -112,4 +112,5 @@
     "genie_python": ("https://isiscomputinggroup.github.io/genie/", None),
     "ibex_bluesky_core": ("https://isiscomputinggroup.github.io/ibex_bluesky_core/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
+    "secop": ("https://sampleenvironment.github.io/secop-site/", None),
 }

doc/iocs/Purchasing-New-Equipment.md

@@ -0,0 +1,51 @@
+# Purchasing new equipment
+
+```{toctree}
+:hidden:
+:glob:
+:titlesonly:
+:maxdepth: 1
+
+purchasing_new_equipment/*
+```
+
+```{note}
+This page relates to "slow" control; if looking at items like cameras, DAQ, or items at a higher frequency than 10Hz, please {external+ibex_user_manual:ref}`contact Experiment Controls <report_a_problem>`.
+```
+
+## Off the shelf devices
+If purchasing "simple" off the shelf devices (e.g. power supplies, temperature controllers, gaussmeters, etc.) please bear the following in mind: 
+- The device itself needs to allow an external computer to control it. 
+- Only certain transport layers will interact with our architecture readily. If it is not in this list, we are unlikely to be able to integrate it easily, so please engage with the group as soon as possible. This list is in order of preference. 
+  * **Serial** (RS232 is preferred, but RS422 and RS485 can be accommodated with advanced warning). Ideally DB9 or DB25 connectors.
+  * **Ethernet** - but please make sure there is provision for updates to the device system. Ideally this would be DHCP capable, but should also allow for configuration of a static IP.
+  * **GPIB**
+- If the only connection option available is **USB**, then you **MUST** get in touch with us early, as the options for integrating these devices are limited, and it may need a dedicated computer purchasing. 
+- With regards to the control protocol, the following can all be integrated easily, other protocols would need to be discussed: 
+  * {external+secop:doc}`SECoP <index>` 
+  * [SCPI](https://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments)
+  * [OPCUA](https://en.wikipedia.org/wiki/OPC_Unified_Architecture)
+  * ASCII based command sets (please see the {doc}`purchasing_new_equipment/Designing-Protocols` guide for more details of preferences of how these would look)
+  * [Modbus](https://en.wikipedia.org/wiki/Modbus)
+
+If a protocol needs to be designed, please consider {external+secop:doc}`SECoP <index>`  first, or read the {doc}`purchasing_new_equipment/Designing-Protocols` guide.
+
+As much warning as possible is needed to ensure availability of new devices within IBEX; please {external+ibex_user_manual:ref}`contact Experiment Controls <report_a_problem>` as soon as possible when considering the purchase of a new device.
+
+## Systems which integrate a Computer 
+
+It is not unusual for moderately complex systems to require a computer to provide suitable control. This raises greater concerns for ISIS generally, as well as the Experiment Controls team. 
+
+Agreement needs to be ensured during tender and selection in relation to: 
+- Who supplies the computer 
+- Who maintains it 
+- Who ensures it is kept up to date 
+- Who deals with changes when the hardware must be updated or the operating system updates cause something to function in an unanticipated manner 
+- Recovery procedures for failure conditions 
+- Who is responsible for the cybersecurity level and maintenance of this computer 
+
+Service level agreements for any of these issues should also be agreed. These should match the expected lifetime of the item being purchased. If this is not possible, then an agreement as to the risk needs to be made, and considerations for ways to mitigate it which do not put undue stress on the resources in question. 
+
+Conversations with the Experiment Controls team from the outset would be beneficial for such items. 
+
+Updates for security aspects are especially important for any item which is placed on a network, there is greater grace available should the communication between IBEX and the device be via a transport layer other than ethernet as the computer can be kept off a network. 

doc/iocs/purchasing_new_equipment/Designing-Protocols.md

@@ -0,0 +1,39 @@
+{#designing_comms_protocol}
+# Designing protocols
+
+```{important}
+If you are considering purshasing a new device or designing a new protocol, please read the
+{doc}`../Purchasing-New-Equipment` page before continuing with this guide.
+```
+ 
+Ideally the transport layer will be one of those listed in the {doc}`../Purchasing-New-Equipment` guide. If a protocol needs to be developed, we would advocate using {external+secop:doc}`SECoP <index>`. If that is not an option for you, then the following guidelines allow for easier integration. 
+
+## Termination characters 
+
+It is very helpful for devices to terminate their messages with a unique set of characters that do not appear elsewhere in the message. A common example of a terminator is a carriage-return, line-feed pair (`<CR><LF>`, `\r\n`, HEX: `0D 0A`). 
+
+## Readability/encoding 
+
+Commands to a device are ideally human-readable so that they can be used via terminal emulators and the device interacted with. Many protocols use an ASCII encoding. 
+
+For example, a temperature controller might implement commands like the following: 
+
+``` 
+Driver to device: 
+temp?<CR><LF> 
+(HEX: 74 65 6D 70 3F 0D 0A) 
+
+Device to driver: 
+temp=30.5<CR><LF> 
+(HEX: 74 65 6D 70 3D 33 30 2E 35 0D 0A) 
+``` 
+
+## Replies 
+
+All commands to a device, whether setting or reading a value, should ideally return some form of reply. This helps the control system to distinguish between a device which is unplugged and an incorrect or invalid command. 
+
+Where no data needs to be returned, a device could generate either an `ACK` ASCII control code or a reply string like `OK` or similar response. Commands which are invalid or rejected could return a `NAK` ASCII control code, or a text string like `NOK` or `error` or similar responses. 
+
+## Unsolicited messages 
+
+We prefer not to receive unsolicited messages. It is better for a driver to explicitly ask for a parameter each time it is required.