2. Run

Introduction

The ebusd binary offers a lot of command-line options to adjust its behaviour. It can either be run as a daemon or in foreground (when using -f).

After installing the binary (either from a release or using make install) you have to tell the system to automatically start the daemon during system startup with systemctl or chkconfig:
sudo systemctl enable ebusd
sudo chkconfig ebusd on

When started automatically in daemon mode, on Debian based systems these options are configured in the file /etc/default/ebusd.

Command-line

ebusd only accepts options (with the exception of --scanconfig and --inject, see below):

ebusd [OPTION...] [INJECT...]

The default value for each option is shown in square brackets like this: [default].

Environment variables

Instead of or in addition to passing arguments to ebusd, almost all (long) arguments can also be passed via environment variables with the prefix EBUSD_, i.e. setting the eBUS device can be done by either passing --device=... or setting the environment variable EBUSD_DEVICE=....

Device options

• -d, --device=DEV
  Use DEV as eBUS device [/dev/ttyUSB0].
  This can be either:

  • ens:DEVICE or ens:IP[:PORT] for enhanced high speed device (e.g. /dev/ttyACM0,
    for eBUS Adapter Shield,
    or adapter v3.1/v3.0 in enhanced mode with firmware since 20220731), or
  • enh:DEVICE or enh:IP[:PORT] for enhanced (normal speed) device (e.g. /dev/ttyUSB0,
    only adapter v3.1/v3.0),
  • DEVICE for serial device (e.g. /dev/ttyUSB0, for all other serial adapters like
    adapter v2 as well as non-enhanced mode), or
  • [udp:]IP[:PORT] for network device (default port 9999).

• -n, --nodevicecheck
  Skip serial eBUS device test

• -r, --readonly
  Only read from device, never write to it

• --initsend
  Send an initial escape symbol after connecting device.
  This is sometimes needed for UDP connected devices to let it know where to send the data.

• --latency=MSEC
  Extra transfer latency in ms [0 for USB, 10 for IP]

Message configuration options

