WebUI/web interface

General

The network module includes an integrated web interface for accessing detailed device information and for configuration.

Prerequisites

To use this web interface, it must be ensured that the module has been integrated in the network correctly. To do this, the IP subnet of the network module must be accessible from the PC on which the browser is being operated.

Browser

The web interface is compatible with newer versions of Google Chrome, Firefox or MS Edge.

Connection setup

• To establish a connection with the web interface, enter the IP address of the BNI module in the browser’s address bar.
  ⇒ WebUI starts with the homepage, which displays the most important device information (see Homepage).

Navigation bar

In the top window area, there is a navigation bar which enables you to switch between the different dialogs of the web interface by clicking on the corresponding icons:

• Homepage (see Homepage)

• Condition monitoring (see Condition Monitoring)

• Diagnosis (see Diagnosis)

• Settings (see Settings)

• Notifications (see Notifications)

• User menu (see User profile)

User profile

Click on the user icon to open a user menu:

• Select Help to view device-specific information and documents (see chapter Information/documents).

• Select the national flag/language to make a language selection (see chapter Language selection).

• With Login a user logs in (see Logging in and logging out).

When logged in, users with the ADMIN role can also see the user management (see User menu (logged in)).

Users with the EXPERT or USER role will see the entry Edit profile here instead, through which the respective profile can be viewed and, if relevant, edited.

Information/documents

Click on Help > About to view device-specific information and documents.

Use the dropdown menu under Online documents to select different online documents, such as manuals, and click on them to open in a new window.

Language selection

The languages German and English are supported. Click on the languageGermanorEnglishto select the language.

User Management (ADMIN)

Select User Management to open a view of the stored users. Information on the user status (active/inactive), the user name, user information, password and its confirmation in hidden view, as well as the user’s role is specified.

Authorizations are role-dependent:

Click on the pen icon to edit fields and buttons.

Click on the information icon in the password field to open a dialog box and view the requirements for a secure password.

A user with the ADMIN role can delete users with the EXPERT or USER role by clicking on the recycle bin icon.

Click on + (Add new user) to add new users and confirm with after entering the corresponding information.

Edit profile (EXPERT/USER)

Users with the EXPERT or USER role can view and, if relevant, change their profile via Edit profile. Only the relevant profile is displayed. EXPERTs and USERs can only change their own user information as well as their own password, but not their role or name. EXPERTs and USERs cannot make any profile deletions.

Logging in and logging out

To make configuration settings on the network module via the web interface, you must first log in with the EXPERT or ADMIN role. Logging in with the USER role activates further dialogs in view-only mode. The user icon indicates the current status.

Login

1. Login (see User menu (not logged in)) opens the login dialog.

   

2. Enter the login details and click on LOGIN.

Each device has its own default password for the admin user. It is printed on the side of the device and is only used for the first login, or it is required when the network module is reset to factory settings.

As soon as the password for the admin user is changed, it is no longer possible to log in with the printed default password.

Log out

• Log out with Logout (see User menu: Language selection).

  Note

  If there is no interaction with the WebUI for more than five minutes, the user will be logged out automatically.

Homepage

The homepage shows information about the network module itself and its network activity. It also shows whether the configuration lock has been activated via the control unit (PLC).

Port overview/configuration

If an IO-Link device is connected to one of the configured IO-Link ports, the module data at the ports and the device data are displayed in buttons on the left-hand side of the figure. After one of these buttons is selected, the corresponding port dialog opens. The default value of the displayed DeviceAlias is adapted to the labeling on the front.
The port numbering always starts at 1, even if the labeling on the front has a different port designation depending on the product variant. This is due to the relevant definition of port numbering in the IO-Link specification and the IO-Link/JSON specification (JSON Integration for IO-Link, Karlsruhe, 2020). The designation of the front label is reflected in the process data layout as well as in the description file (GSD).

Device Status

Some devices (including from external providers) supply the device status defined in the IO-Link Spec. In this case, it is displayed on the home screen. On the homepage, details can be called up by clicking on the icon in the port (see Fig. 8-13). Products that do not supply the device status show a gray control box here.

Opening the port dialog

• Click on the corresponding port field to select the desired IO-Link Port.

  

• Alternatively, select the target port via the breadcrumb navigation in the header.

  

Ports dialog

