Clone this wiki locally
Hexabus basic tools
This page describes the setup and basic use of some low level Hexabus tools. They are needed for testing your Hexabus network, and you can use them to build useful scripts and other nice things that involve a PC connected to a Hexabus network.
Currently, we do not provide binary builds of the tools (which will change in the future). You have to compile the tools on your own. If you have trouble with this, please contact us on the mailing list.
The libhexabus toolset
The libhexabus toolset contains several command-line tools for communication with Hexabus devices:
- hexaswitch - send packets to your Hexabus devices (writes, queries, broadcasts), or receive broadcasts from your Hexabus network, and dump them to the console.
- hexalog - data logging app for Hexabus: Log broadcasts from Hexabus devices to an SQLite database, which can be processed further using the tools provided with libklio.
- hexaupload - used to transfer binary state machine images generated by the Hexabus Assembler to Hexabus devices (see Hexabus Compiler for more information!).
For an easy installation we provide the binary-packages of our nightly builds. Please see how to install the Packages
If you want to compile your self, go ahead.
Make sure boost (1.49+) and associated -dev or -devel packages are installed on your system. You will also need git, cmake and a C++ compiler (g++ or clang).
It is highly recomend to install libklio first, otherwise hexalog won't work. Libklio depends on sqlite3, so make sure it (along with libsqlite3-dev) is installed on your computer.
The other tools libhexabus tools work fine without libklio, it is only used by hexalog (for storing the logged data). For how to use an compile libklio please see also https://github.com/mysmartgrid/libklio/blob/master/README.md
git clone https://github.com/mysmartgrid/libklio.git cd libklio make make release cd ..
make release builds packages for several linux distros, which can be installed using your package manager. If there is no package for your distro available or you don't want to use a package manager, just use
After libklio is installed, you can grab a copy of the hexabus git repo:
git clone https://github.com/mysmartgrid/hexabus.git
This repository contains all the hexabus software as well as the Hexabus device firmware.
Feel free to look through the repo and browse the code.
There are several branches containing different (mostly experimental) versions of the software.
Most likely everything you need is in the
development branch though.
Note: If you are looking for compatibility with older Hexabus devices, you might want to check out the
At the moment, we are only interested in
libhexabus, so check out the development branch and go to the libhexabus directory.
cd hexabus git checkout development cd hostsoftware/libhexabus
Libhexabus can be installed in the same way as libklio: Just run
make release and look for the package files to install, or use
make install if you don't want to use package management.
The package installs three executables in your system:
hexaswitch --help tells you about the command line syntax of hexaswitch.
Dumping all received Hexabus packets to the console can be done by running
hexaswitch -c listen, or, if you want to listen on a specific interface,
hexaswitch -c listen -I<interface name>, e.g.
hexaswitch -c listen -Iusb0.
If you want to send a write packet to a specific Hexabus device, run
hexaswitch -i <IP addr> -c set -e <eid> -d <datatype> -v <value>
For instance, to send WRITE packet with the BOOLean value 0 and EID 1 to the device at abcd::50:c4ff:fe04:1234, use
hexaswitch set abcd::50:c4ff:fe04:1234 -e 1 -d 1 -v 0.
A list of datatypes can be seen running
Inquiring the value of a specific endpoint is done using the get command:
hexaswitch <IP addr> -c get -e <eid>
Example: To get the current value of endpoint 1 on device abcd::50:c4ff:fe04:1234, use
hexaswitch abcd::50:c4ff:fe04:1234 -c get -e 1.
This sends a query packet for the specified EID. Then hexaswitch waits for a response (an INFO packet) and prints it out on the console. If the response is not received for whatever reason (device is not there, packet loss, ...), hexaswitch will wait indefinitely and can be aborted with Ctrl+C.
There are several shorthand commands for setting and querying common EIDs:
- on / off: Set EID1 (the relay of a Hexabus Plug) to 1 / 0.
- status: Get EID1
- power: Get EID2 (the power meter of a Hexabus Plug+)
- devinfo: Get device info
To send broadcasts, use the
hexaswitch -c send -e <eid> -d <datatype> -v <value>
hexaswitch -c send -e 2 -d 3 -v 100 will broadcast a reading of 100 on the endpoint 2 with datatype Uint32. The network interface can be specified with the
-I command line option.
If you want to use hexalog, you first have to create a new klio database:
klio-store create hexalog.klio
Now you can log to it using
hexalog -s hexalog.klio
To get readings out of this file, use the klip-export tool that has been installed along with libklio.
Please refer to Hexabus Compiler for notes on hexaupload.
Mac OS X
brew install pkg-config cmake boost sqlite3 git clone https://github.com/mysmartgrid/libklio.git cd libklio make make install cd .. git clone https://github.com/mysmartgrid/hexabus.git cd hexabus/hostsoftware/hexaswitch make make install
Hexinfo is a tool for reading a Hexbus device descriptor from a device, and finding out the properties of its endpoints. It can also generate header files for the Hexabus Compiler (containing device and endpoint definitions).
You need to install libhexabus (described above) and the Hexabus Compiler (described on it's own page) first.
Then you can change into the
hexinfo directory, run
make release there and install the package that is generated. (It's also possible to run
make install or just use the binary generated by running
Note: Discovery of endpoint Names and datatypes, and therefore HBC header generation, only works with device firmwares from the "development" branch (or newer).
hexinfo <IP> -p (and replace
<IP> by the IPv6 address of a working Hexabus device). The device will now be queried, and the results printed onto the console. (-p is for "print")
If you want to generate a Hexbaus Compiler file containing endpoint definitions for the endpoints discovered by hexinfo, just add
-e filename.hbh (and replace filename.hbh by the name of the file you want to write) to the command line.
If the file already exists (it has to be a valid Hexabus Compiler file then!), the generated endpoint definitions are added at the end. If the file already contains endpoint definitions, only definition blocks for the endpoint IDs not yet present in the file will be generated.
You can also generate a device definition (including the endpoint list) using hexinfo. Just add
-d filename.hbh (replacing filename.hbh by the actual name of the file).
This works much like generating endpoint definitions: If the file already exists and contains device definitions, the device is only added if it doesn't have a definition yet.
It is possible to use the same file for endpoint and device definitions.
Note: There is currently no way to find out the access level of an endpoint from a Hexabus device. Therefore, if you want to use the access level checking feature of the Hexabus Compiler (e.g. giving an error message when you try to write to a read-only endpoint), you have to add the access level to the endpoint definitions manually.
You might want to edit the files manually anyways, because the endpoint names are rather descriptive (and therefore tend to be quite long). Additionally, all the Hexabus Plugs using the development firmware have the same device name, which doesn't work if your network has more than one plug.
Since hexinfo only adds newly discovered information to the files, it can be used to make a list of all devices and their endpoints in a network. If you have a list of IP-addresses of your devices, you can just run hexinfo once for each IP address, using the same filenames each time. But it is also possible to auto-detect the devices on your network:
Automatic device discovery
You can run
hexinfo -c if you want to use this feature.
hexinfo then broadcasts a query packet, which triggers a response from all devices on your network.
It then waits some time (3 seconds) for replies from the devices.
Then each device is inquired for its device descriptor and endpoint descriptors.
You have to combine the -c command line switch with either -p (print info to console) or -e and/or -d (generate endpoint/device info files), or both, if you want hexinfo to generate some output.
There also is the -V (verbose) command line switch which instructs hexinfo to print some more information about what is going on.