Updated documentation for RequestFileTransfer

Author: pylessard

doc/source/udsoncan/client.rst

@@ -440,3 +440,14 @@ Methods by services
 #################################################
 
 .. automethod:: udsoncan.client.Client.write_memory_by_address
+
+-------------
+
+:ref:`RequestFileTransfer<RequestFileTransfer>`
+###############################################
+
+.. automethod:: udsoncan.client.Client.add_file
+.. automethod:: udsoncan.client.Client.delete_file
+.. automethod:: udsoncan.client.Client.replace_file
+.. automethod:: udsoncan.client.Client.read_file
+.. automethod:: udsoncan.client.Client.read_dir

doc/source/udsoncan/helper_classes.rst

@@ -58,6 +58,15 @@ AddressAndLengthFormatIdentifier
 
 -----
 
+.. _Filesize:
+
+Filesize
+--------
+
+.. autoclass:: udsoncan.Filesize
+
+-----
+
 .. _DTC:
 
 DTC

doc/source/udsoncan/questions_answers.rst

@@ -6,14 +6,14 @@ What version of the standard has been used?
 
 .. epigraph::
 
-   ISO-14229:2006, which is the document that I had access to when writing the code.
+   The cod ewas originally written based on ISO-14229:2006. Some addition from the 2013 version has been added, but not exhaustively.
 
-Can we expect an update for the 2013 version?
+Can we expect an update for the 2020 version?
 ---------------------------------------------
 
 .. epigraph::
 
-   Yes, one day, when I'll put my hands on the 2013 document. 
+   Yes, one day, when I'll put my hands on the 2020 document. 
    Access to ISO standard costs money and this project is 100% voluntary.
 
 -----

doc/source/udsoncan/services.rst

@@ -192,6 +192,21 @@ ReadDataByIdentifier (0x22)
 
 -------
 
+.. _RequestFileTransfer :
+
+RequestFileTransfer (0x38)
+--------------------------
+
+.. automethod:: udsoncan.services.RequestFileTransfer.make_request
+.. automethod:: udsoncan.services.RequestFileTransfer.interpret_response
+
+.. autoclass:: udsoncan.services::RequestFileTransfer.ResponseData
+   :members: 
+
+.. note:: This service does not have subfunctions
+
+-------
+
 .. _ReadDTCInformation:
 
 ReadDTCInformation (0x19)

udsoncan/__init__.py

@@ -1078,8 +1078,8 @@ class Filesize:
     :param uncompressed: Represent the uncompressed size in bytes
     :type uncompressed: int
 
-    :param uncompressed: Represent the compressed size in bytes
-    :type uncompressed: int
+    :param compressed: Represent the compressed size in bytes
+    :type compressed: int
 
     :param width: The number of byte that should be used to encode the filesize in a payload
     :type width: int
@@ -1144,4 +1144,18 @@ def get_compressed_bytes(self):
         if self.compressed is not None:
             return self.compressed.to_bytes(self.width, byteorder='big')
         else:
-            return b''
+            return b''
+
+    def __str__(self):
+        uncompressed_str    = 'None' if self.uncompressed   is None else '0x%02x' % self.uncompressed
+        compressed_str      = 'None' if self.compressed     is None else '0x%02x' % self.compressed
+        width_str           = 'None' if self.width          is None else '0x%02x' % self.width
+
+        return "Filesize<Uncompressed=%s, Compressed=%s. Width=%s>" % (uncompressed_str, compressed_str, width_str)
+
+    def __repr__(self):
+        uncompressed_str    = 'None' if self.uncompressed   is None else '0x%02x' % self.uncompressed
+        compressed_str      = 'None' if self.compressed     is None else '0x%02x' % self.compressed
+        width_str           = 'None' if self.width          is None else '0x%02x' % self.width
+
+        return "<Filesize: Uncompressed=%s, Compressed=%s. Width=%s at 0x%08x>" % (uncompressed_str, compressed_str, width_str, id(self))

udsoncan/client.py

@@ -27,13 +27,13 @@ propagate=0
 
 # Unit test
 [logger_UdsClient_unittest]
-level=NOTSET
-handlers=nullHandler
+level=DEBUG
+handlers=consoleHandler,fileHandler
 qualname=UdsClient[unittest]
 propagate=0
 
 [logger_Connection_unittest]
-level=NOTSET
+level=DEBUG
 handlers=consoleHandler,fileHandler
 qualname=Connection[unittest]
 propagate=0

udsoncan/logging.conf

@@ -13,7 +13,7 @@ class RequestFileTransfer(BaseService):
                                         Response.Code.RequestOutOfRange,
                                         Response.Code.UploadDownloadNotAccepted
                                         ]