Click on the expand symbol of a closed tab page to view e.g. information on relevant ISDU parameters. Information that is not currently required can be hidden by clicking on the collapse symbol .

General Information

Under General Information, you can find manufacturer information as well as other general information on the current module. Under IODD, you can see whether a suitable IODD for the IO-Link device connected to this port is uploaded to the network module.

If this is not the case, click on Upload IODD to access the Settings tab page. Based on the connected IO-Link devices, the corresponding device description can be selected for upload.

Process data

Under Process Data, interpreted data is only shown if a suitable IODD is saved. To display the data more clearly, information from the device’s IODD is used here. So, in IODD Interpretation, you can see not only the input data of the example sensor as a hexadecimal number, but also interpreted under Input and provided with corresponding labels from the IODD.

In the Set process data area, the output process data of an IO-Link device can be set manually. The Validity Qualifier can be used to specify whether the process data should be marked as valid or invalid (PD valid).

Parameter (IODD)

Under Parameter (IODD), the device identification data of the IO-Link device is displayed in a table when the Identification tab page is selected (e.g. Dialog view after clicking on Read all or, for each subindex, on Read). The corresponding texts are saved in the IODD.

The input values can either be read out from the IO-Link device individually for a subindex by clicking on Read or for the entire tab page via Read all. A successful request is indicated by a green bar on the right-hand edge of the relevant table row.

The Application Specific Tag is an application-specific field in IO-Link devices and, in the current example (see Application Specific Tag), can either be read out from the IO-Link device with Read or can be individually configured by clicking on the gray input field with the same name and described with Write (provided the required write authorization exists). It is also possible to enter a company-internal device name in this field.

If the IODD of the IO-Link device at the currently selected port also has parameters, these are also displayed in the form of a table (see Ports dialog figure). Similarly to the process for device identification data, parameter values and associated texts from the saved IODD can be configured, depending on the parameter, via Read or Read all.

If available, click on the ▼ icon to open a dropdown list and select a value or select a value within a specific range and confirm with Write.

If there is no Read button next to subindices, these indices cannot be processed individually, but only as a complete index.

ISDU Parameter

Configuration parameters of the IO-Link device can be read and written via the ISDU Parameter option. The parameter indices and subindices of the IO-Link device follow the IO-Link conventions and are described in the corresponding user’s guide.

Parameter indices and subindices can be entered both in decimal and hexadecimal format, while data can only be entered in hexadecimal format.

An input is confirmed with Set or can be rejected with Delete.

Events

Under Events, you can see whether there is a diagnosis event from the IO-Link device.

The events can be displayed in ascending or descending order. The list of events can be updated via further options of the Events card or can be downloaded in CSV format.

LEDs

The LEDs of the network module display information on the current process data and the module status. The meanings of the LEDs can be viewed in a legend.

Opening the LED legend

• At the LED legend, click on OPEN.

  

  ⇒ The legend appears.

  

Condition Monitoring

Click on the corresponding icon in the navigation bar (see Navigation bar) to open the Condition Monitoring dialog.

Module values

In the top section, you can see the condition monitoring values of the module that are not specific. These relate to the entire module. The values in the top area are refreshed automatically every 10 seconds.

Electrical values

The table on theElectrical Valuestab page shows the available values for current consumption and power draw at the individual pins of the different ports.

Diagnosis

Click on the corresponding icon in the navigation bar (see Navigation bar) to open the Diagnosis dialog. The Diagnosis dialog provides general service information about the device and a logging function.

The Status tab page contains information for all service requests, while the Activity Log tab page contains a table view of the log information. The information can be printed as a PDF by clicking on the printer icon (e.g. for a service request).

Information

Via the Information item, you can view information about the device, such as the browser version used or the system operating time.

Activity log

The Activity log displays events in their time dependency and is an important tool for detailed troubleshooting in plants.

The expanded Activity Log tab page provides a table view of the log information, which can be sorted by numbers. The log information consists of a note regarding the severity, a date stamp, information on the origin and the log message itself.

Events are classified via the Severity column:

• Internal error (Emergency, Alert, Critical)

  The network module has found an internal defect (hardware or software), which should not normally occur. If this occurs, the module must be maintained or replaced.

