{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Lesson 1: scaler and count\n",
    "\n",
    "In this lesson, we'll work with a scaler (devices that counts pulses emitted from one or more pulse-emitting ***detector*** electronics) and use this to make a first lesson in using [Bluesky](https://blueskyproject.io/bluesky/) and [related tools](https://blueskyproject.io/).\n",
    "\n",
    "First, we'll show how to start a Jupyter notebook.  Next, we'll connect with an EPICS scaler (using [ophyd](https://blueskyproject.io/ophyd/)), and then use the Bluesky software to count from the scaler.\n",
    "\n",
    "\n",
    "**note**:  This tutorial expects to find an EPICS IOC on the local network configured as a synApps [xxx](https://github.com/epics-modules/xxx) IOC with prefix `sky:`.  A docker container is available to provide this IOC.  See this URL for instructions:  https://github.com/prjemian/epics-docker/blob/master/n3_synApps/README.md\n",
    "\n",
    "\n",
    "## Starting this session in a Jupyter notebook\n",
    "\n",
    "This session was started from the linux command line:\n",
    "\n",
    "```\n",
    "jemian@otz ~ $ source /APSshare/anaconda3/Bluesky/bin/activate \n",
    "(base) jemian@otz ~ $ jupyter-notebook \n",
    "```\n",
    "\n",
    "This command produced the following console output and then started my default web browser with a one-time-token-authenticated connection to the Jupyter Notebook server (still running in the console):\n",
    "\n",
    "```\n",
    "[I 15:16:57.546 NotebookApp] Serving notebooks from local directory: /home/oxygen18/JEMIAN\n",
    "[I 15:16:57.546 NotebookApp] 0 active kernels\n",
    "[I 15:16:57.546 NotebookApp] The Jupyter Notebook is running at:\n",
    "[I 15:16:57.546 NotebookApp] http://localhost:8888/?token=e6a7584762c731a7c64f8f71246b3e616d779f7b4852c9d9\n",
    "[I 15:16:57.546 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).\n",
    "[C 15:16:57.547 NotebookApp] \n",
    "    \n",
    "    Copy/paste this URL into your browser when you connect for the first time,\n",
    "    to login with a token:\n",
    "        http://localhost:8888/?token=e6a7584762c731a7c64f8f71246b3e616d779f7b4852c9d9\n",
    "[I 15:17:00.863 NotebookApp] Accepting one-time-token-authenticated connection from ::1\n",
    "```\n",
    "\n",
    "Next, found the **New** drop-down menu button (top right, below the **Lougout** button) and selected *Python 3* to start a new notebook page using a Python 3 shell (the only kind available here).\n",
    "\n",
    "Finally, from the **File** menu in the jupyter notebook (in the browser), selected *Rename ...* to save the *Untitled* notebook with the name *lesson1* (default extension is `.ipynb`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connect an EPICS scaler\n",
    "\n",
    "I have a synApps (v6.1) *XXX*-style IOC with the prefix `sky:`.  It has a [scaler](https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/std/R3-4-1/documentation/scalerRecord.html), 16 soft channel [motor](https://github.com/epics-modules/motor)s, and some other support we'll ignore in lesson 1.\n",
    "\n",
    "The scaler is `sky:scaler1`.  We'll connect to that first.  To make the connection, we need to import the [ScalerCH](https://blueskyproject.io/ophyd/builtin-devices.html#epicsscaler) device from the [ophyd.scaler](https://blueskyproject.io/ophyd/) library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ophyd.scaler import ScalerCH"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can create the scaler object we'll use as a detector."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler = ScalerCH(\"sky:scaler1\", name=\"scaler\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a script or program, we should wait for that to connect with EPICS."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.wait_for_connection()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's test that connection by asking the scaler to read its values from EPICS."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.read()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the ophyd `ScalerCH` object shows data for only the channels with names defined in EPICS.  Except for one channel (probably a bug in the `ScalerCH` code).  To fix that, we'll load another support library.  (Loading additional support as we need it will be a common theme in these lessons.  Rather than loading all the libraries first, as is common in python code files, we'll load support code as the need arises.)\n",
    "\n",
    "The new support code is `use_EPICS_scaler_channels` from [apstools.devices](https://bcda-aps.github.io/apstools/latest/api/_devices.html#apstools.devices.scaler_support.use_EPICS_scaler_channels)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our scaler only has a few channels in use (that is, channels where the name of the channel has been specified in the GUI screen).  Let's focus on just those channels.\n",
    "\n",
    "To read just the *named* channels, we call the scaler's `select_channels()` method and name the scaler channels we wish to see.  To see all channels with names defined in EPICS, use `None` as shown:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.select_channels(None)\n",
    "scaler.read()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to change the name fields on any of the scaler channels from the command line, follow this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.channels.chan04.chname.put(\"scint\")\n",
    "scaler.channels.chan07.chname.put(\"roi1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, update the `scaler` object for these channels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.select_channels(None)\n",
    "scaler.read()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get, then Set the count time on the scaler\n",
    "\n",
    "The preset counting time (`.TP`) is one of the many fields of the EPICS scaler record.  It is available as `scaler.preset_time` in this scaler object.  We can inspect this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.preset_time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since `scaler.preset_time` is an [EpicsSignal](https://github.com/NSLS-II/ophyd/blob/master/ophyd/signal.py#L647), ([Signal](https://blueskyproject.io/ophyd/signals.html) is a fundamental ophyd structure), we print its `.value`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.preset_time.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set the scaler to count for 1.5 seconds once it is told to count.  We'll count it next."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.preset_time.put(1.5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note, to tell the scaler to count, we put a 1 to its `.CNT` field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.count.put(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, read the scaler again.  This scaler is not very interesting since it is not connected to any hardware.  But, the timestamps have changed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaler.read()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use Bluesky to count the scaler\n",
    "\n",
    "So far, we have used ophyd to talk with the EPICS scaler.  Let's start to use Bluesky.  We need to load support to start the Bluesky [*RunEngine*](https://blueskyproject.io/bluesky/tutorial.html#the-runengine).  For now, we'll use the most basic configuration (does not save data anywhere).  \n",
    "\n",
    "The job of the RunEngine is to process command messages (our data acquisition commands) and to output documents (the data to be acquired).  Initially, we'll use predefined data acquisition sequences (called [*plans*](https://blueskyproject.io/bluesky/plans.html)) and ignore the [documents](https://blueskyproject.io/bluesky/documents.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bluesky import RunEngine\n",
    "RE = RunEngine({})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we'll load a library with many [predefined plans](https://blueskyproject.io/bluesky/plans.html#summary).  The first plan we want to use is [count()](https://blueskyproject.io/bluesky/generated/bluesky.plans.count.html#bluesky.plans.count).  By the way, we'll use a python feature to rename `bluesky.plans` to the shorter `bp` since it will be used a lot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import bluesky.plans as bp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can count the `scaler` by submitting the `bp.count` plan to the RunEngine instance `RE`.  The `bp.count()` plan takes one argument, a *list* of countable objects (just in case you want to count more than one detector at the same time).  Our list has only one object: `scaler`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RE(bp.count([scaler]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The final result from submitting a plan to the RunEngine is an identifier of the sequence of documents.  Since we did not capture that sequence, we can't view it or access it in any way.  Let's *fix* that next."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Report about the documents emitted from the RunEngine\n",
    "\n",
    "To display information about the documents emitted from the RunEngine, we need to make a function that will receive the documents.  \n",
    "\n",
    "In Bluesky terms, this type of function is a *callback*.  It takes two arguments.  The first argument is a `str` that tells what kind of document is coming, the second is a python dictionary with the document's contents.  We'll start by printing summary information.  We then submit the plan again with the name of our callback function as a second argument (not to `bp.count` but as a second argument to `RE()`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def myCallbackBrief(key, doc):\n",
    "    print(key, len(doc))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RE(bp.count([scaler]), myCallbackBrief)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, there were four documents.  See https://blueskyproject.io/bluesky/documents.html for the details of each.  Let's extend our callback to print the details of each."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def myCallback(key, doc):\n",
    "    print(key, len(doc))\n",
    "    for k, v in doc.items():\n",
    "        print(\"\\t\", k, v)\n",
    "    print(\"~~~~~~~~~~~~~~~~~\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RE(bp.count([scaler]), myCallback)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the details, we see more of what is happening.  \n",
    "\n",
    "The first document is a `start` and it says what is happening and how it will be identified.  The identifier (named `uid`) is a [UUID](https://docs.python.org/3.6/library/uuid.html) (specifically, a [uuid4](https://docs.python.org/3.6/library/uuid.html#uuid.uuid4)).  This looks tedious and random.  The one good thing is that these are unique and often can be referred to by the first few characters (6-8 are enough to be *probably* unique).  The `uid` from the `start` document is what the RunEngine reports when the scan stops.\n",
    "\n",
    "The second document is a `descriptor` and it says what, exactly, will be measured.  It also includes a reference to `start`'s `uid`.  We can follow the chain back to `start` this way.\n",
    "\n",
    "The third document is an `event` and it provides the data reading when the scaler was counted.  The data is read according to the `descriptor` document (just actual values for the *named* channels).\n",
    "\n",
    "The last document is a `stop` document that describes how things ended.  It also says there was only one stream of event documents named *primary*.\n",
    "\n",
    "Let's repeat that plan, this time asking to `count` the scaler three times.  This is the `num=3` addition to the call to `bp.count()`.  What's tricky now is keeping track of the parentheses and square braces."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RE(bp.count([scaler], num=3), myCallback)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mostly the same but now there are three `event` documents."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "We'll show this code as a python program:\n",
    "\n",
    "```\n",
    "#!/usr/bin/env python\n",
    "\n",
    "\"lesson 1: EpicsScaler\"\n",
    "\n",
    "from ophyd.scaler import ScalerCH\n",
    "from bluesky import RunEngine\n",
    "import bluesky.plans as bp\n",
    "from apstools.devices import use_EPICS_scaler_channels\n",
    "\n",
    "\n",
    "def myCallback(key, doc):\n",
    "    print(key, len(doc))\n",
    "    for k, v in doc.items():\n",
    "        print(\"\\t\", k, v)\n",
    "    print(\"~~~~~~~~~~~~~~~~~\")\n",
    "\n",
    "\n",
    "RE = RunEngine({})\n",
    "\n",
    "scaler = ScalerCH(\"sky:scaler1\", name=\"scaler\")\n",
    "scaler.preset_time.put(1.5)\n",
    "print(scaler.preset_time.value)\n",
    "\n",
    "scaler.channels.chan04.chname.put(\"scint\")\n",
    "scaler.channels.chan07.chname.put(\"roi1\")\n",
    "\n",
    "scaler.match_names()\n",
    "use_EPICS_scaler_channels(scaler)\n",
    "print(scaler.read())\n",
    "print(RE(bp.count([scaler], num=3), myCallback))\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quit the jupyter notebook\n",
    "\n",
    "* Save the \"lesson1\" page if you wish.\n",
    "* Press the **Logout** button in the upper right corner of \"lesson1\" and close the page.\n",
    "* Press the **Logout** button in the upper right corner of \"Home\" and close the page.\n",
    "* Type Control-C (^C) twice in the jupyter-notebook console to kill the server."
   ]
  }
 ],
 "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}