Using OpcCmd Utility for OPC UA File Transfer: Difference between revisions

From OPC Labs Knowledge Base
No edit summary
 
(27 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:OPC UA]] [[Category:OPC UA File Transfer]] [[Category:OpcCmd Utility]] [[Category:Tools and Online Services]]  
[[Category:OPC UA]] [[Category:OPC UA File Transfer]] [[Category:OpcCmd Utility]] [[Category:Tools and Online Services]]  
For general information about the OpcCmd tool, see [[:Category:OpcCmd Utility]].
For general information about OPC UA File Transfer, see [[OPC UA File Transfer concepts]]. For general information about the OpcCmd tool, see [[:Category:OpcCmd Utility]].
= Tutorial =
= Tutorial =
If you execute the commands listed in the tutorial below, you will get an overview of basic operations that can be made with an OPC UA Server that provides OPC UA File Transfer model.
If you execute the commands listed in the tutorial below, you will get an overview of basic operations that can be made with an OPC UA Server that provides OPC UA File Transfer model:
* Accessing a standalone OPC UA file node, and accessing an OPC UA file system.
* Getting file properties (metadata).
* Saving file contents to a local operating system file.
* Loading file contents from a local operating system file.
* Clearing directory contents.
* Creating a subdirectory in the OPC UA file system.
* Copying files in the OPC UA file system.
* Displaying contents of a directory in OPC UA file system in a table or as a tree.
* Deleting a file from OPC UA file system.


This tutorial works with Unified Automation UA .NET SDK Bundle server. You should be able to use the principles explained in this tutorial with other OPC UA servers that provide the File Transfer model, by modifying the relevant parameters used in the commands.
This tutorial works with Unified Automation UA .NET SDK Bundle server. You should be able to use the principles explained in this tutorial with other OPC UA servers that provide the File Transfer model, by modifying the relevant parameters used in the commands.


