aerotools-ng: Tools for Accessing the Aquaero5(R) USB Device
--------------------------------------------------------------
(C) 2012 lynix <lynix47@gmail.com>
(C) 2013 JinTu <JinTu@praecogito.com>, lynix <lynix47@gmail.com>
SUMMARY
----------------
aerotools-ng aims at providing a C interface for accessing the Aquaero5(R) USB
device by 'Aqua Computer' (http://www.aqua-computer.de).
It consists of a set of functions for data access and conversion, and a
command-line tool using these functions as an example implementation.
REQUIREMENTS
----------------
Unlike its predecessor, aerotools (which targets the Aquaero(R) 4.00),
aerotools-ng currently uses the USB HIDDEV interface provided by the Linux
kernel via the /dev/usb/hiddev? device nodes, so no dependencies for this.
To be able to build and run the JSON RPC server, 'aq5rpcd', you need the JSON
RPC server 'jsonrpc-c' by Henrique Gomes (hmng). It is available under MIT
license on GitHub: https://github.com/hmng/jsonrpc-c.
BUILDING
----------------
To build the main components of the project simply issue `make` in the project
root. Compiled binaries will reside in the 'bin' subdirectory. If building for
firmware version 1027, you must uncomment the appropriate line in the Makefile.
To build optional components such as the JSON RPC server 'aq5rpcd', issue
`make all` in the project root. Be sure to install 'jsonrpc-c' first, and point
to its prefix using the JRPC_PREFIX environment variable if not installing to
/usr.
SETUP
----------------
To be able to query the Aquaero5(R) device you have to set appropriate access
rights for the device node.
You can either do this manually by identifying the device node using `lsusb`
(looking for the Vendor- and Product-ID), or just install a udev rule like this
one:
ATTRS{idVendor}=="0c70", ATTRS{idProduct}=="f001", GROUP="aquaero", MODE="0640"
This will give all members of the 'aquaero' group read access to the device.
As the Aquaero5(R) identifies itself as multiple devices (USB keyboard, mouse
and the actual device we want to query) you have to examine which device node
represents the data source.
In my case, there is /dev/usb/hiddev[0-2] which all match the udev rule provided
above. The correct one for me is /dev/usb/hiddev0, but I don't know whether it is
always the first one. Just try as stated under USAGE - if you choose the wrong
one there will simply be no output at all.
USAGE: aerocli
----------------
aerocli, as stated above, is the example implementation of a command-line tool
that uses the provided query- and format conversion functions provided by
aerotools-ng.
To query the first device found (via autodiscovery), simply issue `aerocli`.
To query a specific device (if you have more than one attached to your system)
simply issue `aerocli -d /dev/usb/hiddevX` (see SETUP for the meaning of X).
To get a more script-friendly output in the form of 'KEY=VALUE' pairs just add
`-o export`.
For more comprehensive output in both default and export modes, use `-a`,
e.g. `-a -o default` or `-a -o export`.
To set software sensor values use `-s SENSOR:VALUE` i.e. `-s 1:30.00` or
`-s 1:11.11 -s 2:22.22 -s 3:33.33`.
Note: Multiple software sensor values must be sent at once. If aerocli is run
again and any sensor value is set, all other unspecified sensors are set to
default (disconnected).
To synchronize the Aquaero5(R) time with your system time use `-T`.
To set a device/sensor name use `-n REFERENCE:INDEX:VALUE` i.e. `-n "sensors:1:Sensor 1"`.
To get a list of the device/sensor name references and all default names,
simply omit the argument to `-n`.
USAGE: aq5rpcd
----------------
aq5rpcd, as stated above, is a JSON RPC server that allows for easy data polling
in third party applications, possibly over a network connection.
To start it, simply call the binary (`./bin/aq5rpcd` from project root).
To change the TCP port 'aq5rpcd' listens on (default: 9090), use the '-p'
parameter.
BUGS / CONTACT
----------------
Feel free to report any bugs you find using the 'issues' function on GitHub. If
you wish to contact the authors, you can drop them an email.
For lynix, you might wish to use his GPG key, #4804CCA9 on keys.gnupg.net
LICENSE
----------------
This program is published under the terms of the GNU General Public License,
version 3. See the file 'LICENSE' for more information.