Manual

The use of Shelly Scanner is quite intuitive however there is also some "hidden" feature, so reading this small manual can be valuable.
Below is the list of buttons that make up the toolbar with the premise that some functions apply only to a single device, others apply also to multiple devices simultaneously; the first ones are recognizable as their icons are disabled when multiple devices are selected on dashboard:

• Re-scans the network looking for connected Shelly devices.
• Immediately Refresh all devices status.
• Opens a window showing the full information set of the selected device in json (native) format. Clicking on any point, the containing curly braces are highlighted.
• Opens a window showing charts for selected devices. Here a detailed description of the window content.
• Opens a window showing the logs of the selected device. First generation devices only allow the viewing of one or two log files (logs must be enabled from the web interface of the devices); on the contrary second generation devices send logs on a streaming channel and it is possible to enable / disable logs, temporarily block (until the window is closed) Shelly Scanner refreshes for the device (in order to stop generation of related logs), select the log level.
• Opens a window showing a configuration checklist for selected devices trying to identify possible errors. Here a detailed description of the window content.
• Opens the web UI of the selected device on the system browser.
• Backs up the configuration of one or more devices. if more than one device is selected, the application asks to select a folder where all files are saved; in this case files get a default name. If you need to change information before restoring, note that backup files, with the sbk extension, are actually a set of zipped json text files; backups of second generation devices also include scripts which, however, are not restored (see the "scripts" paragraph).
  Warning: updating a device firmware can result in unusable old backup files.
• Restores the configuration of the selected device. Restore can be performed from a file generated by a different device as long as it is of the same type; in this case, confirmation will be requested. During the restore process, the application, if applicable for recovery, can ask for the passwords of: restricted login, wi-fi1, wi-fi2, mqtt server. It should be noted that not all parameters are restored; new parametrs are added on new releases.
• Opens a window from where is possible to manage some parameters of several devices at the same time; changes are applied on every selected device on confirmation. Two buttons are available at the bottom-right of the status bar (main view) to select all the devices; for obvious reasons the changes have no effect on offline devices. You can manage:
  • Firmware update to stable or beta version (note that tooltip on version number shows the full version identifier);
  • primary (1) and secondary (2) WI-FI (static IP option is active if only one device is selected);
  • Restricted login
    If some second generation devices is selected the username must be "admin";
  • MQTT configuration
    Blank fields in this section do not affect device configuration.
• Scripts and Key-Value Store management (Generation 2+ devices only). A window opens, initially on the Script panel, allowing to fully manage any detail as described here. With reguard to the KVS, the panel let the user:
  • Create a new entry;
  • Delete an entry;
  • Edit an entry value.
• Reboot (after confirmation) all selected devices.
• Devices individual text notes (archive must be active).
• Toggle to "full view" mode: all informative columns are displayed; the window enlarges, or remains unchanged, according to one of the criteria defined in the application settings. When this mode is active the button icon changes to .
• Export the table content to a file in CSV format.
• Print the table.
• Application settings. A dialog opens with three sections from where you customize the user interface, the connection parameters to the devices, the archive - or archives - of the detected devices. This dialog allows, for example, to choose which columns to display on the main table (in standard or full view mode depending on the current visualization mode), to select the network scan mode, to define the default values (user and PIN) for protected devices authentication (warning: using this function the password is stored in an insecure way on the disk) or to enable/disable the archive.
• Provides information about the application (you will also find a button to test for Shelly Scanner updates and the link to load this page).

The contents of the columns shown by the table have a generally obvious meaning, however some further explanation may be useful:

• Symbols appearing in the Status column have the following meaning:
  • On line;
  • On line - reboot required (second generation devices only);
  • Updating data;
  • Protected device, you need to log in (from the context menu - right mouse button);
  • Off line; the tootip provides the timestamp of the last successful connection to the device;
  • Error (in most cases the cause is due to an application malfunction probably caused by an outdated device firmware).
  • Archived (device detected during a previous run); the tootip provides the timestamp of the last detection (you can permanently remove the device from the archive from the context menu - right click);