# Start the Unified Automation UA .NET SDK Bundle server, by typing {{Style=keyboard|start UaServerNET.exe}} at the operating system command prompt, when in the 'bin' directory of the Unified Automation UA .NET SDK Bundle.<br/><br/>
# Start the Unified Automation UA .NET SDK Bundle server, by typing {{Style=keyboard|start UaServerNET.exe}} at the operating system command prompt, when in the 'bin' directory of the Unified Automation UA .NET SDK Bundle.<br/><br/>
# Start the OpcCmd utility in interactive mode. The interactive mode is always in effect e.g. when you use ClickOnce, or when running the utility from QuickOPC Launcher/Start menu. In other cases, you need to use the <code>-i</code> (or <code>--interactive</code>) option on the command line.<br/><br/>
# Start the OpcCmd utility in interactive mode. The interactive mode is always in effect e.g. when you use ClickOnce, or when running the utility from QuickOPC Launcher/Start menu. In other cases, you need to use the <code>-i</code> (or <code>--interactive</code>) option on the command line.<br/><br/>
# {{Style=keyboard|uaFileTransferClient}}<br/><br/>
# At the {{Style=label|OpcCmd>}} prompt, enter {{Style=keyboard|uaFileTransferClient}}, or shortened: {{Style=keyboard|uaftc}}. This command tells the utility that from now on, we will be accessing the File Transfer functionality of OPC UA. The programs responds with a confirmation of the command.<br/><br/>Subsequent commands are entered at the {{Style=label|uaFileTransferClient>}} prompt. You can enter <code>-?</code>, <code>-h</code> or <code>--help</code> (possibly preceded by the command name) at any time to obtain help for this prompt (or its commands).<br/><br/>
# {{Style=keyboard|1=getFileInfo opc.tcp://localhost:48030 "nsu=http://www.unifiedautomation.com/DemoServer/ ;s=Demo.Files.TextFile"}}<br/><br/>
# In order to access a file that is represented by a standalone node in the server (i.e. not part of the OPC UA file system), enter {{Style=keyboard|1=getFileInfo opc.tcp://localhost:48030 "nsu=http://www.unifiedautomation.com/DemoServer/ ;s=Demo.Files.TextFile" --readOnly}} (<code>getFileInfo</code> can be shortened to <code>gfi</code>, and <code>--readOnly</code> can be shortened to <code>-ro</code>). The node Id used in this command refers to a predefined node in the server which contains a demo text file. The <code>--readOnly</code> option tells OpcCmd that we do not intend to make (and do not want to allow) any modification to the file metadata or contents inside the OPC UA server (this is optional).<br/>Subsequent commands are entered at the {{Style=label|fileInfo>}} prompt.<br/><br/>
# {{Style=keyboard|get}}<br/><br/>
# Display the file properties by entering {{Style=keyboard|get}}.<br/><br/>
# ''(establish trust)''<br/><br/>
# The OpcCmd Utility will now ask you whether you want the client to trust the server certificate. Verify that that you have been presented with the right server server certificate, and if so, accept the certificate by pressing {{Style=keyboard|Y}} for "Yes".<br/>After the certificate is accepted, the <code>get</code> command proceeds. If OpcCmd is set to the "OPC compliance" mode, in which the secure connections are the default, and this is the first operation made from this client on the server, you will most likely receive file properties where the relevant values (such as file length, and last modified date) will be missing. This is caused by the fact that the server does not trust the client. In order to establish the trust:
# {{Style=keyboard|saveTo --osFilePath c:\work\file1.txt}}<br/><br/>
## The Unified Automation UA .NET SDK Bundle server will show the rejected client certificate on the "Rejected Certificates" tab of its window. On this tab, locate the rejected OpcCmd application certificate, right-click on it and select "Trust Permanently"; when asked, confirm the operation.
# {{Style=keyboard|exit}}<br/><br/>
## Enter the {{Style=keyboard|get}} command again.<br/><br/>[[File:OpcCmd-fileInfo-get.png]]<br/><br/>
# {{Style=keyboard|1=getDirectoryContents opc.tcp://localhost:48030 "nsu=http://www.unifiedautomation.com/DemoServer/ ;s=Demo.Files.FileSystem" --EndpointUser root:secret}}<br/><br/>
# Save the contents of the OPC UA file to a file in your local file system by entering {{Style=keyboard|saveTo --osFilePath c:\work\file1.txt}}, or shortened: {{Style=keyboard|st -os c:\work\file1.txt}}. You can replace the file path (for your operating in system) in the command with a different one, as you need. The directory where you want the file be placed must already exist. Note that an existing file on the disk, if it exists, will be overwritten without confirmation. After the operation is finished, you can use the means of your operating system to view the file.<br/><br/>
# {{Style=keyboard|clear}}<br/><br/>
# Enter {{Style=keyboard|exit}} to return to the {{Style=label|uaFileTransferClient>}} prompt.<br/><br/>
# {{Style=keyboard|fileInfo MyTestFile.txt loadFrom --osFilePath c:\work\file1.txt}}<br/><br/>
# In order to access the file system in the OPC UA server (a hierarchical structure consisting of file and directories), enter {{Style=keyboard|1=getDirectoryContents opc.tcp://localhost:48030 "nsu=http://www.unifiedautomation.com/DemoServer/ ;s=Demo.Files.FileSystem" --EndpointUser john:master}} (<code>getDirectoryContents</code> can be shortened to <code>gdc</code>, and <code>--EndpointUser</code> can be shortened to <code>-eu</code>). The node Id used in this command refers to a predefined node in the server which contains a root of the file system (different servers will use a different node, and there can be multiple file system in an OPC UA server). This command also specifies user name and password, because we will be doing modifications to the file system, and the server requires user authentication for such operations.<br/>Subsequent commands are entered at the {{Style=label|directoryContents>}} prompt.<br/><br/>
# {{Style=keyboard|fileInfos?}}<br/><br/>
# In order to remove all files and directories from the file system, enter {{Style=keyboard|clear}} or {{Style=keyboard|clr}}. Caution: Before executing the command, make sure the file system does not contain any information you may later need. This step is included in the tutorial so that the file system starts in a defined state, and we can be sure e.g. that the commands will not collide with files or directories created in previous executions of the tutorial. You can skip this step if you can assure that such conflicts won't arise. The command will ask for confirmation; press {{Style=keyboard|Y}} for "Yes".<br/><br/>
# {{Style=keyboard|createSubdirectory MyTestDirectory}}<br/><br/>
# Create a file named 'MyTestFile.txt' in the root directory of the OPC UA file system and load it with the data from the existing file that we have previously saved to the disk, by entering {{Style=keyboard|fileInfo MyTestFile.txt loadFrom --osFilePath c:\work\file1.txt}}, or shortened: {{Style=keyboard|fi MyTestFile.txt lf -os c:\work\file1.txt}}. Use the path to your local file that you have used in the tutorial step with the <code>saveTo</code> command.<br/><br/>
# {{Style=keyboard|fileInfo MyTestFile.txt copyTo MyTestDirectory/CopyOfMyTestFile.txt}}<br/><br/>
# To display the list of files and directories under the current directory (file system root), enter {{Style=keyboard|fileInfos?}}, or shortened: {{Style=keyboard|fi?}}. The table will contain the 'MyTestFile.txt' file that we have created in the previous step.<br/>[[File:OpcCmd-directoryContents-fileInfosQ.png]]<br/><br/>
# {{Style=keyboard|browseTree}}<br/><br/>
# Create a subdirectory named 'MyTestDirectory' in the root directory, by entering {{Style=keyboard|createSubdirectory MyTestDirectory}}, or shortened: {{Style=keyboard|cs MyTestDirectory}}.<br/><br/>
# {{Style=keyboard|fileInfo MyTestDirectory/CopyOfMyTestFile.txt delete}}<br/><br/>
# Copy the file 'MyTestFile.txt' from the root directory to the 'MyTestDirectory' directory and give it a name 'CopyOfMyTestFile.txt', by entering {{Style=keyboard|fileInfo MyTestFile.txt copyTo MyTestDirectory/CopyOfMyTestFile.txt}}, or shortened: {{Style=keyboard|fi MyTestFile.txt ct MyTestDirectory/CopyOfMyTestFile.txt}}.<br/><br/>
# {{Style=keyboard|browseTree}}<br/><br/>
# To display a tree of the objects currently in the file system, enter {{Style=keyboard|browseTree}} or {{Style=keyboard|bt}}. At this point, the tree will contain the original 'MyTestFile.txt' file created, and a 'MyTestDirectory' subdirectory with the file copy, 'CopyOfMyTestFile.txt'.<br/>[[File:OpcCmd-directoryContents-browseTree.png]]<br/><br/>
# In order to delete the 'CopyOfMyTestFile.txt' file from 'MyTestDirectory', enter {{Style=keyboard|fileInfo MyTestDirectory/CopyOfMyTestFile.txt delete}}, or shortened: {{Style=keyboard|fi MyTestDirectory/CopyOfMyTestFile.txt d}}.<br/><br/>
# Enter {{Style=keyboard|browseTree}} or {{Style=keyboard|bt}} again, and verify that the file from the previous step has been deleted.<br/><br/>
 
