diff --git a/doc/Glossary.md b/doc/Glossary.md index 7976c4422..1303b1b8f 100644 --- a/doc/Glossary.md +++ b/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 ` for details. ## Sequencer diff --git a/doc/IOCs.md b/doc/IOCs.md index 1dc23ea9e..e5e685e00 100644 --- a/doc/IOCs.md +++ b/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)) diff --git a/doc/conf.py b/doc/conf.py index 1f2cb6fbd..5875ccfa2 100644 --- a/doc/conf.py +++ b/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), } diff --git a/doc/iocs/Purchasing-New-Equipment.md b/doc/iocs/Purchasing-New-Equipment.md new file mode 100644 index 000000000..fb1ae2cee --- /dev/null +++ b/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 `. +``` + +## 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 ` + * [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 ` 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 ` 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. \ No newline at end of file diff --git a/doc/iocs/purchasing_new_equipment/Designing-Protocols.md b/doc/iocs/purchasing_new_equipment/Designing-Protocols.md new file mode 100644 index 000000000..57213ddd6 --- /dev/null +++ b/doc/iocs/purchasing_new_equipment/Designing-Protocols.md @@ -0,0 +1,39 @@ +{#designing_comms_protocol} +# Designing protocols + +```{important} +If you are considering purchasing 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 `. 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 (``, `\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? +(HEX: 74 65 6D 70 3F 0D 0A) + +Device to driver: +temp=30.5 +(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. \ No newline at end of file diff --git a/doc/iocs/tips_tricks/Communication-layer-likes-and-dislikes-(protocol,-new-devices).md b/doc/iocs/tips_tricks/Communication-layer-likes-and-dislikes-(protocol,-new-devices).md deleted file mode 100644 index 7e1be4a09..000000000 --- a/doc/iocs/tips_tricks/Communication-layer-likes-and-dislikes-(protocol,-new-devices).md +++ /dev/null @@ -1,69 +0,0 @@ -# Comms layer likes & dislikes - -This page documents an "idealised" communication protocol for communicating with new sample environment drivers at ISIS. It is intended as a useful starting point if new protocols are being developed from scratch and as a set of nice-to-haves for new equipment being purchased. - -## Transport layer - -### Serial (RS232, RS422, RS485) - -This is the most common transport layer at ISIS. Serial settings are flexible in all of our drivers but the most common configuration is: - -- Baud rate: 9600 -- Data bits: 8 -- Parity: None -- Stop bits: 1 -- Flow control: Off - -RS232 is preferable, RS422 and RS485 are avoided as far as reasonable. Note that distances can be extreme if higher baud rates are required. Preferred socket is DB-9, but DB-25 also acceptable. - -### Ethernet - -Ethernet is a commonly used and well-supported transport layer at ISIS using RJ45 ports (AKA 8P8C sockets). Any other port type is to be avoided. It is also preferable that devices use DHCP to find their IP address rather than being issued a static address. - -### USB - -USB devices are difficult to integrate into the Experiment Control System, so should be avoided. - -### Manufacturer software / DLLs - -We prefer not to use these interfaces. However, in some cases, we may be able to work with these. - -### MODBUS - -MODBUS is more difficult for us than ASCII protocols but we can deal with this. - -### Connection Hardware - -Use “standard”, easily maintainable and available connection hardware where possible, so no unusual or bespoke sockets, cables or adapters preferred. - -## Protocol - -### 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 (``, `/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 similar to the following: - -``` -Driver to device: -temp? -(HEX: 74 65 6D 70 3F 0D 0A) - -Device to driver: -temp=30.5 -(HEX: 74 65 6D 70 3D 33 30 2E 35 0D 0A) -``` - -### Replies - -All commands to a device 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 an "ACK" or "OK" or similar response. Commands which are invalid or rejected could return a "NAK" or "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. diff --git a/doc/iocs/tips_tricks/Some-Design-thoughts-for-a-serial-or-Ethernet-IOC.md b/doc/iocs/tips_tricks/Some-Design-thoughts-for-a-serial-or-Ethernet-IOC.md deleted file mode 100644 index a23ceb6a4..000000000 --- a/doc/iocs/tips_tricks/Some-Design-thoughts-for-a-serial-or-Ethernet-IOC.md +++ /dev/null @@ -1,19 +0,0 @@ -# Design thoughts for a serial or ethernet IOC - -## Serial Devices -Applicable - For IOCS (or any code) which ultimately drives something at the end of a real wire or a fibre where the comms. are very much an end-to-end affair. - -Not applicable - Some IOCS are to drive things in crates (with hardware slots interrupt lines etc.) this is not about these, also it is not about things that communicate with other bits of manufacturers code (unless this ultimately ends up driving a serial device). - -## Different models for device communication -There are generally two sorts of "serial" devices. - -Those that "chatter" to the computer regardless of whether you talk to them, for those an IOC should treat this chatter as a heartbeat (i.e. timeout and report a comms. error if it doesn't receive what it should within a time). We’ve generally not preferred these sort of comms. (if we have a choice) because they can be a bit awkward to program and are by definition asynchronous with the code talking to them (unfortunately, hardware people often quite like these). - -Alternatively, there are "obedient" devices which only speak when they are spoken to. These must be polled because this is the only way we will know they still are working. In fact, they must really be polled so as to return at least one data value or response packet. Devices which accept silent commands need to checked for data coming back (one wire may not be connected). The rate of polling for data can then be set lower than this (or on demand) if values are not needed very often. An IOC is simplified if heartbeat and data needs are satisfied at the same rate which is normal. For "chatterers" it may be possible to alter the rate of chatter with a device command. - -As far as I can think, this will apply to any device connected to any simple serial "bus" RS232, Ethernet, MODBUS etc. There is a point to be made that between two bits of code on a local system, polling is generally a poor idea (software should use events/interrupts). When talking to real hardware without its own interrupt lines, it is essential. - -The network load of polling is generally very low for real RS232 speeds even at 115Kb (the CPU load of over-polling serial calls might be higher though). On the Ethernet, saturation of an Ethernet link is slightly possible, but as long as the device is fairly dumb and one waits for a reply, the chances of a very tight loop are quite low (I would always put in a delay though). - -Just some thoughts as you continue into the design of your IOC. diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt index 16f1e50e0..a8b8b4e35 100644 --- a/doc/spelling_wordlist.txt +++ b/doc/spelling_wordlist.txt @@ -161,6 +161,7 @@ Culham customisable cxx Cybaman +cybersecurity cygwin DAC DAE @@ -278,6 +279,7 @@ galilmul galils Galvano Gamry +gaussmeters gazcell gb GC'd