• External error (Error, Warning)

  The network module has found a potentially impermissible event, which is affecting the module from outside. Troubleshooting in the system might be necessary.

• Event (Informational, Notice)

  The network module has found an important normal operating event (such as configuration actions via the web interface and other configuration interfaces, which are recorded) and reports it.

Under additional options () you can access more actions for the log (the log entries are saved in a ring buffer):

• Refresh

• Download CSV

• Clear

Settings

The Settings dialog enables the configuration of connected modules and IO-Link devices. Click on the corresponding icon in the navigation bar (see Navigation bar) to open the Settings dialog.

General settings

General settings such as the name of the module, the module time and security configurations can be made under General.

Settings can be applied by clicking on SAVE and permanently stored in the device.

RESTART restarts the module (like switching the power supply off and on).

RESET TO FACTORY SETTING completely deletes the configuration saved in the device and them performs a reboot. The device is reset to the delivery state.

Manually setting the module time

1. Under General > Module time, either click on the calendar icon or use the Set from PC dialog to transfer the current browser time to the network module.

2. Apply the settings with SAVE.

   Note

   The module time is not permanently stored. After a reset, reboot or power, the time will be reset to the factory setting.

Retrieve module time automatically

An NTP server can be configured from which the time is automatically retrieved.

• Under General > Module time, select the option NTP server activated.

• Under Synchronization interval, select how often the time is retrieved from the NTP server.

• Enter the IP address of the NTP server under NTP server address (internal URLs are not supported).

• Apply the settings with SAVE.

Making security configurations

The following security settings for the REST API interface can be made using the security configurations.

Soft Session Timeout

Defines the time in seconds after which a user is logged out in the event of inactivity.

Hard Session Timeout

Defines the time in seconds after which a user is logged out, even if they are active.

Minimum Password Length

Defines the minimum required password length for newly created users.

Rest API Security

Activates or deactivates authentication when using the REST API directly. If deactivated, it is no longer necessary to log in and send the session token and cookies with a request. All requests have the rights of the ADMIN user.

Make network settings

Under Network, the IP Address, Subnet Mask and Gateway Address fields can be reset separately via the FACTORY DEFAULT button (see HTTP server settings).

The Storage setting can be used to select how long the new network configuration should be valid.

Permanent

Saves the settings after a restart.

Temporary

Saves the settings until the next restart (factory setting).

The factory settings then apply.

HTTP server settings

HTTP server settings can be used to enable or disable unencrypted and encrypted communication with the web server using HTTP(S).

Change protocol

The active fieldbus protocol can be viewed and changed in the sectionFieldbus Protocol.

I/O ports

Via the I/O Ports dialog, the ports of a module can be displayed and configured.

Select Set configuration for all ports to set the IO-Link [Autostart], Digital In and Digital Out configuration modes to the desired mode for all ports.

Click on SET ALL to open a dialog window in which the action can be confirmed or canceled. With a corresponding selection, the message I/O port configuration(s) successfully saved appears in the bottom part of the website.

The ports can also be configured individually. The inputs are confirmed with SAVE or reset with UNDO.

The following parameters can be configured (see IoT):

Device Alias

name of the device that shows what function the sensor executes (e.g. rear left end switch, temperature at boiler floor, etc.)

Modus Pin 4

