Current Controller Management Design

Responsible Module: ControllerManagement RobotUnitModule

NJointControllerBase (very well documented)

• This is the abstract base class for all NJointControllers.
• It implements basic management routines required by the RobotUnit and some basic ice calls.
• NJointControllers are instantiated and managed by the RobotUnit.
  • A NJointController calculates ControlTargets (ControlTargetBase) for a set of ControlDevices (ControlDevice) in a specific ControlMode.
  • This ControlMode is defined for each ControlDevice during construction.

States: Requested and Active

• The state of an NJointController can be requested / not requested and active / inactive.
• All four combinations are possible.

Requested / Not Requested

• If the user wants this NJointController to be executed it is in a requested state (see isControllerRequested).
• Otherwise the controler is not requested.
  • Calling activateController sets the state to requested.
  • Calling deactivateController sets the state to not requested.
• If the \ref NJointControllerBase causes an error or a different NJointController using one or more of the same ControlDevice's is requested, this NJointController is deactivated.

Active / Inactive

• Is the NJointController executed by the RobotUnitModules::ControlThread "ControlThread" it is active (see isControllerActive).
• To be executed by the ControlThread, the NJointController has to be requested at some point in the past.
  • If a controller is active, it has to write a valid ControlTarget for each of its ControlDevices (if it fails, it will be deactivated).

Using ControlTargets

• A NJointController can use peekControlDevice to examine a ControlDevice before using it (e.g.: checking the supported ControlTargets).
• If a ControlDevice should be used by this NJointController, it has to call useControlDevice.
• This sets the ControlMode for the ControlDevice and returns a pointer to the ControlTarget.
  • This pointer has to be used to send commands in each iteration of rtRun.
  • The ControlMode can't be changed afterwards (A new NJointControllerBase has to be created).

Steps (Input: deviceName and controlMode):

1. Check that this function is called during construction
2. Check that the controlDeviceControlModeMap does not have an instance of deviceName yet
3. Get JointController for deviceName and controlMode
4. Get deviceIndex for deviceName from RobotUnitModuleDevices
5. set controlDeviceUsedJointController for deviceName to JointController
6. set controlDeviceControlModeMap for deviceName to controlMode
7. set controlDeviceUsedBitmap at deviceIndex to true
8. insert deviceIndex to controlDeviceUsedIndex

Using SensorValues

• A NJointController can use peekSensorDevice to examine a SensorDevice before using it.
• If a SensorDevice should be used by this NJointController, it has to call useSensorDevice.
• This returns a pointer to the SensorValue.

A synchronized Virtualrobot

• If the controller needs a simox robot in rtRun, it should call useSynchronizedRtRobot.
• This will provide a simoxRobot via rtGetRobot.
• This robot is synchronized with the real robots state before calling rtRun

RobotUnitModuleControllerManagement

Members:

• std::map<std::string, NJointControllerBasePtr> nJointControllers;
  • Holds all currently loaded NJointControllers (index: instanceName)(May not be accessed in rt.)
• std::map<std::string, NJointControllerBasePtr> nJointControllersToBeDeleted;
  • These controllers will be deleted in the next iteration of publish

Creation:

• createNJointController(className, instanceName, NJointControllerConfigPtr)
• createNJointControllerFromVariantConfig(className, instanceName, StringVariantBaseMap)
• createOrReplaceNJointController(className, instanceName, NJointControllerConfigPtr)
• createNJointController(className, instanceName, NJointControllerConfigPtr, deletable)

Steps

1. Check if in ControlThread
2. Check if Devices are ready
3. Check if Controller could be constructed by checking the className and constructing a factory
4. Check if instance with instanceName already exists in nJointControllers (throws if it does)
5. Create Controller with factory
6. Check if Controller uses at least one ControlDevice
7. Add Controller to ArmarXManager
8. Publish that NJointController with instanceName was created

Activation:

• activateNJointController(name)
• activateNJointControllers(vector<name>)
• activateNJointController(NJointControllerBasePtr)
• activateNJointControllers(vector<NJointControllerBasePtr>)

Steps:

1. Check if in ControlThread
2. Check if Devices are ready
3. Check if all controllersToActivate are already active
4. Copy currently requested requestedControllers from ControlThreadDataBuffer
5. Check if controllersToActivate AreNotInConflict with each other¹
6. Check if requestedControllers are in controllersToActivate and NotInConflictWith; if not add them to controllersToActivate
7. setActivateControllersRequest the controllersToActivate
   1. Check if in ControlThread
   2. Check if Devices are ready
   3. Create JointAndNJointControllers request
   4. For each controller in controllersToActivate:
      1. For each controlDevice2ControlMode in ControlDeviceUsedControlModeMap ³
         1. Get jointControlIndex for controlDevice2ControlMode
         2. If request has a jointController(⁴) at jointControlIndex throw controllers to activate are in conflict (This is were globally is checked that only one controller is active for one device)
         3. Add JointController for ControlMode to jointControllers of request at postion jointControlIndex
   5. For each JointController:
      1. get currently used JointController at jointControlIndex
      2. if old controller is a StopMovementController set jointController = oldJointController (??, comment says: "don't replace this controller with emergency stop")
      3. else: set the jointController to the EmergencyStopController for this jointControlIndex
   6. Write message with the requested controller names as output stream

¹ optional<vector<char>> NJointControllerBase::isNotInConflictWith(vector<char> used):

• for each entry in used check if the corresponding entry in controlDeviceBitmap exists; if yes set the corresponding entry of the output vector to true
• controlDeviceBitmap = Bitmap of used ControlDevices² (1 == used, 0 == not used)

² ControlDevice:

• The ControlDevice class represents a logical unit accepting commands via its JointControllers.
• It holds a set of JointControllers with different Controll modes.
  • It always has a JointController with mode ControlModes::EmergencyStop which is used in case of an error.
  • It always has a JointController with mode ControlModes::StopMovement which is used when the controled device should stop any movement.
• It holds a set of tags.
  • These tags are used by different components to create default controllers, check for abilities or present output to the user.

³ controlDeviceControlModeMap:

• Maps names of used ControlDevices to the ControlTarget's control mode
• Basically represents a mapping from ControlDevices to the

Deactivation:

• deactivateNJointController(name)
• deactivateNJointControllers(vector<name>)
• deactivateNJointController(NJointControllerBasePtr)
• deactivateNJointControllers(vector<NJointControllerBasePtr>)

Deletion:

• deleteNJointController(name)
• deleteNJointControllers(vector<name>)
• deleteNJointController(NJointControllerBasePtr)
• deleteNJointControllers(vector<NJointControllerBasePtr>)

Deactivate and Delete

• deactivateAndDeleteNJointController(name)
• deactivateAndDeleteNJointControllers(vector<name>)
• deactivateAndDeleteNJointController(NJointControllerBasePtr)
• deactivateAndDeleteNJointControllers(vector<NJointControllerBasePtr>)