open_source:ccgx:d-bus
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
open_source:ccgx:d-bus [2015-09-03 13:50] – [Basics] mvader | open_source:ccgx:d-bus [2019-07-04 11:17] (current) – jhofstee | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== D-Bus API definition ====== | + | moved to https:// |
- | + | ||
- | ===== Introduction ===== | + | |
- | D-Bus is used as the main data exchange, | + | |
- | + | ||
- | Below diagram gives a good overview on the CCGX: | + | |
- | + | ||
- | {{ : | + | |
- | {{ : | + | |
- | ===== Basics ===== | + | |
- | * 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): | + | |
- | * Connections via canbus: \\ '' | + | |
- | * 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, | + | |
- | * 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 / | + | |
- | * 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, | + | |
- | * Each object on the D-Bus represents one value. In VE.Bus for example, / | + | |
- | * An invalid value is represented by an empty array of integers. In Python this is '' | + | |
- | + | ||
- | === Implementation notes === | + | |
- | * 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 / | + | |
- | + | ||
- | === TODO: verify and finalize below === | + | |
- | * When putting a D-Bus service online, should there be a PropertiesChanged signal for all object paths? | + | |
- | ===== Service name examples ===== | + | |
- | + | ||
- | === Services representing products === | + | |
- | + | ||
- | 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 [[http:// | + | |
- | + | ||
- | ^Service name ^ Description ^ | + | |
- | | com.victronenergy.vebus.ttyO1 | mk2-dbus | | + | |
- | | com.victronenergy.charger.ttyO0 | Charger connected through VE.Direct at tty0 | | + | |
- | | com.victronenergy.solarcharger.ttyO2 | Solar charger connected through VE.Direct at tty2 | | + | |
- | | com.victronenergy.solarcharger.ttyUSB2 | Solar charger connected through VE.Direct via USB cable | | + | |
- | | com.victronenergy.vebus.socketcan_can0_di0 | VE.Bus system connected via canbus 0, and configured for device instance 0 | | + | |
- | | com.victronenergy.vebus.socketcan_can0_di1 | VE.Bus system connected via canbus 0, and configured for device instance 1 | | + | |
- | | com.victronenergy.charger.socketcan_can0_di0 | Skylla-i charger connected on canbus, device instance 0 | | + | |
- | | [[https:// | + | |
- | | [[https:// | + | |
- | | [[https:// | + | |
- | | [[https:// | + | |
- | + | ||
- | === Maintenance services === | + | |
- | ^ Process ^ Description ^ | + | |
- | | [[https:// | + | |
- | | com.victronenergy.gui | gui. takes care of buttons and lcd display | | + | |
- | | vrmlogger | Communication between CCGX and VRM Database | | + | |
- | | vrmpubnub | Two-communication via internet, (to be) used by mobile apps, Portal and VE Power Setup. | | + | |
- | | [[https:// | + | |
- | | [[https:// | + | |
- | + | ||
- | ===== Object-paths ===== | + | |
- | 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. | + | |
- | + | ||
- | === Objects paths that all services need to implement === | + | |
- | ^ Object-path ^ Definition ^ | + | |
- | | / | + | |
- | | / | + | |
- | | / | + | |
- | + | ||
- | === Object paths that are mandatory for services representing products === | + | |
- | ^ Object-path ^ Definition ^ | + | |
- | | /ProductId | As defined in products.h in velib. GetValue should return the decimal, as uint32 (ie 516), \\ and GetText should return this as a hex string: 0x204.| | + | |
- | | / | + | |
- | | / | + | |
- | | / | + | |
- | | / | + | |
- | | /Connected | Value 0 = not-connected, | + | |
- | + | ||
- | === Other standard object paths === | + | |
- | + | ||
- | == /Serial == | + | |
- | 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), | + | |
- | + | ||
- | == / | + | |
- | + | ||
- | 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 / | + | |
- | * 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: | + | |
- | | / | + | |
- | | / | + | |
- | | / | + | |
- | | / | + | |
- | + | ||
- | ===== D-Bus interfaces ===== | + | |
- | All D-Bus object paths have the following interfaces: | + | |
- | + | ||
- | == Interface com.victronenergy.BusItem == | + | |
- | (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. | + | |
- | + | ||
- | == Following is only supported by com.victronenergy.settings == | + | |
- | (Int 32 retval) SetDefault() \\ | + | |
- | Sets the value(s) to default value. When this is called on a group (for example object path / | + | |
- | + | ||
- | (Variant value) GetDefault() \\ | + | |
- | Returns the default value. | + | |
- | + | ||
- | (Int32 retval) AddSetting(String group, String name, Variant defaultValue, | + | |
- | Adds a new local setting according to the specified parameters. | + | |
- | The possible itemType' | + | |
- | 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). | + | |
- | + | ||
- | == Interface org.freedesktop.DBus.Introspectable == | + | |
- | (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. | + | |
- | + |
open_source/ccgx/d-bus.1441281017.txt.gz · Last modified: 2015-09-03 13:50 by mvader