Update can.rst

Add user guide for CAN Transport Interface

docs/source/pages/user_guide/transport/can.rst

@@ -116,17 +116,33 @@ the user perspective it does not provide any additional features to common_ impl
         repeat_wait=True)
 
 
-Send Packet
-```````````
-Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
-is created, there are two methods which can be used to transmit CAN packets:
+Synchronous communication
+`````````````````````````
+.. warning:: Synchronous and asynchronous implementation shall not be mixed, therefore for transmitting and receiving
+    UDS Messages and CAN Packets use either:
+
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_packet`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_packet`
+
+    or
+
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_packet`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_packet`
+
+.. seealso:: :ref:`Examples for python-can Transport Interface <example-python-can>`
 
-- :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_packet` - for
-  synchronous implementation
-- :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_packet` - for
-  asynchronous implementation
+Send Message
+''''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_message`
+method to receive UDS messages over CAN.
 
-**Example synchronous code:**
+**Example code:**
 
 .. code-block::  python
 
@@ -136,14 +152,36 @@ is created, there are two methods which can be used to transmit CAN packets:
     message = uds.message.UdsMessage(addressing_type=uds.transmission_attributes.AddressingType.PHYSICAL,
                                      payload=[0x10, 0x03])
 
-    # segment the message to create a CAN packet
-    can_packet = can_transport_interface.segmenter.segmentation(message)[0]
+    # send UDS Message and receive UDS message record with historic information about the transmission
+    message_record = can_transport_interface.send_message(message)
 
-    # send CAN packet and receive CAN packet record with historic information about the transmission and the transmitted CAN packet
-    can_packet_record = can_transport_interface.send_packet(can_packet)
 
+Receive Message
+'''''''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_message`
+method to receive UDS messages over CAN.
 
-**Example asynchronous code:**
+**Example code:**
+
+.. code-block::  python
+
+    # let's assume that we have `can_transport_interface` already configured as presented in configuration example above
+
+    # receive an UDS message with timeout set to 1000 ms
+    message_record = can_transport_interface.receive_message(timeout=1000)
+
+
+
+Send Packet
+'''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_packet`
+method to send CAN packets.
+
+**Example code:**
 
 .. code-block::  python
 
@@ -157,68 +195,119 @@ is created, there are two methods which can be used to transmit CAN packets:
     can_packet = can_transport_interface.segmenter.segmentation(message)[0]
 
     # send CAN packet and receive CAN packet record with historic information about the transmission and the transmitted CAN packet
-    can_packet_record = await can_transport_interface.async_send_packet(can_packet)
+    can_packet_record = can_transport_interface.send_packet(can_packet)
+
+Receive Packet
+''''''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_packet`
+method to receive CAN packets.
+
+**Example code:**
+
+.. code-block::  python
+
+    # let's assume that we have `can_transport_interface` already configured as presented in configuration example above
+
+    # receive a CAN packet with timeout set to 1000 ms
+    can_packet_record = can_transport_interface.receive_packet(timeout=1000)
+
+
+Asynchronous communication
+``````````````````````````
+.. warning:: Synchronous and asynchronous implementation shall not be mixed, therefore for transmitting and receiving
+    UDS Messages and CAN Packets use either:
 
-.. note:: In the example above, only a coroutine code was presented. If you need a manual how to run an asynchronous
-    program, visit https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program.
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_packet`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_packet`
 
-.. warning:: Synchronous and asynchronous implementation shall not be mixed, so use either
-    :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_packet` and
-    :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_packet`
-    (synchronous)
-    or :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_packet` and
-    :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_packet`
-    (asynchronous) methods for transmitting and receiving CAN Packets.
+    or
+
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_message`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_packet`
+    - :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_packet`
 
 .. seealso:: :ref:`Examples for python-can Transport Interface <example-python-can>`
 
+.. note:: In all examples, only a coroutine code was presented. If you need a manual how to run an asynchronous code,
+    visit https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program.
 
-Receive Packet
-``````````````
-Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class is created,
-there are two methods which can be used to receive CAN packets:
+Send Message
+''''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_message`
+method to receive UDS messages over CAN.
+
+**Example code:**
+
+.. code-block::  python
+
+    # let's assume that we have `can_transport_interface` already configured as presented in configuration example above
+
+    # define some UDS message to send
+    message = uds.message.UdsMessage(addressing_type=uds.transmission_attributes.AddressingType.PHYSICAL,
+                                     payload=[0x10, 0x03])
 
-- :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_packet` - for synchronous
-  implementation
-- :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_packet` - for
-  asynchronous implementation
+    # send UDS Message and receive UDS message record with historic information about the transmission
+    message_record = await can_transport_interface.async_send_message(message)
 
-**Example synchronous code:**
+Receive Message
+'''''''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_message`
+method to receive UDS messages over CAN.
+
+**Example code:**
 
 .. code-block::  python
 
     # let's assume that we have `can_transport_interface` already configured as presented in configuration example above
 
-    # receive a CAN packet with timeout set to 1000 ms
-    can_packet_record = can_transport_interface.receive_packet(timeout=1000)
+    # receive an UDS message with timeout set to 1000 ms
+    message_record = await can_transport_interface.async_receive_message(timeout=1000)
 
+Send Packet
+'''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_packet`
+method to send CAN packets.
 
-**Example asynchronous code:**
+**Example code:**
 
 .. code-block::  python
 
     # let's assume that we have `can_transport_interface` already configured as presented in configuration example above
 
-    # receive a CAN packet with timeout set to 1000 ms
-    can_packet_record = await can_transport_interface.async_receive_packet(timeout=1000)
+    # define some UDS message to send
+    message = uds.message.UdsMessage(addressing_type=uds.transmission_attributes.AddressingType.PHYSICAL,
+                                     payload=[0x10, 0x03])
 
-.. note:: In the example above, only a coroutine code was presented. If you need a manual how to run an asynchronous
-    program, visit https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program.
+    # segment the message to create a CAN packet
+    can_packet = can_transport_interface.segmenter.segmentation(message)[0]
 
-.. warning:: Synchronous and asynchronous implementation shall not be mixed, so use either
-    :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.send_packet` and
-    :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.receive_packet` (synchronous)
-    or :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_send_packet` and
-    :meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_packet` (asynchronous)
-    methods for transmitting and receiving CAN Packets.
+    # send CAN packet and receive CAN packet record with historic information about the transmission and the transmitted CAN packet
+    can_packet_record = await can_transport_interface.async_send_packet(can_packet)
 
-.. seealso:: :ref:`Examples for python-can Transport Interface <example-python-can>`
+Receive Packet
+''''''''''''''
+Once an object of :class:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface` class
+is created, use
+:meth:`~uds.transport_interface.can_transport_interface.python_can.PyCanTransportInterface.async_receive_packet`
+method to receive CAN packets.
 
+**Example code:**
 
-Send Message
-````````````
-TODO: explanation + code snippets + links to examples
+.. code-block::  python
+
+    # let's assume that we have `can_transport_interface` already configured as presented in configuration example above
+
+    # receive a CAN packet with timeout set to 1000 ms
+    can_packet_record = await can_transport_interface.async_receive_packet(timeout=1000)
 
-Receive Message
-```````````````
-TODO: explanation + code snippets + links to examples