Add missing files
[bcusdk.git] / README
blob2cefca7c177449f5e07f38beed32b9ec467f82a4
1 bcusdk - A free development environment for BCU1 and BCU2
2 ---------------------------------------------------------
4 Copyright (C) 2005-2011 Martin Koegler <mkoegler@auto.tuwien.ac.at>
5 http://www.auto.tuwien.ac.at/~mkoegler/
7 In order to justify continuing development, it is helpful to have 
8 an idea of how many people are using this software. To contribute, 
9 please send a short mail to bcusdk@auto.tuwien.ac.at whether you 
10 find this software useful.
12 Please note, that this is not requirement to use/modify/distribute the
13 software.
15 First a legal WARNING:
16 ----------------------
18 This program may destroy hardware or cause other damage.
19 This program comes with no warrenty, refer to clause 11+12
20 of the GNU GPL:
22                             NO WARRANTY
24   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
25 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
26 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
27 PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
28 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
29 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
30 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
31 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
32 REPAIR OR CORRECTION.
34   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
35 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
36 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
37 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
38 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
39 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
40 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
41 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
42 POSSIBILITY OF SUCH DAMAGES.
44 ---------------------------------------------------------
46 After the legal warning, what does this mean:
48 Every thing, except eibd, transforms only files like a normal
49 compiler and is not really dangerous.
51 In the default configuration, eibd is only dangerouse, if a
52 buffer overflow (or similar) is found, because all bus access
53 backends are disabled.
55 Run eibd in a controlled environment, where you don't expect
56 malicious people, because eibd has no access control mechanisms
57 in it. Additionally there has been no audit for security problems.
59 At configure time, you have to enable all backends, with which
60 you like to work (It is possible to enable all, if you like it).
62 Running eibd on Linux 2.6.x (where x is < 11) may crash your kernel,
63 even as normal users, if the tpuarts or bcus backend are used.
64 Linux 2.4.x is not affected.
66 With eibd you can send arbitrary telegrams on the EIB bus, which
67 may destroy your EIB configuration or cause a hardware damage.
69 The problematic operation are:
70 *) writing memory
71 *) writing a property
72 *) writing individul addresses
73 *) loading a image
75 See the BCU SDK documentation for how to recover from errors (Chapter Usage).
76 A recovery should always be possible, if you have access to the PEI
77 of the BCU.
79 ----------------------------------------------------------
81 How to use the BCU SDK is covered in the documentation.
82 Parts of the BCU SDK even run on Windows using Cygwin.
83 See the webpage about it.
85 ----------------------------------------------------------
87 !! YOU SHOULD NOT RUN EIBD AS ROOT !!
89 The only privileges, which eibd needs, are access to the bus
90 interface.  For the BCU 1, you only need to grant read and write
91 access on the device node (/dev/eibX) to the user running eibd. For
92 all other eibd backends based on the serial driver, you need to grant
93 only read and write access on /dev/ttySx. The EIBnet/IP backends
94 require no privilege. The USB backend requires read and write access
95 to the file representing the device in usbfs (normaly mounted at
96 /proc/bus/usb) or in /dev managed by udev.
98 contrib/linux/99-eib.rules contains a sample udev rules file, which shows 
99 how to grant permissins with udev.
101 KNXLive! (http://www.auto.tuwien.ac.at/knx/knxlive.html) contains
102 since version 0.2 a EIBD setup wizard.
104 The shell script is also part of knxconfig_0.0.2.tar.gz (available at
105 http://www.auto.tuwien.ac.at/~mkoegler/index.php/knxlive), filename
106 knxconfig-0.2/setup/setup-eibd.sh.
108 It can be used as reference, how to start eibd for the various
109 supported interfaces and how to run eibd as normal user.
111 The shell script was written for the KNXLive! CD. If you intend to run
112 it on a normal linux system, please take care of the folloing things:
113 * The BCU SDK installation directory must be in the path
114 * dialog or Xdialog must be installed
115 * If you are using a BCU 1, you must load the BCU 1 driver module before.
116 * The script expects, that it can executed commands as root via sudo without any password prompt.
117 * The scripts grants access on /dev/ttyS0-ttyS3, /dev/eib0-eib3 and all KNX USB Interfaces to every user on the computer.
118 * Status files are put under easy guessable names in /tmp
119 * If you notice a problem, you should start the script in a terminal to catch all error messages
121 Martin Koegler
122 mkoegler@auto.tuwien.ac.at
123 http://www.auto.tuwien.ac.at/~mkoegler/index.php/bcus