Modify Device(s) in DeviceHub for One Litmus Edge
To modify Device(s) with Litmus Excel Add-ins, you should be familiar with how Devices work in DeviceHub on Litmus Edge.
Before You Begin
- You have installed the Litmus Excel Add-ins extension. See Install Litmus Excel Add-ins for details.
Initial Preparation
Open a new Device Management Tool File in Excel.
If prompted, Enable Content to allow the code to run.
Make sure the the tool is set to One LE for the Connect To option.
Modify Device(s)
Import Devices
Import the Device Settings for devices defined on Litmus Edge using the Import Device(s) Wizard.
Users can set a filter to reduce the number of devices shown as selection to the user.
- Search Option: Select what type of filter is to be used
- Device Name Mask: Set the filter to be applied. Will be ignored if Search Option is set to ALL
- The wizard will show what filter will be applied.
- Press the Search button to pull the filtered List of devices from Litmus Edge.
- The user will be shown the filtered List of devices matching their filter.
- Select the Devices to import and press the Import button.
Notes:
Users can choose between:
- Press New Search to set another filter and search again if the list doesn't show the devices the user wanted to import
- Select All Devices using the Checkbox in the Header Row.
- Select a Group of Devices by selecting their respective Check Box
- Select one Device by selecting the respective Check Box
- Select No Device and close the Wizard pressing the Close button instead.
- The selected device(s) with their settings are imported into the sheet. Once finished, the user can either.
- perform another search using the New Search button
- finish the import using the Close button
- The Action for each imported device is set to M for modify.
Mandatory Device settings
Users can modify these mandatory settings for a device
Device Name: The Name of an existing Device can be changed.
Important: This will change the topic for all Tags and will cause other services like Analytics, Integrations or Flows not be able to read the data
Device Properties: are a mandatory set of Device Settings, which are populated initially with a set of default values. To connect to your PLC, you will have to provide your specific device properties settings instead. Which you can provide through one of two options.
- Option 1: You can provide your specific Device Properties directly through the Formula Bar or through the cell. You will need to be careful to not remove any of the Key-Value pairs as well as keeping the JSON formatting accurate.
This allows you to edit the Device Properties without the risk of potentially invalidating the JSON Object.
Modify any of the not mandatory settings as needed.
Notes:
You can repeat modifying mandatory and not mandatory for every device you need to modify before executing any Action.
Executing Actions
When all mandatory and not mandatory settings for all device(s) are set, they are ready to be modified.
It is Recommended but not mandatory to verify the configuration first without executing the Action by pressing the Verify Only button.
This will check that all required Device Settings are provided and logically correct. And provide any finding to the user. Example: Below the user did select to have Meta Data but did not provide any.
Important: The tool can not verify if all provided device settings are factually correct. For example it can not verify that the network address provided for the PLC is the correct IP address.
The Device(s) can be modified on Litmus Edge by pressing the Verify + Execute button.
This will check that all required Device Settings are provided and logically correct. And provide any finding to the user. If no issues have been identified, the tool will verify that the user wants to execute ALL the actions from the Action Column:
- A: Add Device(s)
- M: Modify Device(s)
- D: Delete Device(s)
- I: Ignore Device(s) -> do nothing
To perform all actions, press the Yes button.
The Tool will perform ALL Actions row by row. When finished, a result Summary is shown. Close the Result Summary by pressing the X close button.
The tool will ask if the user wants to re-compare the Device(s) against Litmus Edge. To re-compare, press the Yes button. To not re-compare, press the No button.
If the User selected to press the Yes button from aboves messagebox, the tool will pull all the device settings from Litmus Edge again including the DeviceID and also change the Action to M for each Device with a DeviceID.
Not Mandatory Device Settings
Each Device has a number of not mandatory Settings which can be used to meet specific needs.
- Device Description: A short description of the device.
- Enable Meta Data: Select if you want to add Meta Data to the device.
- Meta Data: Provide a JSON Object which holds all the Meta Data you want to add to the Device. See Organize Device and Tag Data by Using Metadata to learn more. It is recommended to use the Meta Data Wizard.
- Enable Status Register: Select if you want to add a Status Register which is used to monitor if the Device is reachable instead of the Default status check mechanism.
- Status Register: Provide the Register definition as a JSON Object. It is recommended to use the Status Register Wizard.
- Enable Alias Topics: Select if you want to substitute long, unreadable device and tag IDs with human-readable device and tag names in topic names
- Enable Logging: Select if you want to enable the Logging option for Gen 2 drivers. Note: For Gen 1 Drivers this option is unavailable.
- Data Store Retention Period: Provide the number of hours the data are to be stored.
- Optional Settings: This provides a JSON Object which allows users to set settings like:
- Publish on Polling Interval: Select if for Gen 2 drivers the driver will always publish messages according to the polling interval configuration.
- Publish Additional Attributes: Select if for some Gen 2 drivers (OPC UA, BACnet, DNP3, Modbus) additional information such as Source Timestamp, Server Timestamp and Status Code It is recommended to use the Optional Settings Wizard.
Troubleshooting
The Tool will perform several checks throughout the proces of defining the device settings. If they do not pass successfully, the user will be notified. The checks include:
- Device Name uniqueness.
- The tool checks if a Device Name already exist in the Tool.
- The user is shown a message box as notification.
- The character(s) are highlighted in red and also shown in a note.
- See Allowed and not allowed Ascii Characters for Names and Descriptions for a full list for both Names and Descriptions.
- Correct JSON formating for Device Properties, Meta Data, Status Register and Optional Settings.
- Example for an invalid JSON formatting of the Device Properties
- Valid entry for Data Store Retention Period to be a number and withhin allowed range
- Example for an invalid entry for the Retention period
- Do exist JSON Key-Value pairs in columns Device Properties, Optional Settings or Status Registers with a value being:
- empty
- null
- empty array "[]"
- empty JSON Object "{}"
- Are the columns Device Properties, Optional Settings or Status Registers empty. If they are, the default JSON Object will be automaticlly added.