Basic Example

To use the ChimeraTK::Device class you need a so called "device map" file (dmap file). It is created manually and contains information which devices are used in your application. More information can be found on the page about Device Mapping.

For the beinning all you need is the alias which identifies the device. In the example.dmap file there is just one entry: MY_DEVICE

Registers are accessed by so called accessors. The accessors contain a buffer which stores the data which is read from or written to the hardware using read() and write() functions. When not reading or writing you can efficiently access or modify the content at will, because it is modifying the internal buffer and not talking to the hardware.

In this basic example are using a register which holds one value. A single value is a scalar, so we are using the ScalarRegisterAccessor. Like all accessors, it is templated to a simple (user) data type and automatically does a data conversion to this type, if needed. The ScalarRegisterAccessor behaves just like the simple data type it represents, so you can just assign to it, add, subtact, multiply or divide it, print it, ... Usually you don't allocate a variable and copy the accessor content to it (which would be really inefficient in case of large data arrays), but just use the accessor.

// SPDX-FileCopyrightText: Deutsches Elektronen-Synchrotron DESY, MSK, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
 
#include <ChimeraTK/Device.h>
#include <ChimeraTK/Utilities.h>
 
#include <iostream>
 
/*
 * All information needed to access the device is
 * the device alias and the register names
 * (plus a .dmap file)
 */
 
int main() {
  /*
   * Before you use a device you have to tell DeviceAccess
   * which dmap file to use.
   */
  ChimeraTK::setDMapFilePath("example.dmap");
 
  /*
   * Create a device. Make sure a device alias is present
   * in the dmap file.
   */
  ChimeraTK::Device myDevice("MY_DEVICE");
  myDevice.open();
 
  /*
   * Registers are defined by a path, which consists of a hierarchy of
   * names separated by '/'. In this is example it is Module/Register.
   * In this basic example we use a register which contains a single value
   * (a scalar).
   *
   * The example device has a temperature controller with a set value.
   */
  ChimeraTK::ScalarRegisterAccessor<float> temperatureSetPoint =
      myDevice.getScalarRegisterAccessor<float>("TEMPERATURE_CONTROLLER/SET_POINT");
 
  /*
   * To get the value from the device call read.
   */
  temperatureSetPoint.read();
 
  /*
   * Now you can treat the accessor as if it was a regular float variable.
   */
  std::cout << "Current temperature set point is " << temperatureSetPoint << std::endl;
  temperatureSetPoint += 1.5;
  std::cout << "Temperature set point changed to " << temperatureSetPoint << std::endl;
 
  /*
   * After you are done manipulating the accessor write it to the hardware.
   */
  temperatureSetPoint.write();
 
  /*
   * It is good style to close the device when you are done, although
   * this would happen automatically once the device goes out of scope.
   */
  myDevice.close();
 
  return 0;
}

Side note

Although the initialisation syntax of _temperatureSetPoint in the example above uses the equals sign, this is calling the copy constructor. Accessors intentionally don't have assignment operators (see Why do RegisterAccessors not have an assignment operator for other RegisterAccessors?).

If you want to initialise an accessor which is already created, use replace(). You need this for instance if the accessor is a class member and has already been instantiated before you call devcie.getXXXAccessor() in the constructor.

ChimeraTK::ScalarRegisterAccessor<float> temperatureSetPoint;
temperatureSetPoint.replace(myDevice.getScalarRegisterAccessor<float>("TEMPERATURE_CONTROLLER/SET_POINT"));

Next topic: Multi Value Registers (1D Register Accessors)