Whisker.io® products ship pre-configured from the factory and are ready to work out of the box.  When the factory configuration is not sufficient, users can change the setup of Whisker.Blocks™ and Smart.Hubs™ using the Configurator app. 


TABLE OF CONTENTS


Introduction


Configurator is a Windows App and will run on any computer or laptop with Windows 7 or later.  It is a proprietary application and is free to use with any Whisker.io® product.  It can be downloaded here:


Download Here: Configurator App - Windows 7+ Installer

    

    Installation instructions: https://support.d6labs.com/en/support/solutions/articles/47001152260-d6-labs-iiot-usbconfigurator-application-installation)

The following image shows the various functions of the app:


1. Serial Port Management


The Configurator app communicates with Smart.Hub™ and Whisker.Block™ devices via a simple USB device called the USBConfigurator (more information or purchase here)


Once the USBConfigurator is connected to an available USB port,  it is automatically assigned a COM: port number by the operating system.  The drop-down selection box provides a list of all available COM ports.  If you do not see the USBConfigurator's port in the list, click the refresh button to the far right.


You must select the COM: port in the drop down before the Configurator app can be used to communicate with Whisker.Block™ or Smart.Hub™ devices.


The serial port status LED indicates when the COM: port is being used by the Configurator app by turning green. If the LED indicator is red, the serial port is not in use and can be used by other applications.  The serial port is automatically opened and closed by the Configurator app which means that the LED will generally be red unless commands are being executed.

 

2. Tabbed Interface


The Configurator app uses a tabbed interface, with each tab consisting of a user interface for a specific function.  In the previous image, all tabs are docked in their default position, but each tab supports drag-and drop functionality and can be docked in a different location or left floating outside the main application window.  This is useful when multiple monitors are being used.


The Configurator app stores the docking state of each tab when closed and loads the previous state when the app is re-opened.


Currently, the Configurator app provides three tabs:


  1. Whisker.Block Configuration- this tab provides a user interface that allows the user to configure Whisker.Block devices.
  2. Whisker.Block Device Monitor- this tab provides a user interface that allows the user to monitor all active Whisker.Block devices on the local network.
  3. Smart.Hub Configuration - this tab provides a user interface that allows the user to configure Smart.Hub devices.


3. Tab User Interface


Each tab provides a user interface designed for a specific purpose.  When a new tab is selected, the visible user interface will change to match the purpose of the selected tab.  Each user interface will be described in detail in later sections.


4. Application Log


The application log records automated and user activity and can be useful for troubleshooting.


Whisker.Block Configuration UI



Every Whisker.Block™ has a product label that indicates the serial number and configuration of the device:

All Whisker.io® wireless products have a 32-bit unique serial number (or MAC address).  This serial number is used to identify the device in the cloud and in the radio network.  This number must be entered in the "Device Serial Number" box on the Whisker.Block Configuration tab and is used to specify which device is being configured by the user.


The Whisker.Block part number specifies how the I/O is configured on any given device.  In the picture of the product label above, the device configuration code is DCDCA4A4 which indicates that this device is configured with 2 digital inputs and 2 4-20mA analog inputs.


Whisker.Blocks can have a wide variety of power, I/O, and antenna configurations.  The following image shows how the part number indicates the various configurations for a specific device.



The device channel configuration code (or device code) must be entered in the Device Code box on the Whisker.Block Configuration tab.  This tells the Configurator app how the device is supposed to be configured so that the app can present the appropriate configuration parameters.


Prior to reading or changing the configuration of a Whisker.Block device, three conditions need to be met:


  1. The device serial number must be entered in the Serial Number box
  2. The device's configuration code must be entered into the Device Code box
  3. The device must be awake.


When Whisker.Block devices ship from the factory, they are placed in deep sleep to conserve battery life.  Likewise, an active Whisker.Block sleeps for the majority of its 5 minute sample period.   In both cases, the Whisker.Block must be placed in an awake status so that it can receive and send configuration data.  This is accomplished by swiping a magnet over the wakeup sensor in the lower left corner of the device.  Please note that you need to use a strong magnet (>=10lbs pull strength) to wake up the device.



