Small library to control and read out lab equipment.
Table of Contents
- Getting the Code
- labRemote Requirements
- Compiling labRemote
- labRemote Examples
- Contributing to labRemote
- Creating New labRemote Based Projects
- Python Bindings
Getting the Code
You can obtain the code by checking out the labRemote repository:
git clone --recursive <url> # example url: https://gitlab.cern.ch/berkeleylab/labRemote.gitThe --recursive flag checks out any of the labRemote external dependencies (e.g.
nlohmann json). If you wish to work off of the
non-default branch of labRemote, please see the next section on Updating submodules when
changing branches.
Updating submodules after changing branches
Typical use cases involve cloning the labRemote repository following the command
described in Getting the Code and then switching to another
branch immediately after. Switching labRemote branches does not automatically update the
submodules contained within labRemote to their respective commit histories of
the labRemote branch that you switch to. Because of this, you must manually update
the labRemote submodules when changing branches. The complete procedure then becomes:
git clone --recursive <url> # as before
cd labRemote
git checkout <branch-name>
git submodule update --init --recursiveAt this point, the submodules will be at their commits corresponding to the branch
<branch-name> as opposed to their state of the default branch checked out in the
initial git clone call.
labRemote Requirements
The minimal requirements for compiling the labRemote code are those provided by
a suitable C++ compiler. labRemote is written with C++11 in mind -- specificifcally, that provided
by the default CentOS7 installation: gcc 4.8.5:
| Requirement | Value |
|---|---|
| gcc | 4.8.5 (C++11) |
Additional Requirements
Additional external libraries may be necessary if you need to leverage specific
labRemote libraries. These are specified in the table below.
For those libraries not provided as labRemote submodules, it is expected
that the user is responsible for installing them on their system if required.
| External Requirement | Comment / Links | Relevant labRemote libraries |
Provided as labRemote submodule under src/exts? |
|---|---|---|---|
| nlohmann_json | Header-only JSON for Modern C++ | libPS and libEquipConf | YES |
| influxdb-cpp | Header-only C++ client for InfluxDB | libDataSink | YES |
| pybind11 |
python bindings for labRemote (see Python Bindings section) |
YES | |
| libftdi | Generic FTDI library | FTDICom | NO |
| libmpsse | Library that implements common communication protocols (I2C, SPI) using the MPSSE framework on FTDI chips | FTDICom | NO |
| linux-gpib | Support for GPIB hardware | libPS | NO |
| Qt 5.9.2 | GUI fun in C++ | Probe Station | NO |
| OpenCV 3.3.1 | Probe Station | NO | |
| gclib | Probe Station | NO | |
| graphviz | Requirement for doxygen, provides dot utility |
NO |
One can also refer to the .gitlab-ci.yml file for a complete listing of installation and dependencies.
Compiling labRemote
Once you have checked out the labRemote repository, follow the usual cmake installation
procedure:
cd path/to/labRemote/
mkdir build
cd build
cmake3 .. # Can be cmake outside of CentOS
makelabRemote Examples
Example programs using labRemote libraries are provided for in the
src/examples directory. Upon successuful compilation,
they should be available as executables under the installation directory
(build/examples/).
Contributing to labRemote
See the project's CONTRIBUTING page for complete info.
Creating New Projects
You can add labRemote as a submodule and create a new project.
All projects should be labRemote-apps.
An example labRemote-app is provided for by ExampleLabRemoteProject
Python Bindings
Python bindings to the labRemote target can be enabled either by setting a flag
during the cmake compilation step or via pip.
Requirements for Python Bindings
A python version >=3.6 is required in order to build the python bindings for labRemote. Ensure that
you have the needed python source files and development packages installed on your system.
On CentOS this can be achieved with:
yum install python3-develMore information on how to install python can be found here.
Installation with pip
You can build the labRemote python bindings using pip. There are two ways you can do this:
-
Method Number One: requires that you first clone the
labRemoterepository as usual -
Method Number Two: does not require that you manually clone
labRemote
The two methods are outlined below.
Method Number One
This method assumes that you have cloned the labRemote repository and is the method
to use if you need to have the labRemote C++ source code and/or utilities available in addition to using
the python bindings. For example, if you are a developer you should follow this method.
The method is outlined here:
cd /path/to/labRemote
python3 -m venv myenv
source myenv/bin/activate # start the virtual environment
{myenv} python -m pip install -U pip
{myenv} python -m pip install .
{myenv} python -c "import labRemote"Note that you are not absolutely required to follow the usual CMake build procedure in order
for the steps above to succeed: the necessary build for the labRemote module occurs during the pip install . step.
Of course, if you wish to use the C++ utilities you will still need to compile labRemote as usual
even after following the above steps.
Method Number Two
This method does not require that you have cloned the labRemote repository beforehand, and is as follows:
python3 -m venv myenv
source myenv/bin/activate # start the virtual environment
{myenv} python -m pip install -U pip
{myenv} python -m pip install git+https://gitlab.cern.ch/berkeleylab/labRemote.git@devel
{myenv} python -c "import labRemote"
How to use the python bindings
Examples of how to use the labRemote python bindings are provided in the examples directory,
where you will find python versions of existing C++ labRemote examples.