= Other Operations =
Other OPC UA File Transfer operations that can be made using OpcCmd, but not shown in this tutorial, include:
* Moving and renaming files.
* Refreshig file metadata information.
* Accessing subdirectories.
* Deleting directories.
* Moving and renaming directories.
* Saving contents of whole directory trees to the local file system.
* Loading contents of whole directory trees from the local file system.
 
= Comparison with Windows and Linux commands =
 
(TBD)
 
Commands at the {{Style=label|directoryContents>}} prompt:
{| class="wikitable"
|-
! Operation !! Windows command<br/>(CMD) !! Linux command<br/>(Bash) !! OpcCmd command<br/>(directoryContents prompt)
|-
| Change current directory || chdir <path> || (tbd) || directoryContents <path>
|-
| Clear the current directory || (tbd) || (tbd) || clear
|-
| Clear the specified directory || (tbd) || (tbd) || directoryContents <path> clear
|-
| Copy a directory tree || xcopy /e <source> <destination> || (tbd) || directoryContents <source> copyTo <destination>
|-
| Copy a file || copy <source> <destination> || (tbd) || fileInfo <source> copyTo <destination>
|-
| Create a directory || mkdir <path> || (tbd) || createSubdirectory <path>
|-
| Delete a directory || rmdir <path> || (tbd) || directoryContents <path> delete
|-
| Delete a file || erase <fileName> || (tbd) || fileInfo <fileName> delete
|-
| Display current directory contents || dir || (tbd) || filesInfos?
|-
| Display specified directory contents || dir <path> || (tbd) || directoryContents <path> filesInfos?
|-
| Move a directory || move <source> <destination> || (tbd) || directoryContents <source> moveTo <destination>
|-
| Move a file || move <source> <destination> || (tbd) || fileInfo <source> moveTo <destination>
|-
| Obtain file information || (tbd) || (tbd) || fileInfo <fileName> get
|-
| Rename a directory || rename <oldDirectoryName> <newDirectoryName> || (tbd) || directoryContents <oldDirectoryName> rename <newDirectoryName>
|-
| Rename a file || rename <oldFileName> <newFileName> || (tbd) || fileInfo <oldFileName> rename <newFileName>
|}

