{"id":23324783,"url":"https://github.com/aphalo/romnidriver","last_synced_at":"2025-06-13T10:09:06.304Z","repository":{"id":149797393,"uuid":"330254485","full_name":"aphalo/romnidriver","owner":"aphalo","description":"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.","archived":false,"fork":false,"pushed_at":"2025-06-06T18:44:57.000Z","size":1545,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-13T10:05:04.795Z","etag":null,"topics":["data-acquisition","spectroscopy"],"latest_commit_sha":null,"homepage":"https://docs.r4photobiology.info/ooacquire","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aphalo.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-16T20:48:20.000Z","updated_at":"2025-06-06T18:44:59.000Z","dependencies_parsed_at":"2023-06-02T16:15:34.405Z","dependency_job_id":"3edc9a7a-57b9-42f5-883d-74c8decab490","html_url":"https://github.com/aphalo/romnidriver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aphalo/romnidriver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aphalo%2Fromnidriver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aphalo%2Fromnidriver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aphalo%2Fromnidriver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aphalo%2Fromnidriver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aphalo","download_url":"https://codeload.github.com/aphalo/romnidriver/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aphalo%2Fromnidriver/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259624723,"owners_count":22886328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-acquisition","spectroscopy"],"created_at":"2024-12-20T18:25:59.356Z","updated_at":"2025-06-13T10:09:06.279Z","avatar_url":"https://github.com/aphalo.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput:\n  github_document:\n    html_preview: true\n---\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\"\n)\n```\n\n# rOmniDriver \u003cimg src=\"man/figures/logo.png\" align=\"right\" width=\"120\" /\u003e\n\n[![rOmniDriver status badge](https://aphalo.r-universe.dev/badges/rOmniDriver)](https://aphalo.r-universe.dev/rOmniDriver)\n\n## Purpose \n\nThe package **rOmniDriver** makes available in R the functions in OmniDriver SDP\nfrom _Ocean Insight_ (formerly _Ocean Optics_). OmniDriver allows to change\nsettings and acquire spectra using any Ocean Insight USB-connected spectrometer.\nIt has been tested with _USB2000_, _Maya2000Pro_, _Flame_ and _Jaz_ instruments\nunder MS-windows 7, MS-Windows 10, and MS-Windows 11. It is known to also work\nunder OS-X, and should also work under OS X, and Linux. All modern\nspectrometers from Ocean Insight are supported by OmniDriver and can be expected\nto also work with this package. \n\nR wrappers are implemented for a large subset of the functions exported by\nOmniDriver. However, functions that write to the instrument EEPROM are not\nimplemented as they require a secret key for activation, and, in addition, their\nuse without risk requires a profound understanding of the instruments' hardware\nand firmware. In addition, most functions specific to spectrometer models we do\nnot have access to are not implemented, as we would be unable to test them. As\ncurrently the API documentation is freely available at Ocean Insight' support\npage, adding additional functions using the source code of the functions\nincluded in our package as example is almost trivial. _If you do add new\nfunctions, please, make a pull request and I will add your contributed code to\nthe package, and your name as contributor to the package in its DESCRIPTION._\n\nOur R package 'ooacquire' provides a high level set of functions for spectral data\nacquisition built using this package as a base.\n\n## Installation\n\n### Skipping installation\n\nIn package 'rOmniDriver' (\u003e= 0.1.16), when initialization fails during loading,\noption `\"rOmniDriver.offline\"` is set to `TRUE` so that packages that include\nthis package in their `Suggests:` can detect whether the connection to Java and\nthe OmniDriver driver are active or not. This makes it possible to disable\nspecific functions rather than the dependent package failing to load. The\ninstructions below are to be followed when on-line access to spectrometers is\nneeded. If this is not the case, Java and OmniDriver do not need to be\ninstalled, and in the case of 'ooacquire', 'rOmniDriver' does not need to be \ninstalled to use functions that do not depend on an active conection to a\nspectrometer.\n\n### Requirements\n\nOmniDriver from Ocean Insight is written in the computer language Java. To\naccess the functions in this driver from R, we need to use a bridge between the\ntwo computer languages, which is provided by R package 'rJava' available from\nCRAN. 'rJava' requires the Java development kit to be installed. installed.\nDistributions **Temurin 8 OpenJDK**, **Corretto 8 OpenJDK**, or **Java 8 JDK**\n(Java Open development kit) are know to work. Temurin OpenJDK and Corretto\nOpenJDK are free distributions, in contrast to Oracle's Java 8, which has some\nrestrictions and is less frequently updated.\n\n*The Java run-time is not enough!* Thus, being able to run other Java programs\ndoes not ensure that the needed JDK is already installed as needed.\n\n#### Java\n\nOf the different Java implementations, **Oracle's Java 8 JDK** and \n**Temurin 8 OpenJDK** \n([download](https://adoptium.net/en-GB/temurin/releases/?version=8)) are known\nto work with\n'rJava' and **OmniDriver**. The 'rJava' package sometimes fails to work with the\nmost recent version of the Java JDK, as its updates may lag slightly behind. On\ncomputers with processors and operating systems like Windows that support two\ncommand sets, 32 bits and 64 bits, and two versions of R are available, the\nversion of Java installed and the R version used should match, being both of\nthem 32 bits or 64 bits. As the 32 bit version of R is soon reaching its\nend-of-life, sticking to the 64 bit versions is a good idea.\n\n**Security updates to Oracle's Java 8 JDK are available only through support\ncontracts. The JDK is free only for personal use, under frequently changing\nlicence terms.** **Temurin 8 OpenJDK is free for commercial and non-commercial\nuses and regularly receives security updates. The OpenJDK is recommended for\nuse with recent versions of 'rJava'.** When installing the OpenJDK make\nsure the `JAVA_HOME` variable and/or registry keys are set. This is not done by\ndefault, but instead needs to be selected during installation. _Be aware that\nchanging the registry keys can affect the use of other versions of Java if they\nare already installed._\n\nGetting R package 'rJava' working is not always straightforward, so one needs to\nmake sure 'rJava' is correctly installed and functional before attempting to\ninstall `rOmniDriver`. This is important, in case problems occur. Sometimes a\nrestart of the operating system can help.\n\nOn Windows, the R distribution (\u003e= 4.2.0) includes only binary packages and R\nbinary for the 64-bit architecture and the Java/Temurin 8 JDK/OpenJDK x64\ninstaller is needed. In contrast, earlier versions of R (\u003c= 4.2.0) installs\npackages and R binaries for both 64-bit and 32-bit architectures, which means\nthat using the default R installation and settings one may need to install also\nboth versions of the JDK/OpenJDK. The examples and documentation for the JDK are\nnot needed to use 'rOmniDriver'. Under Windows, if the Java/Temurin installation\nfails, uninstall and re install as administrator.\n\nDepending on the operating system, manually setting the environment variable\n`\"JAVA_HOME\"` may be necessary. We can check if this variable is set either at\nthe operating system command prompt or from R, as shown here. Windows uses a\n\"registry\" to keep track of the location of programs so even if this variable\nis not set, 'rJava' will find the Java JDK/Temurin OpenJDK under Windows if\nthe registry keys are correctly set.\n\n```{r, eval=FALSE}\nSys.getenv(\"JAVA_HOME\")\n```\n\n\nAt the OS terminal (such as RStudio's Terminal window) we can check the\ncurrently installed version of the JDK with `javac -version`. Be aware that\n`javac` is used for the _JDK_ and `java` for the _JRE_ and for this to work\n`javac` must be not only installed, but also in the `path`.\n\n```{bash, eval=FALSE}\njavac -version\n```\n\n#### OmniDriver\n\nOnce Java is installed and tested working, the next step is to install\n'OmniDriver' using the installer downloaded from Ocean Insight's downloads web\npage corresponding to the operating system you are using. The OmniDriver\ninstaller offers a choice between installing the runtime and the development\nversion. The runtime is free, and is all what is needed to use R package\n'rOmniDriver'. When there is a choice of 32 bit and 64 bit versions, OmniDriver\nshould match Java and R in this respect. I have done all testing with the 64 bit\nversion of OmniDriver, together with the 64 bit Java 8 JDK and 64 bit R under\nWindows 10. (SPAM is not needed either, so the combined download from Ocean\nInsight is overkill.)\n\nAfter the installation of 'Java' and 'OmniDriver' is done, we are ready for the\ninstallation of the R packages. At this point open a _new R session_, or\n_restart an already open R session_. I recommend installing first package\n'rJava' from CRAN. This installation may fail if the path (folder on disk) to\nthe Java installation is not found.\n\n```{r, eval=FALSE}\ninstall.packages(\"rJava\")\n```\n\nOnce this installation has succeeded, and 'rJava' examples tested to work, we\ncan install package 'rOmniDriver'. \n\n### 'rOmniDriver'\n\nThis package is not available through CRAN as it is a wrapper based on\nproprietary software from Ocean Insight with no source code freely available.\n'rOmniDriver' can be installed either from a CRAN-like repository or from\nsources directly from the Git repository at Github.\n\n#### Installation of a released version\n\nThe \"CRAN-like\" repository is hosted by the R-Universe. It serves source\npackages as well as Windows, OS X (Apple Mac) and Ubuntu binaries.\n\nIn recent versions of R, an option can be set to make this\nrepository visible to R before installing packages as usual. The code below\nadds this repository to those already selected.\n\n```{r, eval=FALSE}\nrepos \u003c- getOption(\"repos\", default = list())\nrepos[[\"r4photobiology\"]] \u003c- \"https://aphalo.r-universe.dev'\"\noptions(repos = repos)\n```\n\n```{r, eval=FALSE}\ninstall.packages(\"rOmniDriver\")\n```\n\nWithout setting the option, it is also possible to pass the URL in the call\nto `install.packages()`. It is important to also include the URL to CRAN or\none of its mirrors to ensure that dependencies are installed automatically.\n\n```{r, eval=FALSE}\ninstall.packages('rOmniDriver', \n                 repos = c('https://aphalo.r-universe.dev', \n                           'https://cloud.r-project.org'))\n```\n\n#### Installation of the development version\n\nThe `main` branch of the Git repository at GitHub is automatically retireved\nby the R-Universe builder. It is possible to also install the package from\nsources directly from GitHub, but there is no need for this unless a different\nbranch from `main` is to be installed. **Such branches are likely to be\nincomplete or to contain bugs.** \n\nUnder MS-Windows installation from sources is possible only after installation\nfrom CRAN of a version of Rtools matching the R version in use. Under Linux\noperating systems the requirements for installing R packages from source are\nusually but not always met by default. Under OS-X compilers may need to be\ninstalled. This requirements are the same as for installing any other R packages\nfrom sources.\n\n```{r, eval=FALSE}\ninstall.packages(\"remotes\")\n```\n\n```{r, eval=FALSE}\nremotes::install_github(\"aphalo/romnidriver\")\n```\n\nUse of the package after a successful installation consists in connecting the\nspectrometer through USB and loading the package.\n\n### If problems arise\n\nThe first time you connect an instrument most operating systems\nwill install the USB drivers automatically, as they are made available by the\n'OmniDriver' installation. If this step fails there are different possibilities:\n1) the account you are logged-in does not have the permissions needed to install\nthe driver, 2) the user has no permission to write to the USB port through Java,\nor 3) the spectrometer needs a firmware update for compatibility with newer\nversions of the operating system (e.g. some USB2000 spectrometers under Windows\nversions newer than 7). These problems are operating-system specific and do also\naffect the vendor supplied software to control the spectrometer. If you can\ncontrol the spectrometer using the 'OceanView' program from Ocean Insight, then\nJava and the spectrometer drivers should have been installed and working\ncorrectly. **On the other hand, there is no need for 'OceanView' to be installed\nin a computer to be able to use R package 'rOmniDriver' to communicate and\ncontrol Ocean Optics/Ocean Insight spectrometers.**\n\nThe most frequent reason why installation, or functioning of the 'rOmniDriver'\npackage fails is not finding the path to the installation of OmniDriver. The\n'OmniDriver' installer from Ocean Insight is expected to save this path in an\nenvironment variable (in the operating system) called \"OOI_HOME\", but it not\nalways does. If necessary we can inspect this variable from within R.\n\n```{r, eval=FALSE}\nSys.getenv(\"OOI_HOME\")\n```\n\nThe R statement above should show the path to the folder where OmniDriver is\ninstalled. The OmniDriver installer seems to set this variable reliably under\nWindows but unreliably under Apple's OS X (Unix) and possibly Linux. If the\nvariable is undefined or contains an invalid path the user can set or edit it at\nthe shell prompt or in a shell script run on system start up to point to the\ncorrect folder. Otherwise it can be set within an R script using function\n`Sys.setenv(OOI_HOME = \u003cpath-to-folder\u003e)` replacing `\u003cpath-to-folder\u003e` with\ncorresponding path. Obviously the variable should be set before loading \n'rOmniDriver'. \n\nIf problems are encountered during loading of 'rOmniDriver' a diagnosis message is\ndisplayed. Display of a diagnosis message in the absence of problems can be\nforced by setting `OOI_DIAG = \"TRUE\"` in the operating system before starting R\nor by setting R option verbose with `options(verbose = TRUE)` before loading the\npackage. This will show the location of the `.jar` file loaded and the values of\nthe environment variables `OOI_HOME` and the path to the OmniDriver `.jar` file.\n\n## Documentation\n\nThe implemented wrapper functions respect the names of the functions as they\nappear in the OmniDriver documentation but replacing \"camelCase\" with\n\"snake_case\". For a couple of function with very long names, synonyms are\ndefined in addition to the original names. The documentation for the OmniDriver\nAPI is no longer available at the [Ocean Optics web site](https://www.ocaenoptics.com).\n\nThis package has a vignette, that can be alternatively built with full output\nwith a spectrometer connected, or in simplified form with the instrument\noff-line. A built version of the documentation is available at\n(https://docs.r4photobiology.info/rOmniDriver/).\n\n## Package 'ooacquire'\n\nThe functions in the OmniDriver SDP are \"bare bones\" building blocks that can be\nused to write scripts directly, e.g. to acquire one scan every few seconds, or\nused to create more sophisticated functions for specific protocols and\napplications, of which several examples are provided in package\n['ooacquire'](https://docs.r4photobiology.info/ooacquire/).\n\nFor instructions on how to install package 'ooacquire' please visit [its\nweb site](https://docs.r4photobiology.info/ooacquire/).\n\n## Status of this package and _OmniDriver_\n\nPackage 'rOmniDriver' does NOT require _OceanView_ or _SpectraSuite_, the\ncommercial software from Ocean Insight to be installed, only the free run-time\nof OmniDriver. Consequently, it does not require the purchase of software from\nOcean Insight, but users of the driver OmniDriver run-time are not guaranteed\nsupport by Ocean Insight, unless they acquire a license to the OmniDriver SDP.\nOmniDriver is proprietary, closed source, software. The R package itself is\nopen source and released under GPL.\n\n**Recent versions of _OmniDriver_ (2.70.0, 2.71.0, 2.72.0) lack some functions\nin the API that were included up to version 2.56.0. These newer versions of\nOmniDriver no longer recognize the _USB2000_ spectrometer. As documentation is\nscant, I do not know if support for some other old models like _USB4000_ has\nbeen also removed.**\n\nPackages 'rOmniDriver' and 'ooacquire' have been developed with the agreement\nof Ocean Optics on the condition of they remaining open source and free to use. \nThe GPL ensures that any derivative works also respect this agreement.\n\n## News\n\nNews about updates of this and other packages in the R for Photobiology are \nsuite are regularly posted at (\u003chttps://www.r4photobiology.info/\u003e).\n\n## Contributing\n\nThe source code of the package is open and available at GitHub. Contributions\nand reports of compatibility or lack of it with different spectrometers and\noperating systems are very welcome.\n\nPlease report bugs and request new features at\n(\u003chttps://github.com/aphalo/romnidriver/issues\u003e). Pull requests are\nwelcome at (\u003chttps://github.com/aphalo/romnidriver\u003e).\n\n## Citation\n\nIf you use 'ooacquire' to produce scientific or commercial publications,\nacknowledge this by citing the package according to:\n\n```{r}\ncitation(\"rOmniDriver\")\n```\n\n## License\n\n© 2013-2024 Pedro J. Aphalo\n([pedro.aphalo\\@helsinki.fi](mailto:pedro.aphalo@helsinki.fi)) for the\ncode. Lasse Ylianttila developed the majority of the algorithms used.\nReleased under the GPL, version 2 or greater. This software carries no\nwarranty of any kind.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faphalo%2Fromnidriver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faphalo%2Fromnidriver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faphalo%2Fromnidriver/lists"}