EIPScanner

The ParameterObject class provides a standardized way to access data and configuration from a CIP (Common Industrial Protocol) device.

To use ParameterObject effectively, you must first determine two things from the device:

1. The Instance ID of the parameters (or the total count of parameters available).
2. Attribute Support: Whether the device supports full attributes (such as string descriptions and scaling) by checking the CLASS_DESCRIPTOR.

Once initialized, ParameterObject instances can be used to retrieve parameter types, names, units, and both actual and engineering values.

// Example of creating a vector of ParameterObjects after discovering device capabilities
std::vector<ParameterObject> parameters;
parameters.reserve(paramsCount);
for (int i = 0; i < paramsCount; ++i) {
    // Parameters are typically 1-indexed
    parameters.emplace_back(i + 1, allAttributes, si);
}

Implicit messaging (IO connections) in EtherNet/IP allows a scanner and an adapter to exchange data periodically or upon change via UDP.

In EIPScanner, this is managed through two primary classes:

1. ConnectionManager: Responsible for establishing and managing the lifecycle of IO connections. It uses the forwardOpen method to initiate connections.
2. IOConnection: Returned by forwardOpen (as a weak pointer), this object is used to send data to the adapter and register listeners for incoming data and connection closure events.

To maintain these connections, you must periodically call ConnectionManager::handleConnections. This method handles UDP data reception, connection timeouts, and scheduled data transmission.

// High-level flow
ConnectionManager connectionManager;
auto io = connectionManager.forwardOpen(si, parameters);

if (auto ptr = io.lock()) {
    ptr->setDataToSend(data);
    ptr->setReceiveDataListener([](auto header, auto seq, auto data) { /* handle data */ });
    ptr->setCloseListener([]() { /* handle close */ });
}

// Crucial: periodic maintenance
while (connectionManager.hasOpenConnections()) {
    connectionManager.handleConnections(std::chrono::milliseconds(100));
}

connectionManager.forwardClose(si, io);

To establish an IO connection, you must populate a ConnectionParameters object. Note that ConnectionManager requires an existing EIP session (SessionInfo) to perform the Forward_Open service.

Key Configuration Rules:

• Directionality: Parameters prefixed with o2t (Originator-to-Target) define settings for the Scanner $\rightarrow$ Adapter direction. Parameters prefixed with t2o (Target-to-Originator) define settings for the Adapter $\rightarrow$ Scanner direction.
• Connection Path: Must be a std::vector<uint8_t> following the pattern: 0x20, 0x04, CONFIG_ASSEMBLY_ID, 0x2C, OUTPUT_ASSEMBLY_ID, 0x2C, INPUT_ASSEMBLY (refer to your device's EDS file).
• Connection Size: The last 9 bits of t2oNetworkConnectionParams and o2tNetworkConnectionParams are used for the connection size. Use the |= operator to set these.
• Timing: RPI (Requested Packet Interval) and API values are specified in microseconds.
• Real-Time Format: Set o2tRealTimeFormat = true if required by the device.

ConnectionParameters parameters;
parameters.connectionPath = {0x20, 0x04, 151, 0x2C, 150, 0x2C, 100};
parameters.o2tRealTimeFormat = true;
parameters.originatorVendorId = 342;
parameters.originatorSerialNumber = 0x12345;

// Setting size (last 9 bits) using |=
parameters.t2oNetworkConnectionParams |= NetworkConnectionParams::P2P;
parameters.t2oNetworkConnectionParams |= 32; // size of Assm100

parameters.o2tNetworkConnectionParams |= NetworkConnectionParams::P2P;
parameters.o2tNetworkConnectionParams |= 32; // size of Assm150

parameters.o2tRPI = 1000000; // 1 second in microseconds
parameters.t2oRPI = 1000000;
parameters.transportTypeTrigger |= NetworkConnectionParams::CLASS1;

Before instantiating ParameterObject instances, you must query the device using ServiceCodes::GET_ATTRIBUTE_SINGLE to find the parameter count and the class descriptor.

1. Get Parameter Count

Read the MAX_INSTANCE attribute of the ParameterObject::CLASS_ID. If the returned count is $N$, there are $N$ parameter instances with IDs from $1$ to $N$.

2. Check for Full Attribute Support

Read the CLASS_DESCRIPTOR attribute. Check the second bit of the descriptor using the SUPPORTS_FULL_ATTRIBUTES flag to determine if metadata like scaling and descriptions are available.

// 1. Read the count of parameters via MAX_INSTANCE
auto response = messageRouter.sendRequest(si
        , ServiceCodes::GET_ATTRIBUTE_SINGLE
        , EPath(ParameterObject::CLASS_ID, 0, MAX_INSTANCE));

Buffer buffer(response.getData());
CipUint paramsCount;
buffer >> paramsCount;

// 2. Read the class descriptor to check for full attribute support
response = messageRouter.sendRequest(si
        , ServiceCodes::GET_ATTRIBUTE_SINGLE
        , EPath(ParameterObject::CLASS_ID, 0, CLASS_DESCRIPTOR));

buffer = Buffer(response.getData());
CipUint descriptor;
buffer >> descriptor;

bool allAttributes = descriptor & SUPPORTS_FULL_ATTRIBUTES;

EIPScanner includes a simple embedded logger, utils::Logger, which outputs messages to stdout. You can control the visibility of messages by setting a global minimum log level using Logger::setLogLevel.

Important Note: Logging messages are actually printed during the destructor of the utils::Logger instance. To ensure messages are printed immediately, avoid storing the logger in a long-lived variable or a class field; instead, use it as a temporary object.

#include "utils/Logger.h"

using eipScanner::utils::Logger;
using eipScanner::utils::LogLevel;

int main() {
    // Set the global minimum log level
    Logger::setLogLevel(LogLevel::INFO);

    // This message will be printed because INFO >= INFO
    Logger(LogLevel::INFO) << "You will see this message.";

    // This message will NOT be printed because DEBUG < INFO
    Logger(LogLevel::DEBUG) << "You won't see this message.";

    return 0;
}