Documentation refactoring

- Tried to explain at a much higher level what the library is about
- Most of the readme contents has been integrated into the docs.
- Added pages for configuration and installation

Author: hardbyte

CONTRIBUTORS.txt

@@ -16,3 +16,4 @@ Bruno Pennati
 Jack Jester-Weinstein
 Joshua Villyard
 Giuseppe Corbelli <[email protected]>
+Christian Sandberg

README

@@ -19,169 +19,30 @@ python-can
 The **C**\ ontroller **A**\ rea **N**\ etwork is a bus standard designed
 to allow microcontrollers and devices to communicate with each other. It
 has priority based bus arbitration, reliable deterministic
-communication. It is used in cars, trucks, wheelchairs and more. See
-`wikipedia <http://en.wikipedia.org/wiki/CAN_bus>`__ for more info.
+communication. It is used in cars, trucks, boats, wheelchairs and more.
 
-This module provides controller area network support for
-`Python <http://python.org/download/>`__.
+The ``can`` package provides controller area network support for
+Python developers; providing `common abstractions to
+different hardware devices`, and a suite of utilities for sending and receiving
+messages on a can bus.
 
-Configuration File
-------------------
+The library supports Python 2.7, Python 3.3+ and runs on Mac, Linux and Windows.
 
-In order to use this library a CAN interface needs to be specified. A
-method to do this is to create a configuration file.
-On Linux systems the config file is searched in the following paths:
+You can find more information in the documentation, online at
+`python-can.readthedocs.org <https://python-can.readthedocs.org/en/stable/>`__.
 
-1. ``/etc/can.conf``
-2. ``$HOME/.can``
-3. ``$HOME/.canrc``
 
-On Windows systems the config file is searched in the following paths:
-1. ``can.ini`` (current working directory)
-2. ``$APPDATA/can.ini``
-
-The configuration file sets the default interface and channel:
-
-::
-
-    [default]
-    interface = <the name of the interface to use>
-    channel = <the channel to use by default>
-
-Interfaces
+Discussion
 ----------
 
-The interface available are:
-
-kvaser
-~~~~~~
-
-`Kvaser <http://www.kvaser.com>`__'s CANLib SDK for Windows (also
-available on Linux)
-
-socketcan
-~~~~~~~~~
-
-On linux the socketcan interface is exposed via either:
-
--  socketcan\_ctypes
--  socketcan\_native
-
-serial
-~~~~~~
-
-A text based interface. For example use over bluetooth with
-``/dev/rfcomm0``
-
-pcan
-~~~~
-
-`Peak-System <http://www.peak-system.com/>`__'s PCAN-Basic API.
-
-IXXAT
-~~~~~
-
-`IXXAT <http://www.ixxat.com/>`__'s Virtual CAN Interface V3 SDK ONLY on Windows.
-The Linux ECI SDK is currently unsupported.
-On Linux some devices are supported with socketcan.
-
-virtual
-~~~~~~~
-
-A virtual CAN bus that can be used for automatic tests. Any Bus instances
-connecting to the same channel (in the same python program) will get each
-others messages.
-
-Installation
-------------
-
-GNU/Linux dependencies
-----------------------
-
-Reasonably modern Linux Kernels (2.6.25 or newer) have an implementation
-of ``socketcan``. This version of python-can will directly use socketcan
-if called with Python 3.3 or greater, otherwise that interface is used
-via ctypes.
-
-Windows dependencies
---------------------
-
-Kvaser
-~~~~~~
-
-To install ``python-can`` using the Kvaser CANLib SDK as the backend:
-
-1. Install the `latest stable release of
-   Python <http://python.org/download/>`__.
-
-2. Install `Kvaser's latest Windows CANLib
-   drivers <http://www.kvaser.com/en/downloads.html>`__.
-
-3. Test that Kvaser's own tools work to ensure the driver is properly
-   installed and that the hardware is working.
-
-PCAN
-~~~~
-
-To use the PCAN-Basic API as the backend (which has only been tested
-with Python 2.7):
-
-1. Download the latest version of the `PCAN-Basic
-   API <http://www.peak-system.com/Downloads.76.0.html?>`__.
-
-2. Extract ``PCANBasic.dll`` from the Win32 subfolder of the archive or
-   the x64 subfolder depending on whether you have a 32-bit or 64-bit
-   installation of Python.
-
-3. Copy ``PCANBasic.dll`` into the working directory where you will be
-   running your python script. There is probably a way to install the
-   dll properly, but I'm not certain how to do that.
-
-Note that PCANBasic API timestamps count seconds from system startup. To
-convert these to epoch times, the uptime library is used. If it is not
-available, the times are returned as number of seconds from system
-startup. To install the uptime library, run ``pip install uptime``.
-
-IXXAT
-~~~~~
-
-To install ``python-can`` using the IXXAT VCI V3 SDK as the backend:
-
-1. Install the `latest stable release of
-   Python <http://python.org/download/>`__.
-
-2. Install `IXXAT's latest Windows VCI V3 SDK
-   drivers <http://www.ixxat.com/support/file-and-documents-download/drivers/vci-v3-driver-download>`__.
-
-3. Test that IXXAT's own tools (i.e. MiniMon) work to ensure the driver 
-   is properly installed and that the hardware is working.
-
-Install python-can
-------------------
-
-You may need to install
-`pip <http://www.pip-installer.org/en/latest/installing.html>`__ and
-`setuptools <https://pypi.python.org/pypi/setuptools>`__ first.
-
-Two options, install normally with:
-
-::
-
-    python setup.py install
-
-Or to do a "development" install of this package to your machine (this
-allows you to make changes locally or pull updates from the Mercurial
-repository and use them without having to reinstall):
-
-::
-
-    python setup.py develop
+If you run into bugs, you can file them in our
+`issue tracker <https://bitbucket.org/hardbyte/python-can/issues>`__.
 
