pymeu 0.0.1__tar.gz

pymeu-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 aawilliams85
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymeu-0.0.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.1
+Name: pymeu
+Version: 0.0.1
+Summary: Python ME Utility
+Author-email: aawilliams85 <adair.williams85@gmail.com>
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pycomm3
+
+# pymeu
+
+PyMEU (Python ME Utility) is a set of helper functions built around pycomm3 to interface with Rockwell Automation PanelView Plus 6/7 HMIs.<br>
+
+The current release has only been tested on a very limited selection of hardware.  It is alpha quality at best and could easily brick your device.  Use at your own risk.<br>
+
+## Example
+
+Use the download function to transfer a *.MER file to the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.download('C:\\YourFolder\\YourProgram.mer')
+```
+
+Use the upload function to transfer a *.MER file from the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.upload('C:\\YourFolder\\YourProgram.mer')
+```
+
+Use the upload all function to transfer all *.MER files from the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.upload_all('C:\\YourFolder')
+```
+
+Use the reboot function to restart the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.reboot()
+```

pymeu-0.0.1/README.md

@@ -0,0 +1,39 @@
+# pymeu
+
+PyMEU (Python ME Utility) is a set of helper functions built around pycomm3 to interface with Rockwell Automation PanelView Plus 6/7 HMIs.<br>
+
+The current release has only been tested on a very limited selection of hardware.  It is alpha quality at best and could easily brick your device.  Use at your own risk.<br>
+
+## Example
+
+Use the download function to transfer a *.MER file to the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.download('C:\\YourFolder\\YourProgram.mer')
+```
+
+Use the upload function to transfer a *.MER file from the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.upload('C:\\YourFolder\\YourProgram.mer')
+```
+
+Use the upload all function to transfer all *.MER files from the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.upload_all('C:\\YourFolder')
+```
+
+Use the reboot function to restart the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.reboot()
+```

pymeu-0.0.1/pymeu/__init__.py

@@ -0,0 +1,4 @@
+from .main import MEUtility
+
+__version_info__ = (0, 0, 1)
+__version__ = '.'.join(str(x) for x in __version_info__)

pymeu-0.0.1/pymeu/constants.py

@@ -0,0 +1,32 @@
+CHUNK_SIZE = 1984
+
+HELPER_VERSIONS = {
+    '11.00.00'
+}
+
+ME_VERSIONS = {
+    '11.00.25.230'
+}
+
+PRODUCT_CODES = {
+    '102',
+    '51'
+}
+
+PRODUCT_TYPES = {
+    '24'
+}
+
+CREATE_DIR_SUCCESS = 183 # 'b\xb7'
+
+GET_UNK1_VALUES = {
+    b'\x02\x00'
+}
+
+GET_UNK2_VALUES = {
+    b'\x01\x60'
+}
+
+GET_UNK3_VALUES = {
+    b'\x64\x00'
+}

pymeu-0.0.1/pymeu/main.py

