First release

.github/workflows/release.yml

@@ -0,0 +1,15 @@
+name: Release areaDetector Driver on PR merged into main
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  release-ioc:
+    if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main'
+    uses: CentralLaserFacility/CLF-github-actions/.github/workflows/release-on-github-workflow.yml@main
+    with:
+      runner: ubuntu-latest
+      custom_version: ${{ github.event.pull_request.title }}

.gitignore

@@ -0,0 +1,21 @@
+bin
+lib
+include
+db
+!pixciApp/Db
+dbd
+*_BAK.adl
+documentation.html
+envPaths*
+cdCommands
+dllPath.bat
+auto_settings.sav*
+configure/*.local
+cfg
+fmt
+!pixciApp/src/fmt
+O.*/
+*~
+*.swp
+.vs*
+/devTools

LICENSE

@@ -1,28 +1,15 @@
-BSD 3-Clause License
+3 Clause BSD licence
 
-Copyright (c) 2023, UKRI STFC Central Laser Facility
+© Copyright 2025 UK Research and Innovation, Science and Technology Facilities Council
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+[Authors: Irie Railton, Subindev Devadasan, Aoun Muhammad, Sidharth Sarat Raj Batchu, Timothy Speight]
 
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -0,0 +1,23 @@
+#Makefile at top of application tree
+TOP = .
+include $(TOP)/configure/CONFIG
+DIRS := $(DIRS) configure
+DIRS := $(DIRS) pixciSupport
+DIRS := $(DIRS) pixciApp
+pixciApp_DEPEND_DIRS += pixciSupport
+ifeq ($(BUILD_IOCS), YES)
+DIRS := $(DIRS) $(filter-out $(DIRS), $(wildcard iocs))
+iocs_DEPEND_DIRS += pixciApp
+endif
+include $(TOP)/configure/RULES_TOP
+
+uninstall: uninstall_iocs
+uninstall_iocs:
+	$(MAKE) -C iocs uninstall
+.PHONY: uninstall uninstall_iocs
+
+realuninstall: realuninstall_iocs
+realuninstall_iocs:
+	$(MAKE) -C iocs realuninstall
+.PHONY: realuninstall realuninstall_iocs
+

README.md

@@ -1,2 +1,71 @@
 # ADPixci
