-
Notifications
You must be signed in to change notification settings - Fork 7
3. Commands
This section lists the available commands that ebusd understands on the TCP port it listens to (usually 8888).
In general, a request to ebusd is terminated by a newline and ebusd will answer with one or more lines in return. Since the result may cover more than one line, a response ends with a single empty line.
If the wrong number of arguments was specified, the response starts with "usage:" and explains the command.
If the request was invalid or an error occurred during execution, the response starts with "ERR: " followed by the error message.
On success, the response is "done" unless otherwise noted below.
Read value(s) from a configured message. The result can either be returned from the cache (without accessing the eBUS at all) or retrieved directly from the slave by querying it via the eBUS.
Use the following format to read value(s) from a named message:
read [-f] [-m SECONDS] [-c CIRCUIT] [-d ZZ] [-p PRIO] [-v] [-n] NAME [FIELD[.N]]
-f force reading from the bus (same as '-m 0')
-m SECONDS only return cached value if age is less than SECONDS [300]
-c CIRCUIT limit to messages of CIRCUIT
-d ZZ override destination address ZZ
-p PRIO set the message poll priority (1-9)
-v be verbose (include field names, units, and comments)
-n use numeric value of value=name pairs
NAME the NAME of the message to send
FIELD only retrieve the field named FIELD
N only retrieve the N'th field named FIELD (0-based)
If the configured message contains more than one field and no particular field was requested, all field values are returned and concatenated with a semicolon character in between, so a successful response in principle looks like this:
FIELD[;FIELD]*
In order to retrieve a single field only, use FIELD (and optionally N) to specify which field you want, for example:
read -c mc Timer.Monday from.0
would only return the first "from" field for the mixing circuit's timer program for Mondays.
In verbose mode, each FIELD is prefixed with the field name followed by "=" and suffixed with the unit (if defined) and the comment in square brackets (if defined), e.g. "temp=10.5 °C [temperature]".
For reading a message picked by it's master hex data instead of the message name, use this format:
read [-f] [-m SECONDS] [-c CIRCUIT] -h ZZ PB SB NN Dx
-f force reading from the bus (same as '-m 0')
-m SECONDS only return cached value if age is less than SECONDS [300]
-c CIRCUIT limit to messages of CIRCUIT
-h send hex read message (or answer from cache):
ZZ destination address
PB SB primary/secondary command byte
NN number of following data bytes
Dx the data byte(s) to send
The space between the hex bytes can also be left out.
If successful, the response contains the answer retrieved from the device (or from the cache) in hex digits.
Write value(s) in a configured message, directly send hex data, or send a message without any fields.
Use the following format to write value(s) in a named message:
write [-c] CIRCUIT NAME [VALUE[;VALUE]*]
CIRCUIT the CIRCUIT of the message to send
NAME the NAME of the message to send
VALUE a single field VALUE
The option "-c" is only for convenience, so that all the commands with a CIRCUIT argument can be used in the same way.
If successful, the response contains the answer retrieved from the device or just "done" (if the message does not include an answer, e.g. for broadcast or master destination).
For directly sending hex data, use this format:
write -h ZZ PB SB NN Dx
ZZ destination address (e.g. "FE" for broadcast)
PB SB primary/secondary command byte
NN number of data bytes to send
Dx the data byte(s) to send
The space between the hex bytes can also be left out.
If successful, the response contains the answer retrieved from the device in hex digits.
Find configured messages by name. This will also print the cached value if requested.
usage: find [-v] [-r] [-w] [-p] [-d] [-i PB] [-f] [-e] [-c CIRCUIT] [NAME]
Find message(s).
-v be verbose (append destination address and update time)
-r limit to active read messages (default: read + passive)
-w limit to active write messages (default: read + passive)
-p limit to passive messages (default: read + passive)
-d only include messages with actual data
-i PB limit to messages with primary command byte PB ('0xPB' for hex)
-f list messages in CSV configuration file format
-e match NAME and optional CIRCUIT exactly (ignoring case)
-c CIRCUIT limit to messages of CIRCUIT (or a part thereof without '-e')
NAME the NAME of the messages to find (or a part thereof without '-e')
If successful, the response lists all matching messages in the following format (one line per message):
CIRCUIT NAME = FIELD[;FIELD]*
In verbose mode, the field names, units, and comments are included and each line is suffixed with the hex destination address, the last update time (if available), and the message type in square brackets, e.g. "[ZZ=15, lastup=2015-02-14 08:10:45, active read]".
When using the "-f" option, the response will list the matching messages in CSV configuration file format, where all templates have been resolved to the final value. For example:
find -f -c broadcast outsidetemp
would result in this response:
u,broadcast,outsidetemp,Außentemperatur,,fe,b516,01,temp2,m,D2B,,°C,Temperatur
This format may be useful when configuring other daemons that need a list of available messages and the fields.
Start or stop printing changed values.
To start listening:
listen
To stop listening:
listen stop
If successful, the response is either "listen started", "listen continued", or "listen stopped".
While the client is listening for changes, ebusd will automatically feed it with each message that changed a previously cached value like this:
CIRCUIT NAME = FIELD[;FIELD]*
Report the bus state (signal acquisition).
state
The response is either "no signal", or starts with "signal acquired" followed by the current number of received symbols per second, the maximum number of symbols per second, and the number of masters, e.g.:
signal acquired, 45 symbols/sec (197 max), 5 masters
The maximum possible symbol rate is around 220 symbols/sec.
Grab unknown messages or stop it, or report the seen unknown messages.
When grabbing unknown messages, ebusd will keep the last one of each unknown message depending on the message key. This key is built from the QQZZPBSBNN header plus up to 4 master data bytes that normally are used for building the message ID.
To start grabbing:
grab
To stop grabbing:
grab stop
To report the grabbed messages:
grab result
The response will then list the last seen message for each unique message key, e.g.:
1025b5040101 / 09350300000003000100
1025b504010d / 0500006c0135
1025b505072b000000000000 / 00
1025b509040ef40000 / 00
1050b5040100 / 0a03505911140306152007
1050b5040101 / 09150300000081000100
1050b504010d / 051b00b20115
1050b505072b000000000000 / 00
This can then be used to analyze the message format and create new message definitions.
For master-slave messages only, the slave part is added behind the "/".
Scan for all seen or all possible slaves, or report the scan result.
To initiate a scan over seen slave adresses:
scan
To initiate a full scan over all possible slave adresses:
scan full
The scanning takes a little time depending on the number of queried slaves and the scan configuration (see Scanning).
To show the result of the last scan request:
scan result
If successful, the response lists all devices that answered to the "identification" message, each in one separate line, e.g.:
08;Vaillant;EHP00;0327;7201;21074500;100027790;000000000;N8
15;Vaillant;UIH00;0216;6901; ; ; ;
23;Vaillant;EHP00;0327;7201;21074500;100027790;000000000;N8
25;Vaillant;EHP00;0327;7201;21074500;100027790;000000000;N8
50;Vaillant;EHP00;0327;7201;21074500;100027790;000000000;N8
52;Vaillant;MC2 ;0500;6301;21114030;6782<<<<0;000000000;N6
53;Vaillant;MC2 ;0500;6301;21114030;6782<<<<0;000000000;N6
The columns of each response line are:
- slave address
- manufacturer name (or code)
- identification string
- software version
- hardware version
- further columns depending on the scan configuration (see Scanning)
Adjust the log level or the log facilities.
Set the area(s) to log:
log areas AREA[,AREA]*
The possible AREA values are:
- main: primary system messages
- network: networking subsystem messages
- bus: bus related messages
- update: updates of message values found by listening to the eBUS
- all: include all areas
Set the log level:
log level LEVEL
The possible LEVEL values are (similar to syslog):
- error: only error messages
- notice: error and noticeable messages
- info: error, noticeable and informational messages
- debug: all messages including debug
Toggle logging received and sent raw bytes:
raw
This will produce a lot of entries in the log file. Each received byte is placed in a log entry after a "<" and each sent byte after a ">".
Toggle writing received waw bytes to dump file:
dump
Reload the message configration files:
reload
Stop the ebusd process (this will probably be removed in a future version of ebusd):
stop
Close the client connection:
quit
Print help:
help [COMMAND]
For help on a pparticular command, add the name of the COMMAND.
The main commands are also available using a single letter:
r for read
w for write
f for find
l for listen
s for state
g for grab
q for quit
h for help