@@ -0,0 +1,294 @@
+import os
+import pycomm3
+
+from .types import *
+from .terminal import *
+
+class MEUtility(object):
+    def __init__(self, comms_path: str):
+        self.comms_path = comms_path
+
+    def __download_to_terminal(self, cip: pycomm3.CIPDriver, file: MEFile) -> bool:
+        # Create runtime folder
+        #
+        # TODO: Can we check if this already exists and skip?
+        if not(terminal_create_runtime_directory(cip, file)): raise Exception('Failed to create runtime path on terminal.')
+
+        # Get attributes
+        #
+        # Still no clue on what these are, or when/how they would change.
+        # If they aren't changed by creating paths, could be moved ahead
+        # to is_download_valid().
+        if not(terminal_is_get_unk_valid(cip)): raise Exception('Invalid response from an unknown attribute.  Check packets.')
+
+        # Create a file exchange on the terminal
+        file_instance = terminal_create_file_exchange_for_download(cip, file)
+        self.device.log.append(f'Create file exchange {file_instance} for download.')
+
+        # Set attributes
+        #
+        # Still no clue what this is.  Might be setting file up for write?
+        if not(terminal_is_set_unk_valid(cip)): raise Exception('Invalid response from an unknown attribute.  Check packets.')
+
+        # Transfer *.MER chunk by chunk
+        terminal_file_download_mer(cip, file_instance, file)
+
+        # Mark file exchange as completed on the terminal
+        terminal_end_file_write(cip, file_instance)
+        self.device.log.append(f'Downloaded {file.path} to {file.name} using file exchange {file_instance}.')
+
+        # Delete file exchange on the terminal
+        terminal_delete_file_exchange(cip, file_instance)
+        self.device.log.append(f'Deleted file exchange {file_instance}.')
+
+        return True
+
+    def __get_mer_list(self, cip: pycomm3.CIPDriver):
+        # Create *.MER list
+        terminal_create_mer_list(cip)
+
+        file_instance = terminal_create_file_exchange_for_mer_list(cip)
+        self.device.log.append(f'Create file exchange {file_instance} for upload.')
+
+        # Transfer *.MER list chunk by chunk
+        file_list = terminal_file_upload_mer_list(cip, file_instance)
+        self.device.log.append(f'Uploaded *.MER file list using file exchange {file_instance}.')
+
+        # Delete file exchange on the terminal
+        terminal_delete_file_exchange(cip, file_instance)
+        self.device.log.append(f'Deleted file exchange {file_instance}.')
+
+        return file_list
+
+    def __is_download_valid(self, cip: pycomm3.CIPDriver, file: MEFile) -> bool:
+        # Check that file is correct extension
+        if (file.get_ext() != '.mer'):
+            self.device.log.append(f'File {file.name} is not a *.mer file')
+            return False
+
+        # Check that storage folder exists
+        resp_storage_exists = terminal_get_folder_exists(cip)
+        if not(resp_storage_exists):
+            self.device.log.append(f'Storage folder does not exist on terminal')
+            return False
+
+        # Check free space
+        resp_free_space = terminal_get_free_space(cip)
+        if (resp_free_space > file.get_size()):
+            self.device.log.append(f'File {file.name} requires {file.get_size()} byes.  Free space on terminal {resp_free_space} bytes.')
+        else:
+            self.device.log.append(f'File {file.name} requires {file.get_size()} bytes.  Free space on terminal {resp_free_space} bytes is insufficient.')
+            return False
+
+        # Check if file name already exists
+        resp_file_exists = terminal_get_file_exists(cip, file)
+        file.overwrite_required = False
+        if (resp_file_exists and file.overwrite_requested):
+            self.device.log.append(f'File {file.name} already exists on terminal, and overwrite was requested.  Setting overwrite to required.')
+            file.overwrite_required = True
+        if (resp_file_exists and not(file.overwrite_requested)):
+            self.device.log.append(f'File {file.name} already exists on terminal, and overwrite was NOT requested.  Use kwarg overwrite_requested=True to overwrite existing.')
+            return False
+        if not(resp_file_exists):
+            self.device.log.append(f'File {file.name} does not exist on terminal.  Setting overwrite to not required.')
+
+        # Check space consumed by file if it exists
+        if resp_file_exists:
+            resp_file_size = terminal_get_file_size(cip, file)
+            self.device.log.append(f'File {file.name} on terminal is {resp_file_size} bytes.')
+
+        return True
+
+    def __reboot(self, comms_path: str):
+        cip = pycomm3.CIPDriver(comms_path)
+        cip._cfg['socket_timeout'] = 0.25
+        cip.open()
+        terminal_reboot(cip)
+        cip.close()
+
+    def __get_terminal_info(self, cip: pycomm3.CIPDriver) -> MEDeviceInfo:
+        return MEDeviceInfo(self.comms_path, 
+                            terminal_get_helper_version(cip), 
+                            terminal_get_me_version(cip), 
+                            terminal_get_product_code(cip), 
+                            terminal_get_product_type(cip),
+                            [])
+    
+    def __is_terminal_valid(self, device: MEDeviceInfo) -> bool:
+        if device.helper_version not in HELPER_VERSIONS: return False
+        if device.me_version not in ME_VERSIONS: return False
+        if device.product_code not in PRODUCT_CODES: return False
+        if device.product_type not in PRODUCT_TYPES: return False
+        return True
+    
+    def __upload_from_terminal(self, cip: pycomm3.CIPDriver, file: MEFile, rem_file: MEFile) -> bool:
+        # Verify file exists on terminal
+        if not(terminal_get_file_exists(cip, rem_file)): raise Exception(f'File {rem_file.name} does not exist on terminal.')
+
+        # Create file exchange
+        file_instance = terminal_create_file_exchange_for_upload(cip, rem_file)
+        self.device.log.append(f'Create file exchange {file_instance} for upload.')
+
+        # Transfer *.MER chunk by chunk
+        terminal_file_upload_mer(cip, file_instance, file)
+        self.device.log.append(f'Uploaded {rem_file.name} to {file.path} using file exchange {file_instance}.')
+
+        # Delete file exchange on the terminal
+        terminal_delete_file_exchange(cip, file_instance)
+        self.device.log.append(f'Deleted file exchange {file_instance}.')
+
+        return True
+
+    def download(self, file_path: str, **kwargs) -> MEResponse:
+        #
+        # Used to download a *.MER file from this system to the remote Panelview terminal.
+        #
+        # File path: *.MER path on local system (ex: C:\MyFolder\MyHMI.MER)
+        # 
+        # Optional Keyword Arguments:
+        # Delete Logs: Configures terminal to delete logs at startup
+        # Ignore Terminal Valid: Attempt to proceed with download, even if target
+        #       product ID or version does not match tested whitelist.
+        #       Proceed with caution...
+        # Overwrite: If file exists already on remote terminal, replace it.
+        # Replace Comms: Configures terminal to replace communications
+        #       from *.MER at startup.
+        # Run At Startup: Configures terminal to run downloaded *.MER at startup.
+        #       Note that this option must be selected to use Delete Logs or Replace Comms.
+        #
+        self.delete_logs = kwargs.get('delete_logs', False)
+        self.ignore_terminal_valid = kwargs.get('ignore_terminal_valid', False)
+        self.overwrite = kwargs.get('overwrite', False)
+        self.replace_comms = kwargs.get('replace_comms', False)
+        self.run_at_startup = kwargs.get('run_at_startup', True)
+
+        with pycomm3.CIPDriver(self.comms_path) as cip:
+            file = MEFile(os.path.basename(file_path), self.overwrite, False, file_path)
+
+            # Validate device at this communications path
+            # is a terminal of known version.
+            #
+            # TODO: Test on more hardware to expand validated list
+            self.device = self.__get_terminal_info(cip)
+            if not(self.__is_terminal_valid(self.device)):
+                if self.ignore_terminal_valid:
+                    warn('Invalid device selected, but terminal validation is set to IGNORE.')
+                else:
+                    raise Exception('Invalid device selected.  Use kwarg ignore_terminal_valid=True to proceed at your own risk.')
+                
+            # Validate that all starting conditions for downnload to terminal are as expected
+            if not(self.__is_download_valid(cip, file)): raise Exception('Download to terminal is invalid.')
+
+            # Perform *.MER download to terminal
+            if not(self.__download_to_terminal(cip, file)): raise Exception('Download to terminal failed.')
+
+            # Set *.MER to run at startup and then reboot
+            if self.run_at_startup:
+                terminal_set_startup_file(cip, file, self.replace_comms, self.delete_logs)
+                terminal_reboot(cip)
+
+        return MEResponse(self.device, 'Success')
+
+    def get_terminal_info(self) -> MEResponse:
+        # 
+        # Used to print some info about the remote PanelView terminal.
+        #
+        with pycomm3.CIPDriver(self.comms_path) as cip:
+            self.device = self.__get_terminal_info(cip)
+            if (self.__is_terminal_valid(self.device)):
+                self.device.log.append(f'Terminal storage exists: {terminal_get_folder_exists(cip)}.')
+                self.device.log.append(f'Terminal has {terminal_get_free_space(cip)} free bytes')
+                self.device.log.append(f'Terminal has files: {self.__get_mer_list(cip)}')
+
+        return MEResponse(self.device, 'Success')
+
+    def reboot(self) -> MEResponse:
+        #
+        # Used to reboot the remote PanelView terminal.
+        #
+        with pycomm3.CIPDriver(self.comms_path) as cip:
+            self.device = self.__get_terminal_info(cip)
+            if (self.__is_terminal_valid(self.device)):
+                self.__reboot(self.comms_path)
+
+        return MEResponse(self.device, 'Success')
+
+    def upload(self, file_path: str, **kwargs) -> MEResponse:
+        #
+        # Used to upload a *.MER file from the remote PanelView terminal to this system.
+        #
+        # File Path: Path to upload to on the local system (ex: C:\MyFolder\MyHMI.MER)
+        # 
+        # Optional Keyword Arguments:
+        # Overwrite: If the file already exists on the local system, replace it.
+        # Remote File Name: Use this to specify a different remote filename on the
+        #       terminal than where the local file will end up.
+        #
+        file = MEFile(os.path.basename(file_path), False, False, file_path)
+        self.remote_file_name = kwargs.get('remote_file_name', file.name)
+        self.overwrite = kwargs.get('overwrite', False)
+        rem_file = MEFile(self.remote_file_name,False,False,file_path)
+
+        # Create upload folder if it doesn't exist yet
+        if not(os.path.exists(os.path.dirname(file.path))): os.makedirs(os.path.dirname(file.path))
+
+        # Check for existing *.MER
+        if not(self.overwrite) and (os.path.exists(file.path)): raise Exception(f'File {file.name} already exists.  Use kwarg overwrite=True to overwrite existing local file from the remote terminal.')
+
+        with pycomm3.CIPDriver(self.comms_path) as cip:
+            # Validate device at this communications path
+            # is a terminal of known version.
+            #
+            # TODO: Test on more hardware to expand validated list
+            self.device = self.__get_terminal_info(cip)
+            if not(self.__is_terminal_valid(self.device)):
+                if self.ignore_terminal_valid:
+                    warn('Invalid device selected, but terminal validation is set to IGNORE.')
+                else:
+                    raise Exception('Invalid device selected.  Use kwarg ignore_terminal_valid=True to proceed at your own risk.')
+
+            # Perform *.MER upload from terminal
+            if not(self.__upload_from_terminal(cip, file, rem_file)): raise Exception('Upload from terminal failed.')
+        
+        return MEResponse(self.device, 'Success')
+
+    def upload_all(self, file_path: str, **kwargs):
+        #
+        # Used to upload all *.MER files from the remote PanelView terminal to this system.
+        #
+        # File Path: Path to upload to on the local system (ex: C:\MyFolder)
+        # 
+        # Optional Keyword Arguments:
+        # Overwrite: If the file already exists on the local system, replace it.
+        #
+        self.overwrite = kwargs.get('overwrite', False)
+
+        # Create upload folder if it doesn't exist yet
+        if not(os.path.exists(file_path)): os.makedirs(os.path.dirname(file_path))
+
+        with pycomm3.CIPDriver(self.comms_path) as cip:
+            # Validate device at this communications path
+            # is a terminal of known version.
+            #
+            # TODO: Test on more hardware to expand validated list
+            self.device = self.__get_terminal_info(cip)
+            if not(self.__is_terminal_valid(self.device)):
+                if self.ignore_terminal_valid:
+                    warn('Invalid device selected, but terminal validation is set to IGNORE.')
+                else:
+                    raise Exception('Invalid device selected.  Use kwarg ignore_terminal_valid=True to proceed at your own risk.')
+
+            mer_list = self.__get_mer_list(cip)
+            
+            for mer in mer_list:
+                if len(mer) > 0:
+                    mer_path = os.path.join(file_path, mer)
+                    file = MEFile(os.path.basename(mer_path), self.overwrite, False, mer_path)
+
+                    # Check for existing *.MER
+                    if not(self.overwrite) and (os.path.exists(mer_path)): raise Exception(f'File {mer_path} already exists.  Use kwarg overwrite=True to overwrite existing local file from the remote terminal.')
+
+                    # Perform *.MER upload from terminal
+                    if not(self.__upload_from_terminal(cip, file, file)): raise Exception('Upload from terminal failed.')
+
+        return MEResponse(self.device, 'Success')

