Logitech Script DFU Tool

目的

A SW tool to update FW of supported devices. Intended to be used by IT Managers / Administrators to remotely copy, execute and collect and aggregate results.

サポートされているOS

Windows 7, 8/8.1 and 10 (32 Bit and 64 Bit)

サポートされるデバイス

Logitech Illuminated Living-Room Keyboard K830
Logitech K370s and K375s Multi-Device Wireless Keyboards
LogitechK780マルチデバイスワイヤレスキーボード
Logitech K850 Performance Wireless Keyboard
Logitech Wireless Touch Keyboard K400 Plus and associated unifying receivers

基本的なワークフロー

Software when executed will detect all supported receivers/devices connected to the PC SW is running on, list or update receivers/devices as per the command line arguments and switches and outputs the results on console/file.

チュートリアル

The SW tool must be copied locally on the destination system before executing locally.

When invoking the tool without arguments, the default behavior is to list all devices:

logitech_dfu

1 USB Receiver
1.1 K780
2 USB Receiver
2.1 K850

This is equivalent to using the argument “–list”. This argument is purely informational and does not make any changes to the devices. There are other informational arguments: “–fw _ version”, “–available”, and “–pre-requisite”, which show the current firmware versions, available firmware versions in the DFU archive, and potential pre-requisites (i.e., devices that should be upgraded before others), respectively. Since it is possible to give several arguments, all information can be collected by using:

logitech_dfu --list --fw_version --available --pre-requisite

By default, all informational messages are sent to the standard output (“stdout”) stream and all error messages to the to the standard error (“stderr”) stream. However, output and errors can also be collected and aggregated at a central location (e.g., in “c:\temp”) for processing and review:

Logitech_dfu --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt
--list --fw_version --available --pre-requisite

Before deploying this tool on a PC network, it is strongly recommended, to run the above command on all PCs, first. This allows to test that:

• The tool has been correctly delivered and is executable.
• The log and error files are correctly generated (permissions are adequate) and can be retrieved.
• The tool did not encounter any unexpected problems (null return value, no error messages).
• The DFU archive can be accessed (when planning on using a locally-delivered archive, add the “–archive” argument to the command, see details below).

While this command is a good test case, it is insufficient to build a data-base of all devices with their firmware versions. This is because the firmware versions of devices, which are in low-power mode or otherwise disconnected, are not available. In order to build such a data-base, it is possible to run the tool in background (waiting for devices to reconnect), for example for a 24-hour period:

Logitech_dfu --wait --timeout 86400 --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt --list --fw_version --available --pre-requisite

The main goal of the tool is to upgrade device firmware. The easier way is to use the “–upgrade_latest” argument. For example, to apply the latest firmware for all connected devices PC, use:

logitech_dfu --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt --upgrade_latest

注:

• This command requires an Internet connection, as firmware is downloaded from Logitech’s GitHub site.
• If the target PC is currently being used, the upgraded devices will be temporarily unavailable, but the user will not see any notifications.
• This command will fail if some devices (mice or keyboards) are in low-power mode or otherwise disconnected.
• This command saves information and error messages in “c:\temp”.
• It is strongly recommended to test the return value. If executed from a Windows’ command script, the command “IF NOT %ERRORLEVEL%==0 action” may be used.

If an Internet connection is not available, the archive may be copied to "c:\temp\master.zip" and then the following command should be used instead:

logitech_dfu --archive c:\temp\master.zip --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt --upgrade_latest

In order to warn the user that his/her devices may be unavailable, use:

logitech_dfu --pop-up --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt --upgrade_latest

In order to wait until devices in low-power mode are reconnected, use:

logitech_dfu --pop-up --wait --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt --upgrade_latest

In order to limit the wait period to one day, use:

logitech_dfu --pop-up --wait --timeout 86400 --output c:\temp\dfu_log.txt --error c:\temp\dfu_err.txt --upgrade_latest

Advanced users may want to specifically target devices and/or firmware version (including downgrading the version). The “–target” and “–upgrade” arguments are intended for this (see full usage documentation below). Finally, the “–force” argument may be used to bypass requirement checking. Since this can lead to non-functional systems, this argument should only be used when fully understanding all implications (in doubt, do not use it).

Delivery of updated FW

Update FW are stored based in the metadata defined here https://github.com/Logitech/fw_updates and could be delivered in one of the following ways

• From network path here https://github.com/Logitech/fw_updates
• Using a zip file based on the format of the metadata passed as parameter to the command line tool

使用法