Once the Whisker.Block is awake, the green LED indicators in all 4 corners will start flashing and will remain in that state for approximately 1 minute.  Each time a command is sent or received to or from the device, the timer is reset.  If 1 minute goes by with no activity, the device will return to its sleep/sample cycle.


To read the current configuration of a device, click "Read Configuration":



The dialog will update the progress bar and status log as the read task is completed.  If the task is successfully completed, the dialog will read "Success" along the top and the OK button is enabled.  If the task failed for some reason, the progress bar will read less than 100% and the message along the top will read "Error!".


Click "OK" to close the dialog.  If the configuration was successfully read, the Whisker.Block Configuration tab UI will update to show the configuration of the device.  If the device configuration does not match the Device Code, an error message will pop up to notify the user of the problem.


To make configuration changes, edit any of the parameters and click "Write Configuration".  There are two groups of configuration parameters: Network and I/O.


Network parameters include:


  • Channel - The default channel is 15.  There are 50 available channels.
  • Spread Factor - the default is 9.  This determines the distance and data rate.  Lower spreading factors have shorter range but higher data rate and higher spreading factors have longer range but lower data rate


A network is determined by the combination of channel and spread factor; each unique combination represents a unique network.  Spreading factors are orthogonal so that different spread factors can exist on the same channel without interference.  The default spread factor is optimized for range and battery life.  Lower spreading factors increase the data rate, allowing more devices on a network or faster update rates for a given number of devices.  Higher spreading factors increase the range, allowing fewer devices on the network.  Generally, the spreading factor should not be changed unless the application requires different performance parameters than can be achieved with the factory default settings.


I/O configuration parameters include:


  • Sample Rate- if the device is battery powered, this is measured in minutes.  If the device is powered by external DC voltage, this is measured in seconds.  The Power Mode setting determines how the device is powered.
  • Power Mode - available options are Battery and External DC voltage.
  • Analog Power Up Delay - this is the time (in milliseconds) between when the Whisker.Block turns on the internal sensor power supply and when a sample is taken.  It is normally set at 50mSec, but can be increased for sensors that require more settling time.  Please note that increasing the delay will affect battery life.
  • Dry Contact Input Mode - available options are On/Off, Counter, and Missing Pulse.
  • Analog Sample Mode - available options are Single, 16/128 Sample Average/Minimum/Maximum


Modbus RTU devices have 16 slots, each of which can be configured to read a 16 bit word from any device/table on the RS-485 network:



For MobusRTU Whisker.Blocks, the following configuration parameters are available per slot:


  • Slave Address - this is the device ID or slave address for the target Modbus RTU device.  
  • Table - available options are Coils, Discrete Inputs, Input Registers, and Holding Registers
  • Address - the starting address to read from the selected table


Each slot represents a 16-bit value.  If the selected table is Coils or Discrete inputs, the Whisker.Block will read 16 bits starting at the specified address.  For example, if the starting address is 1, the Whisker.Block will read bits 1 through 16 for the specified slot. 


If the selected table is Input Registers or Holding Registers, the Whisker.Block will read a single 16-bit value from the register at the specified address.


Whisker.Block Device Monitoring UI


The device monitor is a useful tool for verifying proper operation of deployed Whisker.Blocks™.  Once the monitor is started (by clicking the Start button), it opens the serial port and begins listening for all incoming messages from Whisker.Blocks on the configured network.  When an update is received from a new device, the monitor adds a row to the table.  When an update is received from a known device, the monitor updates the data on that devices row.



For each device, the device monitor shows:


  1. Serial number
  2. Age - increments every second and resets when a message is received
  3. RSSI - anything above -120dBm indicates a good signal
  4. Power Supply Voltage - indicates the battery or external DC power supply voltage
  5. Internal Temperature - measured by on-board digital temperature sensor (in °C)
  6. Channel Data - Up to 16 channels of data, depending on the configuration of the device.