-On linux you will need ``sudo`` rights.
+There is also a `python-can <https://groups.google.com/forum/#!forum/python-can>`__
+mailing list for development discussion.
 
-Documentation and Help
-----------------------
+`Stackoverflow <https://stackoverflow.com/questions/tagged/can+python>`__ has several
+questions and answers tagged with ``python+can``.
 
-- The Sphinx documentation for python-can can be viewed online at `python-can.readthedocs.org <https://python-can.readthedocs.org/en/latest/>`__
-- Questions can be found on `StackOverflow <https://stackoverflow.com/questions/tagged/can+python>`__ (tagged with python+can)
-- `Google groups mailing list <https://groups.google.com/forum/#!forum/python-can>`__
+Wherever we interact, we strive to follow the
+`Python Community Code of Conduct <https://www.python.org/psf/codeofconduct/>`__.

can/__init__.py

@@ -1,18 +1,12 @@
 """
 can is an object-orient Controller Area Network interface module.
-
-Modules include:
-
-    :mod:`can.message`
-        defines the :class:`~can.Message` class which is the
-        lowest level of OO access to the library.
-
 """
 import logging
 log = logging.getLogger('can')
 
 rc = dict(channel=0)
 
+
 class CanError(IOError):
     pass
 

can/broadcastmanager.py

@@ -47,8 +47,8 @@ def modify_data(self, message):
         """Update the contents of this periodically sent message without altering
         the timing.
 
-        :param message: The :class:`~can.Message` with new :attr:`Message.data`. Note it must have the same
-        :attr:`Message.arbitration_id`.
+        :param message: The :class:`~can.Message` with new :attr:`Message.data`.
+            Note it must have the same :attr:`~can.Message.arbitration_id`.
         """
 
 

can/bus.py

@@ -43,6 +43,8 @@ def __init__(self, channel=None, can_filters=None, **config):
     def recv(self, timeout=None):
         """Block waiting for a message from the Bus.
 
+        :param float timeout: Seconds to wait for a message.
+
         :return:
             None on timeout or a :class:`can.Message` object.
         """
