Added documentation to new options

Author: aljoshakoecher

README.md

@@ -32,22 +32,42 @@ The PLC2Skill library has to be imported into a PLC program. Skills can then be
 There are three different ways to use the PLC2Skill Mapper. You can either use it locally as a command line application, run it as a web-service or integrate it into your application as a library.
 
 ### CLI
-Download the current `cli-x.x.x-jar-with-dependencies.jar` from the releases into a folder of your choice. Inside that folder, open a shell and execute `java -jar cli-x.x.x-jar -f <PLCopen XML file you want to map> -e <endpointURL of your PLC> -n <root component of the PLC project>`. The mapping result will be written to a file right next to the cli.jar.<br>
+Download the current `cli-x.x.x-jar-with-dependencies.jar` from the releases into a folder of your choice. Inside that folder, open a shell and execute `java -jar cli-x.x.x-jar -f <PLCopen XML file you want to map> -e <endpointURL of your PLC>`. The mapping result will be written to a file right next to the cli.jar.<br>
 A Short description of the CLI arguments:
 - -f / --file: The path to the PLCopen XML file that needs to be exported in the previous step
 - -e / --endpointUrl: The endpointUrl of the OPC UA server running on the PLC. This is typically something like "opc.tcp://" + IP address of your PLC + ":" + Port of the UA server (default is 4840). So for UA server running on localhost with the default port, this argument would have to be set to "opc.tcp://localhost:4840".
-- n / --nodeIdRoot: This one is a bit more tricky than the two before. Unfortunately, PLC open XML does not preserve all information about the PLC project. Information of the root parts of the projects are not exported. This information is often used to create node IDs for UA variables. These node IDs are needed in order to execute a skill via OPC UA. So in order for the PLC2Skill Mapper to create all node IDs, the missing root part of all node IDs has to be presented. You can determine this root component by comparing your PLC project in your programming environment to the root element in the exported PLC open XML file. A more detailed guide on how to determine this root component will follow soon...
+- -u / --user: (Optional) OPC UA user name in case there is no anonymous access. Has to be set if the server requires authentication, otherwise the connection will fail.
+- p / --password: (Optional) Password for the given OPC UA user. Has to be set if the server requires authentication, otherwise the connection will fail.
+- n / --nodeIdRoot: (Optional) A PlcOpen XML doesn't contain complete OPC UA nodeIds. Information of the root parts of the projects are not exported. This information is often used to create node IDs for UA variables. These node IDs are needed in order to execute a skill via OPC UA. So in order for the PLC2Skill Mapper to create all node IDs, the missing root part of all node IDs has to be presented.
+Plc2Skill connects to the server and tries to browse for the nodes by their local names / browse names and resolve the proper nodeIds. Instead of browsing the server, you can also enter the missing prefix of the nodeIds. You can determine this root component by comparing your PLC project in your programming environment to the root element in the exported PLC open XML file. Passing `-n` can help in case you cannot connect to the server or Plc2Skill fails in resolving the nodeIds. 
 
 ### REST-API
 Download the current `rest-api-x.x.x-jar-with-dependencies.jar` from the releases into a folder of your choice and from a shell, run `java -jar rest-api-x.x.x-jar-with-dependencies.jar`. This will start a web server and you can send HTTP POST request to `localhost:9191` to invoke the mapper. When creating the request, make sure to set the `Content-Type` header to `multipart/form-data`. Furthermore, the following information have to be sent inside the request body:
 -  Key: "plc-file" - Value: The PLCopen XML file that should be mapped
 -  Key: "endpointUrl" - Value: The endpoint URL of the PLC's OPC UA server (see above) as a string.
+-  Key: "user" - Value: The endpoint URL of the PLC's OPC UA server (see above) as a string.
+-  Key: "password" - Value: The endpoint URL of the PLC's OPC UA server (see above) as a string.
 -  Key: "nodeIdRoot" - Value: The root component of all node IDs (see above) as a string.
 
 The REST-API can be tested with Tools such as Postman and used e.g. by web applications. Our skill based control system interacts with the PLC2Skill Mapper via the REST API.
 
 ### Library
-You can also include the mapping library which is used in both the CLI-application and REST API in your own projects. In order to do so, import `Plc2SkillMapper` and after obtaining a new instance of the mapper, use `executeMapping(<endpointUr>,<nodeIdRoot>, <Path to your MTP file>)`. A more detailed instruction on how to use the library will follow soon.
+You can also include the mapping library which is used in both the CLI-application and REST API in your own projects. In order to do so, import `Plc2SkillMapper` and after create a new instance of the mapper using its builder. After creating an instance, you can simply call `executeMapping()` to get the mapping result as a String.
+```Java
+Path mappingPath = Paths.get("<path to your mapping>").toAbsolutePath();
+String endpointUrl = "opc.tcp://<your IP>:<your port>"; // default port of OPC UA is 4840 
+String user = "<username>";
+String pw = "<password>";
+// Instead of letting Plc2Skill browse for the nodeIds, you can also pass the missing root part in case you know it 
+// String nodeIdRoot = "|var|CODESYS Control Win V3 x64";
+
+Plc2SkillMapper mapper = new Plc2SkillMapper.Builder(mappingPath, endpointUrl)
+				.setUser(userName, password)
+             // .setNodeIdRoot(nodeIdRoot)              // In case you want to pass nodeIdRoot manually
+				.build();
+		
+String result = mapper.executeMapping();
+```
 
 ## How to cite
 We are excited about everyone using PLC2Skill in their own applications. If you use PLC2Skill in research, please consider giving credit by citing the following paper: