Debugging a protocol plug-in by running the plug-in server and the plug-in on the IBM Watson IoT Platform - Message Gateway server

You can debug your protocol plug-in by running the plug-in server and your plug-in on your IBM® Watson IoT Platform - Message Gateway server.

Before you begin

Download and extract the contents of the SDK bundle. Then, follow the instructions in ImaTools/ImaPlugin/README.txt to import the sample plug-in projects that are provided with the SDK bundle.

About this task

After the first phase of development is finished, you must test your production protocol plug-in by installing it and running it on your IBM Watson IoT Platform - Message Gateway server. If you encounter unexpected problems while you run in that environment, you can use the second debugging approach to connect to the plug-in server that runs on the server. When you debug during this phase, you must create a new plug-in zip file and reinstall it on the IBM Watson IoT Platform - Message Gateway server each time that you make updates to your plug-in classes.

For more information about how to debug your protocol plug-in in the first phase of development, see Debugging a protocol plug-in by running the plug-in server in Eclipse.

Procedure

Deploy the plug-in on the IBM Watson IoT Platform - Message Gateway server and configure the server to enable remote debugging from Eclipse:
1. Create a standard .zip archive file with the plugin.json descriptor file and the JAR files that implement the plug-in. For more information, see Developing a protocol plug-in.
2. Install the plug-in .zip file on your IBM Watson IoT Platform - Message Gateway server. For more information, see Configuring protocol plug-ins.
3. Ensure that the PluginDebugServer property is not set by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:
  http://<admin-endpoint-IP:Port>/ima/v1/configuration/
  Provide PluginDebugServer object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.
```
{    
  "PluginDebugServer": ""
}
```
4. Set the PluginDebugPort property to the port that Eclipse is using for remote debugging by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:
  http://<admin-endpoint-IP:Port>/ima/v1/configuration/
  Provide PluginDebugPort object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.
```
{    
  "PluginDebugPort": 8000
}
```
  Note: The value that is specified for the PluginDebugPort must match the port value that is specified for the Eclipse remote debugger configuration in Step 2e.
  Tip: You can check the value of the PluginDebugPort object by using the IBM Watson IoT Platform - Message Gateway REST API GET method with the following IBM Watson IoT Platform - Message Gateway configuration URI:
  http://<admin-endpoint-IP:Port>/ima/v1/configuration/PluginDebugPort
5. Stop and restart the server by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:
  http://<admin-endpoint-IP:port>/ima/v1/service/restart
  Provide configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.
```
{    
  "Service": "Server"
}
```
Start the Eclipse remote Java™ debugger for the plug-in server that runs on the IBM Watson IoT Platform - Message Gateway server.
1. In Eclipse, from the Run menu, select Debug Configurations...
2. Right-click Remote Java Application and select New
3. In the Name field, enter ImaPluginOnMessageGateway
4. In the Host field, enter the IP address of the server
5. In the Port field, enter 8000
  
  Note: This port value must match the PluginDebugPort that was set for the IBM Watson IoT Platform - Message Gateway server in step 1d.
6. Select the Source tab and click Add
7. Select Java Project and click OK
8. Select the project where the plug-in that you want to debug is and click OK
9. Click Apply
10. Click Debug
Set breakpoints in your plug-in source code and debug it by using the client applications for the protocol that is implemented in your plug-in.
Optional: If you stop the IBM Watson IoT Platform - Message Gateway server after you start debugging, or if you stop the remote Java debugger, you must restart both processes:
1. On the IBM Watson IoT Platform - Message Gateway server, stop and restart the server by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:
  http://<admin-endpoint-IP:port>/ima/v1/service/restart
  Provide configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.
```
{    
  "Service": "Server"
}
```
2. In Eclipse, from the Run menu, select Debug Configurations..
3. Find Remote Java Application and select ImaPlugInOnMessageGateway. Then, click Debug.

What to do next

When you complete this phase of debugging, reset the PluginDebugPort object on the IBM Watson IoT Platform - Message Gateway server. Use the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:
http://<admin-endpoint-IP:Port>/ima/v1/configuration/
Provide PluginDebugPort object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.
```
{    
  "PluginDebugPort": 0
}
```