Device information and management

In addition to listing and filtering devices, the Device Management perspective allows you also to inspect the status and configuration of a particular device, as well as to manage the selected device in terms of managing its features, adding custom attributes to it, adding it to a group, and directly executing the management actions supported by it.

Features having at lease

Select a device from the Devices or Gateways list, upon which the information about it will be shown on the right-side views. The top view, called Features and Task Executions Info, will list the available device features and the mass management tasks in which the device has been involved. The bottom view, called Device Info or Gateway Info - depending on the device type, will show the basic properties of the device.

images/confluence/download/attachments/1164397777/Gateway-Info.png

The Features and Task Executions Info view is further divided into two sections. As their names suggest, the Features section displays all features defined for the selected device, and the Task Executions section displays all tasks in which it has been involved so far. Each section is explored in detail below.

Features

The Features section is expanded by default.

To find a particular feature more easily, you may use the available filtering options - Filter by Vorto model or Filter by ID, which is not case sensitive.

The Filter by Vorto model field provides a combobox which displays a list of all the Vorto models of all the features defined for the respective device. When you select a Vorto model from it, the list of features that appears will be filtered so as to show only those features which have the selected Vorto model.

images/confluence/download/attachments/1164397777/Features-Filtering.png

Make sure you are viewing the feature through the perspective of the most relevant Vorto model. Go to the Filter by Vorto model combobox and select the model whose properties you are going to set for this feature. Then select the feature itself.

As each feature may have zero, one or several Vorto models with different levels of detail, the system loads the most detailed model by default. However, if for some reason this model cannot be found, the system will move to the next one available for this feature.

Features having at least one Vorto model are marked with images/confluence/download/thumbnails/1164397777/dm_di_vorto_feature.png , whereas features without any Vorto model - with images/confluence/download/thumbnails/1164397777/dm_di_non_vorto_feature.png . If you hover over a feature, you will see its corresponding script as a tooltip, which you may copy.

When you select a particular feature, the console will open the Features Info Properties view below, where you can see all properties already defined for this feature. By default, the Features Info Properties view opens in table view. In it, all feature properties are represented according to their format - simple key-value properties, JSON or map.

You can switch between table view and tree view with the button images/confluence/download/thumbnails/1164397777/Tree-Mode.png .

images/confluence/download/attachments/1164397777/Features-Info-Properties.png

Feature actions

If the feature's Vorto model defines any actions, the Actions Info panel will be populated with buttons for all actions that can be called on this feature directly by just clicking them. When you hover over any of these buttons, you will see a short description of the action, as well as its corresponding script. The rightmost button allows you to copy each such script. You may include these scripts in the definition of actions for mass management tasks and rules.

images/confluence/download/attachments/1164397777/dm_di_feature_actions_with_copy.png

When you call any of these actions, a dialogue will appear once the action has been executed. It will display the name of the action, on which feature it has been invoked, and the response, if any.

images/confluence/download/attachments/1164397777/dm_di_result_dialogue.png

If the Actions Info panel does not list any actions, see the next section - Set Feature Properties.

Set feature properties

Instead of invoking an action on a feature through the respective buttons in the Actions Info panel, you can change the feature's property values directly - without executing the script of the respective action. The different ways to do that will be explained below.

Device features have a current state and a desired state.

The current state represents the properties and their values currently reported by the device. The desired state, on the other hand, reflects the desired properties and values that you, or an application respectively, wish to apply on the device, for example in order to change its configuration or behavior. In order to set the properties of a device, it should be online - otherwise you will get a timeout error. However, if you set the properties as desired, they will be persisted in the desired state of the feature and will be applied when the device comes online, unless the device rejects them.

Non-writable properties can be set only as desired properties.

Set writable properties

With writable properties, there is a Set button to the right of each field. When you select or enter a new value for a property, its Set button will become active.

images/confluence/download/attachments/1164397777/dm_userGuide_setWritableFeature.png

Every time you click the Set button, there will be a a pop-up - the Property change options dialog as shown on the screenshot beneath.

images/confluence/download/attachments/1164397777/Property-change-options-dialog.png

There you can choose whether the change should affect:

  • only the digital twin of the device (Change twin), or

  • the physical device (Send to device). If the physical device supports the command it may also set the property in its digital twin.

For example, if you want to change the state property and you choose the Send to device option, you will be calling the $set.state command - if this property does not have a category; $set.configuration/state - if this property's category is configuration; and $set.status/state - if this property's category is status.

  • as a third option, you may also save the new value as the desired state of this property (Save as desired property).

Set non-writable properties

If the property is not writable, the button to the right of its field will be Set as desired instead of just Set, and the tooltip will remind you of the specifics. When you enter a value in the respective field, this button will become active, as on the screenshot below. Click it to set the property value as desired.

images/confluence/download/attachments/1164397777/Set-as-desired.png

With complex properties which have nested structures, for example such in JSON format, each nested property that you are trying to set as desired will be sent as a separate request and only it will be updated, rather than the whole JSON structure.

For them, you will get a warning dialogue as on the screenshot below.
images/confluence/download/attachments/1164397777/dm_userGuide_setComplexPropsAsDesired.png

Property formats

Properties are displayed differently depending on their type and based on that the console allows you to invoke different actions on them, as explained below.

Simple key-value properties

For property fields where you have a combobox, or where you can enter some number or text, you will have only the Set or respectively the Set as desired button.