• Cloud (En/com) contains have a double value: cloud enabled / actual connection to the cloud;
• MQTT (En/com) contains have a double value: MQTT enabled / actual connection to the server;
• Uptime (s) is the time elapsed since the last restart (or firmware update) expressed in seconds; the tooltip, which appears by holding the mouse pointer for a few moments on the uptime cell, shows the same value expressed in days, hours, minutes and seconds;
• The content of the Command column depends on the associated device; in case of devices with "switch" type inputs, the on/off text inside the button represented may be black or orange; the second case means that the input contact is closed regardless of the state of the relay;
• The tootip of the Command column also inform on the event that caused the last change of state if the Source column is not visible.

Hereafters some details that may be not obvious at a first glance:

1. If the application does not find all the devices at startup (consider that some battery-powered devices such as: Button 1, Flood, D&W,... are discovered only at the time they temporarily activate) probably the computer on which Shelly Scanner runs and the devices are not exactly on the same network. In this case it is necessary to configure the application settings from the appropriate dialog (warning: the changes of these parameters are active only on the next application execution).
   In case your computer has more than one physical or virtual network interface (VPN) you must configure the application to perform "full mDNS scan". Compared to the simpler "local mDNS scan" the search for devices will be somehow slower. If the devices are on a separate network (it is, for example, the case of a subnet dedicated to home automation devices) it is necessary to set the "scan by IP" option which, however, inhibits the discovery of some battery-powered Shellyes such as Button 1, Flood or D&W.
   Alternatively you can run the application from a terminal ignoring stored scan settings with the following command line: java -jar <full path>\shellyscan-x.x.x.jar adding -fullscan to perform "full scan" search or -localscan for "local scan" or -ipscan x.y.z.a-b where x.y.z is the network IP prefix, a and b are the lower and higher addresses to check for respectively (e.g. -ipscan 192.168.1.1-254).
2. Double clicking on a row in the table (but not on the "Command" column) shows the detailed information for the corresponding device (this is equivalent to click the button on the toolbar or on contextual menu) or open the web page of the device on the system browser ; this behavior is defined by the application settings.
3. Some actions from the toolbar can be performed on a single device only while others affect all selected devices. Buttons on the toolbar that work on multiple devices are active when multiple devices are selected. This also applies to the "settigs" function.
4. Right clicking on a table row the corresponding device is selected and a contextual menu is shown. This menu reproduces part of the toolbar buttons and add a login command enabled on protected devices for which credentials have not already been provided or, alternatively, the reload command which fully reloads the device information (including the list of other devices possibly connected to it in range extender mode).
5. The table row filter can be edited with keyboard shortcuts: ctrl-S cycles through the combo values that allows you to choose which column to search from; ctrl-F focuses the input text field in which to type the characters sequance to search; ctrl-E select the text field and clear it.
6. From application settings you can choose which table columns are shown. The order of the columns can be altered by dragging each header with the pointer. The new column location is later remembered by Scelly Scanner. CSV export follows the same visibilities and positions settings.
7. Command Line Interface (CLI) and non interactive mode. Running Shelly Scanner from a terminal with the command java -jar <full path>\shellyscan-x.x.x.jar you can add some parameters; we have already seen how to force the search mode at startup ignoring the normal configuration:
   -fullscan (or -full) searches mDNS considering any network interfaces;
   -localscan (or -local) searches mDNS on the main network interface;
   -ipscan (or -ip) followed by a parameter with the format x.y.z.a-b where x.y.z is the network prefix, a and b are respectively the first and last address to be verified; performs IP search (giving up the ability to track all battery-powered devices that are not normally active);
   -noscan just shows the archive.
   There are two additional options the effect of which is the non-interactive execution of Shelly Scanner (the graphical interface does not start, the command is executed and the application terminates):
   -list: lists on the terminal all the devices finds;
   -backup followed by the path of an existing directory: backs up all the devices it finds storing the produced files in the specified directory.
   Using the latter parameters you can also specify one of the parameters that change the search mode.
   Finally the parameter -graphs purpose is described on the page dedicated to charts.
8. If you want to report an application error (for which I would be grateful) please activate the logs running the application from a terminal with the following command line: java -D"org.slf4j.simpleLogger.log.it.usna=debug" -jar <full path>\shellyscan-x.x.x.jar, produce the error and attach to the report the terminal content.

Here some useful technical links are reported:

• Shelly Knowledge Base
• Shelly API
• Direct Device to Device communication (DDD)
• Shelly Script Tutorial
• Examples for Shelly Scripts for Gen2 Shelly devices

• Static IP configuration; best pratics
• Range Extender configuration