The package rOmniDriver makes available in R the functions in OmniDriver SDP from Ocean Insight (formerly Ocean Optics). OmniDriver allows to change settings and acquire spectra using any Ocean Insight USB-connected spectrometer. It has been tested with USB2000, Maya2000Pro, Flame and Jaz instruments under MS-windows 7, MS-Windows 10, and MS-Windows 11. It is known to also work under OS-X, and should also work under OS X, and Linux. All modern spectrometers from Ocean Insight are supported by OmniDriver and can be expected to also work with this package.
R wrappers are implemented for a large subset of the functions exported by OmniDriver. However, functions that write to the instrument EEPROM are not implemented as they require a secret key for activation, and, in addition, their use without risk requires a profound understanding of the instruments’ hardware and firmware. In addition, most functions specific to spectrometer models we do not have access to are not implemented, as we would be unable to test them. As currently the API documentation is freely available at Ocean Insight’ support page, adding additional functions using the source code of the functions included in our package as example is almost trivial. If you do add new functions, please, make a pull request and I will add your contributed code to the package, and your name as contributor to the package in its DESCRIPTION.
Our R package ‘ooacquire’ provides a high level set of functions for spectral data acquisition built using this package as a base.
In package ‘rOmniDriver’ (>= 0.1.16), when initialization fails during
loading, option "rOmniDriver.offline" is set to TRUE so that
packages that include this package in their Suggests: can detect
whether the connection to Java and the OmniDriver driver are active or
not. This makes it possible to disable specific functions rather than
the dependent package failing to load. The instructions below are to be
followed when on-line access to spectrometers is needed. If this is not
the case, Java and OmniDriver do not need to be installed, and in the
case of ‘ooacquire’, ‘rOmniDriver’ does not need to be installed to use
functions that do not depend on an active conection to a spectrometer.
OmniDriver from Ocean Insight is written in the computer language Java. To access the functions in this driver from R, we need to use a bridge between the two computer languages, which is provided by R package ‘rJava’ available from CRAN. ‘rJava’ requires the Java development kit to be installed. installed. Distributions Temurin 8 OpenJDK, Corretto 8 OpenJDK, or Java 8 JDK (Java Open development kit) are know to work. Temurin OpenJDK and Corretto OpenJDK are free distributions, in contrast to Oracle’s Java 8, which has some restrictions and is less frequently updated.
The Java run-time is not enough! Thus, being able to run other Java programs does not ensure that the needed JDK is already installed as needed.
Of the different Java implementations, Oracle’s Java 8 JDK and Temurin 8 OpenJDK (download) are known to work with ‘rJava’ and OmniDriver. The ‘rJava’ package sometimes fails to work with the most recent version of the Java JDK, as its updates may lag slightly behind. On computers with processors and operating systems like Windows that support two command sets, 32 bits and 64 bits, and two versions of R are available, the version of Java installed and the R version used should match, being both of them 32 bits or 64 bits. As the 32 bit version of R is soon reaching its end-of-life, sticking to the 64 bit versions is a good idea.
Security updates to Oracle’s Java 8 JDK are available only through
support contracts. The JDK is free only for personal use, under
frequently changing licence terms. Temurin 8 OpenJDK is free for
commercial and non-commercial uses and regularly receives security
updates. The OpenJDK is recommended for use with recent versions of
‘rJava’. When installing the OpenJDK make sure the JAVA_HOME
variable and/or registry keys are set. This is not done by default, but
instead needs to be selected during installation. Be aware that
changing the registry keys can affect the use of other versions of Java
if they are already installed.
Getting R package ‘rJava’ working is not always straightforward, so one
needs to make sure ‘rJava’ is correctly installed and functional before
attempting to install rOmniDriver. This is important, in case problems
occur. Sometimes a restart of the operating system can help.
On Windows, the R distribution (>= 4.2.0) includes only binary packages and R binary for the 64-bit architecture and the Java/Temurin 8 JDK/OpenJDK x64 installer is needed. In contrast, earlier versions of R (<= 4.2.0) installs packages and R binaries for both 64-bit and 32-bit architectures, which means that using the default R installation and settings one may need to install also both versions of the JDK/OpenJDK. The examples and documentation for the JDK are not needed to use ‘rOmniDriver’. Under Windows, if the Java/Temurin installation fails, uninstall and re install as administrator.
Depending on the operating system, manually setting the environment
variable "JAVA_HOME" may be necessary. We can check if this variable
is set either at the operating system command prompt or from R, as shown
here. Windows uses a “registry” to keep track of the location of
programs so even if this variable is not set, ‘rJava’ will find the Java
JDK/Temurin OpenJDK under Windows if the registry keys are correctly
set.
Sys.getenv("JAVA_HOME")At the OS terminal (such as RStudio’s Terminal window) we can check the
currently installed version of the JDK with javac -version. Be aware
that javac is used for the JDK and java for the JRE and for this
to work javac must be not only installed, but also in the path.
javac -versionOnce Java is installed and tested working, the next step is to install ‘OmniDriver’ using the installer downloaded from Ocean Insight’s downloads web page corresponding to the operating system you are using. The OmniDriver installer offers a choice between installing the runtime and the development version. The runtime is free, and is all what is needed to use R package ‘rOmniDriver’. When there is a choice of 32 bit and 64 bit versions, OmniDriver should match Java and R in this respect. I have done all testing with the 64 bit version of OmniDriver, together with the 64 bit Java 8 JDK and 64 bit R under Windows 10. (SPAM is not needed either, so the combined download from Ocean Insight is overkill.)
After the installation of ‘Java’ and ‘OmniDriver’ is done, we are ready for the installation of the R packages. At this point open a new R session, or restart an already open R session. I recommend installing first package ‘rJava’ from CRAN. This installation may fail if the path (folder on disk) to the Java installation is not found.
install.packages("rJava")Once this installation has succeeded, and ‘rJava’ examples tested to work, we can install package ‘rOmniDriver’.
This package is not available through CRAN as it is a wrapper based on proprietary software from Ocean Insight with no source code freely available. ‘rOmniDriver’ can be installed either from a CRAN-like repository or from sources directly from the Git repository at Github.
The “CRAN-like” repository is hosted by the R-Universe. It serves source packages as well as Windows, OS X (Apple Mac) and Ubuntu binaries.
In recent versions of R, an option can be set to make this repository visible to R before installing packages as usual. The code below adds this repository to those already selected.
repos <- getOption("repos", default = list())
repos[["r4photobiology"]] <- "https://aphalo.r-universe.dev'"
options(repos = repos)install.packages("rOmniDriver")Without setting the option, it is also possible to pass the URL in the
call to install.packages(). It is important to also include the URL to
CRAN or one of its mirrors to ensure that dependencies are installed
automatically.
install.packages('rOmniDriver',
repos = c('https://aphalo.r-universe.dev',
'https://cloud.r-project.org'))The main branch of the Git repository at GitHub is automatically
retireved by the R-Universe builder. It is possible to also install the
package from sources directly from GitHub, but there is no need for this
unless a different branch from main is to be installed. Such
branches are likely to be incomplete or to contain bugs.
Under MS-Windows installation from sources is possible only after installation from CRAN of a version of Rtools matching the R version in use. Under Linux operating systems the requirements for installing R packages from source are usually but not always met by default. Under OS-X compilers may need to be installed. This requirements are the same as for installing any other R packages from sources.
install.packages("remotes")remotes::install_github("aphalo/romnidriver")Use of the package after a successful installation consists in connecting the spectrometer through USB and loading the package.
The first time you connect an instrument most operating systems will install the USB drivers automatically, as they are made available by the ‘OmniDriver’ installation. If this step fails there are different possibilities: 1) the account you are logged-in does not have the permissions needed to install the driver, 2) the user has no permission to write to the USB port through Java, or 3) the spectrometer needs a firmware update for compatibility with newer versions of the operating system (e.g. some USB2000 spectrometers under Windows versions newer than 7). These problems are operating-system specific and do also affect the vendor supplied software to control the spectrometer. If you can control the spectrometer using the ‘OceanView’ program from Ocean Insight, then Java and the spectrometer drivers should have been installed and working correctly. On the other hand, there is no need for ‘OceanView’ to be installed in a computer to be able to use R package ‘rOmniDriver’ to communicate and control Ocean Optics/Ocean Insight spectrometers.
The most frequent reason why installation, or functioning of the ‘rOmniDriver’ package fails is not finding the path to the installation of OmniDriver. The ‘OmniDriver’ installer from Ocean Insight is expected to save this path in an environment variable (in the operating system) called “OOI_HOME”, but it not always does. If necessary we can inspect this variable from within R.
Sys.getenv("OOI_HOME")The R statement above should show the path to the folder where
OmniDriver is installed. The OmniDriver installer seems to set this
variable reliably under Windows but unreliably under Apple’s OS X (Unix)
and possibly Linux. If the variable is undefined or contains an invalid
path the user can set or edit it at the shell prompt or in a shell
script run on system start up to point to the correct folder. Otherwise
it can be set within an R script using function
Sys.setenv(OOI_HOME = <path-to-folder>) replacing <path-to-folder>
with corresponding path. Obviously the variable should be set before
loading ‘rOmniDriver’.
If problems are encountered during loading of ‘rOmniDriver’ a diagnosis
message is displayed. Display of a diagnosis message in the absence of
problems can be forced by setting OOI_DIAG = "TRUE" in the operating
system before starting R or by setting R option verbose with
options(verbose = TRUE) before loading the package. This will show the
location of the .jar file loaded and the values of the environment
variables OOI_HOME and the path to the OmniDriver .jar file.
The implemented wrapper functions respect the names of the functions as they appear in the OmniDriver documentation but replacing “camelCase” with “snake_case”. For a couple of function with very long names, synonyms are defined in addition to the original names. The documentation for the OmniDriver API is currently available at (https://www.oceaninsight.com/globalassets/catalog-blocks-and-images/software-downloads-installers/javadocs-api/omnidriver/index.html).
This package has a vignette, that can be alternatively built with full output with a spectrometer connected, or in simplified form with the instrument off-line. A built version of the documentation is available at (https://docs.r4photobiology.info/rOmniDriver/).
The functions in the OmniDriver SDP are “bare bones” building blocks that can be used to write scripts directly, e.g. to acquire one scan every few seconds, or used to create more sophisticated functions for specific protocols and applications, of which several examples are provided in package ‘ooacquire’.
For instructions on how to install package ‘ooacquire’ please visit its web site.
Package ‘rOmniDriver’ does NOT require OceanView or SpectraSuite, the commercial software from Ocean Insight to be installed, only the free run-time of OmniDriver. Consequently, it does not require the purchase of software from Ocean Insight, but users of the driver OmniDriver run-time are not guaranteed support by Ocean Insight, unless they acquire a license to the OmniDriver SDP. OmniDriver is proprietary, closed source, software. The R package itself is open source and released under GPL.
Recent versions of OmniDriver (2.70.0, 2.71.0, 2.72.0) lack some functions in the API that were included up to version 2.56.0. These newer versions of OmniDriver no longer recognize the USB2000 spectrometer. As documentation is scant, I do not know if support for some other old models like USB4000 has been also removed.
Packages ‘rOmniDriver’ and ‘ooacquire’ have been developed with the agreement of Ocean Optics on the condition of they remaining open source and free to use. The GPL ensures that any derivative works also respect this agreement.
News about updates of this and other packages in the R for Photobiology are suite are regularly posted at (https://www.r4photobiology.info/).
The source code of the package is open and available at GitHub. Contributions and reports of compatibility or lack of it with different spectrometers and operating systems are very welcome.
Please report bugs and request new features at (https://github.com/aphalo/romnidriver/issues). Pull requests are welcome at (https://github.com/aphalo/romnidriver).
If you use ‘ooacquire’ to produce scientific or commercial publications, acknowledge this by citing the package according to:
citation("rOmniDriver")
#> To cite package 'rOmniDriver' in publications use:
#>
#> Aphalo P (2023). _rOmniDriver: Omni Driver R wrapper_. R package
#> version 0.1.20, https://github.com/aphalo/romnidriver,
#> <http://www.r4photobiology.info>.
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Manual{,
#> title = {rOmniDriver: Omni Driver R wrapper},
#> author = {Pedro J. Aphalo},
#> year = {2023},
#> note = {R package version 0.1.20,
#> https://github.com/aphalo/romnidriver},
#> url = {http://www.r4photobiology.info},
#> }© 2013-2024 Pedro J. Aphalo (pedro.aphalo@helsinki.fi) for the code. Lasse Ylianttila developed the majority of the algorithms used. Released under the GPL, version 2 or greater. This software carries no warranty of any kind.