Merge pull request #9 from supermete/improvement/merge_stop_methods

Merge stop and shutdown methods. Update doc

README.md

@@ -22,6 +22,8 @@ You can install *caroa04* via [pip]() from [PyPI]():
 
 ## Usage
 
+You can instantiate a CaroA04 object and start it to communicate with the device as follows.
+
 ``` python
 from caroa04 import CaroA04
 
@@ -41,6 +43,25 @@ caro.node_id.phys = 0xE1  # set address code (will require device power cycle)
 caro.shutdown()  # free the bus
 ```
 
+In order to share the bus with other participants, you can assign the bus attribute of the CaroA04 object before starting it.
+You should simply then add CaroA04's listener to the existing bus' notifier.
+
+``` python
+import canopen
+from caroa04 import CaroA04
+
+nw = canopen.Network()
+nw.connect(interface='pcan', bitrate=250000, channel='PCAN_USBBUS1')
+
+
+caro = CaroA04()
+caro.bus = nw.bus  # use the bus already started by canopen
+nw.notifier.add_listener(caro.listener)  # add listener so that we can receive messages
+
+caro.start(0xE0, 'pcan')  # start communication
+caro.shutdown()  # free the bus
+```
+
 ## Features
 
 - This library uses the python-can library to communicate with the device. Please refer to its documentation to know about all the CAN interfaces that can be used with this library (https://python-can.readthedocs.io/en/stable/)

README.rst

@@ -39,6 +39,8 @@ You can install "caroa04" via pip from PyPI:
 Usage
 -----
 
+You can instantiate a CaroA04 object and start it to communicate with the device as follows.
+
 .. code-block:: python
 
     from caroa04 import CaroA04
@@ -60,6 +62,27 @@ Usage
 
 ..
 
+In order to share the bus with other participants, you can assign the bus attribute of the CaroA04 object before starting it.
+You should simply then add CaroA04's listener to the existing bus' notifier.
+
+.. code-block:: python
+
+    import canopen
+    from caroa04 import CaroA04
+
+    nw = canopen.Network()
+    nw.connect(interface='pcan', bitrate=250000, channel='PCAN_USBBUS1')
+
+
+    caro = CaroA04()
+    caro.bus = nw.bus  # use the bus already started by canopen
+    nw.notifier.add_listener(caro.listener)  # add listener so that we can receive messages
+
+    caro.start(0xE0, 'pcan')  # start communication
+    caro.shutdown()  # free the bus
+
+..
+
 Features
 --------
 

changelog.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [ongoing] - 2024-04-26
 ### Changed
 - Use notifier from can library to allow sharing the bus with other bus users, #7
+- Merge stop and shutdown methods, to only have a stop method to be called when stopping, #8
 
 ### Fixed
 - Fix communication when bus is set before starting , #5

src/caroa04/caroa04.py

@@ -148,8 +148,6 @@ def stop(self):
         """Stops any ongoing thread"""
         if self.notifier is not None:
             self.notifier.stop()
-
-    def shutdown(self):
         if self.bus is not None:
             self.bus.shutdown()  # free the port
             self.bus = None
@@ -165,4 +163,3 @@ def shutdown(self):
     caro.do1.phys = True
     print(caro.do1.phys)
     caro.do1.phys = False
-    caro.shutdown()

tests/test_caroa04.py

@@ -80,8 +80,6 @@ def listener(self, msg):
     def stop(self):
         if self.notifier is not None:
             self.notifier.stop()
-
-    def shutdown(self):
         if self.bus is not None:
             self.bus.shutdown()
             self.bus = None
@@ -105,9 +103,7 @@ def setup_teardown_class(self, caro, virtualdevice):
         yield
 
         caro.stop()
-        caro.shutdown()
         virtualdevice.stop()
-        virtualdevice.shutdown()
 
     def test_do1(self, caro, virtualdevice):
         assert caro.do1.phys is False, "Initial value of DO1 is wrong"