1+ python-can
2+ ==========
3+
4+ |release| |docs| |build|
5+
6+ .. |release| image:: https://img.shields.io/pypi/v/python-can.svg
7+ :target: https://pypi.python.org/pypi/python-can/
8+ :alt: Latest Version
9+
10+ .. |docs| image:: https://readthedocs.org/projects/python-can/badge/?version=latest
11+ :target: http://python-can.readthedocs.org/en/latest/?badge=latest
12+ :alt: Documentation Status
13+
14+ .. |build| image:: https://drone.io/bitbucket.org/hardbyte/python-can/status.png
15+ :target: https://drone.io/bitbucket.org/hardbyte/python-can/latest
16+ :alt: CI Server
17+
18+
19+ The **C**\ ontroller **A**\ rea **N**\ etwork is a bus standard designed
20+ to allow microcontrollers and devices to communicate with each other. It
21+ has priority based bus arbitration, reliable deterministic
22+ communication. It is used in cars, trucks, wheelchairs and more. See
23+ `wikipedia <http://en.wikipedia.org/wiki/CAN_bus>`__ for more info.
24+
25+ This module provides controller area network support for
26+ `Python <http://python.org/download/>`__.
27+
28+ Configuration File
29+ ------------------
30+
31+ In order to use this library a CAN interface needs to be specified. A
32+ method to do this is to create a configuration file.
33+ On Linux systems the config file is searched in the following paths:
34+
35+ 1. ``/etc/can.conf``
36+ 2. ``$HOME/.can``
37+ 3. ``$HOME/.canrc``
38+
39+ On Windows systems the config file is searched in the following paths:
40+ 1. ``can.ini`` (current working directory)
41+ 2. ``$APPDATA/can.ini``
42+
43+ The configuration file sets the default interface and channel:
44+
45+ ::
46+
47+ [default]
48+ interface = <the name of the interface to use>
49+ channel = <the channel to use by default>
50+
51+ Interfaces
52+ ----------
53+
54+ The interface available are:
55+
56+ kvaser
57+ ~~~~~~
58+
59+ `Kvaser <http://www.kvaser.com>`__'s CANLib SDK for Windows (also
60+ available on Linux)
61+
62+ socketcan
63+ ~~~~~~~~~
64+
65+ On linux the socketcan interface is exposed via either:
66+
67+ - socketcan\_ctypes
68+ - socketcan\_native
69+
70+ serial
71+ ~~~~~~
72+
73+ A text based interface. For example use over bluetooth with
74+ ``/dev/rfcomm0``
75+
76+ pcan
77+ ~~~~
78+
79+ `Peak-System <http://www.peak-system.com/>`__'s PCAN-Basic API.
80+
81+ IXXAT
82+ ~~~~~
83+
84+ `IXXAT <http://www.ixxat.com/>`__'s Virtual CAN Interface V3 SDK ONLY on Windows.
85+ The Linux ECI SDK is currently unsupported.
86+ On Linux some devices are supported with socketcan.
87+
88+ virtual
89+ ~~~~~~~
90+
91+ A virtual CAN bus that can be used for automatic tests. Any Bus instances
92+ connecting to the same channel (in the same python program) will get each
93+ others messages.
94+
95+ Installation
96+ ------------
97+
98+ GNU/Linux dependencies
99+ ----------------------
100+
101+ Reasonably modern Linux Kernels (2.6.25 or newer) have an implementation
102+ of ``socketcan``. This version of python-can will directly use socketcan
103+ if called with Python 3.3 or greater, otherwise that interface is used
104+ via ctypes.
105+
106+ Windows dependencies
107+ --------------------
108+
109+ Kvaser
110+ ~~~~~~
111+
112+ To install ``python-can`` using the Kvaser CANLib SDK as the backend:
113+
114+ 1. Install the `latest stable release of
115+ Python <http://python.org/download/>`__.
116+
117+ 2. Install `Kvaser's latest Windows CANLib
118+ drivers <http://www.kvaser.com/en/downloads.html>`__.
119+
120+ 3. Test that Kvaser's own tools work to ensure the driver is properly
121+ installed and that the hardware is working.
122+
123+ PCAN
124+ ~~~~
125+
126+ To use the PCAN-Basic API as the backend (which has only been tested
127+ with Python 2.7):
128+
129+ 1. Download the latest version of the `PCAN-Basic
130+ API <http://www.peak-system.com/Downloads.76.0.html?>`__.
131+
132+ 2. Extract ``PCANBasic.dll`` from the Win32 subfolder of the archive or
133+ the x64 subfolder depending on whether you have a 32-bit or 64-bit
134+ installation of Python.
135+
136+ 3. Copy ``PCANBasic.dll`` into the working directory where you will be
137+ running your python script. There is probably a way to install the
138+ dll properly, but I'm not certain how to do that.
139+
140+ Note that PCANBasic API timestamps count seconds from system startup. To
141+ convert these to epoch times, the uptime library is used. If it is not
142+ available, the times are returned as number of seconds from system
143+ startup. To install the uptime library, run ``pip install uptime``.
144+
145+ IXXAT
146+ ~~~~~
147+
148+ To install ``python-can`` using the IXXAT VCI V3 SDK as the backend:
149+
150+ 1. Install the `latest stable release of
151+ Python <http://python.org/download/>`__.
152+
153+ 2. Install `IXXAT's latest Windows VCI V3 SDK
154+ drivers <http://www.ixxat.com/support/file-and-documents-download/drivers/vci-v3-driver-download>`__.
155+
156+ 3. Test that IXXAT's own tools (i.e. MiniMon) work to ensure the driver
157+ is properly installed and that the hardware is working.
158+
159+ Install python-can
160+ ------------------
161+
162+ You may need to install
163+ `pip <http://www.pip-installer.org/en/latest/installing.html>`__ and
164+ `setuptools <https://pypi.python.org/pypi/setuptools>`__ first.
165+
166+ Two options, install normally with:
167+
168+ ::
169+
170+ python setup.py install
171+
172+ Or to do a "development" install of this package to your machine (this
173+ allows you to make changes locally or pull updates from the Mercurial
174+ repository and use them without having to reinstall):
175+
176+ ::
177+
178+ python setup.py develop
179+
180+ On linux you will need ``sudo`` rights.
181+
182+ Documentation and Help
183+ ----------------------
184+
185+ - The Sphinx documentation for python-can can be viewed online at `python-can.readthedocs.org <https://python-can.readthedocs.org/en/latest/>`__
186+ - Questions can be found on `StackOverflow <https://stackoverflow.com/questions/tagged/can+python>`__ (tagged with python+can)
187+ - `Google groups mailing list <https://groups.google.com/forum/#!forum/python-can>`__
0 commit comments