-
-
Notifications
You must be signed in to change notification settings - Fork 142
3.1. TCP client 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:
usage: read [-f] [-m SECONDS] [-c CIRCUIT] [-d ZZ] [-p PRIO] [-v|-V] [-n] [-i VALUE[;VALUE]*] NAME [FIELD[.N]]
Read value(s) or hex message.
-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 increase verbosity (include names/units/comments)
-V be very verbose (include names, units, and comments)
-n use numeric value of value=name pairs
-i VALUE read additional message parameters from VALUE
NAME 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, the field names (followed by "="), units (following the value), and comments (in square brackets, if defined) can be included (by adding as many "-v" arguments as desired), 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
ZZ destination address
PB SB primary/secondary command byte
NN number of following data bytes
Dx 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 or send a message without any fields.
Use the following format to write value(s) in a named message:
write [-d ZZ] -c CIRCUIT NAME [VALUE[;VALUE]*]
-d ZZ override destination address ZZ
-c CIRCUIT CIRCUIT of the message to send
NAME NAME of the message to send
VALUE a single field VALUE
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 a master destination). For a successfully sent broadcast message, the result is "done broadcast".
For writing a message picked by it's master hex data instead of the message name, use this format:
write [-c CIRCUIT] -h ZZ PB SB NN Dx
-c CIRCUIT CIRCUIT of the message to send
ZZ destination address (e.g. "FE" for broadcast)
PB SB primary/secondary command byte
NN number of following data bytes
Dx 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.
Send arbitrary data in hex (only if enabled, see `--enablehex' in Daemon options):
hex ZZPBSBNNDx
ZZ destination address (e.g. "FE" for broadcast)
PB SB primary/secondary command byte
Dx data byte(s) to send
NN number of data bytes to send
Dx 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 or just "done" (if the message does not include an answer, e.g. for a master destination). For a successfully sent broadcast message, the result is "done broadcast".
Find configured messages by name. This will also print the cached value if requested.
usage: find [-v|-V] [-r] [-w] [-p] [-d] [-h] [-i ID] [-f] [-F COL[,COL]*] [-e] [-c CIRCUIT] [NAME]
Find message(s).
-v increase verbosity (include names/units/comments+destination address+update time)
-V be very verbose (include everything)
-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
-h show hex data instead of decoded values
-i ID limit to messages with ID (in hex, PB, SB and further ID bytes)
-f list messages in CSV configuration file format
-F COL[,COL]* list messages in the specified format
(COL: type,circuit,name,comment,qq,zz,pbsb,id,fields)
-e match NAME and optional CIRCUIT exactly (ignoring case)
-c CIRCUIT limit to messages of CIRCUIT (or a part thereof without '-e')
NAME 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 can be included (by adding as many "-v" arguments as desired) and in most verbose mode, 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]". Alternatively, in hex mode the master and slave data bytes are shown in hex (separated by slash) instead of the fields.
When using one of the "-f" or "-F" options, the response will list the matching messages in CSV format, either in the complete configuration file format with all the columns when using "-f", or just the columns requested with "-F COL[,COL]", 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.
If only the message names and comments are desired, one could use:
find -F name,comment -c broadcast outsidetemp
This would result in this response:
outsidetemp,Außentemperatur
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.
Report information about the daemon, the configuration, and seen devices:
info
The response lists the ebusd version, the signal state, the number of masters, the message count, as well as a list of seen addresses together with their scan state and optionally the loaded configuration file, e.g.:
version: ebusd 2.3.5b88c67
signal: acquired
symbol rate: 46
reconnects: 0
masters: 4
messages: 855
conditional: 213
poll: 3
update: 59
address 03: master #3
address 08: slave #3, scanned "MF=Vaillant;ID=EHP00;SW=0327;HW=7201", loaded "vaillant/08.ehp.csv"
address 10: master #6
address 15: slave #6, scanned "MF=Vaillant;ID=UIH00;SW=0216;HW=6901", loaded "vaillant/15.uih.csv"
address 17: master #9
address 1c: slave #9, scanned "MF=Vaillant;ID=RC C ;SW=0501;HW=6201", loaded "vaillant/1c.rcc.4.csv"
The "scanned" and "loaded" parts of each seen slave address are available with enabled "--scanconfig". After a successful "scan" command, the "scanned" part is available as well (regardless of the configuration options).
The master number between 1 and 25 is shown behind master addresses as well as slave addresses with an associated master.
Grab messages, stop grabbing, or report the unknown or all grabbed messages.
When grabbing messages, ebusd will keep the last one of each 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. ebusd automatically grabs all messages when starting up since version 2.1.0.
To start grabbing messages:
grab
To stop grabbing:
grab stop
To report the grabbed unknown messages:
grab result
To report all grabbed messages:
grab result all
The response will then list the last seen message for each unique message key, the number of times the message was grabbed, as well as the configured message circuit and name (if all messages were requested), e.g.:
1025b5040101 / 09350300000003000100 = 10: hwc Mode
1025b504010d / 050000550135 = 9: hwc Status
1025b505072b000100000000 / 00 = 2
1025b50903290000 / 050000940300 = 1
1025b509040ef40000 / 00 = 2
1050b5040100 / 0a03565511240407167006 = 5: mc DateTime
1050b5040101 / 09140100000081000100 = 5: mc Mode
1050b504010d / 051800840114 = 5: mc Status
1050b505072b000100000000 / 00 = 1
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 "/".
If the result for all messages was requested, the circuit name and message name are added behind the ":" after the message count for known messages.
Scan for seen slaves, all possible slaves (full), a single slave (address ZZ), or report 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)
Alternatively, a synchronous scan for a single slave adresses can be initiated like this:
scan ZZ
This will then respond with a single line containing the (simple) scan result for that slave or the error message.
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 of each received and sent byte:
raw
This will produce a lot of entries in the log file (or alternatively in the file set in the parameters, see --lograwdatafile). Each received byte is placed in a log entry after a "<" and each sent byte after a ">".
Toggle binary dump of received bytes to dump file (see --dumpfile):
dump
Reload the message configration files:
reload
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
i for info
g for grab
q for quit
h for help