pymeu-0.0.1/pymeu/messages.py

@@ -0,0 +1,80 @@
+import pycomm3
+
+def msg_create_file_exchange(cip: pycomm3.CIPDriver, data):
+    return cip.generic_message(
+        service=pycomm3.Services.create,
+        class_code=0x04ff,
+        instance=0x00,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )
+
+def msg_delete_file_exchange(cip: pycomm3.CIPDriver, instance: int):
+    return cip.generic_message(
+        service=pycomm3.Services.delete,
+        class_code=0x04ff,
+        instance=instance,
+        connected=False,
+        route_path=None
+    )
+
+def msg_read_file_chunk(cip: pycomm3.CIPDriver, instance: int, data):
+    return cip.generic_message(
+        service=0x53,
+        class_code=0x04ff,
+        instance=instance,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )
+
+def msg_read_registry(cip: pycomm3.CIPDriver, data):
+    return cip.generic_message(
+        service=0x51,
+        class_code=0x04fe,
+        instance=0x00,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )
+
+def msg_run_function(cip: pycomm3.CIPDriver, data):
+    return cip.generic_message(
+        service=0x50,
+        class_code=0x04fd,
+        instance=0x00,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )
+
+def msg_write_file_chunk(cip: pycomm3.CIPDriver, instance: int, data):
+    return cip.generic_message(
+        service=0x52,
+        class_code=0x04ff,
+        instance=instance,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )
+
+def msg_get_attr_unk(cip: pycomm3.CIPDriver, data):
+    return cip.generic_message(
+        service=pycomm3.Services.get_attribute_single,
+        class_code=0x04ff,
+        instance=0x00,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )
+
+def msg_set_attr_unk(cip: pycomm3.CIPDriver, data):
+    return cip.generic_message(
+        service=pycomm3.Services.set_attribute_single,
+        class_code=0x04ff,
+        instance=0x01,
+        request_data=data,
+        connected=False,
+        route_path=None
+    )