Usage: logitech_dfu
[--url |--archive ] [--target ]
[--force] [--stdinout|--pop-up]
[--wait] [--timeout ]
[--output ] [--error ] [--version] [--help]
[--list] [--fw_version] [--available] [--pre-requisite]
[--upgrade ] [--upgrade_latest]

注:

When more than one of the following commands are specified: “–list”, “–fw _ version” “–available”, “–pre-requisite”, “–upgrade”, “–upgrade _ latest”, they are all executed in order specified by this list, regardless of their order on the command line. When none is specified, the “–list” command is the default.

It is an error to specify the same argument twice or to specify the contradictory arguments (e.g., “–url” and “–archive”).

引数

--url <URL>

提供する URL of the firmware archive. By default: https://github.com/Logitech/fw_updates/archive/master.zip See the section “Archive Format” for details.

--archive <ZIP File>

Provide the firmware archive as a local file 代わりに URL. See the section “Archive Format” for details.

--target <Id.>

Specify a given device identifier. Identifiers are returned by the “–list” command. They are composed of a single number for devices directly attached to the computer (USB of Bluetooth keyboards/mice, USB receivers) and of two numbers, separated by a dot, for devices attached via a receiver (Unifying keyboards/mice).

--force

Force a DFU even when pre-requisites are not satisfied. Warning, using this option may yield a non-functional system.

--stdinout

Redirect any data from/to the console to the standard input stream and to the standard output stream. When used in conjunction with the “–output” argument, console messages are still redirect to the standard output stream (not to the file specified by the “-output” argument). This argument is intended to be used when “logitech_dfu” is executed via a tool that does not handle the console properly, in particular “PSExec「」。

--pop-up

Use a pop-up window for user prompting instead of the console.

--wait

For all commands (“–list”, “–fw_version” “-available”, “–pre-requisite”, “–upgrade”, “–upgrade _ latest”) that cannot be fully completed, because one or several devices are disconnected, the program waits until all device have come online at least once or the timeout expires (if specified, see the “–timeout” argument).

When used in conjunction with several informational commands (“-list”, “–fw _ version” “–available”, “–pre-requisite”), the program should store all the required information to execute the commands in order, without waiting for devices to come on-line several times.

--timeout <Duration>

Specify a timeout (in seconds) for the “–wait” option. By default, there is no timeout (i.e., the program waits indefinitely).

--output <File>

Redirect the standard output stream to the specified file.

--error <File>

Redirect the standard error stream to the specified file.

--version

Display the tool version and exit (other arguments are ignored, except “-help” that has priority).

--help

Display a help message and exit (other arguments are ignored).

--list

Display device identifiers and names. If the “–target” argument is given, only the specified device is listed. Otherwise, all available devices are listed. The names shown correspond to:

• The product string for USB devices.
• The name stored by the receiver for Unifying devices (this allows to list disconnected devices).

Disconnected devices are marked as “[off-line]” (in square brackets, after the name). Devices that require user-action to enter DFU are marked as “[user-action]” (in square brackets, after the name). This is determined by the presence of the HID++ Feature 0x00C1 and the absence of the HID++ Feature 0x00C2.

Examp上： K780 & MX Anywhere 2 connected to a Nordic-based receiver (Tommy) and K850 connected to a TI-based receiver (Goldie):

# logitech_dfu --list

1 USB Receiver
1.1 K780
1.2 MX Anywhere 2 [user-action]
2 USB Receiver
2.1 K850 [off-line]

# logitech_dfu --target 1.2 --list

1.2 MX Anywhere 2

--fw_version

Display device firmware versions. If the “–target” argument is given, only the specified device is listed. Otherwise, all available devices are listed. The firmware version is formatted as follows:

• Firmware prefix (1 to 3 characters, letters and/or numbers).
• Firmware number, padded to 2 decimal digits.
• Dot character (“.”).
• Firmware version, padded to 2 decimal digits.
• Underscore and capital B characters (“_B”).
• Firmware build number, padded to 4 decimal digits.

Disconnected devices are marked as “[off-line]” (in square brackets, without firmware version since it is usually unavailable).

Example: same as above:

# logitech_dfu --fw_version

1 RQR12.03_B0025
1.1 MPK01.02_B0021
1.2 MPM02.01_B0009
2 RQR24.05_B0029
2.1 [off-line]

# logitech_dfu --target 1 --fw_version

1 RQR12.03_B0025

--available