Latest revision as of 05:16, 21 May 2021

For general information about OPC UA File Transfer, see OPC UA File Transfer concepts. For general information about the OpcCmd tool, see Category:OpcCmd Utility.

Tutorial

If you execute the commands listed in the tutorial below, you will get an overview of basic operations that can be made with an OPC UA Server that provides OPC UA File Transfer model:

  • Accessing a standalone OPC UA file node, and accessing an OPC UA file system.
  • Getting file properties (metadata).
  • Saving file contents to a local operating system file.
  • Loading file contents from a local operating system file.
  • Clearing directory contents.
  • Creating a subdirectory in the OPC UA file system.
  • Copying files in the OPC UA file system.
  • Displaying contents of a directory in OPC UA file system in a table or as a tree.
  • Deleting a file from OPC UA file system.

This tutorial works with Unified Automation UA .NET SDK Bundle server. You should be able to use the principles explained in this tutorial with other OPC UA servers that provide the File Transfer model, by modifying the relevant parameters used in the commands.


  1. Start the Unified Automation UA .NET SDK Bundle server, by typing start UaServerNET.exe at the operating system command prompt, when in the 'bin' directory of the Unified Automation UA .NET SDK Bundle.

  2. Start the OpcCmd utility in interactive mode. The interactive mode is always in effect e.g. when you use ClickOnce, or when running the utility from QuickOPC Launcher/Start menu. In other cases, you need to use the -i (or --interactive) option on the command line.

  3. At the OpcCmd> prompt, enter uaFileTransferClient, or shortened: uaftc. This command tells the utility that from now on, we will be accessing the File Transfer functionality of OPC UA. The programs responds with a confirmation of the command.

    Subsequent commands are entered at the uaFileTransferClient> prompt. You can enter -?, -h or --help (possibly preceded by the command name) at any time to obtain help for this prompt (or its commands).

  4. In order to access a file that is represented by a standalone node in the server (i.e. not part of the OPC UA file system), enter getFileInfo opc.tcp://localhost:48030 "nsu=http://www.unifiedautomation.com/DemoServer/ ;s=Demo.Files.TextFile" --readOnly (getFileInfo can be shortened to gfi, and --readOnly can be shortened to -ro). The node Id used in this command refers to a predefined node in the server which contains a demo text file. The --readOnly option tells OpcCmd that we do not intend to make (and do not want to allow) any modification to the file metadata or contents inside the OPC UA server (this is optional).
    Subsequent commands are entered at the fileInfo> prompt.

  5. Display the file properties by entering get.

  6. The OpcCmd Utility will now ask you whether you want the client to trust the server certificate. Verify that that you have been presented with the right server server certificate, and if so, accept the certificate by pressing Y for "Yes".
    After the certificate is accepted, the get command proceeds. If OpcCmd is set to the "OPC compliance" mode, in which the secure connections are the default, and this is the first operation made from this client on the server, you will most likely receive file properties where the relevant values (such as file length, and last modified date) will be missing. This is caused by the fact that the server does not trust the client. In order to establish the trust:
    1. The Unified Automation UA .NET SDK Bundle server will show the rejected client certificate on the "Rejected Certificates" tab of its window. On this tab, locate the rejected OpcCmd application certificate, right-click on it and select "Trust Permanently"; when asked, confirm the operation.
    2. Enter the get command again.

      OpcCmd-fileInfo-get.png

  7. Save the contents of the OPC UA file to a file in your local file system by entering saveTo --osFilePath c:\work\file1.txt, or shortened: st -os c:\work\file1.txt. You can replace the file path (for your operating in system) in the command with a different one, as you need. The directory where you want the file be placed must already exist. Note that an existing file on the disk, if it exists, will be overwritten without confirmation. After the operation is finished, you can use the means of your operating system to view the file.

  8. Enter exit to return to the uaFileTransferClient> prompt.

  9. In order to access the file system in the OPC UA server (a hierarchical structure consisting of file and directories), enter getDirectoryContents opc.tcp://localhost:48030 "nsu=http://www.unifiedautomation.com/DemoServer/ ;s=Demo.Files.FileSystem" --EndpointUser john:master (getDirectoryContents can be shortened to gdc, and --EndpointUser can be shortened to -eu). The node Id used in this command refers to a predefined node in the server which contains a root of the file system (different servers will use a different node, and there can be multiple file system in an OPC UA server). This command also specifies user name and password, because we will be doing modifications to the file system, and the server requires user authentication for such operations.
    Subsequent commands are entered at the directoryContents> prompt.

  10. In order to remove all files and directories from the file system, enter clear or clr. Caution: Before executing the command, make sure the file system does not contain any information you may later need. This step is included in the tutorial so that the file system starts in a defined state, and we can be sure e.g. that the commands will not collide with files or directories created in previous executions of the tutorial. You can skip this step if you can assure that such conflicts won't arise. The command will ask for confirmation; press Y for "Yes".

  11. Create a file named 'MyTestFile.txt' in the root directory of the OPC UA file system and load it with the data from the existing file that we have previously saved to the disk, by entering fileInfo MyTestFile.txt loadFrom --osFilePath c:\work\file1.txt, or shortened: fi MyTestFile.txt lf -os c:\work\file1.txt. Use the path to your local file that you have used in the tutorial step with the saveTo command.

  12. To display the list of files and directories under the current directory (file system root), enter fileInfos?, or shortened: fi?. The table will contain the 'MyTestFile.txt' file that we have created in the previous step.
    OpcCmd-directoryContents-fileInfosQ.png

  13. Create a subdirectory named 'MyTestDirectory' in the root directory, by entering createSubdirectory MyTestDirectory, or shortened: cs MyTestDirectory.

  14. Copy the file 'MyTestFile.txt' from the root directory to the 'MyTestDirectory' directory and give it a name 'CopyOfMyTestFile.txt', by entering fileInfo MyTestFile.txt copyTo MyTestDirectory/CopyOfMyTestFile.txt, or shortened: fi MyTestFile.txt ct MyTestDirectory/CopyOfMyTestFile.txt.

  15. To display a tree of the objects currently in the file system, enter browseTree or bt. At this point, the tree will contain the original 'MyTestFile.txt' file created, and a 'MyTestDirectory' subdirectory with the file copy, 'CopyOfMyTestFile.txt'.
    OpcCmd-directoryContents-browseTree.png

  16. In order to delete the 'CopyOfMyTestFile.txt' file from 'MyTestDirectory', enter fileInfo MyTestDirectory/CopyOfMyTestFile.txt delete, or shortened: fi MyTestDirectory/CopyOfMyTestFile.txt d.

  17. Enter browseTree or bt again, and verify that the file from the previous step has been deleted.