pymeu-0.0.1/pymeu/terminal.py

@@ -0,0 +1,468 @@
+import pycomm3
+import struct
+from warnings import warn
+
+from .constants import *
+from .messages import *
+from .types import *
+
+def terminal_create_directory(cip: pycomm3.CIPDriver, dir: str) -> bool:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'CreateRemDirectory', dir]
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (183 = function ran, otherwise failed)
+    # Byte 4 null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to create directory on terminal.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != CREATE_DIR_SUCCESS):
+        raise Exception('Failed to create directory on terminal.')
+    
+    return True
+
+def terminal_create_file_exchange_for_download(cip: pycomm3.CIPDriver, file: MEFile) -> int:
+    # Request format
+    #
+    # Byte 0 Transfer Type (always 1 for file download?)
+    # Byte 1 Overwrite (0 = New File, 1 = Overwrite Existing)
+    # Byte 2 to 3 Chunk size in bytes
+    # Byte 4 to 7 File size in bytes
+    # Byte 8 to N-1 File name
+    # Byte N null footer
+    req_header = struct.pack('<BBHI', 0x01, int(file.overwrite_required), CHUNK_SIZE, file.get_size())
+    req_args = [f'\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\{file.name}']
+    req_data = req_header + b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 1 message instance (should match request, 0x00)
+    # Byte 2 to 3 unknown purpose
+    # Byte 4 to 5 file instance (use this instance for file transfer)
+    # Byte 6 to 7 chunk size in bytes
+    resp = msg_create_file_exchange(cip, req_data)
+    if not resp: raise Exception('Failed to create file exchange on terminal')
+    resp_msg_instance, resp_unk1, resp_file_instance, resp_chunk_size = struct.unpack('<HHHH', resp.value)
+    if (resp_msg_instance != 0): raise Exception(f'Response message instance {resp_msg_instance} is not zero.  Most likely there was an incomplete transfer.  Reboot terminal and try again.')
+    if (resp_unk1 != 0 ): raise Exception(f'Response unknown bytes {resp_unk1} are not zero.  Examine packets.')
+    if (resp_file_instance != 1): warn(f'Response file instance {resp_file_instance} is not one.  Examine packets.')
+    if (resp_chunk_size != CHUNK_SIZE): raise Exception(f'Response chunk size {resp_chunk_size} did not match request size {CHUNK_SIZE}')
+    return resp_file_instance
+
+def terminal_create_file_exchange_for_mer_list(cip: pycomm3.CIPDriver) -> int:
+    # Request format
+    #
+    # Byte 0 Transfer Type (always 0 for file upload?)
+    # Byte 1 unknown purpose (used for overwrite in download... maybe no purpose here?)
+    # Byte 2 to 3 Chunk size in bytes
+    # Byte 4 to N-1 File name
+    # Byte N null footer
+    req_header = struct.pack('<BBH', 0x00, 0x00, CHUNK_SIZE)
+    req_args = ['\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\Results.txt']
+    req_data = req_header + b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 1 message instance (should match request, 0x00)
+    # Byte 2 to 3 unknown purpose
+    # Byte 4 to 5 file instance (use this instance for file transfer, increases with each subsequent transfer until Delete is run)
+    # Byte 6 to 7 chunk size in bytes
+    # Byte 8 to 11 file size in bytes
+    resp = msg_create_file_exchange(cip, req_data)
+    if not resp: raise Exception('Failed to create file exchange on terminal')
+    resp_msg_instance, resp_unk1, resp_file_instance, resp_chunk_size, resp_file_size = struct.unpack('<HHHHI', resp.value)
+    if (resp_msg_instance != 0): raise Exception(f'Response message instance {resp_msg_instance} is not zero.  Most likely there was an incomplete transfer.  Reboot terminal and try again.')
+    if (resp_unk1 != 0 ): raise Exception(f'Response unknown bytes {resp_unk1} are not zero.  Examine packets.')
+    if (resp_file_instance != 1): warn(f'Response file instance {resp_file_instance} is not one.  Examine packets.')
+    if (resp_chunk_size != CHUNK_SIZE): raise Exception(f'Response chunk size {resp_chunk_size} did not match request size {CHUNK_SIZE}')
+    return resp_file_instance
+
+def terminal_create_file_exchange_for_upload(cip: pycomm3.CIPDriver, file: MEFile) -> int:
+    # Request format
+    #
+    # Byte 0 Transfer Type (always 0 for file upload?)
+    # Byte 1 unknown purpose (used for overwrite in download... maybe no purpose here?)
+    # Byte 2 to 3 Chunk size in bytes
+    # Byte 4 to N-1 File name
+    # Byte N null footer
+    req_header = struct.pack('<BBH', 0x00, 0x00, CHUNK_SIZE)
+    req_args = [f'\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\{file.name}']
+    req_data = req_header + b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 1 message instance (should match request, 0x00)
+    # Byte 2 to 3 unknown purpose
+    # Byte 4 to 5 file instance (use this instance for file transfer, increases with each subsequent transfer until Delete is run)
+    # Byte 6 to 7 chunk size in bytes
+    # Byte 8 to 11 file size in bytes
+    resp = msg_create_file_exchange(cip, req_data)
+    if not resp: raise Exception('Failed to create file exchange on terminal')
+    resp_msg_instance, resp_unk1, resp_file_instance, resp_chunk_size, resp_file_size = struct.unpack('<HHHHI', resp.value)
+    if (resp_msg_instance != 0): raise Exception(f'Response message instance {resp_msg_instance} is not zero.  Most likely there was an incomplete transfer.  Reboot terminal and try again.')
+    if (resp_unk1 != 0 ): raise Exception(f'Response unknown bytes {resp_unk1} are not zero.  Examine packets.')
+    if (resp_file_instance != 1): warn(f'Response file instance {resp_file_instance} is not one.  Examine packets.')
+    if (resp_chunk_size != CHUNK_SIZE): raise Exception(f'Response chunk size {resp_chunk_size} did not match request size {CHUNK_SIZE}')
+    return resp_file_instance
+
+def terminal_create_mer_list(cip: pycomm3.CIPDriver):
+    req_args = ['\\Windows\\RemoteHelper.DLL','FileBrowse','\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\*.mer::\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\Results.txt']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+    return msg_run_function(cip, req_data)
+
+def terminal_create_runtime_directory(cip: pycomm3.CIPDriver, file: MEFile) -> bool:
+    # Create paths
+    if not(terminal_create_directory(cip, '\\Application Data')): return False
+    if not(terminal_create_directory(cip, '\\Application Data\\Rockwell Software')): return False
+    if not(terminal_create_directory(cip, '\\Application Data\\Rockwell Software\\RSViewME')): return False
+    if not(terminal_create_directory(cip, '\\Application Data\\Rockwell Software\\RSViewME\\Runtime')): return False
+    if not(terminal_create_directory(cip, '\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\')): return False
+    return True
+
+def terminal_delete_file_exchange(cip: pycomm3.CIPDriver, instance: int):
+    return msg_delete_file_exchange(cip, instance)
+
+def terminal_delete_mer_list(cip: pycomm3.CIPDriver):
+    req_args = ['\\Windows\\RemoteHelper.DLL','DeleteRemFile','\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\Results.txt']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+    return msg_run_function(cip, req_data)
+
+def terminal_end_file_write(cip: pycomm3.CIPDriver, instance: int):
+    req_data = b'\x00\x00\x00\x00\x02\x00\xff\xff'
+    return msg_write_file_chunk(cip, instance, req_data)
+
+def terminal_file_download_mer(cip: pycomm3.CIPDriver, instance: int, file: MEFile):
+    req_chunk_number = 1
+    with open(file.path, 'rb') as source_file:
+        while True:
+            # Request format
+            #
+            # Byte 0 to 3 chunk number
+            # Byte 4 to 5 chunk size in bytes
+            # Byte 6 to N chunk data
+            req_chunk = source_file.read(CHUNK_SIZE)
+            req_header = struct.pack('<IH', req_chunk_number, len(req_chunk))
+            req_next_chunk_number = req_chunk_number + 1
+            req_data = req_header + req_chunk
+
+            # End of file
+            if not req_chunk:
+                #print(f'File downloaded from: {file.path}')
+                break
+
+            # Response format
+            #
+            # Byte 0 to 3 unknown purpose
+            # Byte 4 to 7 req chunk number echo
+            # Byte 8 to 11 next chunk number
+            resp = msg_write_file_chunk(cip, instance, req_data)
+            if not resp: raise Exception(f'Failed to write chunk {req_chunk_number} to terminal.')
+            resp_unk1, resp_chunk_number, resp_next_chunk_number = struct.unpack('<III', resp.value)
+            if (resp_unk1 != 0 ): raise Exception(f'Response unknown bytes {resp_unk1} are not zero.  Examine packets.')
+            if (resp_chunk_number != req_chunk_number ): raise Exception(f'Response chunk number {resp_chunk_number} did not match request chunk number {req_chunk_number}.')
+            if (resp_next_chunk_number != req_next_chunk_number): raise Exception(f'Response next chunk number {resp_next_chunk_number} did not match expected next chunk number {req_next_chunk_number}.')
+
+            # Continue to next chunk
+            req_chunk_number += 1
+
+def terminal_file_upload_mer(cip: pycomm3.CIPDriver, instance: int, file: MEFile):
+    req_chunk_number = 1
+    with open(file.path, 'wb') as dest_file:
+        while True:
+            # Request format
+            #
+            # Byte 0 to 3 chunk number
+            req_data = struct.pack('<I', req_chunk_number)
+
+            # Response format
+            #
+            # Byte 0 to 3 unknown purpose
+            # Byte 4 to 7 req chunk number echo
+            # Byte 8 to 9 chunk size in bytes
+            # Byte 10 to N chunk data
+            resp = msg_read_file_chunk(cip, instance, req_data)
+            if not resp: raise Exception(f'Failed to read chunk {req_chunk_number} to terminal.')
+            resp_unk1 = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+            resp_chunk_number = int.from_bytes(resp.value[4:8], byteorder='little', signed=False)
+            resp_chunk_size = int.from_bytes(resp.value[8:9], byteorder='little', signed=False)
+            resp_data = bytes(resp.value[10:])
+
+            if (resp_unk1 != 0 ): raise Exception(f'Response unknown bytes {resp_unk1} are not zero.  Examine packets.')
+            if (resp_chunk_number != req_chunk_number) and (resp_chunk_number != 0): raise Exception(f'Response chunk number {resp_chunk_number} did not match request chunk number {req_chunk_number}.')
+
+            # End of file
+            if (resp_chunk_number == 0) and (resp_chunk_size == 2) and (resp_data == b'\xff\xff'):
+                #print(f'File uploaded to: {file.path}')
+                break
+
+            # Write to file
+            dest_file.write(resp_data)
+
+            # Continue to next chunk
+            req_chunk_number += 1
+
+def terminal_file_upload_mer_list(cip: pycomm3.CIPDriver, instance: int):
+    req_chunk_number = 1
+    resp_binary = bytearray()
+    while True:
+        # Request format
+        #
+        # Byte 0 to 3 chunk number
+        req_data = struct.pack('<I', req_chunk_number)
+
+        # Response format
+        #
+        # Byte 0 to 3 unknown purpose
+        # Byte 4 to 7 req chunk number echo
+        # Byte 8 to 9 chunk size in bytes
+        # Byte 10 to N chunk data
+        resp = msg_read_file_chunk(cip, instance, req_data)
+        if not resp: raise Exception(f'Failed to read chunk {req_chunk_number} to terminal.')
+        resp_unk1 = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+        resp_chunk_number = int.from_bytes(resp.value[4:8], byteorder='little', signed=False)
+        resp_chunk_size = int.from_bytes(resp.value[8:9], byteorder='little', signed=False)
+        resp_data = bytes(resp.value[10:])
+
+        if (resp_unk1 != 0 ): raise Exception(f'Response unknown bytes {resp_unk1} are not zero.  Examine packets.')
+        if (resp_chunk_number != req_chunk_number) and (resp_chunk_number != 0): raise Exception(f'Response chunk number {resp_chunk_number} did not match request chunk number {req_chunk_number}.')
+
+        # End of file
+        if (resp_chunk_number == 0) and (resp_chunk_size == 2) and (resp_data == b'\xff\xff'):
+            #print('End of file')
+            break
+
+        # Write to mer list
+        resp_binary += resp_data
+
+        # Continue to next chunk
+        req_chunk_number += 1
+
+    # In the returned list, each file name character is separated
+    # by a null character.
+    #
+    # Each each is separate by a colon.
+    resp_str = "".join([chr(b) for b in resp_binary if b != 0])
+    resp_list = resp_str.split(':')
+    return resp_list
+
+def terminal_get_file_exists(cip: pycomm3.CIPDriver, file: MEFile) -> bool:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'FileExists', f'\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\{file.name}']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 file exists (1 = file exists)
+    # Byte 5 null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to get whether file exists.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        #This one can return false without warning since the outer function will set the overwrite bit accordingly.
+        #
+        #warn(f'Response code was not zero.  Examine packets.')
+        return False
+    
+    resp_file_exists = bool(int(resp.value[4:].decode('utf-8').strip('\x00')))
+    return resp_file_exists
+
+def terminal_get_file_size(cip: pycomm3.CIPDriver, file: MEFile) -> int:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'FileSize', f'\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\{file.name}']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format 
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 to N-1 file size
+    # Byte N null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to get file size of {file.name} on terminal.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    resp_file_size = int(resp.value[4:].decode('utf-8').strip('\x00'))
+    return resp_file_size
+
+def terminal_get_folder_exists(cip: pycomm3.CIPDriver) -> bool:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'StorageExists', '\\Application Data']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 storage exists (1 -> folder exists)
+    # Byte 5 null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to get whether storage exists.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        warn(f'Response code was not zero.  Examine packets.')
+        return False
+
+    resp_storage_exists = bool(int(resp.value[4:].decode('utf-8').strip('\x00')))
+    return resp_storage_exists
+
+def terminal_get_free_space(cip: pycomm3.CIPDriver) -> int:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'FreeSpace', '\\Application Data\\Rockwell Software\\RSViewME\\Runtime\\']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format 
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 to N-1 free space
+    # Byte N null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to get terminal free space.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    resp_free_space = int(resp.value[4:].decode('utf-8').strip('\x00'))
+    return resp_free_space
+
+def terminal_get_helper_version(cip: pycomm3.CIPDriver) -> str:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'GetVersion', '\\Windows\\RemoteHelper.DLL']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 to N-1 terminal version string
+    # Byte N null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to get terminal helper version.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    resp_helper_version = str(resp.value[4:].decode('utf-8').strip('\x00'))
+    return resp_helper_version
+
+def terminal_get_me_version(cip: pycomm3.CIPDriver) -> str:
+    req_args = ['HKEY_LOCAL_MACHINE\\SOFTWARE\\Rockwell Software\\RSView Enterprise\\MEVersion']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 to 7 unknown purpose
+    # Byte 8 to N-1 ME version string
+    # Byte N null footer
+    resp = msg_read_registry(cip, req_data)
+    if not resp: raise Exception('Failed to get terminal ME version.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    resp_unk1 = int.from_bytes(resp.value[4:8], byteorder='little', signed=False)
+    resp_version = str(resp.value[8:].decode('utf-8').strip('\x00'))
+    return resp_version
+
+def terminal_get_product_code(cip: pycomm3.CIPDriver) -> str:
+    req_args = ['HKEY_LOCAL_MACHINE\\SOFTWARE\\Rockwell Software\\RSLinxNG\\CIP Identity\\ProductCode']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 to 7 unknown purpose
+    # Byte 8 to N-1 product code string
+    # Byte N null footer
+    resp = msg_read_registry(cip, req_data)
+    if not resp: raise Exception('Failed to get terminal product code.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    resp_unk1 = int.from_bytes(resp.value[4:8], byteorder='little', signed=False)
+    resp_product_code = str(resp.value[8:].decode('utf-8').strip('\x00'))
+    return resp_product_code
+
+def terminal_get_product_type(cip: pycomm3.CIPDriver) -> str:
+    req_args = ['HKEY_LOCAL_MACHINE\\SOFTWARE\\Rockwell Software\\RSLinxNG\\CIP Identity\\ProductType']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 to 7 unknown purpose
+    # Byte 8 to N-1 product type string
+    # Byte N null footer
+    resp = msg_read_registry(cip, req_data)
+    if not resp: raise Exception('Failed to get terminal product type.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    resp_unk1 = int.from_bytes(resp.value[4:8], byteorder='little', signed=False)
+    resp_product_type = str(resp.value[8:].decode('utf-8').strip('\x00'))
+    return resp_product_type
+
+def terminal_is_get_unk_valid(cip: pycomm3.CIPDriver) -> bool:
+    # I don't know what any of these three attributes are for yet.
+    # It may be checking that the file exchange is available.
+    resp = msg_get_attr_unk(cip, b'\x30\x01')
+    if not resp: return False
+    if resp.value not in GET_UNK1_VALUES:
+        warn(f'Invalid UNK1 value.  Examine packets.')
+        return False
+
+    resp = msg_get_attr_unk(cip, b'\x30\x08')
+    if not resp: return False
+    if resp.value not in GET_UNK2_VALUES:
+        warn(f'Invalid UNK2 value.  Examine packets.')
+        return False
+
+    resp = msg_get_attr_unk(cip, b'\x30\x09')
+    if not resp: return False
+    if resp.value not in GET_UNK3_VALUES:
+        warn(f'Invalid UNK3 value.  Examine packets.')
+        return False
+
+    return True
+
+def terminal_is_set_unk_valid(cip: pycomm3.CIPDriver) -> bool:
+    # I don't know what setting this attribute does yet.
+    # It may be marking the file exchange as in use.
+    #
+    resp = msg_set_attr_unk(cip, b'\x30\x01\xff\xff')
+    if not resp: return False
+
+    return True
+
+def terminal_reboot(cip: pycomm3.CIPDriver):
+    # For some reason this one has an extra trailing byte.
+    # Not sure if it has some other purpose yet
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'BootTerminal']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args) + b'\x00'
+
+    try:
+        resp = msg_run_function(cip, req_data)
+        
+        #Should never get here
+        raise Exception(resp)
+    except pycomm3.exceptions.CommError as e:
+        # Unlike most CIP messages, this one is always expected to
+        # create an exception.  When it is received by the terminal,
+        # the device reboots and breaks the socket.
+        if (str(e) != 'failed to receive reply'): raise e
+
+def terminal_set_startup_file(cip: pycomm3.CIPDriver, file: MEFile, replace_comms: bool, delete_logs: bool) -> bool:
+    req_args = ['\\Windows\\RemoteHelper.DLL', 'CreateRemMEStartupShortcut', f'\\Application Data:{file.name}: /r /delay']
+    if replace_comms: req_args = [req_args[1], req_args[2], req_args[3] + ' /o']
+    if delete_logs: req_args = [req_args[1], req_args[2], req_args[3] + ' /d']
+    req_data = b''.join(arg.encode() + b'\x00' for arg in req_args)
+
+    # Response format
+    #
+    # Byte 0 to 3 response code (0 = function ran, otherwise failed)
+    # Byte 4 null footer
+    resp = msg_run_function(cip, req_data)
+    if not resp: raise Exception('Failed to set terminal startup shortcut.')
+    resp_code = int.from_bytes(resp.value[:4], byteorder='little', signed=False)
+    if (resp_code != 0):
+        raise Exception(f'Response code was not zero.  Examine packets.')
+
+    return True

pymeu-0.0.1/pymeu/types.py

@@ -0,0 +1,30 @@
+import os
+from dataclasses import dataclass
+
+@dataclass
+class MEFile:
+    name: str
+    overwrite_requested: bool
+    overwrite_required: bool
+    path: str
+
+    def get_ext(self) -> str:
+        filename, extension = os.path.splitext(self.path)
+        return extension.lower()
+
+    def get_size(self) -> int:
+        return os.path.getsize(self.path)
+    
+@dataclass
+class MEDeviceInfo:
+    comms_path: str
+    helper_version: str
+    me_version: str
+    product_code: str
+    product_type: str
+    log: list[str]
+
+@dataclass
+class MEResponse(object):
+    device: MEDeviceInfo
+    status: str

pymeu-0.0.1/pymeu.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.1
+Name: pymeu
+Version: 0.0.1
+Summary: Python ME Utility
+Author-email: aawilliams85 <adair.williams85@gmail.com>
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pycomm3
+
+# pymeu
+
+PyMEU (Python ME Utility) is a set of helper functions built around pycomm3 to interface with Rockwell Automation PanelView Plus 6/7 HMIs.<br>
+
+The current release has only been tested on a very limited selection of hardware.  It is alpha quality at best and could easily brick your device.  Use at your own risk.<br>
+
+## Example
+
+Use the download function to transfer a *.MER file to the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.download('C:\\YourFolder\\YourProgram.mer')
+```
+
+Use the upload function to transfer a *.MER file from the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.upload('C:\\YourFolder\\YourProgram.mer')
+```
+
+Use the upload all function to transfer all *.MER files from the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.upload_all('C:\\YourFolder')
+```
+
+Use the reboot function to restart the remote terminal:
+
+```python
+from pymeu import MEUtility
+meu = MEUtility('192.168.1.20')
+meu.reboot()
+```

pymeu-0.0.1/pymeu.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+pymeu/__init__.py
+pymeu/constants.py
+pymeu/main.py
+pymeu/messages.py
+pymeu/terminal.py
+pymeu/types.py
+pymeu.egg-info/PKG-INFO
+pymeu.egg-info/SOURCES.txt
+pymeu.egg-info/dependency_links.txt
+pymeu.egg-info/requires.txt
+pymeu.egg-info/top_level.txt

pymeu-0.0.1/pymeu.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pymeu-0.0.1/pymeu.egg-info/requires.txt

@@ -0,0 +1 @@
+pycomm3

pymeu-0.0.1/pymeu.egg-info/top_level.txt

@@ -0,0 +1 @@
+pymeu

pymeu-0.0.1/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "pymeu"
+description = "Python ME Utility"
+readme = "README.md"
+version = "0.0.1"
+authors = [
+    { name = "aawilliams85", email = "adair.williams85@gmail.com" }
+]
+dependencies = [
+    "pycomm3"
+]

pymeu-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+