initial commit

.gitignore

@@ -0,0 +1,29 @@
+# bluesky-queueserver
+existing_plans_and_devices.yaml
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Microsoft VisualStudio Code Editor
+.vscode/
+
+# log files
+.logs/
+
+# Jupyter notebook checkpoints
+.ipynb_checkpoints/
+
+# filewriter callback output files
+*.h5
+*.dat
+
+# local developer content
+dev_*
+
+# Sphinx build products
+build/
+
+# Macintosh
+.DS_Store

README.md

@@ -0,0 +1,18 @@
+# Bluesky Instrument Template
+
+**Caution**:  If you will use the bluesky queueserver (QS), note that _every_
+Python file in this directory will be executed when QS starts the RunEngine.
+Don't add extra Python files to this directory.  Instead, put them in `user/` or
+somewhere else.
+
+Contains:
+
+description | item(s)
+--- | ---
+Introduction | [`intro2bluesky.md`](https://bcda-aps.github.io/bluesky_training/reference/_intro2bluesky.html)
+IPython console startup | [`console/`](console/README.md)
+Bluesky queueserver support | [introduction](qserver.md), `*qs*`
+Instrument configuration | `instrument/`
+Conda environments | [`environments/`](./environments/README.md)
+Unit tests | [`tests/`](./tests/README.md)
+Documentation | [How-to, examples, tutorials, reference](https://bcda-aps.github.io/bluesky_training)

_run_qs.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+
+# Start the bluesky queueserver.
+
+#--------------------
+# change the program defaults here
+# CONDA: pre-defined in GitHub Actions workflow
+export CONDA=${CONDA:-/APSshare/miniconda/x86_64}
+export CONDA_ENVIRONMENT="${BLUESKY_CONDA_ENV:-training_2022}"
+export DATABROKER_CATALOG=${DATABROKER_CATALOG:-training}
+export QS_SERVER_HOST=$(hostname)  # or host (that passes $(hostname) test below)
+export QS_UPDATE_PLANS_DEVICES=ENVIRONMENT_OPEN
+export QS_USER_GROUP_PERMISSIONS_FILE="./user_group_permissions.yaml"
+export QS_USER_GROUP_PERMISSIONS_RELOAD=ON_STARTUP
+
+# REDIS_ADDR is __always__ localhost.
+# Override if it is not, but you may encounter access issues.  YOYO.
+export REDIS_ADDR=localhost
+#--------------------
+
+# QS and redis must be on the same workstation
+if [ "$(hostname)" != "${QS_SERVER_HOST}" ]; then
+    echo "Must run queueserver on ${QS_SERVER_HOST}.  This is $(hostname)"
+    exit 1
+fi
+
+SHELL_SCRIPT_NAME=${BASH_SOURCE:-${0}}
+if [ -z "$STARTUP_DIR" ] ; then
+    # If no startup dir is specified, use the directory with this script
+    export STARTUP_DIR=$(dirname "${SHELL_SCRIPT_NAME}")
+fi
+
+# activate conda command, if needed
+if [ ! -f "${CONDA_EXE}" ]; then
+    CONDA_ROOTS="${CONDA}"  # In GitHub Actions workflow: (miniconda)
+    CONDA_ROOTS+=" /APSshare/miniconda/x86_64"
+    CONDA_ROOTS+=" /opt/miniconda3"
+    for root in ${CONDA_ROOTS}; do
+        if [ -d "${root}" ] && [ -f "${root}/etc/profile.d/conda.sh" ]; then
+            # Found a match!
+            source "${root}/etc/profile.d/conda.sh"
+            break
+        fi
+    done
+fi
+
+# In GitHub Actions workflow,
+# $ENV_NAME is an environment variable naming the conda environment to be used
+if [ -z "${ENV_NAME}" ] ; then
+    ENV_NAME="${CONDA_ENVIRONMENT}"
+fi
+
+# echo "conda env list = $(conda env list)"
+
+conda activate "${ENV_NAME}"
+
+# #--------------------
+# echo "Environment: $(env | sort)"
+# echo "------"
+# echo "CONDA_ENVIRONMENT=${CONDA_ENVIRONMENT}"
+# echo "CONDA=${CONDA}"
+# echo "DATABROKER_CATALOG=${DATABROKER_CATALOG}"
+# echo "QS_SERVER_HOST=${QS_SERVER_HOST}"
+# echo "QS_UPDATE_PLANS_DEVICES=${QS_UPDATE_PLANS_DEVICES}"
+# echo "QS_USER_GROUP_PERMISSIONS_FILE=${QS_USER_GROUP_PERMISSIONS_FILE}"
+# echo "QS_USER_GROUP_PERMISSIONS_RELOAD=${QS_USER_GROUP_PERMISSIONS_RELOAD}"
+# echo "REDIS_ADDR=${REDIS_ADDR}"
+# echo "SHELL_SCRIPT_NAME=${SHELL_SCRIPT_NAME}"
+# echo "STARTUP_DIR=${STARTUP_DIR}"
+# #--------------------
+
+# Start the bluesky queueserver (QS)
+start-re-manager \
+    --redis-addr "${REDIS_ADDR}" \
+    --startup-dir "${STARTUP_DIR}" \
+    --update-existing-plans-devices "${QS_UPDATE_PLANS_DEVICES}" \
+    --user-group-permissions "${QS_USER_GROUP_PERMISSIONS_FILE}" \
+    --user-group-permissions-reload "${QS_USER_GROUP_PERMISSIONS_RELOAD}" \
+    --zmq-publish-console ON \
+    --keep-re

blueskyStarter.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+
+# Start a bluesky session in IPython console (default) or Jupyter notebook GUI.
+
+# Get the Python environment name.
+# define fallback if BLUESKY_CONDA_ENV is not found
+DEFAULT_ENV=bluesky_2023_3
+export ENV_NAME="${BLUESKY_CONDA_ENV:-${DEFAULT_ENV}}"
+export IPYTHON_PROFILE=bluesky
+export IPYTHONDIR="${HOME}/.ipython-bluesky"
+
+
+pick () {  # activate ENV_NAME (using conda) from given arg
+
+    ARG="${1}"
+
+    if [ "${ARG}" == "" ]; then
+        return 1
+    fi
+
+    if [ -d "${ARG}" ]; then
+        pick "${ARG}/bin/conda"
+
+        if [ "${cmd_base}" != "" ]; then
+            return 0
+        fi
+        return 1
+    fi
+
+    CMD=$(which ${ARG})  # as executable command
+    if [ "${CMD}" == "" ]; then
+        return 1
+    fi
+
+    if [ -x "${CMD}" ]; then
+        match_env_name=$( \
+            ${CMD} env list \
+            | grep "^[ ]*${ENV_NAME} " \
+            | awk '{print $1}' \
+        )
+        if [ "${match_env_name}" != "" ]; then
+            # found the requested environment name
+            cmd_base=$(basename "${CMD}")
+            case "${cmd_base}" in
+                conda)
+                    source "$(dirname ${CMD})/activate" base
+                    "${cmd_base}" activate "${ENV_NAME}"
+                    return 0
+                    ;;
+                *)
+                    return 1
+                    ;;
+            esac
+        fi
+    fi
+
+    return 2
+}
+
+
+pick_environment_executable () {  # Activate the environment
+    # Pick the first "hit"
+    pick "/APSshare/miniconda/x86_64" \
+    || pick "${HOME}" \
+    || pick "conda" \
+    || pick "/opt/miniconda3" \
+    || pick "${HOME}/Apps/miniconda" \
+    || pick "${HOME}/Apps/anaconda"
+
+    echo "==> CONDA_PREFIX=${CONDA_PREFIX}"
+
+    if [ "${cmd_base}" != "" ]; then
+        echo "$(which python) -- $(python --version)"
+        return 0
+    fi
+
+    echo "Could not activate environment: '${ENV_NAME}'"
+    return 3
+}
+
+
+console_session () {
+    export OPTIONS=""
+    export OPTIONS="${OPTIONS} --profile=${IPYTHON_PROFILE}"
+    export OPTIONS="${OPTIONS} --ipython-dir=${IPYTHONDIR}"
+    export OPTIONS="${OPTIONS} --IPCompleter.use_jedi=False"
+    export OPTIONS="${OPTIONS} --InteractiveShellApp.hide_initial_ns=False"
+
+    pick_environment_executable
+
+    ipython ${OPTIONS}
+}
+
+lab_server () {
+    export OPTIONS=""
+    # export OPTIONS="${OPTIONS} --no-browser"
+    export OPTIONS="${OPTIONS} --ip=${HOST}"
+
+    pick_environment_executable
+
+    python -m ipykernel install --user --name "${ENV_NAME}"
+    jupyter-lab ${OPTIONS}
+}
+
+usage () {
+    echo $"Usage: $0 [console | lab | help]"
+}
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+case $(echo "${1}" | tr '[:upper:]' '[:lower:]') in
+  lab) lab_server  ;;
+  "" | console) console_session  ;;
+  help) usage  ;;
+  *) usage; exit 1
+esac

