node-red-contrib-kukavarproxy

A Node-RED node for communicating with KUKA robots to read or write variables via TCP protocol. This node supports batch variable operations, connection reuse, and detailed debugging logs, making it suitable for industrial automation scenarios.

Development Note

This node was developed with assistance from AI tools to enhance code quality, provide internationalization support, and optimize communication logic with KUKA robots. The core functionality was designed specifically for KUKAVarProxy protocol interactions while maintaining compatibility with standard Node-RED practices.

Features

• Read/Write Variables: Read values from KUKA robot variables or write new values to them.
• Batch Operations: Handle multiple variables in a single request (via array/object input).
• Connection Management: Reuse TCP connections to reduce overhead and improve efficiency.
• Debugging Support: Detailed logs with timestamps for easy troubleshooting.
• Flexible Configuration: Use node settings or dynamic values from input messages.

Installation

Install via Node-RED's Palette Manager:

1. Open Node-RED (usually at http://localhost:1880).
2. Go to Manage Palette > Install.
3. Search for @jesson-lewis/kukavarproxy and click Install.

Or install via npm:

cd ~/.node-red
npm i @jesson-lewis/kukavarproxy

Restart Node-RED after installation.

Node Configuration

Drag the kukavarproxy node from the palette to your flow and double-click it to configure:

| Field | Description | Required | |---------------------|-----------------------------------------------------------------------------|----------| | Name | Custom name for the node (optional). | No | | IP Address | IP address of the KUKA robot or proxy server. | Yes | | Port | TCP port for communication (default: typically 5460 or as per your setup). | Yes | | Variable Name | Default variable name to read/write (ignored if using message variables). | No | | Operation | Default operation: read (read variable) or write (write variable). | Yes | | Value | Default value for write operations (ignored if using message variables). | No | | Use Message Vars| If enabled, use variables from the input message (msg.varname). | No | | Debug | Enable detailed debug logs (recommended for troubleshooting). | No |

Usage Examples

1. Basic Read Operation

Read a single variable using node configuration:

1. Set Operation to read.
2. Enter the variable name (e.g., $OV_PRO) in Variable Name.
3. Connect an input trigger (e.g., Inject node) to the kukavarproxy node.
4. Connect a Debug node to the output to view the result.

Output Example:

{
  "payload": {
    "$OV_PRO": "100" 
  },
  "status": "success"
}

2. Batch Read Operation (Using Message Variables)

Read multiple variables by passing an array in msg.varname:

1. Enable Use Message Vars in the node configuration.
2. Use a Function node to set msg.varname as an array of variables:

   msg.varname = ["$OV_PRO", "$AXIS_ACT", "$POS_ACT", "OUT[2001]"];
   return msg;

3. Connect the Function node to the kukavarproxy node.

Output Example:

{
  "payload": {
    "$OV_PRO": "100",
    "OUT[2001]":"TRUE" 
  },
  "status": "success"
}

3. Basic Write Operation

Write a value to a variable using node configuration:

1. Set Operation to write.
2. Enter the variable name (e.g., OUT[2001]) in Variable Name.
3. Enter the value (e.g., FALSE) in Value.
4. Connect an input trigger to the node.

Output Example:

{
  "payload": {
    "OUT[2001]": "FALSE" }
  },
  "status": "success"
}

4. Batch Write Operation (Using Message Variables)

Write multiple variables by passing an object in msg.varname:

1. Enable Use Message Vars in the node configuration.
2. Use a Function node to set msg.varname as an object (key: variable name, value: value):

   msg.varname = {
     "OUT[2001]": "TRUE",
     "$OV_PRO": "80"
   };
   return msg;

3. Connect the Function node to the kukavarproxy node.

Output Example:

{
  "payload": {
    "OUT[2001]":  "TRUE" ,
    "$OV_PRO":  "80" 
  },
  "status": "success"
}

Error Handling

If an error occurs (e.g., connection timeout, invalid variable), the node will:

• Set msg.status to partial_error (partial failure) or error (total failure).
• Include an error field in msg.payload for the failed variable(s):

  {
    "payload": {
      "$OV_PRO": { "error": "Read timeout (1 second)" }
    },
    "status": "partial_error"
  }

• Show a red status dot on the node and log details in the Node-RED console (if debug is enabled).

Troubleshooting

• "msg.varname must be an array" error: Ensure msg.varname is a valid array when using batch read with Use Message Vars.
• Connection failures: Verify the robot's IP address, port, and network connectivity.
• Unexpected values: Check if the variable name matches the KUKA robot's syntax (case-sensitive).
• Missing node: Restart Node-RED and ensure the node is installed correctly (see Installation).

License

GPL V3 License. See the LICENSE file for details.