Merge branch 'release-new-version' of https://github.com/mdabrowski19…

…90/uds into release-new-version
mdabrowski1990 · Oct 29, 2024 · 4239141 · 4239141
2 parents 8538593 + f42d5a5
commit 4239141
Show file tree

Hide file tree

Showing 71 changed files with 4,718 additions and 2,967 deletions.
diff --git a/README.rst b/README.rst
@@ -21,25 +21,27 @@ If you want to become a contributor, please read `CONTRIBUTING.md`_ file.
 
 Why another UDS package?
 ------------------------
-There are a few already existing python packages to handle UDS protocol,
-so you might wonder why would you consider using this one?
+There are a few already existing python packages to handle UDS protocol, so you might wonder why would you consider
+using this one?
 
 This package is meant to support **multiple buses** (including CAN, LIN, Ethernet, K-Line, FlexRay) and **multiple
 bus managers** (e.g. `python-can`_).
-Additionally, it handles both communication nodes (client and server), and contains detailed configuration to fully
-control all timing and transmission parameters.
+Additionally, it handles both communication nodes (client and server), decoding monitored UDS communication,
+and contains detailed configuration to fully control all timing and transmission parameters.
 
 Thanks to all these features, this package can have multiple use-cases, including:
 
-- simple send-receive messages to/from any network
+- simple send-receive packets/messages to/from any network
 - comprehensive node simulations
-- testing of UDS protocol communication implementation
+- testing of UDS protocol communication implementation - either on client (diagnostic tester / ECU) or server (ECU) side
+- sniffing (and decoding) UDS communication
 
-Unfortunately, all previously mentioned plans make the project a huge effort and at the time of writing,
-the implementation process of these features is still ongoing (and probably the status will stay the same for at least
-a couple more years).
-On the other hand, the architecture to support all these features is already designed and some of the features
-are already implemented with others defined or planned.
+Unfortunately, all previously mentioned plans make the project quite huge.
+At the time of writing, the implementation process of these features is still ongoing (and probably the development
+would slowly progress over at least a few more years, unless more people get engaged in the project and/or
+more sponsors are found).
+On the other hand, the architecture to support all these features is already designed and some of them are already
+implemented with others defined or planned.
 
 To check the current implementation status, visit:
 
@@ -55,26 +57,51 @@ python-udsoncan
 Link: https://github.com/pylessard/python-udsoncan
 
 - pros:
-    - comprehensive documentation
-    - handlers for multiple diagnostic services is implemented
+
+  - comprehensive documentation -
+    https://udsoncan.readthedocs.io/en/latest/index.html
+  - maintained with active community - https://udsoncan.readthedocs.io/en/latest/udsoncan/questions_answers.html
+  - various connection types are supported -
+    https://udsoncan.readthedocs.io/en/latest/udsoncan/connection.html#available-connections
+  - CAN bus fully supported with possibility to extension for other buses (requires custom code)
+  - possibility to configure all transmission parameters for CAN using can-isotp package -
+    https://can-isotp.readthedocs.io/en/latest/isotp/implementation.html#
+  - handlers for multiple diagnostic services are implemented -
+    https://udsoncan.readthedocs.io/en/latest/udsoncan/services.html
+  - positive and negatives scenarios are handled - https://udsoncan.readthedocs.io/en/latest/udsoncan/exceptions.html
+  - control over CAN Network parameters (N_As, N_Ar, N_Bs, N_Br, N_Cs, N_Cr) via can-isotp package -
+    https://can-isotp.readthedocs.io/en/latest/isotp/socket.html
+    https://can-isotp.readthedocs.io/en/latest/isotp/implementation.html
+  - possibility to inject some errors on Transport/Network layer -
+    https://udsoncan.readthedocs.io/en/latest/udsoncan/client.html#overriding-the-output
+
 - cons:
