HTTPS clone URL
Subversion checkout URL
- Anatomy of a key management protocol
- Bedienungsanleitung HexaSense
- Bootloader Documentation
- Changing the device MAC address
- Compiling and uploading Firmware
- Compiling Firmware
- Connect PC Directly
- Cpp netlib installation
- Creating RasPi SD images
- Currently used EIDs
- Debian for Hexabus Firmware Development
- Emulate a Hexabus device using libhexabus
- Energy Meter Persistent Storage
- Hexabus Assembler
- Hexabus Compiler
- Hexabus Compiler (old)
- Hexabus hardware at the ITWM
- Hexabus hardware distributed to testers
- Hexabus Howto Setup
- HexaBus Plug
- Hexabus Raspberry Pi Environment
- Hexabus temperature sensor
- Hexabus virtual machine
- Hexajuice interface
- HexaPi setup
- Installationsanleitung HexaBus Basisstation
- Installationsanleitung HexaSense
- iomega iconnect
- Kalibrationsanleitung Plug
- MAC Addresses
- Make Your Own Hexabus Device
- New Bootloader (in progeress)
- New Hexabus Packet Format
- New Hexabus Protocol
- OpenWRT Guide
- Optocouplers on the hexabusplug
- Proposed Hexabus Devices
- Raspbian toolchain
- Reading switch like devices using hexapush
- Reliable state machines (concept)
- Routing Hexabus packets
- Routing tests
- Setting up your Hexabus
- State Machines
- Supply modification the Low Voltage board
- Switching things using hexonoff
- The Date and Time Service
- TP Link TL MR3020 as 6LoWPAN access point
- Upgrade Plug to Plug plus
- Uploading protocol
- Using a S0 meter
- Using Analogread
- Using libHexabus (0.6.0 or later)
- Using the BMP085 Pressure Sensor
- Using the HYT321 humidity sensor
- Using the IR Receiver
- Using the Presence Detector
- Webfrontend ToDo
- Working with Devices
Clone this wiki locally
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 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.
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:
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.