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 [2017-10-19 12:26] – thiemovanengelen | 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:// | + | |
- | + | ||
- | Below is a list of example possible and common service names. | + | |
- | + | ||
- | ^Service name ^ Description ^ | + | |
- | | com.victronenergy.batter.ttyO2 | Battery monitor connected via VE.Direct at tty2 | + | |
- | | com.victronenergy.vebus.ttyO1 | mk2-dbus | | + | |
- | | com.victronenergy.charger.ttyO0 | Charger connected via VE.Direct at tty0 | | + | |
- | | com.victronenergy.solarcharger.ttyO2 | Solar charger connected via VE.Direct at tty2 | | + | |
- | | com.victronenergy.solarcharger.ttyUSB2 | Solar charger connected via 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:// | + | |
- | | [[https:// | + | |
- | | com.victronenergy.battery.lg_resu | LG resu battery | | + | |
- | | [[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:// | + | |
- | | [[https:// | + | |
- | | [[https:// | + | |
- | ===== Device instances ===== | + | |
- | + | ||
- | The device instance (object path / | + | |
- | * NMEA2K devices report the NMEA2K device instance (max. 255). | + | |
- | * Devices connected to a (virtual) serial-port report from 256 up. Their instance is determined by the device name: | + | |
- | * /dev/ttyOx: 256 + x | + | |
- | * /dev/ttySx: 272 + x | + | |
- | * / | + | |
- | * COMx: 256 + x | + | |
- | * Quby AC sensors: 0 if on input 1, 1 if on output, 2 if on input 2 | + | |
- | * Vebus AC sensors: 10 if on input 1, 11 if on output, 12 if on input 2 | + | |
- | * Fronius PV inverters: 20 + x (x depends on order of detection) | + | |
- | * Carlo Gavazzi AC sensors: 30 + x (x depends on order of detection), can be changed in Gui | + | |
- | * SmartEnergyMeter / BLE networking: 40 | + | |
- | * com.victronenergy.system (aka systemcalc): | + | |
- | * com.victronenergy.generator.startstop0: | + | |
- | + | ||
- | === Use of the DeviceInstance in CCGX configuration & settings === | + | |
- | The device instance is used for several configuration items: | + | |
- | * Settings -> System Setup -> Main battery monitor | + | |
- | * Genset start/stop selection of battery monitor and ac source | + | |
- | * and perhaps more config items. | + | |
- | + | ||
- | === Use of the DeviceInstance on VRM === | + | |
- | In logging to the VRM database (vrm.victronenergy.com) the device-instance is used, for example IV1[0] (input 1 voltage of device instance 0), and it (the instance) should therefore not change at random. Maximum of the instance field in the VRM database is 65535. | + | |
- | + | ||
- | === Use of the DeviceInstance on ModbusTCP === | + | |
- | The ModbusTCP server, used by customers to query data from either the total system or separate devices, uses the ModbusTCP server in the addressing. The UnitID aka SlaveID in the request is mapped to the device instance. | + | |
- | + | ||
- | This mapping is not one on one and has a bit of history, since we didn't realize at first that a lot of PLCs do not support a device instance above 247. Also one Customer reported that his PLC cant work with unitid 0. | + | |
- | + | ||
- | More details: [[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. | + | |
- | + | ||
- | A(n attempt to) list of available object paths is here: https:// | + | |
- | + | ||
- | === 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. | + | |
- | + | ||
- | __ /CustomName __ | + | |
- | String, containing an editable name. This can be set by a user to distinguish the device from other devices. When a product name is presented to a user, /CustomName is the preferred name to present. When /CustomName is blank, / | + | |
- | + | ||
- | __ / | + | |
- | 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.1508408779.txt.gz · Last modified: 2017-10-19 12:26 by thiemovanengelen