Other Operations

Other OPC UA File Transfer operations that can be made using OpcCmd, but not shown in this tutorial, include:

  • Moving and renaming files.
  • Refreshig file metadata information.
  • Accessing subdirectories.
  • Deleting directories.
  • Moving and renaming directories.
  • Saving contents of whole directory trees to the local file system.
  • Loading contents of whole directory trees from the local file system.

Comparison with Windows and Linux commands

(TBD)

Commands at the directoryContents> prompt:

Operation Windows command
(CMD)
Linux command
(Bash)
OpcCmd command
(directoryContents prompt)
Change current directory chdir <path> (tbd) directoryContents <path>
Clear the current directory (tbd) (tbd) clear
Clear the specified directory (tbd) (tbd) directoryContents <path> clear
Copy a directory tree xcopy /e <source> <destination> (tbd) directoryContents <source> copyTo <destination>
Copy a file copy <source> <destination> (tbd) fileInfo <source> copyTo <destination>
Create a directory mkdir <path> (tbd) createSubdirectory <path>
Delete a directory rmdir <path> (tbd) directoryContents <path> delete
Delete a file erase <fileName> (tbd) fileInfo <fileName> delete
Display current directory contents dir (tbd) filesInfos?
Display specified directory contents dir <path> (tbd) directoryContents <path> filesInfos?
Move a directory move <source> <destination> (tbd) directoryContents <source> moveTo <destination>
Move a file move <source> <destination> (tbd) fileInfo <source> moveTo <destination>
Obtain file information (tbd) (tbd) fileInfo <fileName> get
Rename a directory rename <oldDirectoryName> <newDirectoryName> (tbd) directoryContents <oldDirectoryName> rename <newDirectoryName>
Rename a file rename <oldFileName> <newFileName> (tbd) fileInfo <oldFileName> rename <newFileName>