D-Bus is used as the main data exchange, to share values such as voltages, as well as settings and other data, between all the processes running on the CCGX. D-Bus is a common linux inter process communication mechanism, see google and the D-Bus page on wikipedia for more information.

Below diagram gives a good overview on the CCGX:

Original file

• Standard Linux D-Bus has to bus-es: Session and System. On the CCGX the System bus is used.
• The D-Bus connection-name of a D-Bus service always begins with com.victronenergy.
• For D-Bus services representing products connected to the system, the service name rules are:
  • Connection via serial port (onboard VE.Bus connection, VE.Direct ports, usb-serial converters): com.victronenergy.[product type].[tty name]
    Note that this can be VE.Direct, but also a GPS for example
  • Connections via canbus:
    com.victronenergy.[product type].[interface]_di[device instance]
• As implied by above naming rules, when one executable connects to different products, it will make create multiple D-Bus services. An example is the process taking care of all canbus communications, vecan-dbus.
• Never use the fourth part in the service name (interface, tty name etc.) to deduct the DeviceInstance or connection method. The only purposes of it is to make the name is unique and easy to identify from the command line. Use /DeviceInstance/ instead.
• Use SI units when publishing data on the D-bus.
  Exceptions: use kWh for energy and degrees Celsius for temperature.
• Processes representing products will connect to the dbus after they know what kind of product they will represent.
• Never change your the service name once on the D-Bus. Instead remove the service and register a new one.
• When a dbus service cannot communicate anymore with its direct counterpart, the process will disconnect from the D-Bus. And, if it has nothing else to do, will exit. An example is a BMV connected through VE.Direct stops communicating, perhaps because it is unplugged.
• Each object on the D-Bus represents one value. In VE.Bus for example, /Dc/0/Voltage is the voltage, /Dc/0/Current the current.
• An invalid value is represented by an empty array of integers. In Python this is dbus.Array([], signature=dbus.Signature('i'), variant_level=1).

• Applications publishing values to the dbus (ie a product driver), do not need to invalidate all values before going offline. Applications using values from dbus, such as the GUI or vrmlogger, need to monitor for nameowner changes / service watches. One reason: an application could also crash (so the dbus service dissapears without a chance of first sending out all invalids).
• Applications using values from the D-Bus, such as GUI or vrmlogger, should take care that when a new D-Bus service comes online, it might not immediately have all object paths.
• Applications publishing values to the D-Bus, should, when adding object paths after they have already created their D-Bus service, send a PropertiesChanged signal.
• Applications publishing values to the D-Bus, that change their /DeviceInstance, should disconnect their service from the D-Bus and reconnect with the new /DeviceInstance value. Or, change your name, to trigger nameowner changes.

• When putting a D-Bus service online, should there be a PropertiesChanged signal for all object paths?

The services below retrieve measurements from devices connected to the color control, and publish them on the D-Bus. The hyperlinks in the tables below refer to the source code of the projects on github. Services without hyperlink are not (yet) open sourced.

The naming convention for new object paths is to write a full word. So /Ac/Voltage instead of /Ac/V and /Management instead of /Mgmt.

String, containing one serialnumber. In a system with multiple units, the one from the master is shown.

Int, containing the N2K unique number. In a system with multiple units, the one from the master is shown.

The Devices object path is only used for products that operate in parallel mode. This object-path is used to access the underlying real products. Examples of products operating in parallel mode are VE.Bus products (Inverters, Multi’s, Quattro’s), Skylla-i’s and MPPT 150/70’s. The first device will report under /Devices/0/… , the second device under /Devices/1/…. Etcetera. When relevant this numbering is kept equal to bus numbering. For example MK2-addressing.

The Interfaces object path is used when access to a certain product goes via known interfaces. For VE.Bus products for example you could find the MK2 in /Interfaces/, or the mk2-can and the mk2. The reasons to do this are:

• How is the device connected
• Publish / retrieve firmware versions of intermediate interfaces
• Diagnostics (where is the connection lost)

An example of the interfaces of a VE.Bus system connected through canbus:

All D-Bus object paths have the following interfaces:

(Variant value) GetValue()
Returns the value.

(String value) GetText()
Returns the value as string, including units. For example ‘21.3 W’. When invalid, it returns an empty string.

(Int32 retval) SetValue(Variant value)
Sets the specified value. Returns 0 when success, and something else when not allowed.

(Variant value) GetMin()
Returns the limit minimum.

(Variant value) GetMax()
Returns the limit maximum.

(Int 32 retval) SetDefault()
Sets the value(s) to default value. When this is called on a group (for example object path /Settings/Logscript, all values in this group are set to default.

(Variant value) GetDefault()
Returns the default value.

(Int32 retval) AddSetting(String group, String name, Variant defaultValue, String itemType, Variant minimum, Variant maximum)
Adds a new local setting according to the specified parameters. The possible itemType's are 'i' (integer), 'f' (float) and 's' (string). The minimum and maximum can be specified when the itemType is an integer or float. Minimum and maximum are ignored when both are specified as 0 (zero).

(String data) Introspect()
Returns the introspection data in XML format. Interface org.freedesktop.DBus.Properties (Variant value) Get(String interface, String property)
Returns the value of specified interface and property. For example the interface com.victronenergy.BusItem and the property Valid.