Even more documentation.

Author: christiansandberg

canopen/common.py

@@ -8,8 +8,7 @@ class Variable(object):
 
     def __init__(self, od):
         self.od = od
-        #: Bits as a dictionary
-        self.bits = Bits(self)
+        self._bits = Bits(self)
 
     def get_data(self):
         raise NotImplementedError()
@@ -19,7 +18,7 @@ def set_data(self, data):
 
     @property
     def data(self):
-        """Bytes."""
+        """Byte representation of the object (:class:`bytes`)."""
         if self.od.access_type == "wo":
             logger.warning("Variable is write only")
         return self.get_data()
@@ -32,6 +31,27 @@ def data(self, data):
 
     @property
     def raw(self):
+        """Raw representation of the object.
+        
+        This table lists the translations between object dictionary data types
+        and Python native data types.
+
+        +---------------------------+----------------------------+
+        | Data type                 | Python type                |
+        +===========================+============================+
+        | UNSIGNEDxx                | :class:`int`               |
+        +---------------------------+                            |
+        | INTEGERxx                 |                            |
+        +---------------------------+----------------------------+
+        | BOOLEAN                   | :class:`bool`              |
+        +---------------------------+----------------------------+
+        | REALxx                    | :class:`float`             |
+        +---------------------------+----------------------------+
+        | VISIBLE_STRING            | :class:`str`               |
+        |                           +----------------------------+
+        |                           | ``unicode`` (Python 2)     |
+        +---------------------------+----------------------------+
+        """
         value = self.od.decode_raw(self.data)
         text = "Value of %s (0x%X:%d) is %s" % (
             self.od.name, self.od.index,
@@ -50,6 +70,12 @@ def raw(self, value):
 
     @property
     def phys(self):
+        """Physical value scaled with some factor (defaults to 1).
+
+        On object dictionaries that support specifying a factor, this can be
+        either a :class:`float` or an :class:`int`.
+        Strings will be passed as is.
+        """
         value = self.od.decode_phys(self.data)
         logger.debug("Value of %s (0x%X:%d) is %s %s",
                      self.od.name, self.od.index,
@@ -65,6 +91,7 @@ def phys(self, value):
 
     @property
     def desc(self):
+        """Converts to and from a description of the value as a string."""
         value = self.od.decode_desc(self.data)
         logger.debug("Description of %s (0x%X:%d) is %s",
                      self.od.name, self.od.index,
@@ -78,6 +105,11 @@ def desc(self, desc):
                      self.od.subindex, desc)
         self.data = self.od.encode_desc(desc)
 
+    @property
+    def bits(self):
+        """Access bits using integers, slices, or bit descriptions."""
+        return self._bits
+
 
 class Bits(object):
 

canopen/nmt.py

@@ -38,10 +38,15 @@
 
 
 class NmtMaster(object):
+    """
+    Can set the state of the node it controls using NMT commands and monitor
+    the current state using the heartbeat protocol.
+    """
 
     def __init__(self, parent):
         self._state = 0
         self._state_received = False
+        #: Timestamp of last heartbeat message
         self.timestamp = 0
         self.state_change = threading.Condition()
         self.parent = parent
@@ -54,6 +59,7 @@ def on_heartbeat(self, can_id, data, timestamp):
             self.state_change.notify_all()
 
     def send_command(self, code):
+        """Send an NMT command code to the node."""
         logger.info("Sending NMT command 0x%X to node %d", code, self.parent.id)
         self.parent.network.send_message(0, [code, self.parent.id])
         if code in COMMAND_TO_STATE:
@@ -62,6 +68,19 @@ def send_command(self, code):
 
     @property
     def state(self):
+        """Attribute to get or set current state as a string.
+
+        Can be one of:
+
+        - INIT
+        - PRE OPERATIONAL
+        - STOPPED
+        - OPERATIONAL
+        - SLEEP
+        - STANDBY
+        - RESET (for setting only)
+        - RESET COMMUNICATION (for setting only)
+        """
         if self._state in NMT_STATES:
             return NMT_STATES[self._state]
         else:

canopen/node.py

@@ -11,10 +11,21 @@
 
 
 class Node(object):
+    """A CANopen slave node.
+
+    :param int node_id:
+        Node ID
+    :param object_dictionary:
+        Object dictionary as either a path to a file or an object.
+    :type object_dictionary: :class:`str`, :class:`canopen.ObjectDictionary` 
+    """
 
     def __init__(self, node_id=1, object_dictionary=None):
+        #: Node ID
         self.id = node_id
+        #: :class:`canopen.Network` owning the node
         self.network = None
+        #: :class:`canopen.ObjectDictionary` associated with the node
         self.object_dictionary = objectdictionary.ObjectDictionary()
         self.service_callbacks = {}
         self.message_callbacks = []
@@ -42,6 +53,12 @@ def set_node_id(self, node_id):
         self.sdo.id = node_id
 
     def set_object_dictionary(self, object_dictionary):
+        """Sets the object dictionary for the node.
+
+        :param object_dictionary:
+            Object dictionary as either a path to a file or an object.
+        :type object_dictionary: :class:`str`, :class:`canopen.ObjectDictionary`
+        """ 
         assert object_dictionary, "An Object Dictionary file has not been specified"
         if not isinstance(object_dictionary, objectdictionary.ObjectDictionary):
             object_dictionary = objectdictionary.import_od(object_dictionary)

canopen/objectdictionary/__init__.py

@@ -26,6 +26,14 @@
 
 
 def import_od(filename):
+    """Parse an EDS or EPF file.
+
+    :param str filename:
+        Path to object dictionary file.
+
+    :return:
+        A :class:`canopen.ObjectDictionary` object.
+    """
     if filename.endswith(".eds"):
         from . import eds
         return eds.import_eds(filename)
@@ -35,18 +43,19 @@ def import_od(filename):
 
 
 class ObjectDictionary(collections.Mapping):
+    """Representation of the object dictionary as a Python dictionary."""
 
     def __init__(self):
         self.indexes = collections.OrderedDict()
         self.names = collections.OrderedDict()
+        #: Default bitrate if specified by file
         self.bitrate = None
 
     def __getitem__(self, index):
-        """Get Object Dictionary index."""
+        """Get object from object dictionary by name or index."""
         return self.names.get(index) or self.indexes[index]
 
     def __iter__(self):
-        """Iterates over all Object Dictionary indexes."""
         return iter(self.names)
 
     def __len__(self):
@@ -56,14 +65,26 @@ def __contains__(self, index):
         return index in self.names or index in self.indexes
 
     def add_object(self, obj):
+        """Add object to the object dictionary.
+
+        :param obj:
+            Should be either one of
+            :class:`canopen.objectdictionary.Variable`,
+            :class:`canopen.objectdictionary.Record`, or
+            :class:`canopen.objectdictionary.Array`.
+        """
         obj.parent = self
         self.indexes[obj.index] = obj
         self.names[obj.name] = obj
 
 
 class Record(collections.Mapping):
+    """Groups multiple :class:`canopen.objectdictionary.Variable` objects using
+    subindexes.
+    """
 
     def __init__(self, name, index):
+        #: The :class:`canopen.ObjectDictionary` owning the record.
         self.parent = None
         self.index = index
         self.name = name
@@ -86,22 +107,31 @@ def __eq__(self, other):
         return self.index == other.index
 
     def add_member(self, variable):
+        """Adds a :class:`canopen.objectdictionary.Variable` to the record."""
         variable.parent = self
         self.subindexes[variable.subindex] = variable
         self.names[variable.name] = variable
 
 
 class Array(collections.Sequence):
+    """An array of :class:`canopen.objectdictionary.Variable` objects using
+    subindexes.
+    
+    Actual length of array must be read from the node using SDO.
+    """
 
     def __init__(self, name, index):
+        #: The :class:`canopen.ObjectDictionary` owning the array.
         self.parent = None
         self.index = index
         self.name = name
         self.length = 255
+        #: Variable to read to get length of array
         self.last_subindex = Variable(
             "Number of entries", index, 0)
         self.last_subindex.data_type = UNSIGNED8
         self.last_subindex.parent = self
+        #: Each variable will be based on this with unique subindexes
         self.template = None
 
     def __getitem__(self, subindex):
@@ -122,7 +152,7 @@ def __len__(self):
 
 
 class Variable(object):
-    """Object Dictionary VAR."""
+    """Simple variable."""
 
     STRUCT_TYPES = {
         BOOLEAN: struct.Struct("?"),
@@ -139,16 +169,29 @@ class Variable(object):
     }
 
     def __init__(self, name, index, subindex=0):
+        #: The :class:`canopen.ObjectDictionary`,
+        #: :class:`canopen.objectdictionary.Record` or
+        #: :class:`canopen.objectdictionary.Array` owning the variable
         self.parent = None
+        #: 16-bit address of the object in the dictionary
         self.index = index
+        #: 8-bit sub-index of the object in the dictionary
         self.subindex = subindex
+        #: String representation of the variable
         self.name = name
+        #: Data type according to the standard as an :class:`int`
         self.data_type = UNSIGNED32
+        #: Access type, should be "rw", "ro", "wo", or "const"
         self.access_type = "rw"
+        #: Physical unit
         self.unit = ""
+        #: Factor between physical unit and integer value
         self.factor = 1
+        #: Minimum allowed value
         self.min = None
+        #: Maximum allowed value
         self.max = None
+        #: Dictionary of value descriptions
         self.value_descriptions = {}
         self.bit_definitions = {}
 

canopen/sdo.py

@@ -30,8 +30,10 @@
 
 
 class SdoClient(collections.Mapping):
+    """Handles communication with an SDO server."""
 
     def __init__(self, parent, node_id):
+        #: Node ID
         self.id = node_id
         self.parent = parent
         self.response = None
@@ -66,6 +68,21 @@ def send_request(self, sdo_request):
             return self.response
 
     def upload(self, index, subindex):
+        """May be called to manually make a read operation.
+
+        :param int index:
+            Index of object to read.
+        :param int subindex:
+            Sub-index of object to read.
+
+        :return: A data object.
+        :rtype: bytes
+
+        :raises canopen.SdoCommunicationError:
+            On unexpected response or timeout.
+        :raises canopen.SdoAbortedError:
+            When node responds with an error.
+        """
         request = SDO_STRUCT.pack(REQUEST_UPLOAD, index, subindex, b'')
         response = self.send_request(request)
         res_command, res_index, res_subindex, res_data = SDO_STRUCT.unpack(response)
@@ -108,6 +125,20 @@ def upload(self, index, subindex):
         return res_data[:length] if length is not None else res_data
 
     def download(self, index, subindex, data):
+        """May be called to manually make a write operation.
+
+        :param int index:
+            Index of object to write.
+        :param int subindex:
+            Sub-index of object to write.
+        :param bytes data:
+            Data to be written.
+
+        :raises canopen.SdoCommunicationError:
+            On unexpected response or timeout.
+        :raises canopen.SdoAbortedError:
+            When node responds with an error.
+        """
         length = len(data)
         command = REQUEST_DOWNLOAD | SIZE_SPECIFIED
 
@@ -196,6 +227,7 @@ def __contains__(self, subindex):
 
 
 class Variable(common.Variable):
+    """Access object dictionary variable values using SDO protocol."""
 
     def __init__(self, sdo_node, od):
         self.sdo_node = sdo_node