Display a comma-separated list of available firmware (in the archive). If the “–target” argument is given, only the specified device is listed. Otherwise, all available devices are listed. Each available firmware is referenced by its version, which is formatted exactly as described for the “–fw_version” argument.

When a firmware is available, but requires another device to be updated first, it is marked as “[pre-requisite]” (in square brackets). When a pre-requisite may apply, but cannot be assessed, because the other device is disconnected, it is marked as “[pre-requisite?]”.

In many case, it is possible to establish a list of available firmware, even when a device is disconnected. However, when this is not possible, the device is marked “[off-line]”.

Example: same as above:

# logitech_dfu --available

1 RQR12.05_B0028, RQR12.07_B0029, RQR12.08_B0030 [pre-requisite]
1.1 MPK01.02_B0021, MPK01.03_B0024
1.2
2 RQR24.03_B0027, RQR24.05_B0029, RQR24.06_B0030 [pre-requisite?]
2.1 MPK04.01_B0010

# logitech_dfu --target 2 --available

2 RQR24.03_B0027, RQR24.05_B0029, RQR24.06_B0030 [pre-requisite?]

注:

• The list for Device 1.2 is empty because there is no firmware available in the archive.
• The firmware “RQR12.08_B0030” is marked as “[pre-requisite]” because the firmware version “MPK01.02_B0021” of Device 1.1 is not compatible.
• The firmware “RQR24.06_B0030” is marked as “[pre-requisite?]” because there may be a compatibility issue with Device 2.1. However, this device is disconnected and its firmware version is not available.
• After an upgrade, Devices 1.1 and 2 could be restored to their original firmware, but not Device 1, because the original firmware is missing from the archive (in this example）。
• The firmware versions RQR12.09_B0030 and RQR24.07_B0030 are not listed (even though they are in the archive), because they are incompatible with the boot-loaders of Devices 1 and 2, respectively. This can be inferred from the meta-data.

--pre-requisite

Display a semi-colon-separated list of firmware that require at least one pre-requisite. Each of them is followed by a colon (“:”) and a comma-separated list of available pre-requisites. If the “–target” argument is given, only the specified device is listed. Otherwise, all available devices are listed. Each pre-requisite is a pair consisting of a device identifier and a firmware separated by an arrow (“->”). If several firmware are possible to solve a given pre-requisite, they are separated by vertical bars (“|”). On the other hand, if there are no firmware, which can solve a pre-requisite, the arrow is followed by “[none available]”. When a pre-requisite may apply, but cannot be assessed, because the other devices is disconnected, it is marked as “[pre-requisite?]”.

Example: same as above:

# logitech_dfu-pre-requisite

1 RQR12.08 B0030: 1.1 -> MPK01.03 B0024
1.1
1.2
2 RQR24.06_B0030: [pre-requisite?]
2.1 # logitech_dfu-target 1.2 --pre-requisite
1.2

Example: more complex output examp上：

# logitech_dfu --target 1 --pre-requisite

1 RQR12.09_B0030: 1.1 -> MPK01.03_B0024 | MPK01.04_B0025, 1.4 ->
MPK03.02_B0009 | MPK03.03_B0010; RQR12.10_B0031: 1.1 -> MPK01.04_B0025,
1.4 -> MPK03.03_B0010

--upgrade <Firmware>

Upgrade devices with the specified firmware. If the “–target” argument is given, only the specified device is upgraded. Otherwise, all devices, of the type compatible with the firmware, are upgraded. The upgrade is performed even if the current firmware is newer or identical to the specified firmware (i.е., downgrade and re-programming are possible).

This command will fail when:

• The firmware is incompatible with the device (when the “–target” argument is specified).
• At least one of the target devices (or the target device, if the “–target” argument is specified) is disconnected. When used in conjunction with “–wait”, this condition applies at time-out.
• At least one of the target devices (or the target device, if the “–target” argument is specified) does not satisfy a pre-requisite (marked “[pre-requisite]”) ог may not satisfy a pre-requisite (marked “[pre-requisite?]”), unless the “–force” option is also specified. When used in conjunction with “–wait”, the latter condition applies at time-out.
• A DFU error occured with at least one of the target devices (or the target device, if the “–target” argument is specified).

If a device requires user-action to enter DFU (marked as “[user-action]”), the user is prompted to do so. When used in conjunction with the “–wait” option, the user is prompted before upgrading any device that was disconnected at the time the program was started. Prompting is done using the console, unless the “–pop-up” option is specified.

Example: same as above:

[Assuming that Device 2.1 is on-line]

# logitech_dfu-target 2.1 --upgrade MPK04.01_B0010
Firmware upgrade in progress. Do not turn off your K850 … [console]
K850 upgraded successfully to MPK04.01_B0010 [standard output]

# logitech_dfu --wait --target 2.1 --upgrade MPK04.01_B0010
Firmware upgrade in progress. Do not turn off your K850 … [console]
K850 upgraded successfully to MPK04.01_B0010 [standard output]

[Assuming that Device 2.1 is off-line]

# logitech_dfu --target 2.1 --upgrade MPK04.01_B0010
Cannot upgrade K850: device is offline [standard error]

# logitech_dfu --wait --target 2.1 --upgrade MPK04.01_B0010
Waiting for K850 to come online … [standard output]

[Once Device 2.1 comes on-line]

Please press enter to upgrade your K850 … [console]
Firmware upgrade in progress. Do not turn off your K850 … [console]
K850 upgraded successfully to MPK04.01_B0010 [standard output]

--upgrade_latest

Upgrade devices with the latest firmware. If the “–target” argument is given, only the specified device may be upgraded. Otherwise, all devices may be upgraded. The upgrade is only performed when the current firmware is not the latest one available (in the archive).

This command will fail when:

• At least one of the target devices (or the target device, if the “–target” argument is specified) is disconnected. When used in conjunction with “–wait”, this condition applies at time-out.
• At least one of the target devices (or the target device, if the “–target” argument is specified) does not satisfy a pre-requisite (marked “[pre-requisite]”) or may not satisfy a pre-requisite (marked “[pre-requisite?]”), unless the “–force” option is also specified. When used in conjunction with “–wait”, the latter condition applies at time-out.
• A DFU error occured with at least one of the target devices (or the target device, if the “–target” argument is specified).

If a device requires user-action to enter DFU (marked as “[user-action]”), the user is prompted to do so. When used in conjunction with the “–wait” option, the user is prompted before upgrading any device that was disconnected at the time the program was started. Prompting is done using the console, unless the “–pop-up” option is specified.

入出力

Expected messages (included success messages) are displayed to the standard output stream, unless redirected (see “–output” argument).

Error messages are displayed to the standard error stream, unless redirected (see “–error” argument). All errors yield at least one error message. The program usually stops after the first error.

When required, the user is prompted using the console (“CON”), unless the “–pop-up” option is specified. The console is used both for the prompt message (even if the standard output stream is re-directed) and for the user response.

戻り値

Upon success, a null value is returned. All errors return a non-null value (besides yielding a message, see above).

Possible error codes:

• (code 0) Success
• (code -1) Invalid Argument: invalid timeout or target value is specified, or one of the program arguments is not recognized
• (code 1) Generic Error: generic error, might appear in rare cases when some Windows API is not available (e.g. because of a very old version of Windows)
• (code 2) Archive Error: archive could not be downloaded or opened
• (code 3) Invalid Firmware (for –upgrade command): specified firmware is missing from the archive, or is incompatible with the device (if –target argument is specified)
• (code 4) Prerequisites NotSatisfied: the provided (or latest) firmware does not (or may not) satisfy the prerequisites of the target device (or one of the devices)
• (code 5) Not Connected: cannot upgrade because the device is disconnected, or was unplugged after the program was started
• (code 6) Device Error: generic error when firmware upgrade fails (see error stream for details)

Archive format

The archive shall contain:

• A single top-level folder, whose name is irrelevant.
• A sub-folder for each product. Valid product folders shall have a name composed of the firmware prefix and number (i.e., formatted as described for the “–fw_version” argument before the dot character).
• Within each product folder, a sub-folder for each available firmware version Valid firmware folders shall have a name composed of the firmware prefix, number, and version (i.e., formatted as described for the “–fw_version” argument before the underscore character) or a name corresponding to the full firmware version (i.e., formatted exactly as described for the “–fw_version” argument).
• Within each firmware folder, the DFU file in Intel hexadecimal format (“.hex”), signed hexadecimal format (“.shex”), or HID++ Feature 0x00D0 format (“.dfu”). The root name of this file (i.e., without extension), shall correspond to the full firmware version (i.e., formatted exactly as described for the “–fw_version” argument).
• Within each firmware folder, a sub-folder called “lvfs”, containing meta-data in XML format.

The updater tools shall recognize an archive organized as described above. Optionally, it may relax these constraints when checking for valid archives.

ドキュメント / リソース

Logitech Script DFU Tool [pdf] 取扱説明書 Script DFU Tool, DFU Tool

参考文献

• ユーザーマニュアル