diff --git a/can/broadcastmanager.py b/can/broadcastmanager.py index 2c7072739..5e9ff7118 100644 --- a/can/broadcastmanager.py +++ b/can/broadcastmanager.py @@ -10,7 +10,6 @@ import abc import logging - import threading import time @@ -20,7 +19,7 @@ class CyclicTask(object): """ - Abstract Base for all Cyclic Tasks + Abstract Base for all cyclic tasks. """ @abc.abstractmethod @@ -36,7 +35,7 @@ class CyclicSendTaskABC(CyclicTask): def __init__(self, message, period): """ - :param message: The :class:`can.Message` to be sent periodically. + :param can.Message message: The message to be sent periodically. :param float period: The rate in seconds at which to send the message. """ self.message = message @@ -51,7 +50,7 @@ class LimitedDurationCyclicSendTaskABC(CyclicSendTaskABC): def __init__(self, message, period, duration): """Message send task with a defined duration and period. - :param message: The :class:`can.Message` to be sent periodically. + :param can.Message message: The message to be sent periodically. :param float period: The rate in seconds at which to send the message. :param float duration: The duration to keep sending this message at given rate. @@ -76,19 +75,28 @@ 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:`can.Message.data`. + :param can.Message message: + The message with the new :attr:`can.Message.data`. + Note: The arbitration ID cannot be changed. """ self.message = message class MultiRateCyclicSendTaskABC(CyclicSendTaskABC): """Exposes more of the full power of the TX_SETUP opcode. - - Transmits a message `count` times at `initial_period` then - continues to transmit message at `subsequent_period`. """ def __init__(self, channel, message, count, initial_period, subsequent_period): + """ + Transmits a message `count` times at `initial_period` then continues to + transmit message at `subsequent_period`. + + :param can.interface.Bus channel: + :param can.Message message: + :param int count: + :param float initial_period: + :param float subsequent_period: + """ super(MultiRateCyclicSendTaskABC, self).__init__(channel, message, subsequent_period) @@ -135,12 +143,14 @@ def _run(self): def send_periodic(bus, message, period, *args, **kwargs): - """Send a message every `period` seconds on the given channel. + """ + Send a :class:`~can.Message` every `period` seconds on the given bus. - :param bus: The :class:`can.BusABC` to transmit to. - :param message: The :class:`can.Message` instance to periodically send + :param can.BusABC bus: A CAN bus which supports sending. + :param can.Message message: Message to send periodically. + :param float period: The minimum time between sending messages. :return: A started task instance """ log.warning("The function `can.send_periodic` is deprecated and will " + - "be removed in version 2.3. Please use `can.Bus.send_periodic` instead.") + "be removed in version 2.3. Please use `can.Bus.send_periodic` instead.") return bus.send_periodic(message, period, *args, **kwargs) diff --git a/can/bus.py b/can/bus.py index 90bc3b343..f10c3a1e5 100644 --- a/can/bus.py +++ b/can/bus.py @@ -59,7 +59,7 @@ def recv(self, timeout=None): :param float timeout: seconds to wait for a message or None to wait indefinitely - :rtype: can.Message or None + :rtype: can.Message or NoneType :return: None on timeout or a :class:`can.Message` object. :raises can.CanError: @@ -118,9 +118,9 @@ def _recv_internal(self, timeout): Thus it cannot be simplified to a constant value. :param float timeout: seconds to wait for a message, - see :meth:`can.BusABC.send` + see :meth:`~can.BusABC.send` - :rtype: tuple[can.Message, bool] or tuple[None, bool] + :rtype: tuple[can.Message, bool] or tuple[NoneType, bool] :return: 1. a message that was read or None on timeout 2. a bool that is True if message filtering has already @@ -172,7 +172,7 @@ def send_periodic(self, msg, period, duration=None): Note the duration before the message stops being sent may not be exactly the same as the duration specified by the user. In general the message will be sent at the given rate until at - least *duration* seconds. + least **duration** seconds. """ if not hasattr(self, "_lock_send_periodic"): diff --git a/can/interfaces/iscan.py b/can/interfaces/iscan.py index 7f127b241..232447f84 100644 --- a/can/interfaces/iscan.py +++ b/can/interfaces/iscan.py @@ -36,7 +36,7 @@ def check_status(result, function, arguments): try: iscan = ctypes.cdll.LoadLibrary("iscandrv") -except Exception as e: +except OSError as e: iscan = None logger.warning("Failed to load IS-CAN driver: %s", e) else: diff --git a/can/interfaces/pcan/PCANBasic.py b/can/interfaces/pcan/basic.py similarity index 100% rename from can/interfaces/pcan/PCANBasic.py rename to can/interfaces/pcan/basic.py diff --git a/can/interfaces/pcan/pcan.py b/can/interfaces/pcan/pcan.py index ebf95b5dc..01779a61c 100644 --- a/can/interfaces/pcan/pcan.py +++ b/can/interfaces/pcan/pcan.py @@ -5,7 +5,7 @@ Enable basic CAN over a PCAN USB device. """ -from __future__ import absolute_import, print_function +from __future__ import absolute_import, print_function, division import logging import sys @@ -13,8 +13,8 @@ import can from can import CanError, Message, BusABC -from .PCANBasic import * from can.bus import BusState +from .basic import * boottimeEpoch = 0 try: @@ -72,13 +72,13 @@ def __init__(self, channel, state=BusState.ACTIVE, *args, **kwargs): """A PCAN USB interface to CAN. On top of the usual :class:`~can.Bus` methods provided, - the PCAN interface includes the :meth:`~can.interface.pcan.PcanBus.flash()` - and :meth:`~can.interface.pcan.PcanBus.status()` methods. + the PCAN interface includes the :meth:`~can.interface.pcan.PcanBus.flash` + and :meth:`~can.interface.pcan.PcanBus.status` methods. :param str channel: The can interface name. An example would be 'PCAN_USBBUS1' - :param BusState state: + :param can.bus.BusState state: BusState of the channel. Default is ACTIVE @@ -160,7 +160,8 @@ def status(self): """ Query the PCAN bus status. - :return: The status code. See values in pcan_constants.py + :rtype: int + :return: The status code. See values in **basic.PCAN_ERROR_** """ return self.m_objPCANBasic.GetStatus(self.m_PcanHandle) diff --git a/can/util.py b/can/util.py index a471fda89..0b9c9f1b2 100644 --- a/can/util.py +++ b/can/util.py @@ -190,10 +190,10 @@ def load_config(path=None, config=None): if 'bitrate' in config: config['bitrate'] = int(config['bitrate']) - can.log.debug("loaded can config: {}".format(config)) + can.log.debug("can config: {}".format(config)) return config - + def set_logging_level(level_name=None): """Set the logging level for the "can" logger. Expects one of: 'critical', 'error', 'warning', 'info', 'debug', 'subdebug' diff --git a/doc/bcm.rst b/doc/bcm.rst index f53bc1444..0676a77eb 100644 --- a/doc/bcm.rst +++ b/doc/bcm.rst @@ -1,57 +1,51 @@ Broadcast Manager ================= +.. module:: can.broadcastmanager + The broadcast manager isn't yet supported by all interfaces. -Currently SockerCAN and IXXAT are supported at least partially. +Currently SocketCAN and IXXAT are supported at least partially. It allows the user to setup periodic message jobs. If periodic transmission is not supported natively, a software thread based scheduler is used as a fallback. -This example shows the socketcan_ctypes backend using the broadcast manager: - +This example shows the socketcan backend using the broadcast manager: .. literalinclude:: ../examples/cyclic.py :language: python :linenos: -Class based API ---------------- - -.. autoclass:: can.broadcastmanager.CyclicTask - :members: +Message Sending Tasks +~~~~~~~~~~~~~~~~~~~~~ +The class based api for the broadcast manager uses a series of +`mixin classes `_. +All mixins inherit from :class:`~can.broadcastmanager.CyclicSendTaskABC` .. autoclass:: can.broadcastmanager.CyclicSendTaskABC :members: -.. autoclass:: can.broadcastmanager.LimitedDurationCyclicSendTaskABC +.. autoclass:: LimitedDurationCyclicSendTaskABC :members: - -.. autoclass:: can.broadcastmanager.RestartableCyclicTaskABC +.. autoclass:: MultiRateCyclicSendTaskABC :members: - -.. autoclass:: can.broadcastmanager.ModifiableCyclicTaskABC +.. autoclass:: can.ModifiableCyclicTaskABC :members: -.. autoclass:: can.broadcastmanager.MultiRateCyclicSendTaskABC +.. autoclass:: can.RestartableCyclicTaskABC :members: -.. autoclass:: can.broadcastmanager.ThreadBasedCyclicSendTask - :members: - - Functional API -------------- -.. note:: - The functional API in :func:`can.broadcastmanager.send_periodic` is now deprecated. +.. warning:: + The functional API in :func:`can.broadcastmanager.send_periodic` is now deprecated + and will be removed in version 2.3. Use the object oriented API via :meth:`can.BusABC.send_periodic` instead. - .. autofunction:: can.broadcastmanager.send_periodic - diff --git a/doc/bus.rst b/doc/bus.rst index 0a2291591..2d2472e6e 100644 --- a/doc/bus.rst +++ b/doc/bus.rst @@ -3,8 +3,8 @@ Bus --- -The :class:`can.BusABC` class, as the name suggests, provides an abstraction of a CAN bus. -The bus provides an abstract wrapper around a physical or virtual CAN Bus. +The :class:`~can.BusABC` class, as the name suggests, provides an abstraction of a CAN bus. +The bus provides a wrapper around a physical or virtual CAN Bus. A thread safe bus wrapper is also available, see `Thread safe bus`_. @@ -61,10 +61,10 @@ It can be used exactly like the normal :class:`~can.BusABC`: .. autoclass:: can.ThreadSafeBus :members: + Autoconfig Bus -------------- .. autoclass:: can.interface.Bus :members: :special-members: __iter__ - diff --git a/doc/conf.py b/doc/conf.py index 9adaf9b7d..e61801a6f 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,6 +28,8 @@ # -- General configuration ----------------------------------------------------- +primary_domain = 'py' + # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', @@ -45,7 +47,7 @@ } intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None) + 'python': ('https://docs.python.org/3/', None), } # If this is True, todo and todolist produce output, else they produce nothing. diff --git a/doc/development.rst b/doc/development.rst index 17e7f68ab..8ebadb208 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -42,8 +42,9 @@ These steps are a guideline on how to add a new backend to python-can. an entry in ``doc/interface/*``. - Add tests in ``test/*`` where appropiate. + About the ``BusABC`` class -========================== +-------------------------- Concrete implementations *have to* implement the following: * :meth:`~can.BusABC.send` to send individual messages diff --git a/doc/interfaces/serial.rst b/doc/interfaces/serial.rst index 651fb1b14..8335b39eb 100644 --- a/doc/interfaces/serial.rst +++ b/doc/interfaces/serial.rst @@ -8,8 +8,8 @@ The interface is a simple implementation that has been used for recording CAN traces. .. note:: - The properties extended_id, is_remote_frame and is_error_frame - from the class can.Message are not in use. These interface will not + The properties **extended_id**, **is_remote_frame** and **is_error_frame** + from the class:`~can.Message` are not in use. This interface will not send or receive flags for this properties. Bus @@ -95,4 +95,4 @@ Examples of serial frames | Start of frame | Timestamp | DLC | Arbitration ID | End of frame | +================+=====================+======+=====================+==============+ | 0xAA | 0x66 0x73 0x00 0x00 | 0x00 | 0x01 0x00 0x00 0x00 | 0xBBS | -+----------------+---------------------+------+---------------------+--------------+ \ No newline at end of file ++----------------+---------------------+------+---------------------+--------------+ diff --git a/doc/listeners.rst b/doc/listeners.rst index 3f2b57425..0b69b631b 100644 --- a/doc/listeners.rst +++ b/doc/listeners.rst @@ -13,7 +13,7 @@ Listeners are registered with :ref:`notifier` object(s) which ensure they are notified whenever a new message is received. Subclasses of Listener that do not override **on_message_received** will cause -`NotImplementedError` to be thrown when a message is received on +:class:`NotImplementedError` to be thrown when a message is received on the CAN bus. .. autoclass:: can.Listener @@ -31,7 +31,7 @@ Logger ------ The :class:`can.Logger` uses the following :class:`can.Listener` types to -create *.asc*, *.csv* and *.db* files with the messages received. +create log files with different file types of the messages received. .. autoclass:: can.Logger :members: @@ -50,6 +50,9 @@ CSVWriter .. autoclass:: can.CSVWriter :members: +.. autoclass:: can.CSVReader + :members: + SqliteWriter ------------ @@ -57,6 +60,10 @@ SqliteWriter .. autoclass:: can.SqliteWriter :members: +.. autoclass:: can.SqliteReader + :members: + + Database table format ~~~~~~~~~~~~~~~~~~~~~ @@ -113,12 +120,12 @@ As specification following references can-utils can be used: `log2asc `_. -.. autoclass:: can.io.CanutilsLogWriter +.. autoclass:: can.CanutilsLogWriter :members: -CanutilsLogReader reads CAN data from ASCII log files .log +**CanutilsLogReader** reads CAN data from ASCII log files .log -.. autoclass:: can.io.CanutilsLogReader +.. autoclass:: can.CanutilsLogReader :members: @@ -130,12 +137,12 @@ CAN log format from Vector Informatik GmbH. The data is stored in a compressed format which makes it very compact. -.. note:: - - Channels will be converted to integers. +.. note:: Channels will be converted to integers. .. autoclass:: can.BLFWriter :members: +The following class can be used to read messages from BLF file: + .. autoclass:: can.BLFReader :members: diff --git a/examples/cyclic.py b/examples/cyclic.py index 281b7c43e..f7972f55c 100755 --- a/examples/cyclic.py +++ b/examples/cyclic.py @@ -16,6 +16,7 @@ import time import can + logging.basicConfig(level=logging.INFO) @@ -104,15 +105,13 @@ def test_periodic_send_with_modifying_data(bus): reset_msg = can.Message(arbitration_id=0x00, data=[0, 0, 0, 0, 0, 0], extended_id=False) - for interface, channel in [ - ('socketcan_ctypes', 'can0'), - ('socketcan_native', 'can0') + ('socketcan', 'can0'), #('ixxat', 0) ]: print("Carrying out cyclic tests with {} interface".format(interface)) - bus = can.interface.Bus(bustype=interface, channel=channel, bitrate=500000) + bus = can.Bus(interface=interface, channel=channel, bitrate=500000) bus.send(reset_msg) simple_periodic_send(bus)