-    - only positive use case scenarios (where communication is in line with UDS standard) are supported
-    - only CAN bus is supported
-    - only Client side communication can be handled
-    - limited communication parameters configuration
+
+  - no support for full-duplex communication (sending and receiving at the same time)
+  - only Client side communication is implemented - https://udsoncan.readthedocs.io/en/latest/udsoncan/client.html#
 
 
 python-uds
 ''''''''''
 Link: https://github.com/richClubb/python-uds
 
 - pros:
-    - CAN and LIN buses are supported
+
+  - CAN and LIN buses are supported
+
 - cons:
-    - modest documentation
-    - only a few communication interfaces are supported
-    - only Client side communication can be handled
-    - limited communication parameters configuration
+
+  - very modest documentation - https://python-uds.readthedocs.io/en/latest/
+  - is not maintained with the last release in March 2019 - https://pypi.org/project/python-uds/
+  - only a few communication interfaces (I have only found examples with python-can) are supported -
+    https://python-uds.readthedocs.io/en/latest/interface.html
+  - no support for full-duplex communication (sending and receiving at the same time)
+  - only Client side communication is implemented
+  - limited communication parameters configuration - https://python-uds.readthedocs.io/en/latest/configuration.html
+  - no option for injecting errors on Transport/Network layer, e.g.
+
+    - Overflow / Wait value of Flow Status (parameter of Flow Control packet)
+    - CAN packets in wrong order (e.g. incorrect Sequence Numbers order in Consecutive Frames)
 
 
 Contact

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,15 +1,15 @@
 Welcome to UDS documentation!
 =============================
 .. toctree::
-    :hidden:
+  :hidden:
 
-    Home <self>
-    pages/installation.rst
-    pages/user_guide.rst
-    pages/examples.rst
-    autoapi/index.rst
-    pages/knowledge_base.rst
-    pages/contribution.rst
+  Home <self>
+  pages/installation.rst
+  pages/user_guide.rst
+  pages/examples.rst
+  autoapi/index.rst
+  pages/knowledge_base.rst
+  pages/contribution.rst
 
 
 Overview
@@ -22,10 +22,11 @@ and decode diagnostic communication.
 The architecture enables to use it with various communication buses (e.g. CAN, LIN).
 
 The most likely use cases of this package are:
- - communication with your vehicle (e.g. reading Diagnostic Trouble Codes)
- - monitoring and decoding UDS communication
- - performing tests against on-board ECU (server)
- - performing tests against OBD Tester (client)
+
+- communication with your vehicle (e.g. reading Diagnostic Trouble Codes)
+- monitoring and decoding UDS communication
+- performing tests against on-board ECU (server)
+- performing tests against OBD Tester (client)
 
 
 Implementation Status
@@ -39,32 +40,32 @@ Features
 ````````
 Current implementation status of package features:
 
-+----------------------------------------------+--------------------------------------------+
-|                    Feature                   |            Implementation Status           |
-+==============================================+============================================+
-| UDS Messages and Packets                     | Available since version `0.0.2             |
-|                                              | <https://pypi.org/project/py-uds/0.0.2/>`_ |
-+----------------------------------------------+--------------------------------------------+
-| UDS Packets Reception and Transmission       | Available since version `0.3.0             |
-|                                              | <https://pypi.org/project/py-uds/0.3.0/>`_ |
-+----------------------------------------------+--------------------------------------------+
-| UDS Messages Reception and Transmission      | Available since version `1.0.0             |
-|                                              | <https://pypi.org/project/py-uds/1.0.0/>`_ |
-+----------------------------------------------+--------------------------------------------+
-| Messages Segmentation                        | Available since version `0.2.0             |
-|                                              | <https://pypi.org/project/py-uds/0.2.0/>`_ |
-+----------------------------------------------+--------------------------------------------+
-| UDS Packets Desegmentation                   | Available since version `0.2.0             |
-|                                              | <https://pypi.org/project/py-uds/0.2.0/>`_ |
-+----------------------------------------------+--------------------------------------------+
-| Support for Services with multiple responses | Planned                                    |
-+----------------------------------------------+--------------------------------------------+
-| Client Simulation                            | Planned                                    |
-+----------------------------------------------+--------------------------------------------+
-| Server Simulation                            | Planned                                    |
-+----------------------------------------------+--------------------------------------------+
-| Support for Messages Databases               | Planned                                    |
-+----------------------------------------------+--------------------------------------------+
++-----------------------------------------+--------------------------------------------+
+|                 Feature                 |            Implementation Status           |
++=========================================+============================================+
+| UDS Messages and Packets                | Available since version `0.0.2             |
+|                                         | <https://pypi.org/project/py-uds/0.0.2/>`_ |
++-----------------------------------------+--------------------------------------------+
+| UDS Packets Reception and Transmission  | Available since version `0.3.0             |
+|                                         | <https://pypi.org/project/py-uds/0.3.0/>`_ |
++-----------------------------------------+--------------------------------------------+
+| UDS Messages Reception and Transmission | Available since version `1.0.0             |
+|                                         | <https://pypi.org/project/py-uds/1.0.0/>`_ |
++-----------------------------------------+--------------------------------------------+
+| Messages Segmentation                   | Available since version `0.2.0             |
+|                                         | <https://pypi.org/project/py-uds/0.2.0/>`_ |
++-----------------------------------------+--------------------------------------------+
+| UDS Packets Desegmentation              | Available since version `0.2.0             |
+|                                         | <https://pypi.org/project/py-uds/0.2.0/>`_ |
++-----------------------------------------+--------------------------------------------+
+| Client Simulation                       | Planned                                    |
++-----------------------------------------+--------------------------------------------+
+| Server Simulation                       | Planned                                    |
++-----------------------------------------+--------------------------------------------+
+| UDS Sniffer                             | Planned                                    |
++-----------------------------------------+--------------------------------------------+
+| Support for Messages Databases          | Planned                                    |
++-----------------------------------------+--------------------------------------------+
 
 
 Buses supported
@@ -100,4 +101,4 @@ Contact
 
 .. admonition:: Documentation generated
 
-    |today|
+  |today|