Epics Signal.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Epics Signal\n",
    "\n",
    "In this notebook you will:\n",
    "\n",
    "* Connect to some simulated hardware using `EpicsSignal`\n",
    "* Explore the `EpicsSignal` interface.\n",
    "\n",
    "Recommend Prerequisites:\n",
    "\n",
    "* [Hello Python and Jupyter](./Hello%20Python%20and%20Jupyter.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simulated Hardware\n",
    "Below, we will connect to EPICS IOC(s) controlling simulated hardware in lieu of actual motors, detectors. The IOCs should already be running in the background. Run this command to verify that they are running: it should produce output with RUNNING on each line. In the event of a problem, edit this command to replace `status` with `restart all` and run again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!supervisorctl -c supervisor/supervisord.conf status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hello, EpicsSignal\n",
    "\n",
    "An `EpicsSignal` is ophyd's representation of a single EPICS channel or a pair of channels, one readable and one writeable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ophyd import EpicsSignal"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = EpicsSignal('simple:A', name='a')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.name  # human-friendly label, which will be encoded in 'documents' emitted by bluesky"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.wait_for_connection()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.connected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.get()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.put(3)\n",
    "a.get()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.read()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.describe()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise\n",
    "\n",
    "Instaniate an `EpicsSignal` that is connect to some made-up PV that does not exist, as in:\n",
    "\n",
    "```py\n",
    "broken = EpicsSignal('THIS_IS_NOT_A_THING', name='broken')\n",
    "```\n",
    "\n",
    "What does `broken.connected` do? What about `broken.wait_for_connection()`? And `broken.read()`?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Read-only"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `EpicsSignalRO` represents a read-only signal. It can't be put to."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ophyd import EpicsSignalRO\n",
    "\n",
    "x = EpicsSignalRO('random_walk:x', name='x')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try putting a value to `x` It will raise a `ReadOnlyError`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A read&ndash;write pair\n",
    "\n",
    "Sometimes the readback and setpoint are different PVs. We can group them into one `EpicsSignal`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp = EpicsSignal('thermo:I', write_pv='thermo:SP', name='temp')\n",
    "temp"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp.get()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp.put(105)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This IOC simulates the oscillations of a temperature controller and will take some time to settle to the desired value. Executing the cell above several times will return varied values. This illustrates the importance of tracking \"done\"-ness, which we will address in the tutorial on Devices."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More on `status` later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Subscribe\n",
    "\n",
    "The actions on an EPICS channel are:\n",
    "\n",
    "* read (get)\n",
    "* write (put)\n",
    "* monitor (subscribe, \"event add\")\n",
    "\n",
    "To subscribe is to say, \"Send me updates asynchronously whenever the value changes.\" To process these changes, we write a function that will be called each time a new value arrives and register than function with the Signal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = EpicsSignal('random_walk:x', name='x')\n",
    "\n",
    "def callback(value, old_value, **kwargs):\n",
    "    print(f\"Value changed from {old_value} to {value}.\")\n",
    "    \n",
    "token = x.subscribe(callback)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "token  # We can use this to unsubscribe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.unsubscribe(token)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise\n",
    "\n",
    "Define and subscribe a callback that prints \"+\" when the value changes in the positive direction and \"-\" when it changes in the negative direction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load solutions/callback_print_sign.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `set` is `put` like with a way to know when the action is complete.\n",
    "\n",
    "`put` is the low-level method that actually communicates with hardware. `set` is a higher-level method that calls `put` and then tracks when the action initiated by `put` has completed, either by using Channel Access \"put completion\" or by polling the signal on a background thread."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp.tolerance = 0.05"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = temp.set(273)\n",
    "status.add_callback(lambda *args, **kwargs: print('done!'))\n",
    "# Wait several seconds and then 'done!' will be printed by a background thread."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More about `status` and exactly what is happening here in the notebook on `Device`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing the PV name for debugging\n",
    "\n",
    "When we have *many* signals in play, it can be useful to as a Signal which PV it is connected to (or attempting to connect to)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.pvname  # PV name we gave above"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If ophyd is failing to connect, we can try to isolate the problem by using another Channel Access client like `caget` or `caproto-get`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!caproto-get 'simple:A'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can add verbose output to learn more about which server this is from, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!caproto-get -v 'simple:A'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!caproto-get -vvv 'simple:A'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## So many names\n",
    "\n",
    "In summary, we have:\n",
    "\n",
    "* The `pvname`, an address for machines\n",
    "* The `name`, a label for humans and downstream analysis code that wants `'temperature'` not `'PV:asdfoijefopefpoaewaopivjapoefijaeftep'`.\n",
    "* The name of the variable in Python, the name we use in the code. There could be multiple of these pointing to the same object, as in `a = b = EpicsSignal(...)`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}