unCoreInternals 9.2.1
Multiple Command Tool Documentation for Devices

Introduction

A prototype panel called unSetMultiDeviceValue.pnl was developed in 2013 to be able to send commands over multiple devices that have the same type. The original request came from Cryogenics and the idea was to be able to send a global command to a user preselected list of devices, instead of having to select and send the command to each device individually. However, the prototype was never used within the UNICOS framework, and remained unknown for many, if not all the UNICOS users.

The initial developed prototype worked for some specific devices and types, but presented too many limitations and risks, too much redundant and unnecessary code from the unSetDPEConfigs.pnl panel, and some bugs that had to be addressed first. Therefore, an understanding of the functionality of the panel and a refactor was required before trying to improve and deliver the functionality to the UNICOS users.

Access to Devices – First Limitation

The first reported limitation is that the access to the devices must be checked for the user operating with the multiple command tool. This is crucial, because if access is granted to a user that does not have the appropriate access rights, then commands can be sent to devices that must not be accessed, creating a security breach and potential serious risks.

There is a proposed solution for the first limitation by changing the use of the function unSelectDeselectHMI_select that selects/deselects devices without checking the access rights, by unGenericObject_selectDevice and unGenericObject_ButtonSelectAction. The unGenericObject_selectDevice function checks if the state of the device is ready to be selected and if the user has the rights for it. If the conditions are met, then the access to that device is granted. The unGenericObject_ButtonSelectAction function is only used to deselect a previously selected device.

Buttons to send global commands - Second Limitation

The second reported limitation can be divided into two parts: the state of the buttons (enabled/disabled) for each device and knowing which button has been clicked for the list of devices.

  • For the state of the buttons, we do not have a function to determine if an individual button is enabled or disabled for a device. This is important, as knowing if a command can be sent to a device or not should depend on the status of the button. The problem is that in the code dpSetWait is used, which bypass the enable or disable limitation, and creates potential harm and risks for the selected devices.

    Some functions like unGenericButtonFunctionsHMI_isAccessAllowedMultiple exist to know the list of actions that are allowed for a particular user, but this does not have in consideration the state of the buttons and the device.

    So, to summarize, we know which buttons can be accessed for a user, but not know which buttons are enabled or disabled for a device.

  • The second problem is that the button that was pressed is unknown to the list of selected devices.

    A potential solution for this would be to use a global variable that is populated in each button when clicking on them to know which action was triggered. Then, this global variable would be used to determine if the action is in the list of the allowed actions for the user that has requested it (unGenericButtonFunctionsHMI_isAccessAllowedMultiple), which is doable, and if the button associated to the action is enabled or disabled in the command module, which is not possible at this moment.

  • An additional issue is that the buttons populated for each device might be different. Also, the state of each device is not the same, which means that the buttons state and availability to send commands must be different as well.

Mock device vs First selected device in the list

  • In the original prototype, a mock device is created for each device type when clicking on the Build Selection button. This mock device is used to propagate the global command by clicking on a button to the list of devices selected.

    The issue using a mock device is that the predefined buttons displayed on the command module area is the default one, which might not be the same for the devices that have been selected on the list. Also, the buttons that are enabled or disabled vary from device to device, therefore the mock device might not have available some of the buttons that all the other devices in the list have.

    Having a mock device can also be confusing for users, as this device can be observed from the device tree overview. This can create a risk of sending a multiple command to a preselect list of devices if the unSetMultiDeviceValue.pnl panel is open.

    The new code update for unSetMultiDeviceValue.pnl using the mock device is in the Gitlab branch UNCORE-253.

  • The alternative to the mock device is to create a device list using the first selected device to propagate the global command to the rest of the devices. The advantage of this is that a mock device is not created, and the users are not confused by it. The sending command process is slightly quicker, and the code is simpler, easier to understand and maintain.

    The buttons that are displayed on the command module to propagate the commands are the ones that belong to the first selected device. This means that the buttons for the current device type might or might not be the predefined buttons depending on the user configurations, which is an advantage. However, buttons that are enabled/disabled still vary from device to device and at this moment, there is not a simple way to determine which buttons are enabled and which buttons are not for each different device.

    The potential risk by using this approach is that when the unSetMultiDeviceValue.pnl panel is open, any change to the *.ProcessOutput.ManReg01 datapoint element of this ‘first’ selected device will be propagated to the list of selected devices. Therefore, there is a risk of sending an unintended multiple command to the preselected device list. This risk is more significant than using the mock device, as the mock device does not exist, i.e., it does not have a hardware associated to it, so an unintended automatic change in *.ProcessOutput.ManReg01 cannot happen there.

    The new code update for unSetMultiDeviceValue.pnl using the first selected device is in the Gitlab branch UNCORE-253_Bis.

Explanation of the functions

The original unSetMultiDeviceValue.pnl was a copied of unSetDPEConfigs.pnl with some extra functions and variables to send multiple commands. After the refactoring, the main functions work as follows:

  • DeviceTable - SelectionChanged event: Enables or disables the BuildSelection button according to the user rights for the panel, and the list of selected devices.
  • BuildSelection - Clicked event: It gets the list of current devices selected from the list, checks if they have the same type, updates the device log, selects or deselects devices, and calls the connectMultiDevices() function if the list of selected devices is not empty and have the same device type.
  • connectMultiDevices: Disconnects any previous selected devices from connectMultiDevicesCB, and connects to connectMultiDevicesCB to be called whenever there is a change in the *.ProcessOutput.* (*.ProcessOutput.ManReg01) for the mock device or first selected device in the list. The change in this datapoint element occurs when a button in the command module area is clicked, effectively sending the command to this device.
  • connectMultiDevicesCB: It is the function that is triggered when a click in the buttons of the command module occurs. It iterates over the list of selected devices checking that the devices are accessible by state and user (by using the function unGenericObject_selectDevice, which determines whether a device can be selected or not), and updating the *.ProcessOutput.ManReg01 datapoint element of each device by using dpSetWait with the command that was sent to the mock or first selected device. The connectMultiDevicesCB also calls the action progress bar at the beginning, and once more at the end to close the popup window signaling the user that the multiple command that was sent over has finished the process.
  • updateButtons: Enables or disables buttons for a user according to what has been defined in the File Access Control configuration.
  • showSelection: Displays the selected devices list in the log. It also shows the processing progress bar.