@@ -76,7 +78,7 @@ def __iter__(self):
         logger.debug("done iterating over bus messages")
 
     def flush_tx_buffer(self):
-        """Used for CAN backends which need to flush their transmit buffer.
+        """Used for CAN interfaces which need to flush their transmit buffer.
 
         """
         pass

can/interfaces/interface.py

@@ -11,14 +11,18 @@ class Bus(object):
     """
     Instantiates a CAN Bus of the given `bustype`, falls back to reading a
     configuration file from default locations.
-
-    :raises: NotImplementedError if the bustype isn't recognized
-
     """
 
     @classmethod
     def __new__(cls, other, channel=None, *args, **kwargs):
+        """
+        Takes the same arguments as :class:`can.BusABC` with the addition of:
+
+        :param kwargs:
+            Should contain a bustype key with a valid interface name.
 
+        :raises: NotImplementedError if the bustype isn't recognized
+        """
         if 'bustype' in kwargs:
             can.rc['interface'] = kwargs['bustype']
             del kwargs['bustype']

can/interfaces/pcan.py

@@ -60,9 +60,6 @@ def __init__(self, channel, *args, **kwargs):
         :param str channel:
             The can interface name. An example would be PCAN_USBBUS1
 
-        Backend Configuration
-        ---------------------
-
         :param int bitrate:
             Bitrate of channel in bit/s.
             Default is 500 Kbs

can/interfaces/socketcan_ctypes.py

@@ -17,6 +17,19 @@
 log.info("Loading socketcan ctypes backend")
 
 
+if not sys.platform.startswith("win32"):
+    libc = ctypes.cdll.LoadLibrary(find_library("c"))
+    log.info("Loading libc with ctypes")
+else:
+    log.warning("libc is unavailable")
+    libc = None
+
+
+start_sec = 0
+start_usec = 0
+SEC_USEC = 1000000
+
+
 class SocketscanCtypes_Bus(BusABC):
     """
     An implementation of the :class:`can.bus.BusABC` for SocketCAN using :mod:`ctypes`.
@@ -78,14 +91,6 @@ def send(self, msg):
         return sendPacket(self.socket, msg)
 
 
-log.debug("Loading libc with ctypes...")
-libc = ctypes.cdll.LoadLibrary(find_library("c"))
-
-start_sec = 0
-start_usec = 0
-SEC_USEC = 1000000
-
-
 class SOCKADDR(ctypes.Structure):
     # See /usr/include/i386-linux-gnu/bits/socket.h for original struct
     _fields_ = [("sa_family", ctypes.c_uint16),
@@ -471,7 +476,3 @@ def __init__(self, channel, message, count, initial_period, subsequent_period):
         if bytes_sent == -1:
             logging.debug("Error sending frame :-/")
 
-if __name__ == "__main__":
-    socket_id = createSocket(CAN_RAW)
-    print("Created socket (id = {})".format(socket_id))
-    print(bindSocket(socket_id))

can/interfaces/socketcan_native.py

@@ -6,21 +6,25 @@
 """
 
 import socket
-import fcntl
 import struct
 import logging
 from collections import namedtuple
 import select
 
+
 log = logging.getLogger('can.socketcan.native')
 #log.setLevel(logging.DEBUG)
 log.debug("Loading native socket can implementation")
 
+try:
+    import fcntl
+except ImportError:
+    log.warning("fcntl not available on this platform")
+
 try:
     socket.CAN_RAW
 except:
-    log.error("Note Python 3.3 or later is required to use native socketcan")
-    raise ImportError()
+    log.debug("CAN_* properties not found in socket module. These are required to use native socketcan")
 
 
 from can import Message

can/message.py

@@ -5,6 +5,8 @@
 class Message(object):
     """
     The :class:`~can.Message` object is used to represent CAN messages for both sending and receiving.
+
+    Messages can use extended identifiers, be remote or error frames, and contain data.
     """
 
     def __init__(self, timestamp=0.0, is_remote_frame=False, extended_id=True,