                        Phidget22 Admin Tool
                            Version 1.25

Summary
=======

 The Phidget22 Admin Tool will list local and remote Phidgets and their
 channels, Network Phidgets (SBCs) and Phidget servers, and open Phidget
 channels and active connections on Phidget Network Servers.

 The Tool can upgrade or downgrade firmware on local and remote Phidgets.

Installation
============

    ./configure; make; make install

Requirements
============

    libphidget22
    libphidget22extra

Usage
=====

    phidget22admin [options]...

 Options:

  -A            Set password for the server specified by -H. The password
                will be prompted - it is not specified as an argument. This
                allows connections to Phidget Network Servers that have a
                password set.

  -F path       Set path of firmware upgrade files. By default, the tool
                looks for a 'firmware' directory in the current directory,
                and if not found looks for installed firmware (on Linux)
                in the standard install path (/usr/share/phidget22admin/).

  -H srvname    Filter by server name. This will filter results to a single
                Network Server. This is required when using -o, -c or -k,
                or upgrading firmware on a remote Phidget.

  -L            Include local devices when listing devices with -d. If
                neither -L nor -R are specified, both default to true.

  -M sn[/hp/ch] Filter by serial number / hub port / channel. This is used
                to filter the output of -d, or to select a device for firmware
                upgrade. '-M 1234' will show devices with the serial number
                '1234', '-M 1234/2' will show VINT devices connected to port
                2 of a VINT hub with serial number '1234', '-M 1234//0' will
                show all channel 0 connected to serial number '1234', etc..

  -R            Include remote devices when listing devices with -d. If
                neither -L nor -R are specified, both default to true.

  -U            Perform a firmware upgrade. This requires that a unique
                device is specified with -M. To upgrade a remote device, -H
                must be specified as well. To perform a major version upgrade,
                specify -m; otherwise a minor upgrade will be performed.
                Firmware is upgraded to the newest available (major or minor)
                version that is newer than the installed version, unless
                the version is overriden with -V.

  -m            Allow major firmware upgrades of 100+. Major upgrades can
                break compatibility with existing software and so are
                explicitely opt-in.

  -V version    Specify firmware version for upgrade. This can be used to
                install a particular firmware version - by default, the
                newest firmware version is installed.

  -a            List ALL devices which support firmware upgrade - by default
                only devices with a newer firmware version available are
                listed. This option requires -d and -u.

  -c            List open channels on server specified by -H. This displays
                a list of channels that the specified server has open, along
                with which clients are accessing them.

  -d            List Phidget devices and their channels. This is filtered by
                -M, -H, -L, -R. If -u is specified, this displays devices
                which can be firmware upgraded, along with available firmware
                versions.

  -k key[=val]  Print or set a key, on the control dictionary, on the server
                specified by -H. This could be used to change the log level on
                a running Network server, to read out the open connections
                json string, etc.

  -l            Enable phidget22 logging. Logs are written to
                'phidget22admin.log' in the current directory. -l can be
                specified multiple times to increase the logging verbosity.

  -o            List open connections on server specified by -H. This displays
                a list of all clients connected to a server.
  
  -q            Quiet output. When used with -u, displays firmware upgrade info
                in machine readable form:
   isRemote,isVint,serial,port,sku,version_installed,version_latest,server_name

  -s            List Phidget Network Servers and Network Phidgets such as the
                PhidgetSBC and HUB5000.

  -u            Modify -d to display devices which support firmware upgrade
                instead of displaying devices and channels. This also lists
                the installed and available firmware version for each device.
                By default, only devices with a newer firmware available are
                shown. Specify -a to also list devices that are up to date.

  -v            Verbose output. This displays extra information for servers
                listed by -s

  -w seconds    Time to wait for devices and/or servers before proceeding to
                list devices, list servers, upgrade firmware, etc.. This
                defaults to 3 seconds. On a busy or slow network, increasing
                the delay may discover more servers/devices.

Examples
========

    phidget22admin -d
        List all local and remote Phidgets and channels.

    phidget22admin -s
        List all Phidget Network Servers and Network Phidgets.

    phidget22admin -du
        List Phidgets which have a newer firmware available.

    phidget22admin -U -M 123456
        Upgrade firmware of a local USB Phidget with serial number 123456.

    phidget22admin -U -M 123456/2
        Upgrade firmware of a local VINT Phidget connected to port 2 of a
        VINT Hub with serial number 123456.

    phidget22admin -U -H "phidgetsbc" -M 123456
        Upgrade firmware of a remote USB Phidget with serial number 123456
        on the Network Server 'phidgetsbc'.
