Emulating Devices

Wiki > The Backend System > IOCs > Emulating devices

Introduction

So you've created an IOC to talk to a device, and you want to test it: just borrow an actual piece of hardware and test with that. What if that's not possible?

The only way to know an IOC will work with an actual device is to use an actual device.

However, we can try and get as close as possible at the development stage. We also might want to make minor changes to an IOC we know that works without all the effort of tracking down an actual piece of hardware. The above principle still applies, but we can still take steps to improve our odds.

Our emulators are written within the Lewis framework developed at ESS. The purpose of this page is not to replicate the full Lewis documentation, which can be found here, but to give quick pointers to common actions and describe how it all fits within IBEX.

Note: we initially wrote a few emulators using the basic framework introduced at CLF. Documentation for that framework can be found here until we decide to retire it.

Get the framework

Lewis is included as an installed module in genie_python.

Set up a new emulator

1. Create a subdirectory for your new emulator under support/DeviceEmulator/master/lewis_emulators/.
2. Documentation for how to write a Lewis emulator can be found here, and you can refer to the examples in the Lewis library (i.e. C:\Instrument\Apps\Python\libs\site-packages\lewis\devices and ...\examples).
3. NOTE: the simple examples simple_device and example_motor have all the code in a single __init__.py file, but we should stick to a consistent tidy structure like that of the linkam_t95 emulator, i.e. with separate files for the device itself, its states (if it's a state machine), and its interfaces.
4. Don't forget to add __init__.py files in all of your folders!
5. At the time of writing, the Lewis StreamAdapter.handle_error() method does nothing. Please make sure your interface class deriving from StreamAdapter prints the content of the error, which makes it easier to understand what's going on (see for example the iris_cryo_valve emulator).

Run the emulator

To run from the command line, use

lewis -p stream -a C:\Instrument\Apps\EPICS\support\DeviceEmulator\master -k lewis_emulators iris_cryo_valve -- --bind-address localhost --port 57677

where we have picked port 57677 (see Lewis's doc for defaults). Note that the lewis executable is located in C:\Instrument\Apps\Python\Scripts, at time of writing we don't add the directory to our standard EPICS environment PATH variables, so you may need to provide a fully qualified file path.

Congratulations! Your emulator is now running. You can test it by connecting to it via a telnet client such as PuTTY (please see the troubleshooting note below).

The backdoor

It's possible to modify the device's state on the fly as it's running in case you want to push it into a specific state (as a backdoor). The backdoor can also be used to alter simulation paramters, e.g. to simulate a loss of connection or speed up the simulation time. Full documentation can be found here for device access and here for simulation access.

The host and port for the backdoor are specified in the -r argument at startup:

lewis -p stream -r 127.0.0.1:10000 -a C:\Instrument\Apps\EPICS\support\DeviceEmulator\master -k lewis_emulators iris_cryo_valve -- --bind-address localhost --port 57677

NOTE: at the time of writing, you can't type localhost for the -r argumen.

The backdoor can be operated either via the command line through lewis-control or can be scripted, as described in the Lewis documentation.

NOTE: The simulation command disconnect_device seems to simulate the device not responding to the port, which is different from a lost connection: the IOC reports No reply from device within xxx ms. When the emulator is actually stopped, with the simulation stop command, the IOC detects that there is really no connection and reports Can't connect to localhost:<port>.

Connecting your IOC

So, we've got our emulator running, now we need to get our IOC talking to it. Go to st.cmd for your IOC and find where the serial port communication is configured, for instance:

drvAsynSerialPortConfigure("$(DEVICE)", "$(PORT)", 0, 0, 0, 0)
asynSetOption("$(DEVICE)", -1, "baud", "$(BAUD=9600)")
asynSetOption("$(DEVICE)", -1, "bits", "$(BITS=8)")
asynSetOption("$(DEVICE)", -1, "parity", "$(PARITY=none)")
asynSetOption("$(DEVICE)", -1, "stop", "$(STOP=1)")
asynOctetSetInputEos("$(DEVICE)", -1, "$(OEOS=\n)")

Replace it with a macro defined by IBEX backend which comments it out when set

$(IFNOTDEVSIM) drvAsynSerialPortConfigure("$(DEVICE)", "$(PORT)", 0, 0, 0, 0)
$(IFNOTDEVSIM) asynSetOption("$(DEVICE)", -1, "baud", "$(BAUD=9600)")
$(IFNOTDEVSIM) asynSetOption("$(DEVICE)", -1, "bits", "$(BITS=8)")
$(IFNOTDEVSIM) asynSetOption("$(DEVICE)", -1, "parity", "$(PARITY=none)")
$(IFNOTDEVSIM) asynSetOption("$(DEVICE)", -1, "stop", "$(STOP=1)")
$(IFNOTDEVSIM) asynOctetSetInputEos("$(DEVICE)", -1, "$(OEOS=\n)")

and then add

$(IFDEVSIM) drvAsynIPPortConfigure("$(DEVICE)", "localhost:[PORT]")

where again [PORT] is replaced with the port number we're running on. We could factor this out into a non-hard-coded macro in globals.txt but a lot of the time it's easier just to do it here.

Enabling and disabling IFDEVSIM can be done via the IBEX GUI if the whole IBEX system is running. Otherwise, if you are just testing one IOC then it can be enabled in the globals.txt file in one's configuration folder (C:\Instrument\Settings\config\NDWXXX\configurations\globals.txt) like so:

JULABO_01__DEVSIM=1

GO!

Start the IOC as normal by running runIOC.bat st.cmd. If everything's hooked up correctly, you should see a Client connected message in the emulated device console. At the time of writing, Lewis emulators don't echo requests from the client, but this should be implemented soon. With any luck, the data from the emulator should then be updated to your PVs.

Troubleshooting

We haven't done much with emulators yet, so not much has gone wrong, so please add to this section as you can.

• Telnet server is running, but is not receiving any data from the IOC: Is your st.cmd correct? Try removing the 4 < $(IOCSTARTUP)... lines, and the drvAsyn{IP,Serial}PortConfigure lines and run runIOC.bat st.cmd. Are you getting any error or warning messages? Sort those out first.
• When connecting to a Lewis emulator via a Telnet client such as PuTTY, beware that Telnet uses \r\n as a terminator. If your emulator interface has a different one (like for the linkam_t95), the protocol won't work. You could temporarily use the Telnet terminator instead. Note also that PuTTY sends some extra characters at the start of the communication, so the very first command you send probably won't work.