selection of the actuation (e.g. Deactivated, IO-Link [Manual], IO-Link [Autostart], Digital in or Digital out. Depending on the selection, further dialog fields open, which require an input (e.g. when the IO-Link [Manual] option is selected).

Validation and Backup

Settings see Validation and backup.

Cycle Time

if the IO-Link [Manual] or IO-Link [Autostart] options are selected for point Modus Pin 4, the desired communication cycle can be set by selecting the corresponding value from the dropdown list.

Modus Pin 2 (CLASS_A)

selection of the options Digital in or Digital out.

Current pin 2

Maximum current at which the pin switches off. Can only be configured if the pin is configured as an output.

Current pin 4

Maximum current at which the pin switches off. Can only be configured if the pin is configured as an output.

IoT

The IoT settings of the device can be made via the IoT dialog.

MQTT client settings

The BNI features a MQTT interface that allows parameters and product information to be called up. The BNI acts as a MQTT client whose messages are sent cyclically. For events, the BNI sends messages to a MQTT broker (PUBLISH). Other MQTT clients, e.g. applications that store data in an external database, can subscribe to topics provided via the MQTT broker (SUBSCRIBE). Communication is unencrypted and takes place via Port 1883 as standard.

The data sent via MQTT can be used, for example:

• for Condition Monitoring

• as an interface to Track&Trace applications

• for further processing in the cloud

Connection status

The following information can be viewed:

• Status: Indicates whether the client is connected or there is an error.

• Address: Displays the address of the broker to which the client is currently connected.

• Uptime: Displays the elapsed time in seconds since the connection was established.

IODD status messages

Indicates whether the correct IODD could be found and loaded for each device and which value is used for any condition variable. The correct IODD is required to send parsed IO-Link data.

In addition, the IODD can be reloaded manually if a change to one of the ports or the condition variable is not detected.

Client configuration

The following settings can be made:

• Enable Client Enables or disables the client.

• MQTT Client ID Defines the client ID that will be used for the connection.

• MQTT Broker URL Defines the address of the broker. In addition, an individual port can be specified separated by a colon, e.g. 192.168.1.42:1234. If no port is specified, port 1883 is used by default when TLS is deactivated and port 8883 is used when TLS is activated.

• MQTT Prefix Defines a prefix to be placed in front of each MQTT topic (e.g. {prefix}/identification ).

• Keep Alive Defines the keep alive time of the MQTT in seconds.

• Enable encryption (TLS) Defines whether TSL should be used for MQTT communication.

Lastwill

Allows a message to be configured that is to be sent automatically when the client disconnects from the broker. The following settings can be made:

• Topic: Defines the topic of the message.

• Message: Defines the content of the message.

• QoS: Defines the QoS (Quality of Service) level at which the message is sent.

• Retain: Sends the message with or without the retain flag.

Authentication

The following settings can be made:

• Password: Authentication is done with password and username.

• No authentication: The client logs on to the broker anonymously.

MQTT Message Configuration

Among other things, the process data of the connected sensors or the status of the digital inputs and outputs can be sent via MQTT.

In the delivery state all message formats described in the AsyncApi specification are sent cyclically.

This behavior can be adjusted via the Mqtt Message Configuration dialog, e.g. that messages should only be sent in the event of a change or in a fixed cycle.

The following settings can be made:

General

Enables general, port-independent messages to be configured, e.g. the sender of the master’s identification data.

Port 1…8

Enables port-specific messages to be configured, e.g. sending the identification data of a connected IO-Link device or its process data.

The following can be configured for each message to be sent:

Topic

Defines the topic under which the message is published. If the Generate topic automatically option is activated, a user input is ignored and the default path specified in the AsyncApi is used.

DataType

Defines the type of message. The individual types are described in the AsyncApi specification, the operation ID listed there corresponds to the data type to be selected here.

Description

Defines a description text for the configured message. Only serves as an overview and has no other function.

Interval

Defines the fixed interval for sending a message. Either an interval and or the Trigger on change option must be set.

Min. interval

Defines a minimum interval for sending between two messages.

Example:

The measured value of a connected sensor changes every millisecond. A minimum interval of 100 milliseconds is configured. This means that a message is sent every 100 milliseconds, although the value changes more frequently.

Trigger on change

If active, a message is sent each time a change is made. Either this option or an interval must be set.

IODD

Via the IODD dialog, device description files for IO-Link devices (IODDs) and the associated device images can be uploaded to the network module so that a more detailed illustration of the connected IO-Link devices can be provided in the Ports dialog.

Connected IO-Link devices

When IO-Link devices are connected and IO-Link ports are activated, the dialog shows a table with information on the IO-Link devices. The table can be updated by clicking on the refresh icon .

Available IODDs

The available IODDs are listed under Available IODDs and can be removed by clicking on the recycle bin icon, if necessary.

An IODD can be uploaded via the Choose an IODD to upload dialog between the two tab pages.

In order for the automatic assignment of IODDs to connected IO-Link devices to work, the files must be named according to a specific scheme. This is done automatically in the background for IODD files. If an individual image file is selected for upload via UPLOAD FILE, which does not meet the naming requirements, a dialog will open with a corresponding message.

The Connected IO-Link devices bar also displays help in the form of a list of currently connected IO-Link devices as well as the associated, required IODD file name (column IODD Filename).

Firmware

Under Firmware you can see which version of the firmware is being used and when it was uploaded. Via Firmware Upload, you can upload a different firmware version. The installation starts after uploading the firmware file. Only files in bff format are supported.

You can check for firmware updates online via CHECK FOR A NEW VERSION and install an update directly.

Notifications

Clicking on the corresponding icon in the navigation bar (see chapter Navigation bar) opens the notifications.

The notification history can be deleted with Dismiss all.

REST API

Via the REST API interface, identification data, process data and configuration settings of the network module and other connected devices can be requested and modified. The REST API interface is used by the user interface of the web interface for communication with the module.

The specification of the REST API implemented in the module is stored in YAML files in the device and can be downloaded via Help > Documents or viewed and tested via Help > Api documentation.

The present module supports the following REST APIs:

• Generic REST API for Balluff devices and applications. Base path of the REST API in the module: http://[ip-address]/api/balluff/v1/

• The REST API (JSON for IO-Link) standardized by the IO-Link community.

  Link to the official documentation (JSON for IO-Link) in the IO-Link Integration area. JSON Integration for IO-Link (ZIP file).

  Base path of the REST API in the module: http://[ip-address]/iolink/v1/

Some examples below explain how REST-API is applied.

Registration and authentication are required for some calls.

REST Login

Login is possible by entering the following address: http://[ip-address]/api/balluff/v1/users/login.

A JSON object is also specified, in which, as shown below, a user name and password are specified (see Logging in and logging out):

{
  "username": "[username]",
  "password": "[password]"
}

If the login was successful, a bearer token is returned, e.g.:

{
  "bearer": " 7euh07tdfawjej"
}

In addition, a cookie is set that must be sent with each request, e.g.:

{
  "JSESSIONID": "fgaa74a4fa2xdfg"
}

This token can now be used to perform methods that require authentication. For this, a corresponding request must be equipped with the following headers:

• Authorization: Bearer 7euh07tdfawjej

• Cookie: JSESSIONID fgaa74a4fa2xdfg

Requesting the device identification of the module

The device identification data of a network module can be requested via the following address:

• http://[ip-address]/api/balluff/v1/identification

• http://[ip-address]/iolink/v1/masters/1/identification

In the event of a successful request, an answer is supplied in the form of a JSON object with properties such as thevendorID, theserialNumberor thefirmwareRevisionof the respective network module.

Requesting port information

All relevant configuration and status data for all IO ports of a module can be requested via:

http://[ip-address]/api/balluff/v1/ports/information

Requesting an IO-Link device parameter (applicationSpecificTag)

Device-specific parameters can be requested via the following addresses:

• http://[ip-address]/api/balluff/v1/devices/identification

• http://[ip-address]/iolink/v1/devices/[deviceAlias]/identification

A request via the generic REST API is the bulk version of the identical request via JSON for IO-Link.

In the case of a request via JSON for IO-Link, a deviceAlias is also specified. This corresponds to the device designation that must be configured previously. The standard device designation is Port_Xyz, with yz representing the port number (e.g. Port_X00).

In the case of successful execution, a JSON object with parameters such as vendorID, productName and applicationSpecificTag is supplied as a response.

Setting an IO-Link device parameter (applicationSpecificTag)

Device-specific parameters for connected IO-Link devices can be set via the following address:

http://[ip-address]/iolink/v1/devices/{deviceAlias}/parameters/{index}/value

The deviceAlias corresponds to the device designation of the IO-Link device (e.g. Port_X00). The index reflects the ISDU parameter variable to be set in the IO-Link device. In the case of the applicationSpecificTag, this would be the value 24.

To set values, a JSON object must also be specified, in which corresponding parameters and values are specified as in the following example:

{ "value": [
49,
50,
51,
52,
53,
54
]}

In the case above, parameter 24 (applicationSpecificTag) was described with the ASCII string "123456".

Successful execution is not confirmed in the form of a JSON object, but with a Code 204 (Successful operation).

Setting a master parameter (sysName)

A master parameter, such as SysName, can be set via the following address: http://[ip-address]/api/balluff/v1/

A JSON object with the corresponding information must also be specified:

{
  "sysName": "[SysName]"
}

Successful execution is not confirmed in the form of a JSON object, but with a Code 204 (Successful operation).