-    class ModeOfOperation(BaseSubfunction):
+    class ModeOfOperation(BaseSubfunction): # Not really a subfunction, but we wantto inherit the helpers in BaseSubfunction class
         """
         RequestFileTransfer Mode Of Operation (MOOP). Represent the action that can be done on the server filesystem.
         See ISO-14229:2013 Annex G
@@ -40,6 +40,28 @@ def normalize_data_format_identifier(cls, dfi):
 
     @classmethod
     def make_request(cls, moop, path, dfi = None, filesize = None):
+        """
+        Generates a request for RequestFileTransfer
+
+        :param moop: Mode of operation. Can be AddFile(1), DeleteFile(2), ReplaceFile(3), ReadFile(4), ReadDir(5). See :class:`RequestFileTransfer.ModeOfOperation<udsoncan.services.RequestFileTransfer.ModeOfOperation>`
+        :type moop: int
+
+        :param path: String representing the path to the target file or directory.
+        :type path: string
+
+        :param dfi: DataFormatIdentifier defining the compression and encryption scheme of the data. 
+                If not specified, the default value of 00 will be used, specifying no encryption and no compression. 
+                This value is only used when ModeOfOperation is : ``AddFile``, ``ReplaceFile``, ``ReadFile``
+        :type dfi: :ref:`DataFormatIdentifier<DataFormatIdentifier>`
+
+        :param filesize: The filesize of the file to write when ModeOfOperation is ``AddFile`` or ``ReplaceFile``. 
+            If filesize is an object of type :ref:`Filesize<Filesize>`, the uncompressed size and compressed size will be encoded on
+            the minimum amount of bytes necessary, unless a ``width`` is explicitly defined. If no compressed size is given or filesize is an ``int``,
+            then the compressed size will be set equal to the uncompressed size or the integer value given as specified by ISO-14229
+        :type filesize: :ref:`Filesize<Filesize>` or int
+
+        :raises ValueError: If parameters are out of range, missing or wrong type
+        """             
         from udsoncan import Request, Filesize
         if not isinstance(moop, int):
             raise ValueError('Mode of operation must be an integer')
@@ -106,6 +128,15 @@ def make_request(cls, moop, path, dfi = None, filesize = None):
 
     @classmethod
     def interpret_response(cls, response, tolerate_zero_padding=True):
+        """
+        Populates the response ``service_data`` property with an instance of :class:`RequestFileTransfer.ResponseData<udsoncan.services.RequestFileTransfer.ResponseData>`
+
+        :param response: The received response to interpret
+        :type response: :ref:`Response<Response>`
+
+        :raises InvalidResponseException: If length of ``response.data`` is too short or payload does not respect ISO-14229 specifications
+        :raises NotImplementedError: If the MaxNumberOfBlock or fileSizeUncompressedOrDirInfoLength value is encoded over more than 8 bytes.
+        """         
         from udsoncan import Filesize, DataFormatIdentifier
         response.service_data = cls.ResponseData()
         if len(response.data) < 1:
@@ -187,7 +218,6 @@ def interpret_response(cls, response, tolerate_zero_padding=True):
             else:
                 compressed_size = None
 
-        
         if has_uncompressed_filesize and response.service_data.moop_echo == cls.ModeOfOperation.ReadDir:
             response.service_data.dirinfo_length = uncompressed_size
         else:
@@ -199,17 +229,48 @@ def interpret_response(cls, response, tolerate_zero_padding=True):
                 pass
             else:
                 raise InvalidResponseException(response, 'Response payload has extra data that has no meaning')
-        #from IPython import embed
-        #embed()
+
         response.service_data = response.service_data
 
     class ResponseData(BaseResponseData):
+        """
+        .. data:: moop_echo (int)
+
+                Request ModeOfOperation echoed back by the server
+
+        .. data:: max_length (int)
+
+                The MaxNumberOfBlockLength returned by the server. Represent the number of data bytes that should be included
+                in each subsequent TransferData request excepted the last one that might be smaller. 
+
+                Not set for a response to ``DeleteFile``.
+        
+        .. data:: dfi (DataFormatIdentifier)
+
+                Request DataFormatIdentifier echoed back by the server.
+
+                Not set for a response to ``DeleteFile``.
+                Set to Compression=0, Encryption=0, when getting a response for ``ReadDir`` as specified by ISO-14229.
+
+        .. data:: filesize (Filesize)
+
+                Defines the size fo the file to be read in bytes, including its uncompressed and compressed size.
+
+                Only set when performing a ``ReadFile`` request
+
+        .. data:: dirinfo_length (int)
+
+                Defines the size of the directory information to be read in bytes.
+
+                Only set when performing a ``ReadDir`` request
+
+        """ 
         __slots__ = 'moop_echo', 'max_length', 'dfi', 'filesize', 'dirinfo_length'
 
         def __init__(self):
             super().__init__(RequestFileTransfer)
-            self.moop_echo          = None
-            self.max_length         = None
-            self.dfi           = None
-            self.filesize           = None
-            self.dirinfo_length     = None
+            self.moop_echo      = None
+            self.max_length     = None
+            self.dfi            = None
+            self.filesize       = None
+            self.dirinfo_length = None