Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/aphalo/romnidriver

An R wrapper of the OminiDriver runtime from Ocean Insight (formerly Ocean Optics), written in Java, allowing control and data acquisition from most spectromters from this supplier.
https://github.com/aphalo/romnidriver

data-acquisition spectroscopy

Last synced: 20 days ago
JSON representation

An R wrapper of the OminiDriver runtime from Ocean Insight (formerly Ocean Optics), written in Java, allowing control and data acquisition from most spectromters from this supplier.

Awesome Lists containing this project

README 

        
---

output:

  github_document:

    html_preview: true

---



```{r, echo = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>"

)

```



# rOmniDriver 



[![rOmniDriver status badge](https://aphalo.r-universe.dev/badges/rOmniDriver)](https://aphalo.r-universe.dev/rOmniDriver)



## Purpose 



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.



## Installation



### Skipping installation



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.



### Requirements



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.



#### Java



Of the different Java implementations, **Oracle's Java 8 JDK** and 

**Temurin 8 OpenJDK** 

([download](https://adoptium.net/en-GB/temurin/releases/?version=8)) 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.



```{r, eval=FALSE}

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`.



```{bash, eval=FALSE}

javac -version

```



#### OmniDriver



Once 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.



```{r, eval=FALSE}

install.packages("rJava")

```



Once this installation has succeeded, and 'rJava' examples tested to work, we

can install package 'rOmniDriver'. 



### '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.



#### Installation of a released version



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.



```{r, eval=FALSE}

repos <- getOption("repos", default = list())

repos[["r4photobiology"]] <- "https://aphalo.r-universe.dev'"

options(repos = repos)

```



```{r, eval=FALSE}

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.



```{r, eval=FALSE}

install.packages('rOmniDriver', 

                 repos = c('https://aphalo.r-universe.dev', 

                           'https://cloud.r-project.org'))

```



#### Installation of the development version



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.



```{r, eval=FALSE}

install.packages("remotes")

```



```{r, eval=FALSE}

remotes::install_github("aphalo/romnidriver")

```



Use of the package after a successful installation consists in connecting the

spectrometer through USB and loading the package.



### If problems arise



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.



```{r, eval=FALSE}

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 = )` replacing `` 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.



## Documentation



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 no longer available at the [Ocean Optics web site](https://www.ocaenoptics.com).



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/).



## Package 'ooacquire'



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'](https://docs.r4photobiology.info/ooacquire/).



For instructions on how to install package 'ooacquire' please visit [its

web site](https://docs.r4photobiology.info/ooacquire/).



## Status of this package and _OmniDriver_



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



News about updates of this and other packages in the R for Photobiology are 

suite are regularly posted at ().



## Contributing



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

(). Pull requests are

welcome at ().



## Citation



If you use 'ooacquire' to produce scientific or commercial publications,

acknowledge this by citing the package according to:



```{r}

citation("rOmniDriver")

```



## License



© 2013-2024 Pedro J. Aphalo

([pedro.aphalo\@helsinki.fi](mailto:[email protected])) 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.