console/README.md

@@ -0,0 +1,5 @@
+# Bluesky IPython Console Session
+
+Loads the `instrument` [package](https://bcda-aps.github.io/bluesky_training/instrument) for use in an interactive IPython console session (or Jupyter notebook).
+
+Copy or link the `__start_bluesky_instrument__.py` file to the appropriate IPython profile `startup` directory, such as: `~/.ipython-bluesky/profile_bluesky/startup/__start_bluesky_instrument__.py`

console/__start_bluesky_instrument__.py

@@ -0,0 +1,26 @@
+"""
+start bluesky in IPython console session
+"""
+
+# start a Bluesky data collection console session
+from IPython import get_ipython
+import pathlib
+import sys
+
+# find the "bluesky/" directory
+BLUESKY_DIRECTORY = pathlib.Path.home() / "bluesky"
+if not BLUESKY_DIRECTORY.exists():
+    # <training repository directory>
+    BLUESKY_DIRECTORY = pathlib.Path(__file__).absolute().parent.parent.parent
+    BLUESKY_DIRECTORY = BLUESKY_DIRECTORY / "bluesky"
+if not BLUESKY_DIRECTORY.exists():
+    raise FileNotFoundError(
+        f"Cannot find bluesky directory: {BLUESKY_DIRECTORY}"
+    )
+# put bluesky directory on the import path
+sys.path.append(str(BLUESKY_DIRECTORY))
+
+# terse error dumps (Exception tracebacks)
+get_ipython().run_line_magic('xmode', 'Minimal')
+
+from instrument.collection import *

environments/README.md

@@ -0,0 +1,37 @@
+# Environment Definitions
+
+This directory contains the [YAML](https://yaml.org) files that define the
+package requirements (and possibly the acceptable versions) for a conda
+environment.
+
+## YAML files
+
+This directory contains the master source for these YAML files.
+The repository is: https://github.com/BCDA-APS/bluesky_training/
+
+version | file
+--- | ---
+2023-3 (latest) | [`environment_2023_3.yml`](./environment_2023_3.yml)
+2023-2 | [`environment_2023_2.yml`](./environment_2023_2.yml)
+2023-1 | [`environment_2023_1.yml`](./archive/environment_2023_1.yml)
+2022_3 | [`environment_2022_3.yml`](./archive/environment_2022_3.yml)
+2022_2 | [`environment_2022_2.yml`](./archive/environment_2022_2.yml)
+2022_1 | [`environment_2022_1.yml`](./archive/environment_2022_1.yml)
+2021_2 | [`environment_2021_2.yml`](./archive/environment_2021_2.yml)
+2021_1 | [`environment_2021_1.yml`](./archive/environment_2021_1.yml)
+
+_note_: Prior to the 2023-2 version, the master source for these YAML files was the
+[BCDA Bluesky
+configuration](https://github.com/BCDA-APS/use_bluesky/tree/main/install)
+repository.
+
+## Managing environments
+
+First you must activate the conda
+[environment](https://bcda-aps.github.io/bluesky_training/reference/_conda_environment.html)
+you will use (if not already activated). Such as:
+
+```bash
+(base) prjemian@zap:~$ conda activate bluesky_2023_3
+(bluesky_2023_3) prjemian@zap:~$ 
+```

environments/archive/environment_2021_1.yml

@@ -0,0 +1,65 @@
+name: bluesky_2021_1
+channels:
+  - defaults
+  - conda-forge
+  - aps-anl-tag
+  - nsls2forge
+  - pydm-tag
+  - pcds-tag
+dependencies:
+  - python>=3.8
+  # remove anaconda package, it makes install and update take much longer or become unsuccessful
+  # - anaconda
+  - aps-dm-api
+  - apstools
+  - area-detector-handlers
+  - black
+  - bluesky>=1.6.2
+  - caproto
+  - conda-build
+  - coverage
+  - databroker>=1.0.6
+  - databroker-pack
+  # - epics-pydb
+  - flake8
+  - h5py
+  - happi
+  - hklpy
+  - imagecodecs-lite
+  - ipython
+  - jupyter
+  - jupyterlab
+  - lxml
+  - nexpy
+  - notebook
+  - ophyd>=1.5.1
+  - pandas
+  - pandoc
+  - pint
+  - pip
+  - psutil
+  - punx
+  - pvview
+  - pydm
+  - pyEpics>=3.4.2
+  - pylint
+  - pymca
+  - pymongo
+  - pyqt=5
+  - pyRestTable
+  - pytest
+  - qt=5
+  - scikit-image
+  - spec2nexus
+  - sphinx
+  - sphinxcontrib-napoleon
+  - stdlogpj
+  - twine
+  - typhos
+  - versioneer
+  - xlrd
+  - pip:
+    - bluesky-live
+    # - ipython-genutils==0.2.0
+    - sphinx-rtd-theme
+    - super-state-machine