IMST iOKE868 Optical Reading Head User Manual

IMST GmbH
Carl-Friedrich-Gauß-Str. 2-4, D-47475 Kamp-Lintfort
WS Configurator
User Manual iOKE868
Version 1.6

iOKE868 Optical Reading Head

Document State
final
Date
September 2023
Document ID
4000/40140/0162
© 2023 IMST GmbH – All rights reserved
User Manual iOKE868
History

● updated detect Obis Ids
● updated meter values
1.4| February 2022| ● LoRaWAN® options for experienced users added
1.3| October 2021| ● Device information changed
● Meter protocol adapted
1.2| January 2021| ● System options adapted
1.1| November 2020| ● Firmware update added
1.0| September 2020| Initial Version

Introduction iOKE868
The WS-Configurator Tool is used to configure the iOKE868 easily. The detailed configuration options are described below in detail.

Installation

WS-Configurator is designed to be executed from any location without the need to install the software.
To run the application choose the ZIP archive matching your operation system from the list of available packages. Unpack the archive to a location of your choice. During this process a new directory WS-Configurator is created and all necessary files are copied into it. Afterwards start the application by executing the WS-Configurator binary file.

Software

After startup, the interface of the WS-Configurator consists of only a few elements. To unlock the full range of options, the application must be connected to a device by selecting the target connection from the list of available connections (1) and by clicking the connect button (2) afterwards. The question mark (3) leads to the “Configuration” and “About” page.

Only devices already connected at start up time are listed as auto connection! See chapter “Connection management” for further informations.

Overview – iOKE868
When there is an active connection to the device, various options are available on the left-hand side of the application.

Those values are readonly.
| Configuration| Summary of all changeable operating parameters.
| Meter values| Overview of the last received meter values.

By clicking one of the icons, the right-hand side of the application changes and represent appropiate view. Further information can be found in the following chapters.

Device information – iOKE868

The first view that can be seen after connecting the device is the Device information view. All important device information are summarized here at a glance.

Firmware (1) and Device (2) information
These fields provide an overview of the Hard- and Software the device is composed of. The informations could be used to check for new firmware updates or to get in contact with our support team.

Device status (3 – 7)
The summarized status information of the device at the time the status was requested.

time was synchronized at last.
Meter data read ok (IR)| This counter shows the number of correct received data-packets over IR from the meter.
Meter data read failed (IR)| This counter shows the number of failed IR meter data readout.
Meter data sent (LoRaWAN)| Counter for number of send LoRaWAN payload with IR meter data.
Reset Counter| Number of resets / power cycles since delivery.
LoRaWAN activated| LoRaWAN is activated.
Network time synchronized| Time is synchronized over LoRaWAN.
System time synchronized| Time is synchronized locally.
LoRaWAN configuration available| An LoRaWAN configuration is set up.
OTAA pending| The iOKE868 tries actually to join the LoRaWAN network.
Calendar list empty| No events are set up in the calendar. Please set up in minimum one.

To check the actual status press the icon

For resetting the three meter data counters press the reset button.

Meter protocol information
This feature is available from firmware version 1.2 of the iOKE868.

If the meter protocol is set to ‘Determine automatically’ or the baudrate is negotiated on bidirectional communication , then here can be read out which protocol and baudrate is really used.
After a change of the meter protocol, which should be used, by the user, the updated meter protocol information is updated only after a read request of the iOKE868. This can be initiated by the user by detecting OBIS IDs or read meter values or by read out events performed by the calendar.
To check the actual information press the icon

Detect Obis ids
When a connection to the device has been established, a scan is triggered to determine which Obis IDs are made available by the meter. All Obis IDs found are displayed in this section. Last update refers to your local time at the time the list was received.
If no value exists for a value group of the Obis metrics, this position is filled with ‘X’.

A scan of all Obis Ids may take longer when a small baud rate is used. In such a case, the list will be enlarged and the timestamp will be adjusted.
A new scan can be triggered at any time by pressing the icon

Detected Obis ids can be saved in a ‘csv’ file by pressing the icon.

Configuration – iOKE868
The configuration of the device is separated into logical groups with one or more configuration option. To ensure full flexibility, these can be processed independently of each other. Data handling of each group could be controlled with the following options:

Be carefull, as this overrides the data of the whole configuration block in the device!
| Read the complete configuration block from device.
Be carefull, as this overrides the complete block in the application. Any information you may have entered before will be lost!
| Write or read list data from file.
Depending on whether the data is read or written, all previous information in the application or an already existing file will be overridden!
Additional options for lists
| Remove one or more entries from the list.
Be aware that deleted entries can’t be restored!
| Add a new entry to the list.
| Delete all entries from the list.

