Skip to content

Latest commit

 

History

History
427 lines (349 loc) · 16.3 KB

examples.md

File metadata and controls

427 lines (349 loc) · 16.3 KB

Examples

Real runs of ethernetipctl against its own simulated adapter, generated by scripts/examples.sh (make examples): the adapter runs as ethernetipctl adapter --listen 127.0.0.1 --io-address 127.0.0.1:2223 --echo --logix (its I/O on 2223: the commands' I/O endpoint takes 2222 on the same host), and every command and its output below are as they were printed (stdout and stderr together). Timings, session handles and serial numbers change from run to run; with a real device, replace 127.0.0.1 by its address.

Discover and identify

One ListIdentity datagram to one address (a broadcast address reaches every device of a segment), then the identity of one device.

Discover

$ ethernetipctl discover --address 127.0.0.1 --wait 500ms
ListIdentity to 127.0.0.1:44818: 1 device(s) in 502 ms
  127.0.0.1:44818       "ethernetipctl adapter" (vendor 65535 -, Communications Adapter, product 1, rev 1.1, serial 0x00000001)

Discover, as a table

$ ethernetipctl discover --address 127.0.0.1 --wait 500ms --format table
ADDRESS          PRODUCT                VENDOR  DEVICE_TYPE             PRODUCT_CODE  REVISION  SERIAL      STATE
-                -                      -       -                       -             -         -           -
127.0.0.1:44818  ethernetipctl adapter  65535   Communications Adapter  1             1.1       0x00000001  operational

Identify

$ ethernetipctl identify 127.0.0.1
Identity of 127.0.0.1:44818 (in 1 ms)
ListIdentity:
  protocol version: 1
  socket:         127.0.0.1:44818
  product name:   "ethernetipctl adapter"
  vendor:         65535 (-)
  device type:    12 (Communications Adapter)
  product code:   1
  revision:       1.1
  serial number:  0x00000001
  status:         0x0000 -
  state:          3 (operational)
Identity object (Get_Attributes_All @1/1):
  product name:   "ethernetipctl adapter"
  vendor:         65535 (-)
  device type:    12 (Communications Adapter)
  product code:   1
  revision:       1.1
  serial number:  0x00000001
  status:         0x0000 -

Status in one line

$ ethernetipctl status 127.0.0.1
127.0.0.1:44818: ok  state 3 operational  status 0x0000 -  "ethernetipctl adapter" (vendor 65535 -, Communications Adapter, product 1, rev 1.1, serial 0x00000001)  (0.1 ms)

Services

$ ethernetipctl services 127.0.0.1
ListServices of 127.0.0.1:44818: 1 service(s)
  Communications   version 1  capabilities 0x0120  tcp=true udp=true

Attributes and objects

Get_Attribute_Single, Get_Attributes_All, Set_Attribute_Single; unconnected or over a Class 3 connection.

Read the product name, decoded

$ ethernetipctl read 127.0.0.1 @1/1/7 --type SHORT_STRING
Read @1/1/7 (Identity) Get_Attribute_Single at 127.0.0.1:44818: 22 octets in 0.1 ms
  data:           15 65 74 68 65 72 6e 65 74 69 70 63 74 6c 20 61 64 61 70 74 65 72
  value:          SHORT_STRING "ethernetipctl adapter"

Read it over a Class 3 connection

$ ethernetipctl read 127.0.0.1 @1/1/7 --type SHORT_STRING --connected
Read @1/1/7 (Identity) Get_Attribute_Single at 127.0.0.1:44818 (connected): 22 octets in 0.1 ms
  data:           15 65 74 68 65 72 6e 65 74 69 70 63 74 6c 20 61 64 61 70 74 65 72
  value:          SHORT_STRING "ethernetipctl adapter"

Read a whole object

$ ethernetipctl read 127.0.0.1 @1/1 --all
Read @1/1 (Identity) Get_Attributes_All at 127.0.0.1:44818: 36 octets in 0.1 ms
  data:           ff ff 0c 00 01 00 01 01 00 00 01 00 00 00 15 65 74 68 65 72 6e 65 74 69 70 63 74 6c 20 61 64 61 70 74 65 72

An attribute the device does not have

$ ethernetipctl read 127.0.0.1 @1/1/99
error: the target refused the request: Get_Attribute_Single @1/1/99: attribute not supported (0x14)
$ echo $?
6

The same error as JSON

$ ethernetipctl read 127.0.0.1 @1/1/99 --format json
{
  "error": {
    "kind": "refused",
    "code": "attribute_not_supported",
    "message": "the target refused the request: Get_Attribute_Single @1/1/99: attribute not supported (0x14)",
    "cip_status": 20
  }
}
$ echo $?
6

The object list

$ ethernetipctl objects 127.0.0.1
Objects of 127.0.0.1:44818 (Message Router @2/1/1): 10 classes
  0x01       1  Identity
  0x02       2  Message Router
  0x04       4  Assembly
  0x06       6  Connection Manager
  0x64     100  Program Name (Rockwell)
  0x6B     107  Symbol (Rockwell)
  0x6C     108  Template (Rockwell)
  0xF4     244  Port
  0xF5     245  TCP/IP Interface
  0xF6     246  Ethernet Link

One object

$ ethernetipctl object 127.0.0.1 identity
Class 0x01 Identity at 127.0.0.1:44818
Class attributes (instance 0):
   1 revision               1 (01 00)
   2 max_instance           1 (01 00)
   3 number_of_instances    1 (01 00)
   6 max_class_attribute    7 (07 00)
   7 max_instance_attribute 8 (08 00)
Instance 1 (Get_Attributes_All):
  ff ff 0c 00 01 00 01 01 00 00 01 00 00 00 15 65 74 68 65 72 6e 65 74 69 70 63 74 6c 20 61 64 61 70 74 65 72

A write without --yes changes nothing

$ ethernetipctl write 127.0.0.1 @4/150/3 --data 0102030405060708091011121314151617181920212223242526272829303132
error: write changes the target: add --yes to confirm (nothing was sent)
$ echo $?
2

A write

$ ethernetipctl write 127.0.0.1 @4/150/3 --data 0102030405060708091011121314151617181920212223242526272829303132 --yes
Wrote @4/150/3 (Assembly) Set_Attribute_Single at 127.0.0.1:44818: 32 octets in 0.1 ms
  data:           01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

Its echo in the input assembly

$ ethernetipctl assembly read 127.0.0.1 100
Read @4/100/3 (Assembly) Get_Attribute_Single at 127.0.0.1:44818: 32 octets in 0.1 ms
  data:           01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

Connections and I/O

Forward_Open tests, an input-only connection streaming inputs, an exclusive owner writing outputs, the Connection Manager counters.

Test a Forward_Open

$ ethernetipctl forward-open 127.0.0.1 --config 151 --output 150 --input 100 --output-size 32 --input-size 32 --rpi 10ms
Forward_Open to 127.0.0.1:44818 accepted in 0.1 ms (class 1 cyclic, O->T 38 octets, T->O 34 octets)
  class:          1
  O->T conn ID:   0x846B67D9
  T->O conn ID:   0x8771401F
  triad:          serial 19005 vendor 65535 originator 3839162013
  API:            O->T 10 ms, T->O 10 ms
  path:           [class 0x04] [instance 151] [point 150] [point 100]
closed again with Forward_Close

A Forward_Open the device refuses (wrong size)

$ ethernetipctl forward-open 127.0.0.1 --config 151 --output 150 --input 100 --output-size 31 --input-size 32 --rpi 10ms
error: the target refused the request: Forward_Open @6/1: connection failure (0x01), extended 0x0127 (invalid O->T size) 0x0026
$ echo $?
6

Watch the inputs through an input-only connection

$ ethernetipctl io 127.0.0.1 --config 151 --output 152 --input 100 --input-size 32 --rpi 100ms --duration 350ms
I/O connection to 127.0.0.1:44818 open: O->T 0x130BC748, T->O 0xDF7BFDA3, API 100ms/100ms, path [class 0x04] [instance 151] [point 152] [point 100]
2026-10-26T19:46:28.356Z  #1      run   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
1 sample(s) written; sent 4, received 4, dropped 0, duplicates 3; state connected

Exclusive owner writing outputs, as JSON Lines

$ ethernetipctl io 127.0.0.1 --config 151 --output 150 --input 100 --output-size 32 --input-size 32 --rpi 100ms --duration 250ms --output-data aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899 --yes --format json
I/O connection to 127.0.0.1:44818 open: O->T 0x7D267B75, T->O 0x2FF82C15, API 100ms/100ms, path [class 0x04] [instance 151] [point 150] [point 100]
{"received_at":"2026-10-26T19:46:28.743Z","seq":1,"run":true,"size":32,"data":"0102030405060708091011121314151617181920212223242526272829303132"}
{"received_at":"2026-10-26T19:46:28.844Z","seq":2,"run":true,"size":32,"data":"aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"}
2 sample(s) written; sent 3, received 3, dropped 0, duplicates 1; state connected

Connection Manager counters

$ ethernetipctl connections 127.0.0.1
Connections of 127.0.0.1:44818
  active:         0
  maximum:        128
Connection Manager counters:
  open_requests            5
  open_format_rejects      0
  open_resource_rejects    0
  open_other_rejects       1
  close_requests           4
  close_format_rejects     0
  close_other_rejects      0
  connection_timeouts      0

Diagnose

$ ethernetipctl diagnose 127.0.0.1
Diagnosis of 127.0.0.1:44818: 8 passed, 0 failed, 0 skipped in 2 ms
  OK      tcp-connect               0.3 ms  address=127.0.0.1:44818
  OK      register-session          0.2 ms  session=0xAC9D44A4
  OK      list-identity             0.1 ms  product_name=ethernetipctl adapter revision=1.1 state=operational status=0x0000 vendor_id=65535
  OK      list-services             0.1 ms  services=Communications
  OK      identity                  0.3 ms  product_code=1 product_name=ethernetipctl adapter serial_number=0x00000001
  OK      tcpip-interface           0.3 ms  gateway=0.0.0.0 ip=127.0.0.1 mask=0.0.0.0 status=1
  OK      ethernet-link             0.2 ms  full_duplex=true link_active=true mac=00:00:00:00:00:00 speed_mbps=100
  OK      connection-manager        0.6 ms  close_format_rejects=0 close_other_rejects=0 close_requests=4 connection_timeouts=0 open_format_rejects=0 open_other_rejects=1 open_requests=5 open_resource_rejects=0

Logix tags (Rockwell, vendor specific)

The adapter's --logix tag database: atomic, array, STRING and structure tags.

The tag list

$ ethernetipctl tag list 127.0.0.1
Tags of controller scope at 127.0.0.1:44818: 6 (project "OTFabric")
  Count                            DINT             instance 1
  Speed                            REAL             instance 2
  Flags                            DINT             instance 3
  Values[10]                       INT              instance 4
  Name                             STRING           instance 5
  Motors[2]                        Motor            instance 6

Read a tag

$ ethernetipctl tag read 127.0.0.1 Count
Count = DINT[1] at 127.0.0.1:44818 in 0.1 ms
  [0] 42

Write it

$ ethernetipctl tag write 127.0.0.1 Count --type DINT --value 42 --yes
Wrote Count = DINT[1] {42} at 127.0.0.1:44818 in 0.1 ms

Read it back as JSON

$ ethernetipctl tag read 127.0.0.1 Count --format json
{
  "target": "127.0.0.1:44818",
  "connected": false,
  "tag": "Count",
  "type": "DINT",
  "count": 1,
  "data": "2a000000",
  "values": [
    42
  ],
  "rtt_ms": 0.103
}

Read part of an array

$ ethernetipctl tag read 127.0.0.1 Values\[2\] --count 4
Values[2] = INT[4] at 127.0.0.1:44818 in 0.2 ms
  [0] 2
  [1] 3
  [2] 4
  [3] 5

Set one bit

$ ethernetipctl tag write 127.0.0.1 Flags.3 --type DINT --value 1 --yes
Wrote Flags.3 = DINT[1] {1} at 127.0.0.1:44818 in 0.1 ms

A STRING

$ ethernetipctl tag read 127.0.0.1 Name
Name = STRING[1] at 127.0.0.1:44818 in 0.1 ms
  [0] "line 1"

A structure's template

$ ethernetipctl tag types 127.0.0.1 0x123
Template 0x0123 Motor at 127.0.0.1:44818: handle 0xBEEF, 112 octets, 5 members
  Speed                    REAL             offset 0    info 0
  Count                    DINT[4]          offset 4    info 4
  ZZZZZZZZZZMotor0         SINT             offset 20   info 0 (hidden)
  Running                  BOOL             offset 20   info 0
  Name                     STRING           offset 24   info 0

A structure, decoded

$ ethernetipctl tag decode 127.0.0.1 Motors\[1\]
Motors[1] = Motor[1] (handle 0xBEEF) at 127.0.0.1:44818 in 0.2 ms
  Speed                REAL     0
  Count                DINT     [0 0 0 0]
  Running              BOOL     false
  Name                 STRING   ""

EDS files

Inspect, validate and generate Electronic Data Sheets.

Inspect

$ ethernetipctl eds inspect testdata/otfabric_adapter.eds
testdata/otfabric_adapter.eds: "e2e adapter" rev 3.7, vendor 65535 (OT Fabric), Communications Adapter (type 12), product code 42
  catalog:        OTF-EIP-1
  sections:       File, Device, Device Classification, Params, Assembly, Connection Manager, Port
  validation:     0 error(s), 0 warning(s)
Parameters (5):
  Param1   "RPI"                    UDINT  1000..3600000000 default 10000 us
  Param2   "Speed setpoint"         UINT   0..3000 default 1500 rpm
  Param3   "Mode"                   SINT   0..2 default 0 
  Param4   "Temperature"            REAL   -40..125 default 20 degC
  Param5   "Padding"                USINT  0..0 default 0 
Assemblies (5):
  Assem100 "Input"                  instance 100  32 octets, 1 members
  Assem150 "Output"                 instance 150  32 octets, 1 members
  Assem151 "Configuration"          instance 151  10 octets, 5 members
  Assem152 "Input only heartbeat"   instance 152  0 octets, 0 members
  Assem153 "Listen only heartbeat"  instance 153  0 octets, 0 members
Connections (3):
  Connection1  "Exclusive owner"        class 1  O->T 32 octets, T->O 32 octets  RPI Param1  path [class 0x04] [instance 151] [point 150] [point 100]
  Connection2  "Input only"             class 1  O->T 0 octets, T->O 32 octets  RPI Param1  path [class 0x04] [instance 151] [point 152] [point 100]
  Connection3  "Listen only"            class 1  O->T 0 octets, T->O 32 octets  RPI Param1  path [class 0x04] [instance 151] [point 153] [point 100]

Validate a broken file

$ ethernetipctl eds validate testdata/invalid.eds
testdata/invalid.eds: INVALID, 4 error(s), 1 warning(s)
  error   line 4    [File] CreateDate "13-45-2026" is not a date (mm-dd-yyyy)
  error   line 5    [File] CreateTime "25:00:00" is not a time (hh:mm:ss)
  error   line 13   [Device] ProdCode: not a 16-bit number: banana
  error   line 19   [Assembly] Assem100: member Param9 does not exist
  warning line 0    [Device Classification] no [Device Classification] section (EtherNetIP)
$ echo $?
3

The simulated adapter's events

What the adapter printed while the examples above ran (its stdout, one line per event; --format json writes JSON Lines), without the connected and disconnected events of each command's session.

$ ethernetipctl adapter --listen 127.0.0.1 --io-address 127.0.0.1:2223 --echo --logix
2026-10-26T19:46:26.914Z  listening           address=127.0.0.1:44818  detail=io 127.0.0.1:2223 udp 127.0.0.1:44818
2026-10-26T19:46:28.202Z  connection-opened   remote=127.0.0.1:55920  connection=class3 ot=0xB7D7DB1A to=0xF129A143 serial=9239 path=@2/1
2026-10-26T19:46:28.202Z  connection-closed   remote=127.0.0.1  connection=class3 ot=0xB7D7DB1A to=0xF129A143 serial=9239 path=@2/1
2026-10-26T19:46:28.302Z  assembly-write      instance=150  size=32  data=0102030405060708091011121314151617181920212223242526272829303132  run=true
2026-10-26T19:46:28.330Z  connection-opened   remote=127.0.0.1:55928  connection=class1 ot=0x846B67D9 to=0x8771401F serial=19005 path=[class 0x04] [instance 151] [point 150] [point 100]
2026-10-26T19:46:28.331Z  connection-closed   remote=127.0.0.1  connection=class1 ot=0x846B67D9 to=0x8771401F serial=19005 path=[class 0x04] [instance 151] [point 150] [point 100]
2026-10-26T19:46:28.356Z  connection-opened   remote=127.0.0.1:55930  connection=class1 ot=0x130BC748 to=0xDF7BFDA3 serial=35852 path=[class 0x04] [instance 151] [point 152] [point 100]
2026-10-26T19:46:28.710Z  connection-closed   remote=127.0.0.1  connection=class1 ot=0x130BC748 to=0xDF7BFDA3 serial=35852 path=[class 0x04] [instance 151] [point 152] [point 100]
2026-10-26T19:46:28.743Z  connection-opened   remote=127.0.0.1:55931  connection=class1 ot=0x7D267B75 to=0x2FF82C15 serial=3667 path=[class 0x04] [instance 151] [point 150] [point 100]
2026-10-26T19:46:28.743Z  assembly-write      instance=150  size=32  data=aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899  run=true
2026-10-26T19:46:28.994Z  connection-closed   remote=127.0.0.1  connection=class1 ot=0x7D267B75 to=0x2FF82C15 serial=3667 path=[class 0x04] [instance 151] [point 150] [point 100]
2026-10-26T19:46:29.102Z  tag-write           tag=Count
2026-10-26T19:46:29.155Z  tag-write           tag=Flags