images/confluence/download/attachments/1164397777/dm_userGuide_features_setProperty.png

JSON properties

For JSON properties, you can edit the JSON schema directly, and will have Set/Set as desired and Reset buttons.

images/confluence/download/attachments/1164397777/dm_userGuide_features_jsonPropertyChange.png

Map properties

For table/map properties, you will have:

  • an Add button in order to add a new line, which you should then type manually,

  • a Remove button – to remove a particular line,

  • a Reset button – to remove all changes that have been made on this property and return to its old state, and

  • a Set/Set as desired button - to set the whole map.

images/confluence/download/attachments/1164397777/dm_userGuide_features_mapPropertyChange.png

Manage features

You are allowed to Create, Edit and Delete features, using the following buttons respectively:

images/confluence/download/thumbnails/1164397777/Manage-Features.png

You can also copy a feature's script through a right click on a feature, as explained at the end of this section.

Clicking Create Feature will open a wizard where you need to fill in an arbitrary Feature ID and add a Vorto model ID in the definitions section (see screenshot). The Vorto model ID should follow the standard convention for Vorto models, in particular namespace:name:version. It should be the ID of an existing model or one that is expected to be created, in order to benefit from the capabilities defined in it. Check the Vorto GitHub repository for any models that may be suitable for you. When searching for Vorto models in the repository, you have to select the Functionblock option in the TYPES combobox.

images/confluence/download/thumbnails/1164397777/Functionblock.png

For example, try with the Geolocation model that you see on the screenshot.

You may also optionally define any additional properties with their values and categories (property types) in the properties section below. The property type can be either status or configuration, and is also not mandatory even if you add a property and its value.

Confirm with Create.

images/confluence/download/attachments/1164397777/Create-a-Feature.png

Clicking Edit Feature will open a wizard with the same information, where you can add, remove and change definitions and properties.

It is also possible to edit a feature directly from the Features Info Properties view described above (see Features), without having to use the Edit button.

Clicking Delete Feature will ask for your confirmation before deleting the feature completely.

You also have the possibility to Copy the script which you see when you hover over a feature. Right click on the feature of interest and select the Copy script button from the menu.

images/confluence/download/thumbnails/1164397777/dm_di_feature_right_click_menu.png

Clicking Copy script will open a dialogue with the feature script in a format which allows you to copy it. You may include such scripts in the definition of actions for mass management tasks and rules.

images/confluence/download/thumbnails/1164397777/dm_di_copy_feature_script_dialogue.png

Task executions

Within the same Features and Task Executions info view, you can expand the Task Executions section to find quickly all mass management tasks in which the particular device has been involved. All such tasks will be listed as you see on the screenshot below and you can expand each of them for further execution details such as start and finish times, etc.

Double click on a partial execution result (the innermost level) to open a Task Details view below with further information such as action script, origin, etc.

images/confluence/download/attachments/1164397777/dm_di_task_executions_view_partial_executions.png

Your current Task Details view will only change when you click on another partial execution, so make sure that you don't just click on another task from the list but rather expand it and click on its relevant partial execution.

Further details are available at Switching between Monitoring Levels.

Device/Gateway info

The Device/Gateway Info view contains device-related information such as:

  • Display Name - The name you choose to be displayed for this device, which may differ from the Device ID which you provided during device registration.
    You can only set it through the Developer Console (Things Section>Attributes>Info Attribute). This field will not be available on all devices.

  • Device ID - The unique ID of the specific device including the namespace of the current subscription.

  • Is Gateway - This value is either true or false and is set automatically based on the provisioning information.

  • Policy ID - The ID of the policy. If not specified explicitly it will coincide with the Device ID.

  • Path - Shows the directory where the device is located, if you place it in a particular directory group.

  • Tags - All tags attached to the particular device.

  • Created - Shows when the device was registered in the system.

  • Modified - Timestamp of when the device was last modified.

  • Revision - Shows how many times the device has been updated.

images/confluence/download/attachments/1164397777/dm_gs_gatewayInfo.png

Attach/Move Device button - lets you attach a device to a specific directory or move it from one directory to another. Select the desired target directory and click OK.

Tag Device button - lets you attach a tag to a device. Enter the name of an already existing tag. If it doesn't exist yet - create it first and then attach it to the device.

Attributes

The Attributes section contains all attributes assigned to the particular device during the device provisioning or later on.

To add a new attribute to the device:

  1. Click the Add Property button -

    images/confluence/download/thumbnails/1164397777/dm_di_.png
  2. On the dialogue that appears, choose the relevant format from the combobox - either a key-value pair in plain text, or a JSON which should contain a path field and a value field.

  3. Depending on the chosen format, write the new property and its value in the corresponding fields.

  4. Click the Save - images/confluence/download/thumbnails/1164397777/dm_di_save.png (if not saved you will receive a Save resource reminder).

  5. If you need to edit a property, use the Edit Property icon - images/confluence/download/thumbnails/1164397777/Edit-Attributes.png and also save your changes. This icon is active only in Tree Mode, whereas in table view you can directly type in the relevant field.
    You can switch between Tree Mode and Table Mode with the images/confluence/download/thumbnails/1164397777/Tree-Mode.png icon.

images/confluence/download/attachments/1164397777/Table-mode.png

Attributes displayed with a grey background in Table Mode are reserved and are not editable.