The value displayed for channel data depends on the channel type:


  • Analog - value in mA (based on 4-20mA) and V (based on 0-5V)
  • Digital - value is High or Low
  • Thermistor - value is temperature in °C
  • Modbus Slot - raw value (0-65535) is displayed


Note: You cannot configure Whisker.Blocks or Smart.Hubs while the device monitor is active.  You must click the Stop button first.

Smart.Hub Configuration UI


The Smart.Hub is an extremely flexible IIoT gateway.  It is capable of mapping Whisker.Block data to the Whisker.io® cloud platform, Modbus TCP server, and SparkPlug B broker and can be configured on a device by device basis.



The Configurator app is used to configure the various operating parameters of the Smart.Hub, including:


  • Ethernet port - IP address, subnet, gateway, and DNS servers
  • SparkPlug B client - broker URL and credentials, topic settings, and device/tag mappings
  • Modbus TCP client - Holding Register mapping per device


Smart.Hub configuration is different than Whisker.Block configuration.  All  Whisker.Block configuration is done using the USBConfigurator and the wireless connection to the Whisker.Block.  Unfortunately, the amount of data required to fully configure a Smart.Hub is more than the bandwidth of the Whisker.io® wireless network can support. 


That is why Smart.Hub configuration is split into two channels:


  • Wireless - Ethernet settings are configured over the wireless port
  • Ethernet - Once Ethernet configuration is set and a connection can be established between the computer running Configurator and the Smart.Hub, the remainder of settings are configured using a TCP connection.


We chose to configure the Ethernet settings over the wireless port to make things simple; if you make a mistake and set the wrong sub-net or gateway, you can easily fix it without having to alter the network settings of your computer.


Once the Ethernet settings are established and the computer can ping the Smart.Hub, the LED by the Ethernet IP address turns green.  This indicates that you can complete the rest of the configuration process.


Configuring Ethernet Port


Configuring the Ethernet port of a Smart.Hub is easy:


  1. Enter the Smart.Hub's serial number and ensure the LED is green
  2. Select the serial port used for the USBConfigurator
  3. Click "Read IP" to read the current IP settings of the Smart.Hub
  4. Make any required changes to the Ethernet settings
  5. Click "Write IP" to send the new configuration to the Smart.Hub


Once the Ethernet settings are written, the Ethernet IP Address LED should turn green which indicates that the computer can ping the Smart.Hub on the local network.


At this point, the Read Config button is enabled.  The Write Config button is disabled to ensure that a Smart.Hub's configuration information is read before it is written.  This is a measure of protection against losing a Smart.Hub's configuration data by inadvertently writing an empty configuration profile.


Configuring Protocols


The Whisker.io® MQTT, SparkPlug B, and Modbus TCP protocols can all be configured via the Smart.Hub Configuration tab once the Ethernet port configuration is complete.


Each protocol has configuration parameters for the Smart.Hub and for each device that is to map to that protocol.  For example, to enable the SparkPlugB client on the Smart.Hub:


  1. Check "Is Enabled" on the left-hand SparkPlugB tab and 
  2. Enter the URL, user name, password, and Group ID for the SparkPlugB broker.  
  3. On the Managed Device panel, select a device and enter the Location Name, Device Name, and Channel Names.  The Location and Device name are used in the topic and the Channel Names will become the tag names on the SparkPlugB broker.
  4. Select the device's SparkPlugB tab and click "Is Enabled"
  5. Click "Write Configuration" to send the new configuration to the Smart.Hub


Now, the SparkPlugB client is enabled and the selected device will map its sensor data to the appropriate topic and forward it to the broker.


To learn more about Managed Devices, protocol configuration, and configuration documentation, see Smart.Hub™ Configuration


Further Reading


This has been a basic introduction to the Configurator app.  For more detailed instructions on using Configurator to configure Whisker.Blocks and Smart.Hubs for specific applications, see the following articles: