Merge branch 'main' into 215-home-page---more-content

CHANGES.rst

@@ -43,8 +43,10 @@ New Features
 Maintenance
 ------------
 
+* Add 'Hello, World!' test to installation checklist.
 * Drop the (unused now) *stdlogpj* package for configuring Python's *logging*.
 * Environment for bluesky_2024_1.
+* Updates (learned from 2-ID) for new installations.
 * Various documentation updates.
 
 

bluesky/instrument/epics_signal_config.py

@@ -9,16 +9,16 @@
 
 import logging
 
+from ophyd.signal import EpicsSignalBase
+
 logger = logging.getLogger(__name__)
 logger.info(__file__)
 
-from . import iconfig
-from ophyd.signal import EpicsSignal
-from ophyd.signal import EpicsSignalBase
+from . import iconfig  # noqa
 
 
-# set default timeout for all EpicsSignal connections & communications
-# always first, before ANY ophyd EPICS-based signals are created
+# Set default timeout for all EpicsSignal connections & communications.
+# Always call first, before ANY ophyd EPICS-based signals are created.
 TIMEOUT = 60
 if not EpicsSignalBase._EpicsSignalBase__any_instantiated:
     EpicsSignalBase.set_defaults(
@@ -33,25 +33,32 @@
     logger.info("Using RunEngine metadata for scan_id")
     scan_id_epics = None
 else:
+    from ophyd.signal import EpicsSignal
+
     logger.info("Using EPICS PV %s for scan_id", pvname)
+    # Must not call _before_ default timeouts are set.
     scan_id_epics = EpicsSignal(pvname, name="scan_id_epics")
 
 
 def epics_scan_id_source(*args, **kwargs):
     """
     Callback function for RunEngine.  Returns *next* scan_id to be used.
 
+    * Ignore args and kwargs.
     * Get current scan_id from PV.
     * Apply lower limit of zero.
     * Increment.
     * Set PV with new value.
     * Return new value.
+
+    Exception will be raised if PV is not connected when next
+    ``bluesky.plan_stubs.open_run()`` is called.
     """
     if scan_id_epics is None:
         raise RuntimeError(
             "epics_scan_id_source() called when"
             " 'RUN_ENGINE_SCAN_ID_PV' is"
-            "undefined in 'iconfig.yml' file."
+            " undefined in 'iconfig.yml' file."
         )
     new_scan_id = max(scan_id_epics.get(), 0) + 1
     scan_id_epics.put(new_scan_id)

bluesky/instrument/framework/initialize.py

@@ -47,7 +47,7 @@
 def get_md_path():
     path = iconfig.get("RUNENGINE_MD_PATH")
     if path is None:
-        path = pathlib.Path.home() / "Bluesky_RunEngine_md"
+        path = pathlib.Path.home() / ".config" / "Bluesky_RunEngine_md"
     else:
         path = pathlib.Path(path)
     logger.info("RunEngine metadata saved in directory: %s", str(path))
@@ -109,47 +109,14 @@ def get_md_path():
 # diagnostics
 # RE.msg_hook = ts_msg_hook
 
-# set default timeout for all EpicsSignal connections & communications
-TIMEOUT = 60
-if not EpicsSignalBase._EpicsSignalBase__any_instantiated:
-    EpicsSignalBase.set_defaults(
-        auto_monitor=True,
-        timeout=iconfig.get("PV_READ_TIMEOUT", TIMEOUT),
-        write_timeout=iconfig.get("PV_WRITE_TIMEOUT", TIMEOUT),
-        connection_timeout=iconfig.get("PV_CONNECTION_TIMEOUT", TIMEOUT),
-    )
-
-# Create a registry of ophyd devices
-registry = Registry(auto_register=True)
-
-_pv = iconfig.get("RUN_ENGINE_SCAN_ID_PV")
-if _pv is None:
-    logger.info("Using RunEngine metadata for scan_id")
-else:
-    from ophyd import EpicsSignal
-
-    logger.info("Using EPICS PV %s for scan_id", _pv)
-    scan_id_epics = EpicsSignal(_pv, name="scan_id_epics")
-
-    def epics_scan_id_source(_md):
-        """
-        Callback function for RunEngine.  Returns *next* scan_id to be used.
-
-        * Ignore metadata dictionary passed as argument.
-        * Get current scan_id from PV.
-        * Apply lower limit of zero.
-        * Increment (so that scan_id numbering starts from 1).
-        * Set PV with new value.
-        * Return new value.
-
-        Exception will be raised if PV is not connected when next
-        ``bps.open_run()`` is called.
-        """
-        new_scan_id = max(scan_id_epics.get(), 0) + 1
-        scan_id_epics.put(new_scan_id)
-        return new_scan_id
+if iconfig.get("RUN_ENGINE_SCAN_ID_PV") is not None:
+    from ..epics_signal_config import epics_scan_id_source
+    from ..epics_signal_config import scan_id_epics
 
     # tell RunEngine to use the EPICS PV to provide the scan_id.
     RE.scan_id_source = epics_scan_id_source
     scan_id_epics.wait_for_connection()
     RE.md["scan_id"] = scan_id_epics.get()
+
+# Create a registry of ophyd devices
+registry = Registry(auto_register=True)

bluesky/instrument/iconfig.yml

@@ -41,7 +41,7 @@ WRITE_SPEC_DATA_FILES: true
 
 # Directory to "autosave" the RE.md dictionary (uses PersistentDict)
 # Uncomment and modify to change from the default.
-# RUNENGINE_MD_PATH: /home/USERNAME/Bluesky_RunEngine_md
+# RUNENGINE_MD_PATH: /home/USERNAME/.config/Bluesky_RunEngine_md
 
 # override default control layer for ophyd
 # if undefined, defaults to PyEpics

bluesky/user/quick_hello.py

@@ -1,5 +1,5 @@
 """
-Hello, World! demo for bluesky-queueserver testing.
+Demo 'Hello, World!' for testing, including bluesky-queueserver.
 
 EXAMPLE::
 
@@ -41,4 +41,4 @@ class HelloDevice(Device):
 
 def hello_world():
     """Simple bluesky plan for demonstrating Hello, World!."""
-    yield from bp.count([hello_device], md=dict(title="test QS"))
+    yield from bp.count([hello_device], md=dict(subtitle="test Bluesky"))

docs/source/instrument/_install_new_instrument.rst

@@ -17,6 +17,7 @@ to the documentation for each step.
 #. `create conda environment <https://bcda-aps.github.io/bluesky_training/reference/_create_conda_env.html>`__
 #. `configure IPython profile startup <https://bcda-aps.github.io/bluesky_training/reference/_ipython.html>`__
 #. `configure bash with environment variable and alias <https://bcda-aps.github.io/bluesky_training/reference/_create_conda_env.html#create-an-alias-to-activate-the-bluesky-environment>`__
+#. Verify the installation by running the `Hello, World! tutorial. <https://bcda-aps.github.io/bluesky_training/tutor/hello_world.html>`__
 #. create soft link:  ``ln -s ${HOME}/bluesky/blueskyStarter.sh ~/bin/``
 #. Assign a MongoDB catalog for databroker: `instructions for BCDA <https://git.aps.anl.gov/bcda/bluesky-catalogs/-/blob/master/README.md>`__
 #. `databroker catalog configuration <https://bcda-aps.github.io/bluesky_training/instrument/_configure_databroker.html#setup-your-databroker-catalog-configuration>`__
@@ -346,8 +347,6 @@ Note that the bluesky team recommends GitHub. (Why is that? See section
          </ul>
 
 
-
-
 The next steps are common to both web-based repositories (GitHub and GitLab):
 
 - copy the remote `repository URL <https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#choosing-a-url-for-your-remote-repository>`_, for example,

docs/source/instrument/_test_new_instrument.md

@@ -10,7 +10,9 @@ Visit <a href=https://bcda-aps.github.io/bluesky_training/instrument/_install_ne
 
 <details>
 <summary>How to test my Bluesky installation?</summary>
-Visit <a href=https://bcda-aps.github.io/bluesky_training/tutor/_hello_word.html> Hello World</a>.
+Test (verify) the installation by running the <a
+href=https://bcda-aps.github.io/bluesky_training/tutor/hello_world.html>Hello, World!</a>
+tutorial.
 </details>
 
 <br>