System time (8)

As the device event system depends on a valid time to work properly, the device tries to synchronize the system time with an LoRaWAN® server. Therefore the correponding calendar event Get Network Time (UTC Format) must be configured and executed regularly.

In cases where the server does not support this feature or the LoRaWAN® stack of the device is not yet activated, the system time can also be configured locally via the serial interface.

To change the time, two options exist:

The time and date values can be modified by clicking the plus and minus button for single steps or by holding the buttons or spinning the mouse wheel above the value to adjust more than one step at once.

The device is operating with an UTC time. Your system time is converted by using your local timezone to match the device requirements.
Be aware that the time and date has to be written to the device after modifying the values! These values are not synchronized automatically.
Be sure that you configure the calendar event Get Network Time (UTC Format) so that this is executed regularly (e.g. once per week). This keeps the device time synchronized.
A power cycle will reset the system time to the time set at the last syncronisation (LoRaWAN® or manually)

Device parameter (9)
The local output can be configured with the options below

over the USB interface
Via HCI message| All information send via LoRaWAN® to a server will also be output over the USB interface
1 to 1 output| All internal features of the iOKE868 are deactivated. The data received at the IR-Interface will be directly send to USB.
In this mode the user has to decode the data send by the meter for himself.
Interface are 115200/8/N/1

To support different meter types, meter protocol could be one of the following variants

is supported by the meter
SML| Use Smart Message Language (SML) as communication protocol
Bidirectional (IEC Mode A / B / C)| The protocol is IEC mode A, B or C, detected automatically.
Unidirectional (IEC Mode D)| The protocol is IEC is mode D.

Additionally the output can be configured to fit special use cases (Configuration options).

effective power saving mode.
TxPower is reduced to 13 dBm if enabled.
Include meter id| If a meter id is received by IR-interface it will be added to each LoRaWAN® payload if activated.
Include status| The status information of the iOKE868 will be added to each LoRaWAN® payload if activated.
Include time| The local time of the iOKE868 will be added to each LoRaWAN® payload if activated.
Omit units| If an OBIS ID contains a unit it will normally be added to each LoRaWAN® payload. Activate this option to prevent adding the unit.
Try IEC number conversion| The device tries to split a possible string value to its numeric counterpart. Only applicable in IEC mode
Fast wakeup sequence (IEC mode)| Send fast wakeup sequence for battery powered devices. Only applicable in IEC mode.

System commands (10)
At the current time two commands exists:
The device can be paired with the smart meter id. To activate this option the device has to be mounted on the wanted smart meter. The pairing avoid sending data, if the device is mounted on a different meter.
Second command can be used to restart/reset the device.

Configuration – LoRaWAN®

