# Bosch Rexroth ctrlX Data Layer Input Plugin

This plugin gathers data from the [ctrlX Data Layer][ctrlx] a communication
middleware running on Bosch Rexroth's [ctrlX CORE devices][core_devs]. The
platform is used for professional automation applications like industrial
automation, building automation, robotics, IoT Gateways or as classical PLC.

⭐ Telegraf v1.27.0
🏷️ iot, messaging
💻 all

[ctrlx]: https://ctrlx-automation.com
[core_devs]: https://ctrlx-core.com

## Global configuration options <!-- @/docs/includes/plugin_config.md -->

In addition to the plugin-specific configuration settings, plugins support
additional global and plugin configuration settings. These settings are used to
modify metrics, tags, and field or create aliases and configure ordering, etc.
See the [CONFIGURATION.md][CONFIGURATION.md] for more details.

[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins

## Configuration

```toml @sample.conf
# A ctrlX Data Layer server sent event input plugin
[[inputs.ctrlx_datalayer]]
   ## Hostname or IP address of the ctrlX CORE Data Layer server
   ##  example: server = "localhost"        # Telegraf is running directly on the device
   ##           server = "192.168.1.1"      # Connect to ctrlX CORE remote via IP
   ##           server = "host.example.com" # Connect to ctrlX CORE remote via hostname
   ##           server = "10.0.2.2:8443"    # Connect to ctrlX CORE Virtual from development environment
   server = "localhost"

   ## Authentication credentials
   username = "boschrexroth"
   password = "boschrexroth"

   ## Use TLS but skip chain & host verification
   # insecure_skip_verify = false

   ## Timeout for HTTP requests. (default: "10s")
   # timeout = "10s"


   ## Create a ctrlX Data Layer subscription.
   ## It is possible to define multiple subscriptions per host. Each subscription can have its own
   ## sampling properties and a list of nodes to subscribe to.
   ## All subscriptions share the same credentials.
   [[inputs.ctrlx_datalayer.subscription]]
      ## The name of the measurement. (default: "ctrlx")
      measurement = "memory"

      ## Configure the ctrlX Data Layer nodes which should be subscribed.
      ## address - node address in ctrlX Data Layer (mandatory)
      ## name    - field name to use in the output (optional, default: base name of address)
      ## tags    - extra node tags to be added to the output metric (optional)
      ## Note: 
      ## Use either the inline notation or the bracketed notation, not both.
      ## The tags property is only supported in bracketed notation due to toml parser restrictions
      ## Examples:
      ## Inline notation 
      nodes=[
         {name="available", address="framework/metrics/system/memavailable-mb"},
         {name="used", address="framework/metrics/system/memused-mb"},
      ]
      ## Bracketed notation
      # [[inputs.ctrlx_datalayer.subscription.nodes]]
      #    name   ="available"
      #    address="framework/metrics/system/memavailable-mb"
      #    ## Define extra tags related to node to be added to the output metric (optional)
      #    [inputs.ctrlx_datalayer.subscription.nodes.tags]
      #       node_tag1="node_tag1"
      #       node_tag2="node_tag2"
      # [[inputs.ctrlx_datalayer.subscription.nodes]]
      #    name   ="used"
      #    address="framework/metrics/system/memused-mb"

      ## The switch "output_json_string" enables output of the measurement as json. 
      ## That way it can be used in in a subsequent processor plugin, e.g. "Starlark Processor Plugin".
      # output_json_string = false

      ## Define extra tags related to subscription to be added to the output metric (optional)
      # [inputs.ctrlx_datalayer.subscription.tags]
      #    subscription_tag1 = "subscription_tag1"
      #    subscription_tag2 = "subscription_tag2"

      ## The interval in which messages shall be sent by the ctrlX Data Layer to this plugin. (default: 1s)
      ## Higher values reduce load on network by queuing samples on server side and sending as a single TCP packet.
      # publish_interval = "1s"

      ## The interval a "keepalive" message is sent if no change of data occurs. (default: 60s)
      ## Only used internally to detect broken network connections.
      # keep_alive_interval = "60s"

      ## The interval an "error" message is sent if an error was received from a node. (default: 10s)
      ## Higher values reduce load on output target and network in case of errors by limiting frequency of error messages.
      # error_interval = "10s"

      ## The interval that defines the fastest rate at which the node values should be sampled and values captured. (default: 1s)
      ## The sampling frequency should be adjusted to the dynamics of the signal to be sampled.
      ## Higher sampling frequencies increases load on ctrlX Data Layer.
      ## The sampling frequency can be higher, than the publish interval. Captured samples are put in a queue and sent in publish interval.
      ## Note: The minimum sampling interval can be overruled by a global setting in the ctrlX Data Layer configuration ('datalayer/subscriptions/settings').
      # sampling_interval = "1s"

      ## The requested size of the node value queue. (default: 10)
      ## Relevant if more values are captured than can be sent.
      # queue_size = 10

      ## The behaviour of the queue if it is full. (default: "DiscardOldest")
      ## Possible values: 
      ## - "DiscardOldest"
      ##   The oldest value gets deleted from the queue when it is full.
      ## - "DiscardNewest"
      ##   The newest value gets deleted from the queue when it is full.
      # queue_behaviour = "DiscardOldest"

      ## The filter when a new value will be sampled. (default: 0.0)
      ## Calculation rule: If (abs(lastCapturedValue - newValue) > dead_band_value) capture(newValue).
      # dead_band_value = 0.0

      ## The conditions on which a sample should be captured and thus will be sent as a message. (default: "StatusValue")
      ## Possible values:
      ## - "Status"
      ##   Capture the value only, when the state of the node changes from or to error state. Value changes are ignored.
      ## - "StatusValue" 
      ##   Capture when the value changes or the node changes from or to error state.
      ##   See also 'dead_band_value' for what is considered as a value change.
      ## - "StatusValueTimestamp": 
      ##   Capture even if the value is the same, but the timestamp of the value is newer.
      ##   Note: This might lead to high load on the network because every sample will be sent as a message
      ##   even if the value of the node did not change.
      # value_change = "StatusValue"
      
```

## Metrics

All measurements are tagged with the server address of the device and the
corresponding node address as defined in the ctrlX Data Layer.

- measurement name
  - tags:
    - `source` (ctrlX Data Layer server where the metrics are gathered from)
    - `node` (Address of the ctrlX Data Layer node)
  - fields:
    - `{name}` (for nodes with simple data types)
    - `{name}_{index}`(for nodes with array data types)
    - `{name}_{jsonflat.key}` (for nodes with object data types)

### Output Format

The switch "output_json_string" determines the format of the output metric.

#### Output default format

With the output default format

```toml
output_json_string=false
```

the output is formatted automatically as follows depending on the data type:

##### Simple data type

The value is passed 'as it is' to a metric with pattern:

```text
{name}={value}
```

Simple data types of ctrlX Data Layer:

```text
bool8,int8,uint8,int16,uint16,int32,uint32,int64,uint64,float,double,string,timestamp
```

##### Array data type

Every value in the array is passed to a metric with pattern:

```text
{name}_{index}={value[index]}
```

example:

```text
myarray=[1,2,3] -> myarray_1=1, myarray_2=2, myarray_3=3
```

Array data types of ctrlX Data Layer:

```text
arbool8,arint8,aruint8,arint16,aruint16,arint32,aruint32,arint64,aruint64,arfloat,ardouble,arstring,artimestamp
```

##### Object data type (JSON)

Every value of the flattened json is passed to a metric with pattern:

```text
{name}_{jsonflat.key}={jsonflat.value}
```

example:

```text
myobj={"a":1,"b":2,"c":{"d": 3}} -> myobj_a=1, myobj_b=2, myobj_c_d=3
```

#### Output JSON format

With the output JSON format

```toml
output_json_string=true
```

the output is formatted as JSON string:

```text
{name}="{value}"
```

examples:

```text
input=true -> output="true"
```

```text
input=[1,2,3] -> output="[1,2,3]"
```

```text
input={"x":4720,"y":9440,"z":{"d": 14160}} -> output="{\"x\":4720,\"y\":9440,\"z\":14160}"
```

The JSON output string can be passed to a processor plugin for transformation
e.g. [Parser Processor Plugin][PARSER.md]
or [Starlark Processor Plugin][STARLARK.md]

[PARSER.md]: ../../processors/parser/README.md
[STARLARK.md]: ../../processors/starlark/README.md

example:

```toml
[[inputs.ctrlx_datalayer.subscription]]
   measurement = "osci"
   nodes = [
     {address="oscilloscope/instances/Osci_PLC/rec-values/allsignals"},
   ]
   output_json_string = true

[[processors.starlark]]
   namepass = [
      'osci',
   ]
   script = "oscilloscope.star"
```

## Troubleshooting

This plugin was contributed by
[Bosch Rexroth](https://www.boschrexroth.com).
For questions regarding ctrlX AUTOMATION and this plugin feel
free to check out and be part of the
[ctrlX AUTOMATION Community](https://ctrlx-automation.com/community)
to get additional support or leave some ideas and feedback.

Also, join
[InfluxData Community Slack](https://influxdata.com/slack) or
[InfluxData Community Page](https://community.influxdata.com/)
if you have questions or comments for the telegraf engineering teams.

## Example Output

The plugin handles simple, array and object (JSON) data types.

### Example with simple data type

Configuration:

```toml
[[inputs.ctrlx_datalayer.subscription]]
   measurement="memory"
   [inputs.ctrlx_datalayer.subscription.tags]
      sub_tag1="memory_tag1"
      sub_tag2="memory_tag2"

   [[inputs.ctrlx_datalayer.subscription.nodes]]
      name   ="available"
      address="framework/metrics/system/memavailable-mb"
      [inputs.ctrlx_datalayer.subscription.nodes.tags]
         node_tag1="memory_available_tag1"
         node_tag2="memory_available_tag2"

   [[inputs.ctrlx_datalayer.subscription.nodes]]
      name   ="used"
      address="framework/metrics/system/memused-mb"
      [inputs.ctrlx_datalayer.subscription.nodes.tags]
         node_tag1="memory_used_node_tag1"
         node_tag2="memory_used_node_tag2"
```

Source:

```json
"framework/metrics/system/memavailable-mb" : 365.93359375
"framework/metrics/system/memused-mb" : 567.67578125
```

Metrics:

```text
memory,source=192.168.1.1,host=host.example.com,node=framework/metrics/system/memavailable-mb,node_tag1=memory_available_tag1,node_tag2=memory_available_tag2,sub_tag1=memory2_tag1,sub_tag2=memory_tag2 available=365.93359375 1680093310249627400
memory,source=192.168.1.1,host=host.example.com,node=framework/metrics/system/memused-mb,node_tag1=memory_used_node_tag1,node_tag2=memory_used_node_tag2,sub_tag1=memory2_tag1,sub_tag2=memory_tag2 used=567.67578125 1680093310249667600
```

### Example with array data type

Configuration:

```toml
[[inputs.ctrlx_datalayer.subscription]]
   measurement="array"
   nodes=[
      { name="ar_uint8", address="alldata/dynamic/array-of-uint8"},
      { name="ar_bool8", address="alldata/dynamic/array-of-bool8"},
   ]
```

Source:

```json
"alldata/dynamic/array-of-bool8" : [true, false, true]
"alldata/dynamic/array-of-uint8" : [0, 255]
```

Metrics:

```text
array,source=192.168.1.1,host=host.example.com,node=alldata/dynamic/array-of-bool8 ar_bool8_0=true,ar_bool8_1=false,ar_bool8_2=true 1680095727347018800
array,source=192.168.1.1,host=host.example.com,node=alldata/dynamic/array-of-uint8 ar_uint8_0=0,ar_uint8_1=255 1680095727347223300
```

### Example with object data type (JSON)

Configuration:

```toml
[[inputs.ctrlx_datalayer.subscription]]
   measurement="motion"
   nodes=[
      {name="linear", address="motion/axs/Axis_1/state/values/actual"},
      {name="rotational", address="motion/axs/Axis_2/state/values/actual"},
   ]
```

Source:

```json
"motion/axs/Axis_1/state/values/actual" : {"actualPos":65.249329860957,"actualVel":5,"actualAcc":0,"actualTorque":0,"distLeft":0,"actualPosUnit":"mm","actualVelUnit":"mm/min","actualAccUnit":"m/s^2","actualTorqueUnit":"Nm","distLeftUnit":"mm"}
"motion/axs/Axis_2/state/values/actual" : {"actualPos":120,"actualVel":0,"actualAcc":0,"actualTorque":0,"distLeft":0,"actualPosUnit":"deg","actualVelUnit":"rpm","actualAccUnit":"rad/s^2","actualTorqueUnit":"Nm","distLeftUnit":"deg"}
```

Metrics:

```text
motion,source=192.168.1.1,host=host.example.com,node=motion/axs/Axis_1/state/values/actual linear_actualVel=5,linear_distLeftUnit="mm",linear_actualAcc=0,linear_distLeft=0,linear_actualPosUnit="mm",linear_actualAccUnit="m/s^2",linear_actualTorqueUnit="Nm",linear_actualPos=65.249329860957,linear_actualVelUnit="mm/min",linear_actualTorque=0 1680258290342523500
motion,source=192.168.1.1,host=host.example.com,node=motion/axs/Axis_2/state/values/actual rotational_distLeft=0,rotational_actualVelUnit="rpm",rotational_actualAccUnit="rad/s^2",rotational_distLeftUnit="deg",rotational_actualPos=120,rotational_actualVel=0,rotational_actualAcc=0,rotational_actualPosUnit="deg",rotational_actualTorqueUnit="Nm",rotational_actualTorque=0 1680258290342538100
```

If `output_json_string` is set in the configuration:

```toml
  output_json_string = true
```

then the metrics will be generated like this:

```text
motion,source=192.168.1.1,host=host.example.com,node=motion/axs/Axis_1/state/values/actual linear="{\"actualAcc\":0,\"actualAccUnit\":\"m/s^2\",\"actualPos\":65.249329860957,\"actualPosUnit\":\"mm\",\"actualTorque\":0,\"actualTorqueUnit\":\"Nm\",\"actualVel\":5,\"actualVelUnit\":\"mm/min\",\"distLeft\":0,\"distLeftUnit\":\"mm\"}" 1680258290342523500
motion,source=192.168.1.1,host=host.example.com,node=motion/axs/Axis_2/state/values/actual rotational="{\"actualAcc\":0,\"actualAccUnit\":\"rad/s^2\",\"actualPos\":120,\"actualPosUnit\":\"deg\",\"actualTorque\":0,\"actualTorqueUnit\":\"Nm\",\"actualVel\":0,\"actualVelUnit\":\"rpm\",\"distLeft\":0,\"distLeftUnit\":\"deg\"}" 1680258290342538100
```