-AreaDetector driver for Raptor Eagle-XV camera using Pixci frame grabber
+[AreaDetector](https://areadetector.github.io/areaDetector/) driver for integrating [PIXCI®](https://www.epixinc.com/products/framegrabbers.htm) camera link frame grabbers with supported cameras into [EPICS](https://epics-controls.org/). \
+Uses the [XCLIB™ Library](https://www.epixinc.com/products/xclib.htm) to interface with frame grabbers.
+
+### Supported Hardware
+#### Cameras
+- [Raptor Photonics Eagle XV](https://www.raptorphotonics.com/products/eagle-xv/) 4240
+- [Raptor Photonics Eagle XV](https://www.raptorphotonics.com/products/eagle-xv/) 4710
+
+#### Frame Grabbers
+- PIXCI® EB1 
+- PIXCI® E8
+
+This software has only been tested on the above camera link frame grabbers but *should* work for other similar ones too.
+
+#### Manuals
+
+[The PIXCI® E8 User's Manual](https://www.epixinc.com/manuals/pixci_e14el/index.htm) and [PIXCI® EB1 User's Manual](https://www.epixinc.com/manuals/pixci_eb1/index.htm) from [EPIX, Inc](https://www.epixinc.com) were used to inform the development of ADPixci. \
+The Eagle XV II Instruction Manual from [Raptor Photonics](https://www.raptorphotonics.com/) was used to inform the development of ADRaptorEagleXV, but it is only available upon request from their support team.
+
+### Architecture
+The high level architecture of this driver is shown in the below diagram. \
+*Note: this does not show all methods and attributes.*
+
+The abstract class ADPixci inherits from the base areaDetector driver and provides generic code for using PIXCI® frame grabbers with areaDetector. \
+ADRaptorEagleXV inherits from ADPixci, providing camera specific code and serial commands.
+
+```mermaid
+classDiagram
+    direction LR
+    ADDriver <|-- ADPixci
+    ADPixci <|-- ADRaptorEagleXV
+    class ADDriver{
+        - deviceIsReachable: bool
+        + writeInt32()
+        + connect()
+        + getShutter()
+    }
+    class ADPixci["*ADPixci*"]{
+        # driverName: string
+        - paramMsgQue: Queue
+        + acquireTask()
+        + paramTask()
+        # addtoParamQueue()
+        # writeReadSerial() int
+        # writeInt32() asynStatus
+        # writeFloat64() asynStatus
+        # acquireStart() asynStatus
+        # acquireStop() asynStatus
+        # changeVideoFormatConfig() asynStatus
+    }
+    class ADRaptorEagleXV{
+        - writeSerialRegister() asynStatus
+        - readSerialRegister() asynStatus
+        - writeInt32() asynStatus
+        - changeVideoFormatConfig() asynStatus
+    }
+    click ADDriver href "https://areadetector.github.io/areaDetector/ADCore/ADDriver.html" "ADDriver documentation"
+```
+
+## Contributing
+
+To contribute to this repository please fork it, develop your code in your fork, and then create a pull request back into this repository. \
+Please use cpplint to check your source code matches the code conventions of the repository with the config file `pixciApp/src/CPPLINT.cfg` before opening a PR.
+From there, two CLF developers will review and merge your feature or fix.
+
+### Adding a new detector
+If you encounter a new detector that recommends the use of the PIXCI&reg; frame grabber and XCLIB&trade; software, you can create a new detector class that inherits from ADPixci, in a similar manner to ADRaptorEagleXV. \
+The `changeVideoFormatConfig` method **must** be implemented for loading format files for different binning values. \
+If the `writeInt32`, `writeFloat64`, `updateInitialPVs`, or `handleParamTask`  methods are overloaded, make sure to call their ADPixci implementation too. \
+There are a few pure virtual functions for camera attributes you might want to use in ADPixci.h that can be implemented if needed too.

configure/CONFIG

@@ -0,0 +1,29 @@
+# CONFIG - Load build configuration data
+#
+# Do not make changes to this file!
+
+# Allow user to override where the build rules come from
+RULES = $(EPICS_BASE)
+
+# RELEASE files point to other application tops
+include $(TOP)/configure/RELEASE
+-include $(TOP)/configure/RELEASE.$(EPICS_HOST_ARCH).Common
+ifdef T_A
+-include $(TOP)/configure/RELEASE.Common.$(T_A)
+-include $(TOP)/configure/RELEASE.$(EPICS_HOST_ARCH).$(T_A)
+endif
+
+CONFIG = $(RULES)/configure
+include $(CONFIG)/CONFIG
+
+# Override the Base definition:
+INSTALL_LOCATION = $(TOP)
+
+# CONFIG_SITE files contain other build configuration settings
+include $(TOP)/configure/CONFIG_SITE
+-include $(TOP)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH).Common
+ifdef T_A
+ -include $(TOP)/configure/CONFIG_SITE.Common.$(T_A)
+ -include $(TOP)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH).$(T_A)
+endif
+

configure/CONFIG_FMT

@@ -0,0 +1,4 @@
+#CONFIG_FMT
+
+FILE_TYPE += FMT
+INSTALL_FMT = $(INSTALL_LOCATION)/fmt

configure/CONFIG_SITE

@@ -0,0 +1,42 @@
+# CONFIG_SITE
+
+# Make any application-specific changes to the EPICS build
+#   configuration variables in this file.
+#
+# Host/target specific settings can be specified in files named
+#   CONFIG_SITE.$(EPICS_HOST_ARCH).Common
+#   CONFIG_SITE.Common.$(T_A)
+#   CONFIG_SITE.$(EPICS_HOST_ARCH).$(T_A)
+
+# CHECK_RELEASE controls the consistency checking of the support
+#   applications pointed to by the RELEASE* files.
+# Normally CHECK_RELEASE should be set to YES.
+# Set CHECK_RELEASE to NO to disable checking completely.
+# Set CHECK_RELEASE to WARN to perform consistency checking but
+#   continue building anyway if conflicts are found.
+CHECK_RELEASE = YES
+
+# Set this when you only want to compile this application
+#   for a subset of the cross-compiled target architectures
+#   that Base is built for.
+#CROSS_COMPILER_TARGET_ARCHS = vxWorks-68040
+
+# To install files into a location other than $(TOP) define
+#   INSTALL_LOCATION here.
+#INSTALL_LOCATION=</path/name/to/install/top>
+
+# Set this when your IOC and the host use different paths
+#   to access the application. This will be needed to boot
+#   from a Microsoft FTP server or with some NFS mounts.
+# You must rebuild in the iocBoot directory for this to
+#   take effect.
+#IOCS_APPL_TOP = </IOC/path/to/application/top>
+
+# Get settings from AREA_DETECTOR, so we only have to configure once for all detectors if we want to
+-include $(AREA_DETECTOR)/configure/CONFIG_SITE
+-include $(AREA_DETECTOR)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH)
+-include $(AREA_DETECTOR)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH).Common
+ifdef T_A
+  -include $(AREA_DETECTOR)/configure/CONFIG_SITE.Common.$(T_A)
+  -include $(AREA_DETECTOR)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH).$(T_A)
+endif

configure/Makefile

@@ -0,0 +1,9 @@
+TOP=..
+
+include $(TOP)/configure/CONFIG
+
+TARGETS = $(CONFIG_TARGETS)
+CONFIGS += $(subst ../,,$(wildcard $(CONFIG_INSTALLS)))
+CFG += CONFIG_FMT RULES_FMT
+
+include $(TOP)/configure/RULES

configure/RELEASE

@@ -0,0 +1,8 @@
+#RELEASE Location of external products
+# Run "gnumake clean uninstall install" in the application
+# top directory each time this file is changed.
+
+-include $(TOP)/../configure/RELEASE_LIBS_INCLUDE
+-include $(TOP)/RELEASE.local
+-include $(TOP)/configure/RELEASE.local
+

configure/RULES

@@ -0,0 +1,6 @@
+# RULES
+
+include $(CONFIG)/RULES
+
+# Library should be rebuilt because LIBOBJS may have changed.
+$(LIBNAME): ../Makefile

configure/RULES.ioc

@@ -0,0 +1,2 @@
+#RULES.ioc
+include $(CONFIG)/RULES.ioc

configure/RULES_DIRS

@@ -0,0 +1,2 @@
+#RULES_DIRS
+include $(CONFIG)/RULES_DIRS

configure/RULES_FMT

@@ -0,0 +1,8 @@
+#RULES_FMT
+
+override INSTALLS_FMT := $(FMT:%=$(INSTALL_FMT)/%)
+
+$(INSTALL_FMT)/%.fmt: ../fmt/%/bin_1x1.fmt
+	@echo "Installing FMT file: $@"
+	@if not exist "$(dir $@)" mkdir "$(dir $@)"
+	@if exist "$<" ( copy /Y $(subst /,\,$<) $(subst /,\,$@) ) else ( echo "Error: Source file $< not found!" && exit 1 )

configure/RULES_TOP

@@ -0,0 +1,3 @@
+#RULES_TOP
+include $(CONFIG)/RULES_TOP
+

iocs/Makefile

@@ -0,0 +1,24 @@
+TOP = ..
+include $(TOP)/configure/CONFIG
+
+DIRS := $(wildcard *IOC)
+
+include $(TOP)/configure/RULES_TOP
+
+uninstallTargets = $(foreach dir, $(DIRS), $(dir)$(DIVIDER)uninstall)
+uninstall: $(uninstallTargets)
+define UNINSTALL_template
+$(1)$(DIVIDER)uninstall:
+	$(MAKE) -C $(1) uninstall
+endef
+$(foreach dir, $(DIRS), $(eval $(call UNINSTALL_template,$(dir))))
+.PHONY: uninstall $(uninstallTargets)
+
+realuninstallTargets = $(foreach dir, $(DIRS), $(dir)$(DIVIDER)realuninstall)
+realuninstall: $(realuninstallTargets)
+define REALUNINSTALL_template
+$(1)$(DIVIDER)realuninstall:
+	$(MAKE) -C $(1) realuninstall
+endef
+$(foreach dir, $(DIRS), $(eval $(call REALUNINSTALL_template,$(dir))))
+.PHONY: realuninstall $(realuninstallTargets)

iocs/pixciIOC/Makefile

@@ -0,0 +1,31 @@
+# Makefile at top of application tree
+TOP = .
+include $(TOP)/configure/CONFIG
+
+# Directories to build, any order
+DIRS += configure
+DIRS += $(wildcard *Sup)
+DIRS += $(wildcard *App)
+DIRS += $(wildcard *Top)
+DIRS += $(wildcard iocBoot)
+
+# The build order is controlled by these dependency rules:
+
+# All dirs except configure depend on configure
+$(foreach dir, $(filter-out configure, $(DIRS)), \
+    $(eval $(dir)_DEPEND_DIRS += configure))
+
+# Any *App dirs depend on all *Sup dirs
+$(foreach dir, $(filter %App, $(DIRS)), \
+    $(eval $(dir)_DEPEND_DIRS += $(filter %Sup, $(DIRS))))
+
+# Any *Top dirs depend on all *Sup and *App dirs
+$(foreach dir, $(filter %Top, $(DIRS)), \
+    $(eval $(dir)_DEPEND_DIRS += $(filter %Sup %App, $(DIRS))))
+
+# iocBoot depends on all *App dirs
+iocBoot_DEPEND_DIRS += $(filter %App,$(DIRS))
+
+# Add any additional dependency rules here:
+
+include $(TOP)/configure/RULES_TOP

iocs/pixciIOC/configure/CONFIG

@@ -0,0 +1,29 @@
+# CONFIG - Load build configuration data
+#
+# Do not make changes to this file!
+
+# Allow user to override where the build rules come from
+RULES = $(EPICS_BASE)
+
+# RELEASE files point to other application tops
+include $(TOP)/configure/RELEASE
+-include $(TOP)/configure/RELEASE.$(EPICS_HOST_ARCH).Common
+ifdef T_A
+-include $(TOP)/configure/RELEASE.Common.$(T_A)
+-include $(TOP)/configure/RELEASE.$(EPICS_HOST_ARCH).$(T_A)
+endif
+
+CONFIG = $(RULES)/configure
+include $(CONFIG)/CONFIG
+
+# Override the Base definition:
+INSTALL_LOCATION = $(TOP)
+
+# CONFIG_SITE files contain other build configuration settings
+include $(TOP)/configure/CONFIG_SITE
+-include $(TOP)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH).Common
+ifdef T_A
+ -include $(TOP)/configure/CONFIG_SITE.Common.$(T_A)
+ -include $(TOP)/configure/CONFIG_SITE.$(EPICS_HOST_ARCH).$(T_A)
+endif
+