The LoRaWAN® configuration consist of three parts necessary to connect to the LoRaWAN® server:
The Device EUI (11) uniquely identifies the device and can also be obtained from the sticker on the case.
Your device supports two types of Activation modes (12) to activate the device on the LoRaWAN® network. Depending on your selection of the activation mode, the last part of the LoRaWAN configuration will be adjusted. ®
When activating the device by Activation By Personalization (ABP), it is assumed that both the end device and the server know all necessary keys (Application Session Key and Network Session Key) and an identifier on the network (Device address (13).

The second choice, Over-the-Air Activation (OTAA), is used in case the security keys should be negotiated at the time the device tries to enter the LoRaWAN® network. In that case, the device needs to know that specific LoRaWAN® server “login” data.
The Application EUI is used to identify the server, whereas the Application key is needed to secure the initial communication phase (14).

Keys cannot be read from the device! Always make sure to enter valid keys before writing the data into the device, otherwise the LoRaWAN® network activation will fail.

Advanced Options (only visible when activated via general configuration)

In a LoRaWAN® net the data rate is adjusted during the operation to use the perfect match of transmission speed and link quality. This feature could be disabled to use a fixed data rate.

Activate max header commands allows the usage of up to 15 bytes from the regular uplink message for mac command transmission. If command length exceeds the given max value, they will be sent immediatly using the port 0. By deactivation the option  the header length is reduced to zero.
On private LoRAWAN® networks this options has to be set to allow the device to join the network.

Configuration – CALENDAR EVENTS

Every action the device is able to execute is configured as a time bases event. The first step is to choose an event (15) which should be executed at the given time (17). To help navigate through the list of events, events are marked with color codes.

network server the device is connected to. Server must support corresponding MAC command.
Send Status| Send a status message to the LoRaWAN® server.
Red| Receive and output meter data
Stop reading values| Stop the reception of meter data.
Read out a single block of values| One-time reading of the configured Obis IDs.
Read out values continuously| The Obis IDs are read out until the event is ended by a corresponding stop command.
Use this only for short testing purposes on the LoRaWAN® network. Duty Cycle will also limit this periode.

Beside an event executed only once, it is also possible to define a repetition interval by enabling the Repeat event (17) field. In general the period could be configured from 1 to 256 and with an unit of minutes, hours, days, weeks and months. It is not possible to enter periods greater than a year, therefore weeks are limited to 52 and months to 12 at a max.

For each read event to work properly at least one Obis IDs has to be set (16) . Obis IDs could be added to the events Linked Obis IDs list by choosing one of the at startup detected Obis IDs or by entering the ID manually.

available, check the placement of the reader on the meter and start a new scan process (7)
| Link this Obis ID with the event

• 1-0:1.8.0*255 = Positive active energy (A+) total [kWh]
• 1-0:1.8.1*255 = Positive active energy (A+) in tariff T1 [kWh]
• 1-0:1.8.2*255 = Positive active energy (A+) in tariff T2 [kWh]
• 1-0:2.8.0*255 = Negative active energy (A-) total [kWh]
• 1-0:2.8.1*255 = Negative active energy (A-) in tariff T1 [kWh]
• 1-0:2.8.2*255 = Negative active energy (A-) in tariff T2 [kWh]
• 1-0:15.7.0*255 = Absolute active instantaneous power (|A|) [kW]

Meter values – iOKE868
With an active local HCI output the WS-Configurator is able to display the received values each time a calendar event with linked Obis IDs occurs.
If no value exists for a value group of the Obis metrics, this position is filled with ‘X’.

readout
Grey| value was not read out
Icon| Description
---|---
| Clear the complete list
| Pause refreshing the display by repeated readout triggered by calendar events
| One time readout of all/some Obis IDs and values provided by the meter depending on whole length

Application settings

To enter the configuration view, open the menu under (3) and choose Configuration. Switch to the GENERAL tab to adjust application settings according to your needs.

Dark mode
As a bright GUI is not always the best option in every enviroment, the complete GUI can be set into a dark mode. The differences can be seen in the following example:

Select language
Currently the following languages are supported

• English
• German

Automatically determine serial interfacces
During startup phase, the application tries to detect available devices and the associated interfaces. To avoid the extended startup time or keep the list of available connection short, this feature is deactivatable.

Show options for advanced user
When activated the device configuration could be extended with configuration fields which are not necessary for normal operation but offer the experienced user more opportunities to influence the behavior of the device.

Connection management
The list of available connections could contain two types of connections:

Manually configured connections
To create a new manually configured connection, open the menu under (3) and choose Configuration. Switch to the CONNECTIONS tab and press the add button. After the connection has been named and an available interface has been selected, the connection can be stored and used afterwards. If the interface is not available at the time of creation, it is also possible to name the interface by yourself. Depending on your operational system the naming follows one of the following schemes: \\.\COMX on Windows or /dev/ttyUSBX on Linux machines.
Replace the X with the number provided by your OS.
Already configured conections can be modified or removed as well. By selecting an existing connection from the list, the corresponding options are displayed.

Auto-detected connections
The WSConfigurator continuously searches for physically connected devices. For each device found, a new connection is added, identified by the prefix auto and the corresponding interface as connection name. If the interface is already used in a manually configured connection , it will not be added to the list of auto detected connections again.
As auto-detected connections are not stored automatically and thus not available if no device is present at start time, it is possible to use them as template for a manually configured connection. Open the auto-detected connection from the connection configuration list and change the connection name as you like. The new name must not be prefixed with auto.

Be aware, that management of connections is only possible with disconnected connection.

Firmware Update

To start the update procedure, a suitable image must be selected. As a first step the serial port to which the device is connected has to be choosen. The application will try to detect the connected device type afterwards. In case the device type could be determined, the device type field will be deactivated and a firmware image can be selected via the file dialog. If the application is unable to determine the device type, the device has to be chosen by selecting one of the available types from the drop down menu.

Firmware Update – iOKE868
To ensure that that no interaction disturbs the process, please unplug all other IMST devices from your computer before starting the actual update process. When the update process was started, it runs without any further user action. After the update process  has been completed, the device must be restarted once and can then be used as usual.

Don’t interrupt the update process, as this will render the device unusable.

System requirements

Supported operating systems

• Windows 10, 64Bit and 32Bit

Best to use with a screen resolution of 1920 x 1080
Minimum recommendation is a resolution of 1280 x 800

LoRaWAN® is a mark used under license from the LoRa Alliance®.

WS Configurator / User Manual iOKE868 / Version 1.6

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>