• -c, --configpath=PATH
  Read CSV config files from PATH (local folder or HTTPS URL) [https://cfg.ebusd.eu/]

• -s, --scanconfig[=ADDR]
  Pick CSV config files matching initial scan: empty for broadcast ident message (default when configpath is not given), "none" for no initial scan message, "full" for full scan, a single hex address to scan, or "off" for not picking CSV files by scan result (default when configpath is given).
  If combined with --checkconfig, you can add scan message data as arguments for checking a particular scan configuration, e.g. "FF08070400/0AB5454850303003277201". For further details on this option, see Automatic configuration.

• --scanretries=COUNT
  Retry scanning devices COUNT times [5]

• --configlang=LANG
  Set the preferred language code for reading config files to LANG [system default language].
  For message and/or field definition parts that support translation, the one having the specified language code as suffix after a dot in the column name will be preferred.

• --checkconfig
  Check CSV config files, then stop.
  For further details on this option, see Probing the configuration.

• --dumpconfig[=FORMAT]
  Check and dump config files in FORMAT ("json" or "csv", defaults to "csv"), then stop

• --dumpconfigto=FILE
  Dump config files to FILE

• --pollinterval=SEC
  Poll for data every SEC seconds (0=disable) [5]

• -i, --inject[=stop]
  Inject remaining arguments as already seen messages (e.g. "FF08070400/0AB5454850303003277201"), optionally stop afterwards

• [INJECT...]
  Message(s) to inject (if --inject was given)

• --cafile=FILE
  Use CA FILE for checking certificates (uses defaults, set to "#" for insecure)

• --capath=PATH
  Use CA PATH for checking certificates (uses defaults)

eBUS options

• -a, --address=ADDR
  Use hex ADDR as own master bus address [31]

• --answer
  Actively answer to requests from other masters

• --acquiretimeout=MSEC
  Stop bus acquisition after MSEC ms [10]

• --acquireretries=COUNT
  Retry bus acquisition COUNT times [2]

• --sendretries=COUNT
  Repeat failed sends COUNT times [2]

• --receivetimeout=MSEC
  Expect a slave to answer within MSEC ms [25]

• --numbermasters=COUNT
  Expect COUNT masters on the bus, 0 for auto detection [0]

• --generatesyn
  Enable AUTO-SYN symbol generation (to make ebusd act as SYN generator)

Daemon options

• --accesslevel=LEVEL
  Set default access level(s) to LEVEL ("*" for everything, multiple levels separated by comma) [""]

• --aclfile=FILE
  Read access control list from FILE. Each line is supposed to contain user name, secret, and access level(s) separated by comma.

• -f, --foreground
  Run in foreground

• --enablehex
  Enable hex, inject, and answer commands.

• --enabledefine
  Enable define command and "-def" option in read and write commands.

• --pidfile=FILE
  PID file name (only for daemon) [/var/run/ebusd.pid]

• -p, --port=PORT
  Listen for command line connections connections on PORT [8888]

• --localhost
  Listen for command line connections on 127.0.0.1 interface only

• --httpport=PORT
  Listen for HTTP connections on PORT, 0 to disable [0]

• --htmlpath=PATH
  Path for HTML files served by HTTP port [/var/ebusd/html]

• --updatecheck=MODE
  Set automatic update check to MODE (on|off) [on]

Log options

• -l, --logfile=FILE
  Write log to FILE (only for daemon, empty string for using syslog) [/var/log/ebusd.log]

• --log=AREAS:LEVEL
  Only write log for matching AREAs (main|network|bus|update|other|all) up to LEVEL (error|notice|info|debug) [all:notice].
  This is an alternative form to using "--logareas"/"--loglevel" and allows to specify an individual level for each area by using the option multiple times. E.g. for having only bus messages in info level and all other in error level, use --log=all:error --log=bus:info.

• --logareas=AREAS
  Only write log for matching AREA(S): main|network|bus|update|other|all [all].
  This is the "old" form allowing to set one level for all areas only. Use "--log" for having an individual level per area instead.

• --loglevel=LEVEL
  Only write log up to LEVEL: error|notice|info|debug [notice].
  This is the "old" form allowing to set one level for all areas only. Use "--log" for having an individual level per area instead.

Raw logging options

• --lograwdata[=bytes]
  Log messages or all received/sent bytes on the bus (see raw command)

• --lograwdatafile=FILE
  Write raw log to FILE [/var/log/ebusd.log]

• --lograwdatasize=SIZE
  Make raw log file no larger than SIZE kB [100]

Binary dump options

• -D, --dump
  Enable dump of received bytes (see dump command)

• --dumpfile=FILE
  Dump received bytes to FILE [/tmp/ebusd_dump.bin]

• --dumpsize=SIZE
  Make dump files no larger than SIZE kB [100]

• --dumpflush
  Flush each dumped byte immediately. This is suitable for forwarding the data as is to another target without any delay.

MQTT options

If support for MQTT was built in (see Installing dependencies), the following additional options are available (some depend on the library version compiled against):

• --mqtthost=HOST
  Connect to MQTT broker on HOST [localhost]

• --mqttport=PORT
  Connect to MQTT broker on PORT (usually 1883), 0 to disable [0]

• --mqtttopic=TOPIC
  Use MQTT TOPIC for the topic. [ebusd]
  This can be:

  • the prefix before /%circuit/%name (if no % character is included at all)
  • a complete format string like ebusd/%circuit/%name for a non field specific topic (i.e. one MQTT message is sent per eBUS message)
  • including %field for having a field specific topic (i.e. one MQTT message is sent per field)
  • a static topic (using a final # as hint for ebusd to not append defaults). In this case the payload is reformatted to include the circuit+message names in addition to the fields in JSON format, and the circuit+message name as prefix circuit;name; in string format.

• --mqttglobal=TOPIC
  Use TOPIC for global data (instead of the global/ suffix to mqtttopic prefix) [global/]

• --mqttretain
  Set the retain flag on all topics instead of only selected global ones

• --mqttqos=QOS
  Set the QoS value for all topics (0-2) [0]

• --mqttint=FILE
  Read MQTT integration settings from FILE (no default). See (MQTT integration)[MQTT-integration] for details.

• --mqttvar=NAME=VALUE[,NAME=VALUE]*
  Add variable(s) to the read MQTT integration settings.

• --mqttjson[=short]
  Publish in JSON format instead of strings, optionally in short (value directly below field key)

• --mqttverbose
  Publish all available attributes

• --mqttignoreinvalid
  Ignore invalid parameters during init (e.g. for DNS not resolvable yet).

• --mqttchanges
  Whether to only publish changed messages instead of all received

• --mqttclientid=ID
  Set client ID for connection to MQTT broker [ebusd_<version>_<pid>]

• --mqttuser=USER
  Connect as USER to MQTT broker (no default)

• --mqttpass=PASSWORD
  Use PASSWORD when connecting to MQTT broker (no default)

• --mqttca=CA
  Use CA file or dir (ending with '/') for MQTT TLS (no default)

• --mqttcert=CERTFILE
  Use CERTFILE for MQTT TLS client certificate (no default)

• --mqttkey=KEYFILE
  Use KEYFILE for MQTT TLS client certificate (no default)

• --mqttkeypass=PASSWORD
  Use PASSWORD for the encrypted KEYFILE (no default)

• --mqttinsecure
  Allow insecure TLS connection, e.g. a self signed certificate

• --mqttlog
  Log library events

• --mqttversion=VERSION
  Use protocol VERSION (e.g. 3.1.1) [3.1]

KNX options:

The following options are available unless support for KNX was excluded in the build process:

• --knxurl[=URL]
  KNX URL to open (no default), either

  • [multicast][@interface] for KNXnet/IP (e.g. --knxurl="" for default multicast on default interface), or
  • ip:host[:port] for knxd listening on port (if support for knxd was compiled in), or
  • local:/socketpath for knxd Unix domain socket (if support for knxd was compiled in).

• --knxint=FILE Read KNX integration settings from FILE [/etc/ebusd/knx.cfg]
  See KNX device and the default /etc/ebusd/knx.cfg for details.

• --knxvar=NAME=VALUE[,NAME=VALUE]*
  Add variable(s) to the read KNX integration settings.
  See KNX device for details. When using KNXnet/IP, at least the device address needs to be set, e.g.
  --knxvar=address=1.1.1.

• --knxrage=SEC
  Maximum age in seconds for using the last value of read messages (0=disable) [5]

• --knxwage=SEC
  Maximum age in seconds for using the last value for reads on write messages (0=disable) [unlimited]

Other options

• -?, --help
  Give this help list

• -V, --version
  Print program version