Mercurial > ~darius > hgwebdir.cgi > epro

comparison velib_python/README.md @ 8:9c0435a617db

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import velib_python
author Daniel O'Connor <darius@dons.net.au>
date Sun, 05 Dec 2021 14:35:36 +1030
parents
children
comparison
equal deleted inserted replaced
5:982eeffe9d95 8:9c0435a617db
1 velib_python
2 ============
3
4 [![Build Status](https://travis-ci.com/victronenergy/velib_python.svg?branch=master)](https://travis-ci.org/victronenergy/velib_python)
5
6 This is the general python library within Victron. It contains code that is related to D-Bus and the Color
7 Control GX. See http://www.victronenergy.com/panel-systems-remote-monitoring/colorcontrol/ for more
8 infomation about that panel.
9
10 Files busitem.py, dbusitem.py and tracing.py are deprecated.
11
12 The main files are vedbus.py, dbusmonitor.py and settingsdevice.py.
13
14 - Use VeDbusService to put your process on dbus and let other services interact with you.
15 - Use VeDbusItemImport to read a single value from other processes the dbus, and monitor its signals.
16 - Use DbusMonitor to monitor multiple values from other processes
17 - Use SettingsDevice to store your settings in flash, via the com.victronenergy.settings dbus service. See
18 https://github.com/victronenergy/localsettings for more info.
19
20 Code style
21 ==========
22
23 Comply with PEP8, except:
24 - use tabs instead of spaces, since we use tabs for all projects within Victron.
25 - max line length = 110
26
27 Run this command to set git diff to tabsize is 4 spaces. Replace --local with --global to do it globally for the current
28 user account.
29
30 git config --local core.pager 'less -x4'
31
32 Run this command to check your code agains PEP8
33
34 pep8 --max-line-length=110 --ignore=W191 *.py
35
36 D-Bus
37 =====
38
39 D-Bus is an/the inter process communication bus used on Linux for many things. Victron uses it on the CCGX to have all the different processes exchange data. Protocol drivers publish data read from products (for example battery voltage) on the D-Bus, and other processes (the GUI for example) takes it from the D-Bus to show it on the display.
40
41 Libraries that implement D-Bus connectivity are available in many programming languages (C, Python, etc). There are also many commandline tools available to talk to a running process via D-bus. See for example the dbuscli (executeable name dbus): http://code.google.com/p/dbus-tools/wiki/DBusCli, and also dbus-monitor and dbus-send.
42
43 There are two sides in using the D-Bus, putting information on it (exporting as service with objects) and reading/writing to a process exporting a service. Note that instead of reading with GetValue, you can also subscribe to receive a signal when datachanges. Doing this saves unncessary context-switches in most cases.
44
45 To get an idea of how to publish data on the dbus, run the example:
46
47 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ python vedbusservice_example.py
48 vedbusservice_example.py starting up
49 /Position value is 5
50 /Position value is now 10
51 try changing our RPM by executing the following command from a terminal
52
53 dbus-send --print-reply --dest=com.victronenergy.example /RPM com.victronenergy.BusItem.SetValue int32:1200
54 Reply will be <> 0 for values > 1000: not accepted. And reply will be 0 for values < 1000: accepted.
55
56 Leave that terminal open, start a second terminal, and interrogate above service from the commandline:
57
58 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ dbus
59 org.freedesktop.DBus
60 org.freedesktop.PowerManagement
61 com.victronenergy.example
62 org.xfce.Terminal5
63 org.xfce.Xfconf
64 [and many more services in which we are not interested]
65
66 To get more details, add the servicename:
67
68 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ dbus com.victronenergy.example
69 /
70 /Float
71 /Int
72 /NegativeInt
73 /Position
74 /RPM
75 /String
76
77 And get the value for the position:
78
79 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ dbus com.victronenergy.example /RPM GetValue
80 100
81
82 And setting the value is also possible, the % makes dbus evaluate what comes behind it, resulting in an int instead of the default (a string).:
83
84 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ dbus com.victronenergy.example /RPM SetValue %1
85 0
86
87 In this example, the 0 indicates succes. When trying an unsupported value, 2000, this is what happens:
88
89 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ dbus com.victronenergy.example /RPM SetValue %2000
90 2
91
92 Exporting services, and the object paths (/Float, /Position, /Group1/Value1, etcetera) is standard D-Bus functionality. At Victron we designed and implemented a D-Bus interface, called com.victronenergy.BusItem. Example showing all interfaces supported by an object:
93
94 matthijs@matthijs-VirtualBox:~/dev/velib_python/examples$ dbus com.victronenergy.example /RPM
95 Interface org.freedesktop.DBus.Introspectable:
96 String Introspect()
97
98 Interface com.victronenergy.BusItem:
99 Int32 SetValue(Variant newvalue)
100 String GetDescription(String language, Int32 length)
101 String GetText()
102 Variant GetValue()