PyVLCB 0.1.1__tar.gz → 0.1.3__tar.gz

{pyvlcb-0.1.1/src/PyVLCB.egg-info → pyvlcb-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyVLCB
-Version: 0.1.1
+Version: 0.1.3
 Summary: A library for CBUS / VLCB communication
 Author-email: "Stewart Watkiss (penguintutor)" <5587863+penguintutor@users.noreply.github.com>
 License: MIT License
@@ -35,30 +35,41 @@ License-File: LICENSE
 Requires-Dist: pyserial>=3.4
 Dynamic: license-file
 
-# PyVLCB Python Software Library for CBUS / VLCB
+# PyVLCB Python Software Library for VLCB
 
-This is a small software library for CBUS and VLCB using Python. 
+This is a Python library for VLCB (Versatile Layout Control Bus). It implements the core 
+communication protocols defined by the CBUS® protocol and includes extensions for the newer 
+VLCB specifications.
 
-It's designed for use with the MERG CANUSB4 CBUS adapter. 
+It is designed for use with the MERG CANUSB4 CBUS adapter and other compatible hardware.
 
+---
 
 ## Install
 
 
 For most systems including a Raspberry Pi then Python is managed using virtual environment.
-To setup a virtual environment enter the following commands
 
-    mkdir ~/venv
-    python3 -m venv ~/venv/pyvlcb --system-site-packages
+**Setup a virtual environment:**
 
-You will then need to run the following command to activate the virtual environment
+```bash
+mkdir ~/venv
+python3 -m venv ~/venv/pyvlcb --system-site-packages
+```
 
-    source ~/venv/pyvlcb/bin/activate
+**Activate the virtual environment:**
+
+```bash
+source ~/venv/pyvlcb/bin/activate
+```
     
-To instally the latest release use
+**Install the latest release:**
 
-    pip install pyvlcb
+```bash
+pip install pyvlcb
+```
 
+---
 
 ## Development 
 
@@ -69,12 +80,14 @@ The latest source code is available from GitHub. [PyVLCB on GitHub](https://gith
 
 To install the library, as a submodule in your own git project repository, then enter your project directory and run:
 
-    git submodule add https://github.com/penguintutor/pyvlcb.git lib/pyvlcb
-    pip install lib/pyvlcb
+```bash
+git submodule add https://github.com/penguintutor/pyvlcb.git lib/pyvlcb
+pip install lib/pyvlcb
+```
 
-If you subsequently want to get the latest version of the library run a git pull then use the pip install command again. 
+*Note: To use as a submodule, you must create your own git project first and install within the project folder. To update, run `git pull` and repeat the pip install command.*
 
-_Important_ To use as a submodule you must create your own git project first and install within the project folder.
+---
 
 ## Library Reference 
 
@@ -84,12 +97,21 @@ See the link below for the library reference documentation
 
 ## Demo examples 
 
-Example code is stored within the demo folder available from GitHub. Copy these into your project folder to test the library and connectivity. 
-The demos are created for a Raspberry Pi or other Linux computer. The USB port is hard-coded as /dev/ttyACM0
-For other computers / USB ports then edit the python file directory and update the port statement.
+Example code is stored within the demo folder available on GitHub. Copy these into your project folder to test the library and connectivity.
+
+* The demos are created for a Raspberry Pi or other Linux computers.
+* The USB port is hard-coded as /dev/ttyACM0.
+* For other computers or USB ports, edit the Python file and update the port statement.Example code is stored within the demo folder available from GitHub. Copy these into your project folder to test the library and connectivity. 
 
 ## More Details
 
-For more details see: [PenguinTutor PyVLCB library page](https://www.penguintutor.com/projects/pyvlcb)
+* Project page: [PenguinTutor PyVLCB library page](https://www.penguintutor.com/projects/pyvlcb)
+* Application example: [PenguinTutor Pi SignalBox project page](https://www.penguintutor.com/projects/pisignalbox)
+
+## Legal and Trademarks
+
+* **CBUS®** is a registered trademark of Dr. Michael Bolton. 
+* This library is an independent implementation based on publicly available protocol documentation and is not officially affiliated with or endorsed by the trademark holder.
+* All other trademarks are the property of their respective owners.
+
 
-For an example of a program using this library see the [PenguinTutor Pi SignalBox project page](https://www.penguintutor.com/projects/pisignalbox)

pyvlcb-0.1.3/README.md

@@ -0,0 +1,80 @@
+# PyVLCB Python Software Library for VLCB
+
+This is a Python library for VLCB (Versatile Layout Control Bus). It implements the core 
+communication protocols defined by the CBUS® protocol and includes extensions for the newer 
+VLCB specifications.
+
+It is designed for use with the MERG CANUSB4 CBUS adapter and other compatible hardware.
+
+---
+
+## Install
+
+
+For most systems including a Raspberry Pi then Python is managed using virtual environment.
+
+**Setup a virtual environment:**
+
+```bash
+mkdir ~/venv
+python3 -m venv ~/venv/pyvlcb --system-site-packages
+```
+
+**Activate the virtual environment:**
+
+```bash
+source ~/venv/pyvlcb/bin/activate
+```
+    
+**Install the latest release:**
+
+```bash
+pip install pyvlcb
+```
+
+---
+
+## Development 
+
+The latest source code is available from GitHub. [PyVLCB on GitHub](https://github.com/penguintutor/pyvlcb).
+
+
+### Installing as a git submodule
+
+To install the library, as a submodule in your own git project repository, then enter your project directory and run:
+
+```bash
+git submodule add https://github.com/penguintutor/pyvlcb.git lib/pyvlcb
+pip install lib/pyvlcb
+```
+
+*Note: To use as a submodule, you must create your own git project first and install within the project folder. To update, run `git pull` and repeat the pip install command.*
+
+---
+
+## Library Reference 
+
+See the link below for the library reference documentation
+[PyVLCB Library Reference Documentation](https://penguintutor.github.io/pyvlcb/reference/)
+
+
+## Demo examples 
+
+Example code is stored within the demo folder available on GitHub. Copy these into your project folder to test the library and connectivity.
+
+* The demos are created for a Raspberry Pi or other Linux computers.
+* The USB port is hard-coded as /dev/ttyACM0.
+* For other computers or USB ports, edit the Python file and update the port statement.Example code is stored within the demo folder available from GitHub. Copy these into your project folder to test the library and connectivity. 
+
+## More Details
+
+* Project page: [PenguinTutor PyVLCB library page](https://www.penguintutor.com/projects/pyvlcb)
+* Application example: [PenguinTutor Pi SignalBox project page](https://www.penguintutor.com/projects/pisignalbox)
+
+## Legal and Trademarks
+
+* **CBUS®** is a registered trademark of Dr. Michael Bolton. 
+* This library is an independent implementation based on publicly available protocol documentation and is not officially affiliated with or endorsed by the trademark holder.
+* All other trademarks are the property of their respective owners.
+
+

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyVLCB"
-version = "0.1.1"
+version = "0.1.3"
 description = "A library for CBUS / VLCB communication"
 readme = {file="README.md",  content-type = "text/markdown"} 
 requires-python = ">=3.6"

{pyvlcb-0.1.1 → pyvlcb-0.1.3/src/PyVLCB.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyVLCB
-Version: 0.1.1
+Version: 0.1.3
 Summary: A library for CBUS / VLCB communication
 Author-email: "Stewart Watkiss (penguintutor)" <5587863+penguintutor@users.noreply.github.com>
 License: MIT License
@@ -35,30 +35,41 @@ License-File: LICENSE
 Requires-Dist: pyserial>=3.4
 Dynamic: license-file
 
-# PyVLCB Python Software Library for CBUS / VLCB
+# PyVLCB Python Software Library for VLCB
 
-This is a small software library for CBUS and VLCB using Python. 
+This is a Python library for VLCB (Versatile Layout Control Bus). It implements the core 
+communication protocols defined by the CBUS® protocol and includes extensions for the newer 
+VLCB specifications.
 
-It's designed for use with the MERG CANUSB4 CBUS adapter. 
+It is designed for use with the MERG CANUSB4 CBUS adapter and other compatible hardware.
 
+---
 
 ## Install
 
 
 For most systems including a Raspberry Pi then Python is managed using virtual environment.
-To setup a virtual environment enter the following commands
 
-    mkdir ~/venv
-    python3 -m venv ~/venv/pyvlcb --system-site-packages
+**Setup a virtual environment:**
 
-You will then need to run the following command to activate the virtual environment
+```bash
+mkdir ~/venv
+python3 -m venv ~/venv/pyvlcb --system-site-packages
+```
 
-    source ~/venv/pyvlcb/bin/activate
+**Activate the virtual environment:**
+
+```bash
+source ~/venv/pyvlcb/bin/activate
+```
     
-To instally the latest release use
+**Install the latest release:**
 
-    pip install pyvlcb
+```bash
+pip install pyvlcb
+```
 
+---
 
 ## Development 
 
@@ -69,12 +80,14 @@ The latest source code is available from GitHub. [PyVLCB on GitHub](https://gith
 
 To install the library, as a submodule in your own git project repository, then enter your project directory and run:
 
-    git submodule add https://github.com/penguintutor/pyvlcb.git lib/pyvlcb
-    pip install lib/pyvlcb
+```bash
+git submodule add https://github.com/penguintutor/pyvlcb.git lib/pyvlcb
+pip install lib/pyvlcb
+```
 
-If you subsequently want to get the latest version of the library run a git pull then use the pip install command again. 
+*Note: To use as a submodule, you must create your own git project first and install within the project folder. To update, run `git pull` and repeat the pip install command.*
 
-_Important_ To use as a submodule you must create your own git project first and install within the project folder.
+---
 
 ## Library Reference 
 
@@ -84,12 +97,21 @@ See the link below for the library reference documentation
 
 ## Demo examples 
 
-Example code is stored within the demo folder available from GitHub. Copy these into your project folder to test the library and connectivity. 
-The demos are created for a Raspberry Pi or other Linux computer. The USB port is hard-coded as /dev/ttyACM0
-For other computers / USB ports then edit the python file directory and update the port statement.
+Example code is stored within the demo folder available on GitHub. Copy these into your project folder to test the library and connectivity.
+
+* The demos are created for a Raspberry Pi or other Linux computers.
+* The USB port is hard-coded as /dev/ttyACM0.
+* For other computers or USB ports, edit the Python file and update the port statement.Example code is stored within the demo folder available from GitHub. Copy these into your project folder to test the library and connectivity. 
 
 ## More Details
 
-For more details see: [PenguinTutor PyVLCB library page](https://www.penguintutor.com/projects/pyvlcb)
+* Project page: [PenguinTutor PyVLCB library page](https://www.penguintutor.com/projects/pyvlcb)
+* Application example: [PenguinTutor Pi SignalBox project page](https://www.penguintutor.com/projects/pisignalbox)
+
+## Legal and Trademarks
+
+* **CBUS®** is a registered trademark of Dr. Michael Bolton. 
+* This library is an independent implementation based on publicly available protocol documentation and is not officially affiliated with or endorsed by the trademark holder.
+* All other trademarks are the property of their respective owners.
+
 
-For an example of a program using this library see the [PenguinTutor Pi SignalBox project page](https://www.penguintutor.com/projects/pisignalbox)

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/PyVLCB.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/PyVLCB.egg-info/top_level.txt
 src/pyvlcb/__init__.py
 src/pyvlcb/canusb.py
 src/pyvlcb/exceptions.py
+src/pyvlcb/utils.py
 src/pyvlcb/vlcbformat.py
 src/pyvlcb/tests/run_tests.py
 src/pyvlcb/tests/test_canusb4.py

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/pyvlcb/__init__.py

@@ -3,6 +3,7 @@
 
 from .vlcbformat import VLCBFormat, VLCBOpcode
 from .canusb import CanUSB4
+from .utils import num_to_1hexstr, num_to_2hexstr, num_to_4hexstr, f_to_bytes, dict_to_string
 from .exceptions import (
     MyLibraryError, 
     DeviceConnectionError, 
@@ -122,162 +123,17 @@ class VLCB:
         opcode = vlcb_entry.data[0:2]
         opcode_string = f'{opcode} - {VLCBOpcode.opcode_mnemonic(opcode)}'
         #data_string = f"{VLCBOpcode.parse_data(vlcb_entry.data)}"
-        data_string = VLCB._dict_to_string(VLCBOpcode.parse_data(vlcb_entry.data))
+        data_string = dict_to_string(VLCBOpcode.parse_data(vlcb_entry.data))
         return [date_string, direction, message, str(vlcb_entry.can_id), opcode_string, data_string]
         # Todo - error handling 
     
-    # dict to string without {} or ""
-    @staticmethod
-    def _dict_to_string (dictionary: dict) -> str:
-        """ Convert a dict to a string without {} or quotes """
-        data_string = ""
-        for key, value in dictionary.items():
-            if data_string != "":
-                data_string += " , "
-            data_string += f"{key} = {value}"
-        return data_string
-    
-    @staticmethod
-    def f_to_bytes (f_num: int, function_status: List[int]) -> Tuple[bytes, bytes]:
-        """ Convert a Fnumber (Loco function ID) to bytes
-
-        Can be used to create correct format for loco_set_dfun
-        Limited to range 0 to 28 - which is max for DFUN
-        Higher would need to use DFNON/DFOFF
-
-        Args:
-            f_num: Function number
-            function_status: List with value of all functions (must be updated before calling)
-            
-        Returns:
-            Tuple of two bytes
-            
-        Raises: ValueError
-
-        """
-        # Must be an F number between 0 and 28
-        if f_num < 0 or f_num > 28:
-            raise ValueError (f"Fnumber needs to be between 0 and 28. Number provided {f_num}")
-        
-        # Extend function_status to 29 entries
-        function_list = function_status + [0] * (29 - len(function_status))
-
-        if f_num <= 4:
-            byte1 = 1
-            byte2 = (0b10000 * function_list[0] +  # fn0 is higher nibble (bit 5)
-                     0b0001 * function_list[1] +
-                     0b0010 * function_list[2] +
-                     0b0100 * function_list[3] +
-                     0b1000 * function_list[4]
-                     )
-        elif f_num <= 8:
-            byte1 = 2
-            byte2 = (0b0001 * function_list[5] +
-                     0b0010 * function_list[6] +
-                     0b0100 * function_list[7] +
-                     0b1000 * function_list[8]
-                     )
-        elif f_num <= 12:
-            byte1 = 3
-            byte2 = (0b0001 * function_list[9] +
-                     0b0010 * function_list[10] +
-                     0b0100 * function_list[11] +
-                     0b1000 * function_list[12]
-                     )
-        elif f_num <= 20:
-            byte1 = 4
-            byte2 = (0b0001 * function_list[13] +
-                     0b0010 * function_list[14] +
-                     0b0100 * function_list[15] +
-                     0b1000 * function_list[16] +
-                     0b10000 * function_list[17] +
-                     0b100000 * function_list[18] +
-                     0b1000000 * function_list[19] +
-                     0b10000000 * function_list[20]
-                     )
-        elif f_num <= 28:
-            byte1 = 5
-            byte2 = (0b0001 * function_list[21] +
-                     0b0010 * function_list[22] +
-                     0b0100 * function_list[23] +
-                     0b1000 * function_list[24] +
-                     0b10000 * function_list[25] +
-                     0b100000 * function_list[26] +
-                     0b1000000 * function_list[27] +
-                     0b10000000 * function_list[28]
-                     )
-        return (byte1, byte2)
         
+    # Static Methods moved to utils
+    #num_to_1hexstr = staticmethod(num_to_1hexstr)
+    #num_to_2hexstr = staticmethod(num_to_2hexstr)
+    #num_to_4hexstr = staticmethod(num_to_4hexstr)
     
-    @staticmethod
-    # Where 1 x bytes (2 chars)
-    def num_to_1hexstr (num: int) -> str:
-        """Convert number to a byte
-
-        Args:
-            num (int): Number to convert
-
-        Returns:
-            String: A hex representation of the number (2 chars)
-        """
-        return f"{hex(num).upper()[2:]:0>2}"
-    
-    @staticmethod
-    # Where 2 x bytes (4 chars)
-    def num_to_2hexstr (num: int) -> str:
-        """Convert number to 2 bytes
-
-        Args:
-            num (int): Number to convert
-
-        Returns:
-            String: A hex representation of the number (4 chars)
-        """
-        return f"{hex(num).upper()[2:]:0>4}"
-    
-    @staticmethod
-    # Where 4 x bytes (8 chars)
-    def num_to_4hexstr (num: int) -> str:
-        """Convert number to 4 bytes
-
-        Args:
-            num (int): Number to convert
-
-        Returns:
-            String: A hex representation of the number (8 chars)
-        """
-        return f"{hex(num).upper()[2:]:0>8}"
-    
-    @staticmethod
-    # Where 2 bytes convert to addr id
-    def bytes_to_addr (byte1: bytes, byte2: bytes) -> int:
-        """Convert 2 byte values into an address id sring
-
-        Args:
-            byte1 (bytes): Most significant byte
-            byte2 (bytes): Least significant byte
-
-        Returns:
-            Int: The address id value
-        """
-        msb = int(byte1)
-        lsb = int(byte2)
-        return ((msb << 8) + lsb)
-    
-    @staticmethod
-    def bytes_to_hexstr (byte1: bytes, byte2: bytes) -> str:
-        """Convert 2 bytes to a hex string
-
-        Args:
-            byte1 (bytes): Most significant byte
-            byte2 (bytes): Least significant byte
 
-        Returns:
-            String: A hex representation of the number
-        """
-        return f"{hex(byte1).upper()[2:]:0>2}{hex(byte2).upper()[2:]:0>2}"
-        
-    
     # Create header using low priority and can_id (or self.can_id)
     # If opcode provided, but no priority then appropriate min code looked up
     # MajPri would be based on packet aging - needs to be managed outside of this
@@ -312,6 +168,7 @@ class VLCB:
         return header_string
         #return header_string.encode('utf-8')
     
+    
     # Discover nodes
     def discover (self) -> str:
         """Create a discovery string 
@@ -336,7 +193,7 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='58')}58{VLCB.num_to_2hexstr(node_id)};" 
+        return f"{self.make_header(opcode='58')}58{num_to_2hexstr(node_id)};" 
         
     # Discover number of events available
     def discover_nevn (self, node_id: int) -> str:
@@ -350,7 +207,7 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='56')}56{VLCB.num_to_2hexstr(node_id)};"
+        return f"{self.make_header(opcode='56')}56{num_to_2hexstr(node_id)};"
     
     # Discover stored events NERD
     def discover_nerd (self, node_id: int) -> str:
@@ -364,7 +221,7 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='57')}57{VLCB.num_to_2hexstr(node_id)};"
+        return f"{self.make_header(opcode='57')}57{num_to_2hexstr(node_id)};"
     
     # Emergency stop all locos
     # RESTP
@@ -419,10 +276,10 @@ class VLCB:
         # Turn on
         if state == True or state == "on":
             # ASON
-            return f"{self.make_header(opcode='98')}98{VLCB.num_to_2hexstr(node_id)}{VLCB.num_to_2hexstr(ev_id)};"
+            return f"{self.make_header(opcode='98')}98{num_to_2hexstr(node_id)}{num_to_2hexstr(ev_id)};"
         # Turn off = ASOFF
         else:
-            return f"{self.make_header(opcode='99')}99{VLCB.num_to_2hexstr(node_id)}{VLCB.num_to_2hexstr(ev_id)};"
+            return f"{self.make_header(opcode='99')}99{num_to_2hexstr(node_id)}{num_to_2hexstr(ev_id)};"
         
     def accessory_long_command (self, node_id: int, ev_id: int, state: Union[str, bool]) -> str:
         """Create an accessory long command
@@ -440,10 +297,10 @@ class VLCB:
         # Turn on
         if state == True or state == "on":
             # ASON
-            return f"{self.make_header(opcode='90')}90{VLCB.num_to_4hexstr(ev_id)};"
+            return f"{self.make_header(opcode='90')}90{num_to_4hexstr(ev_id)};"
         # Turn off = ASOFF
         else:
-            return f"{self.make_header(opcode='91')}91{VLCB.num_to_4hexstr(ev_id)};"
+            return f"{self.make_header(opcode='91')}91{num_to_4hexstr(ev_id)};"
         
     # RLOC (Allocate loco) :SB040N40D446;
     # Short address upper address all zeros, only 6 bits of the lower byte are used (1 to 127) 0 is decoderless
@@ -468,7 +325,7 @@ class VLCB:
             raise ValueError ("Invalid short code. Loco ID {loco_id} is larger than 127")
         if long == True:
             loco_id = loco_id | 0xC000
-        return f"{self.make_header(opcode='40')}40{VLCB.num_to_2hexstr(loco_id)};"
+        return f"{self.make_header(opcode='40')}40{num_to_2hexstr(loco_id)};"
     
     def release_loco (self, session_id: int) -> str:
         """Create a release loco request
@@ -481,7 +338,7 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='21')}21{VLCB.num_to_1hexstr(session_id)};"
+        return f"{self.make_header(opcode='21')}21{num_to_1hexstr(session_id)};"
     
     def steal_loco (self, loco_id: int, long: Optional[bool] = True) -> str:
         """Create an steal loco request
@@ -504,7 +361,7 @@ class VLCB:
             raise InvalidLocoError(f"Invalid short code {loco_id}")
         if long == True:
             loco_id = loco_id | 0xC000
-        return f"{self.make_header(opcode='61')}61{VLCB.num_to_2hexstr(loco_id)}01;"   
+        return f"{self.make_header(opcode='61')}61{num_to_2hexstr(loco_id)}01;"   
         
     def share_loco (self, loco_id: int, long: Optional[bool] = True) -> str:
         """Create an share loco request
@@ -527,7 +384,7 @@ class VLCB:
             raise InvalidLocoError(f"Invalid short code {loco_id}")
         if long == True:
             loco_id = loco_id | 0xC000
-        return f"{self.make_header(opcode='61')}61{VLCB.num_to_2hexstr(loco_id)}02;" 
+        return f"{self.make_header(opcode='61')}61{num_to_2hexstr(loco_id)}02;" 
         
     def keep_alive (self, session_id: int) -> str:
         """Create an keep alive request
@@ -541,14 +398,44 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='23')}23{VLCB.num_to_1hexstr(session_id)};"
+        return f"{self.make_header(opcode='23')}23{num_to_1hexstr(session_id)};"
+    
+    def loco_speed_dir (self, session_id: int, speed: int, direction: int) -> str:
+        """Set loco speed and direction based on separate arguments
+
+        Same as loco_speeddir but this takes 2 arguments, whereas loco_speeddir needs a combined value
+        Maximum call this once every 32 milliseconds
+
+        Uses DSPD (47)
+
+        Args:
+            session_id: Session ID
+            speed: 0 to 127 (1 is increased to 2 to avoid emergency stop)
+            direction: 1 = forward, 0 = reverse
+
+        Returns:
+            String: A string for the request
+            
+        Raises:
+            ValueError is speed is out of range, or invalid direction
+        """
+        if speed < 0 or speed > 127:
+            raise ValueError ("Invalid speed specified. Must be in range 0 to 127")
+        if direction <0 or direction > 1:
+            raise ValueError ("Direction is not valid. Use 1 for forward, 0 for reverse")
+        # special case - ignore emergency stop
+        if speed == 1:
+            speed = 2
+        speeddir = (direction * 0x80) + speed
+        return self.loco_speeddir (session_id, speeddir)
     
     # Set loco speed and direction (always done together)
-    # Maximum once every 32 miliseconds (GUI configured based on non triggered so shouldn't be an issue)
-    # Could add time detection if required
-    # This uses the combined speed and direction value
     def loco_speeddir (self, session_id: int, speeddir: int) -> str:
-        """Create a combined set speed and direction event
+        """Set loco speed and direction
+
+        Maximum call this once every 32 milliseconds
+        Needs combined speed and direction value.
+        If speed is set to 1 then that is considered an emergency stop
 
         Uses DSPD (47)
 
@@ -559,7 +446,7 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='47')}47{VLCB.num_to_1hexstr(session_id)}{VLCB.num_to_1hexstr(speeddir)};"
+        return f"{self.make_header(opcode='47')}47{num_to_1hexstr(session_id)}{num_to_1hexstr(speeddir)};"
     
     # Set function using DFUN - needs to be provided with the two bytes
     # First byte is group (1 = F1 to F4, 2 = F5 to F8, 3 = F9 to F12)
@@ -579,6 +466,29 @@ class VLCB:
         Returns:
             String: A string for the request
         """
-        return f"{self.make_header(opcode='60')}60{VLCB.num_to_1hexstr(session_id)}{VLCB.num_to_1hexstr(byte1)}{VLCB.num_to_1hexstr(byte2)};"
-        
+        return f"{self.make_header(opcode='60')}60{num_to_1hexstr(session_id)}{num_to_1hexstr(byte1)}{num_to_1hexstr(byte2)};"
     
+    def loco_set_function (self, session_id: int, function_num, function_list) -> str:
+        """Create a set function request using the function list
+        Sends the entire group of functions where the function_num resides
+        This is an alternative to loco_set_dfun as this calculates the bytes
+        this method can only be used for functions 0 to 27
+
+        Uses DFUN (60)
+
+        Args:
+            session_id: Session ID
+            byte1: Function number
+            byte2: List of current function statuses
+
+        Returns:
+            String: A string for the request
+            
+        Raises:
+            ValueError: Typically raised from f_to_bytes
+        """
+        byte1_2 = f_to_bytes(function_num, function_list)
+        return f"{self.make_header(opcode='60')}60{num_to_1hexstr(session_id)}{byte1_2[0]}{byte1_2[1]};"
+        
+
+    

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/pyvlcb/canusb.py

@@ -22,7 +22,8 @@ class CanUSB4 ():
     def __init__ (self, 
                   port: str, 
                   baud: Optional[int] = 115200, 
-                  timeout: Optional[float] = 0.01) -> None:
+                  timeout: Optional[float] = 0.01,
+                  exclusive: Optional[bool] = True) -> None:
         """Inits CanUSB4 with a USB port
         
         Args:
@@ -41,6 +42,10 @@ class CanUSB4 ():
         self.timeout = timeout
         self.max_retry = 30    # How many times to attempt on get_data must be at least as long as frame
         # Timeout for a request could be max_rety x timeout
+        self.exclusive = exclusive	# Exclusive determines if check for exclusive use of the USB port
+        # If this is set to false then if another application is already using the port then the application
+        # will run, but appear to hang if there is no response because another thread has already
+        # taken the incoming data
         
         if not port:
             raise InvalidConfigurationError("Port name cannot be empty")
@@ -53,7 +58,11 @@ class CanUSB4 ():
         
         
     # Optional arguments override existing
-    def connect(self, port=None, baud=None, timeout=None):
+    def connect(self,
+                port: Optional[str] = None,
+                baud: Optional[int] = None,
+                timeout: Optional[float] = None,
+                exclusive: Optional[bool] = None) -> None:
         """Inits CanUSB4 with a USB port
         
         Args:
@@ -74,8 +83,15 @@ class CanUSB4 ():
             self.baud = baud
         if timeout != None:
             self.timeout = timeout
+        if exclusive != None:
+            self.exclusive = exclusive
         try:
-            self.ser = serial.Serial(self.port, self.baud, timeout=self.timeout)
+            self.ser = serial.Serial(
+                self.port,
+                self.baud,
+                timeout=self.timeout,
+                exclusive = exclusive
+                )
         except serial.SerialException as e:
             raise DeviceConnectionError(f"Could not open port {self.port}") from e
         if self.ser:

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/pyvlcb/exceptions.py

@@ -55,5 +55,14 @@ class InvalidLocoError(MyLibraryError):
     Raised for an invalid loco definition
     Includes if the ID is out of range
     or short code specified but code needs long code
+    or if the packet does not contain a loco_id (eg. certain Err codes)
+    """
+    pass
+
+class InvalidFunctionError(MyLibraryError):
+    """
+    Raised for an invalid function requests
+    For example asking for function information
+    from a response which doesn't include the function information.
     """
     pass

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/pyvlcb/tests/test_canusb4.py

@@ -34,7 +34,7 @@ class TestCanUSB4(unittest.TestCase):
     def test_init_valid(self):
         """Test that initialization opens the serial port with correct settings."""
         # Check if serial.Serial was called with correct args
-        self.mock_serial_class.assert_called_with(self.port, 115200, timeout=0.01)
+        self.mock_serial_class.assert_called_with(self.port, 115200, timeout=0.01, exclusive=None)
 
     def test_init_empty_port(self):
         """Test that empty port raises InvalidConfigurationError."""

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/pyvlcb/tests/test_vlcb.py

@@ -1,6 +1,8 @@
 import unittest
 from typing import Optional
 from pyvlcb import VLCB
+# Import utils
+from pyvlcb import num_to_1hexstr, num_to_2hexstr, num_to_4hexstr, f_to_bytes
 from pyvlcb.vlcbformat import VLCBFormat
 
 class TestVLCB(unittest.TestCase):
@@ -13,14 +15,14 @@ class TestVLCB(unittest.TestCase):
     def test_num_to_hex_conversions(self):
         """Test that numbers are correctly padded and converted to hex strings."""
         # Test 1 byte (2 chars)
-        self.assertEqual(VLCB.num_to_1hexstr(10), "0A")
-        self.assertEqual(VLCB.num_to_1hexstr(255), "FF")
+        self.assertEqual(num_to_1hexstr(10), "0A")
+        self.assertEqual(num_to_1hexstr(255), "FF")
         
         # Test 2 bytes (4 chars)
-        self.assertEqual(VLCB.num_to_2hexstr(10), "000A")
+        self.assertEqual(num_to_2hexstr(10), "000A")
         
         # Test 4 bytes (8 chars)
-        self.assertEqual(VLCB.num_to_4hexstr(10), "0000000A")
+        self.assertEqual(num_to_4hexstr(10), "0000000A")
 
     ## Tests for Packet Parsing
     def test_parse_input_valid_1(self):
@@ -86,10 +88,10 @@ class TestVLCB(unittest.TestCase):
     #f_to_bytes (f_num: int, function_status: List[int]) -> Tuple[bytes, bytes]
     def test_f_to_bytes(self):
         functions = [1, 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 1]
-        self.assertEqual(self.vlcb.f_to_bytes (1, functions), (1, 25))
-        self.assertEqual(self.vlcb.f_to_bytes (2, functions), (1, 25))
-        self.assertEqual(self.vlcb.f_to_bytes (7, functions), (2, 6))
-        self.assertEqual(self.vlcb.f_to_bytes (24, functions), (5, 0))
+        self.assertEqual(f_to_bytes (1, functions), ("01", "19"))
+        self.assertEqual(f_to_bytes (2, functions), ("01", "19"))
+        self.assertEqual(f_to_bytes (7, functions), ("02", "06"))
+        self.assertEqual(f_to_bytes (24, functions), ("05", "00"))
 
 
 if __name__ == "__main__":

pyvlcb-0.1.3/src/pyvlcb/utils.py

@@ -0,0 +1,180 @@
+""" Utils for use by other parts of the library """
+
+from typing import Optional, Union, Tuple, List
+
+# Where 1 x bytes (2 chars)
+def num_to_1hexstr (num: int) -> str:
+    """Convert number to a byte
+
+    Args:
+        num (int): Number to convert
+
+    Returns:
+        String: A hex representation of the number (2 chars)
+    """
+    return f"{hex(num).upper()[2:]:0>2}"
+
+# Where 2 x bytes (4 chars)
+def num_to_2hexstr (num: int) -> str:
+    """Convert number to 2 bytes
+
+    Args:
+        num (int): Number to convert
+
+    Returns:
+        String: A hex representation of the number (4 chars)
+    """
+    return f"{hex(num).upper()[2:]:0>4}"
+
+# Where 4 x bytes (8 chars)
+def num_to_4hexstr (num: int) -> str:
+    """Convert number to 4 bytes
+
+    Args:
+        num (int): Number to convert
+
+    Returns:
+        String: A hex representation of the number (8 chars)
+    """
+    return f"{hex(num).upper()[2:]:0>8}"
+
+
+# dict to string without {} or ""
+def dict_to_string (dictionary: dict) -> str:
+    """ Convert a dict to a string without {} or quotes """
+    data_string = ""
+    for key, value in dictionary.items():
+        if data_string != "":
+            data_string += " , "
+        data_string += f"{key} = {value}"
+    return data_string
+
+def f_to_bytes (f_num: int, function_status: List[int]) -> Tuple[str, str]:
+    """ Convert a Fnumber (Loco function ID) to bytes as string representation
+
+    Can be used to create correct format for loco_set_dfun
+    Limited to range 0 to 28 - which is max for DFUN
+    Higher would need to use DFNON/DFOFF
+
+    Args:
+        f_num: Function number
+        function_status: List with value of all functions (must be updated before calling)
+        
+    Returns:
+        Tuple of two x 2-characer strings representing the bytes
+        
+    Raises: ValueError
+
+    """
+    # Must be an F number between 0 and 28
+    if f_num < 0 or f_num > 28:
+        raise ValueError (f"Fnumber needs to be between 0 and 28. Number provided {f_num}")
+    
+    # Extend function_status to 29 entries
+    function_list = function_status + [0] * (29 - len(function_status))
+
+    if f_num <= 4:
+        byte1 = 1
+        byte2 = (0b10000 * function_list[0] +  # fn0 is higher nibble (bit 5)
+                 0b0001 * function_list[1] +
+                 0b0010 * function_list[2] +
+                 0b0100 * function_list[3] +
+                 0b1000 * function_list[4]
+                 )
+    elif f_num <= 8:
+        byte1 = 2
+        byte2 = (0b0001 * function_list[5] +
+                 0b0010 * function_list[6] +
+                 0b0100 * function_list[7] +
+                 0b1000 * function_list[8]
+                 )
+    elif f_num <= 12:
+        byte1 = 3
+        byte2 = (0b0001 * function_list[9] +
+                 0b0010 * function_list[10] +
+                 0b0100 * function_list[11] +
+                 0b1000 * function_list[12]
+                 )
+    elif f_num <= 20:
+        byte1 = 4
+        byte2 = (0b0001 * function_list[13] +
+                 0b0010 * function_list[14] +
+                 0b0100 * function_list[15] +
+                 0b1000 * function_list[16] +
+                 0b10000 * function_list[17] +
+                 0b100000 * function_list[18] +
+                 0b1000000 * function_list[19] +
+                 0b10000000 * function_list[20]
+                 )
+    elif f_num <= 28:
+        byte1 = 5
+        byte2 = (0b0001 * function_list[21] +
+                 0b0010 * function_list[22] +
+                 0b0100 * function_list[23] +
+                 0b1000 * function_list[24] +
+                 0b10000 * function_list[25] +
+                 0b100000 * function_list[26] +
+                 0b1000000 * function_list[27] +
+                 0b10000000 * function_list[28]
+                 )
+    # convert to strings before returning
+    # and with 0xFF guarentees it doesn't overflow (although not really neccessary for this method)
+    str1 = f"{ (byte1 & 0xFF) :02x}"
+    str2 = f"{ (byte2 & 0xFF) :02x}"
+    return (str1, str2)
+
+
+# Where 2 bytes convert to addr id
+def bytes_to_addr (byte1: bytes, byte2: bytes) -> int:
+    """Convert 2 byte values into an address id sring
+
+    Args:
+        byte1 (bytes): Most significant byte
+        byte2 (bytes): Least significant byte
+
+    Returns:
+        Int: The address id value
+    """
+    msb = int(byte1)
+    lsb = int(byte2)
+    return ((msb << 8) + lsb)
+
+
+def bytes_to_hexstr (byte1: bytes, byte2: bytes) -> str:
+    """Convert 2 bytes to a hex string
+
+    Args:
+        byte1 (bytes): Most significant byte
+        byte2 (bytes): Least significant byte
+
+    Returns:
+        String: A hex representation of the number
+    """
+    return f"{hex(byte1).upper()[2:]:0>2}{hex(byte2).upper()[2:]:0>2}"
+    
+
+def bytes_to_functions (fn1: bytes, fn2: bytes, fn3: bytes) -> List[int]:
+    """ Sets the value of the functions from a PLOC message
+    Only returns values for F0 to F12 (others not included in PLOC)
+    Provides as a list for inclusion in menus etc.
+    
+    Args:
+        fn1: Function byte F0 to F4 - bit 5 = dir lighting (F0), bit 6 = direction, bit 7 = res, bit 8 = 0
+        fn2: Function byte F5 to F8 - bit 5 upwards reserved
+        fn3: Function byte F9 to F12
+        
+    Returns:
+        List of function values as 0 or 1 for each function as off and on
+    
+    """    
+    data_in = [fn1, fn2, fn3]
+    mask = [0b0001, 0b0010, 0b0100, 0b1000]
+    function_status = [0] * 29
+    # Handle 0 separately as it's in the upper nibble
+    function_status[0] = data_in[0] & 0b10000
+    # Create a list of 12 entries
+    for i in range (0, 3):
+        for j in range (0, 4):
+            function_status[(i*4)+j+1] = 1 if (data_in[i] & mask[j]) > 0 else 0
+            
+    return function_status

{pyvlcb-0.1.1 → pyvlcb-0.1.3}/src/pyvlcb/vlcbformat.py

@@ -1,5 +1,6 @@
 import logging
 import warnings
+from .utils import bytes_to_addr, bytes_to_functions
 from typing import List, Optional, Union, Dict, Any
 
 # Set up a null handler so nothing prints by default unless the user enables it
@@ -49,7 +50,18 @@ class VLCBFormat :
             return VLCBOpcode.opcodes[str_value]['opc']
         else:
             raise ValueError(f"Opcode {str_value} is not defined.")
-    
+
+    def get_data (self) -> OpcodeData:
+        """Returns the opcode associated with the data string as a dict
+
+        Returns:
+            OpcodeData: Dict from the VLCBOpcode
+
+        Raises:
+            ValueError: If opcode not found
+        """
+        return VLCBOpcode.parse_data(self.data)
+
     def format_data (self) -> OpcodeData:
         """Returns the opcode associated with the data string
 
@@ -60,7 +72,66 @@ class VLCBFormat :
             ValueError: If opcode not found
         """
         return VLCBOpcode.parse_data(self.data)
+    
+    def get_loco_id (self) -> int:
+        """Converts AddrHigh and AddrLow into a loco_id
+
+        Only valid with certain VLCBFormat packets associated with Locos.
+        If packet is does not contain the AddrHigh & AddrLow values (which
+        may be formatted differently) then raises a InvalidLocoError
         
+        Returns:
+            loco_id: Loco number
+            
+        Raises:
+            InvalidLocoError: If AddrHigh / AddrLow are not in the packet
+        """
+        loco_id = None
+        if self.opcode() == "PLOC":
+            # Get data
+            data_dict = VLCBOpcode.parse_data(self.data)
+            loco_id = data_dict['AddrHigh_AddrLow'] & 0x3FFF
+        elif self.opcode() == "ERR":
+            # also check it's one of the Error codes associated with allocate loco etc.
+            # 1 = loco stack full 2 = loco taken, 7 = invalid request
+            # The following are not supported as data bytes contain session / consist ID and not loco_id
+            # 3 = no session, 4 consist empty, 5 loco not found, 6 can bus error
+            data_dict = VLCBOpcode.parse_data(self.data)
+            if data_dict["ErrCode"] in [1, 2, 7]:
+                loco_id = bytes_to_addr(data_dict['Byte1'],data_dict['Byte2']) & 0x3FFF
+            else:
+                raise InvalidLocoError (f"Error code {data_dict['ErrCode']} does not contain a loco_id")
+            
+        # If loco_id not updated then raise error
+        if loco_id != None:
+            return loco_id
+        else:
+            raise InvalidLocoError(f"Opcode {self.opcode()} does not contain a loco_id")
+
+    def get_function_list (self) -> List[int]:
+        """Where packet contains Fn1, Fn2, Fn3 (eg. PLOC)
+        returns 
+
+        Only valid with certain VLCBFormat packets associated with Locos.
+        If packet is does not contain the 3 byte values (which
+        may be formatted differently) then raises a InvalidFunctionError
+        
+        Returns:
+            List of function values as 0 or 1 for each function as off and on
+            
+        Raises:
+            InvalidFunctionError: If Function Bytes are not in the packet
+        """
+        if self.opcode() == "PLOC":
+            # Get data
+            data_dict = VLCBOpcode.parse_data(self.data)
+            return bytes_to_functions (data_dict['Fn1'], data_dict['Fn2'], data_dict['Fn3'])
+        else:
+            raise InvalidLocoError(f"Opcode {self.opcode()} does not contain a loco_id")
+
+
+
+
     def __str__ (self):
         return f'{self.priority} : {self.can_id} : {self.opcode()} ({self.data[0:2]}) : {self.data} / {self.format_data()}'
 

pyvlcb-0.1.1/README.md

@@ -1,58 +0,0 @@
-# PyVLCB Python Software Library for CBUS / VLCB
-
-This is a small software library for CBUS and VLCB using Python. 
-
-It's designed for use with the MERG CANUSB4 CBUS adapter. 
-
-
-## Install
-
-
-For most systems including a Raspberry Pi then Python is managed using virtual environment.
-To setup a virtual environment enter the following commands
-
-    mkdir ~/venv
-    python3 -m venv ~/venv/pyvlcb --system-site-packages
-
-You will then need to run the following command to activate the virtual environment
-
-    source ~/venv/pyvlcb/bin/activate
-    
-To instally the latest release use
-
-    pip install pyvlcb
-
-
-## Development 
-
-The latest source code is available from GitHub. [PyVLCB on GitHub](https://github.com/penguintutor/pyvlcb).
-
-
-### Installing as a git submodule
-
-To install the library, as a submodule in your own git project repository, then enter your project directory and run:
-
-    git submodule add https://github.com/penguintutor/pyvlcb.git lib/pyvlcb
-    pip install lib/pyvlcb
-
-If you subsequently want to get the latest version of the library run a git pull then use the pip install command again. 
-
-_Important_ To use as a submodule you must create your own git project first and install within the project folder.
-
-## Library Reference 
-
-See the link below for the library reference documentation
-[PyVLCB Library Reference Documentation](https://penguintutor.github.io/pyvlcb/reference/)
-
-
-## Demo examples 
-
-Example code is stored within the demo folder available from GitHub. Copy these into your project folder to test the library and connectivity. 
-The demos are created for a Raspberry Pi or other Linux computer. The USB port is hard-coded as /dev/ttyACM0
-For other computers / USB ports then edit the python file directory and update the port statement.
-
-## More Details
-
-For more details see: [PenguinTutor PyVLCB library page](https://www.penguintutor.com/projects/pyvlcb)
-
-For an example of a program using this library see the [PenguinTutor Pi SignalBox project page](https://www.penguintutor.com/projects/pisignalbox)