Ethernet Client C++ Library

This documentation provides an overview of the Ethernet Client, a static C++ library designed for efficient Ethernet communication with SOMANET Integro devices.

‍Note: To use this library, your SOMANET Integro device must have Ethernet firmware installed.

The pre-built static library and examples are available in this public repository.

HTTP Server (ec2h)

An HTTP server application is available that wraps this library and exposes its functionality through HTTP endpoints. A web-based user interface (UI) is also included. Both the server installer and the UI can be accessed here: http://motion-master-console.synapticon.com/ethernet

Usage

To establish communication, the SOMANET Integro device must have a valid IP address. This can be configured in one of two ways:

• Static Configuration: Assign a fixed IP address using EtherCAT communication.
• Dynamic Configuration: Configuring a DHCP Server (Windows) on your computer to automatically assign an IP address to the connected device.

EthernetDevice Class

Handles TCP communication with SOMANET devices over Ethernet.

This class provides methods for connecting to a remote server, sending messages, and receiving responses over a TCP connection using Boost.Asio. It manages the underlying socket, connection, and I/O operations required for client-server communication.

All message exchanges with the device are designed to be thread-safe.

Connection

Create an instance of the EthernetDevice class by specifying the device's IP address and port number:

const std::string kIp = "192.168.100.5";
const int kPort = 8080;
auto ed = EthernetDevice{kIp, kPort};

Then, connect to the device with:

auto connected = ed.connect();

When the device is powered on, it will automatically transition to the OPERATIONAL state, which you can check with:

state = ed.getState();
assert(state == 8); // Verify state is OPERATIONAL (8)
// Other states: INIT(1), PREOP(2), SAFEOP(4), OP(8), BOOT(3)

Most request functions support an optional expiryTime parameter of type std::chrono::steady_clock::duration. This specifies the maximum time to wait for a response from the device before a timeout error is triggered. For example:

try {
  ed.setState(0x02, std::chrono::milliseconds(1000));
} catch (const std::exception& e) {
  std::cerr << "Failed to set state: " << e.what() << std::endl;
}

Parameters

To read a device parameter value (e.g., 0x6079: DC link circuit voltage), use:

std::vector<uint8_t> value = ed.readSdo(0x6079, 0x01);

The returned value is a vector of uint8_t representing a raw data buffer.

To write a device parameter value (e.g., 0x607A: Target position), use:

std::vector<uint8_t> value{0xe2, 0x04, 0x00, 0x00};
auto success = ed.writeSdo(0x607a, 0x00, value);

There's a better, type-safe way to read and write parameter values. It requires first loading the parameters:

ed.loadParameters(false); // Load parameter metadata without reading actual values

This loads parameter metadata from the device into an internal parameter map. Refer to the common::Parameter class for more details. Once the Ethernet device has its parameters loaded, you can upload (read) and download (write) parameters using concrete types. These operations will automatically update the stored parameter value.

auto voltage = ed.upload<uint32_t>(0x6079, 0x00); // Reads DC link circuit voltage as uint32_t
ed.download<int32_t>(0x607a, 0x00, 543); // Writes 543 to target position

You can also retrieve a parameter and check its value after upload or download:

auto& parameter = ed.findParameter(0x607a, 0x00);
assert(parameter.getValue<int32_t>() == 543);

Files

To read a file from the device:

std::vector<uint8_t> ed.readFile(".hardware_description");

To write a file to the device:

std::vector<uint8_t> fileData(5000, 0xFF);
bool success = ed.writeFile("ui.config.json", fileData);

If you write app_firmware.bin or com_firmware.bin, you must trigger a firmware update afterward:

ed.triggerFirmwareUpdate();

To read the list of available files:

std::vector<std::string> ed.readFileList(true); // strip file name size suffix

To remove a file from the device:

bool success = ed.removeFile("ui.config.json");

Process Data

Process data exchange works similarly to SDO communication. You can either use raw data buffers or a simplified, parameter-based interface.

Raw buffer example:

std::vector<uint8_t> outputs(35, 0x00);  // Create an RxPDO with 35 bytes
std::vector<uint8_t> inputs = ed.sendAndReceiveProcessData(outputs);

With the simplified interface, start by loading parameter metadata:

ed.loadParameters(false); // Load parameter metadata without reading actual values

Then retrieve and modify a parameter value, for example:

auto& parameter = ed.findParameter(0x607a, 0x00);
parameter.setValue<int32_t>(123)

To perform the process data exchange and automatically update parameter values based on the PDO mapping:

ed.exchangeProcessDataAndUpdateParameters();

This will send all mapped RxPDO parameter values, receive TxPDO values from the device, and update the corresponding local parameters.

‍Note: The PDO map is currently static and defined internally by the EthernetDevice. In future versions, it will be dynamically refreshed when loadParameters() is called.

Configuring a DHCP Server (Windows)

1. Download the DHCP Server

   Download the DHCP Server for Windows from https://www.dhcpserver.de/cms/download/.

2. Extract the Server Files

   Extract the contents to C:\dhcpsrv2.5.2.

3. Add Configuration File

   Copy the dhcpsrv.ini file into the extracted folder (C:\dhcpsrv2.5.2).

   [SETTINGS]
   IPPOOL_1=192.168.100.5-254
   IPBIND_1=192.168.100.1
   AssociateBindsToPools=1
   Trace=1
   DeleteOnRelease=0
   ExpiredLeaseTimeout=3600
    
   [GENERAL]
   LEASETIME=86400
   NODETYPE=8
   SUBNETMASK=255.255.255.0
   NEXTSERVER=192.168.100.1
   ROUTER_0=0.0.0.0
    
   [DNS-SETTINGS]
   EnableDNS=0
    
   [TFTP-SETTINGS]
   EnableTFTP=0
   ROOT=C:\dhcpsrv2.5.2\wwwroot
   WritePermission=0
    
   [HTTP-SETTINGS]
   EnableHTTP=1
   ROOT=C:\dhcpsrv2.5.2\wwwroot
   [40-49-8A-01-21-04]
   IPADDR=192.168.100.5
   AutoConfig=04/08/2025 13:03:01
   LeaseEnd=1744196934

4. Configure Ethernet Adapter
   • Open Network Connections.
   • For your Ethernet adapter, open the properties for Internet Protocol Version 4 (TCP/IPv4).
   • Set the following static IP configuration:
     • IP Address: 192.168.100.1
     • Subnet Mask: 255.255.255.0
5. Start the DHCP Server
   • Run C:\dhcpsrv2.5.2\dhcpsrv.exe.
   • Click Admin, then Service START, and finally Continue as tray app.
6. Verify DHCP Assignment
   • Right-click the tray icon labeled DHCP Server v2.5.2.3 and select Open Status.
   • Under SERVER_0 > DHCP Clients, you should see the assigned IP 192.168.100.5, indicating the device successfully received its address from the DHCP server.

Installing Firmware Using integro_sock_client.py script

1. Download the firmware from the following link:
   Firmware Download
2. Unpack the downloaded package.
3. Rename the com_motion-drive... file to test_com_firmware.bin.
4. Move test_com_firmware.bin to the same directory where integro_sock_client.py is located.
5. Execute the following command to write the boot file:
   python.exe .\integro_sock_client.py -t write_file_boot test_com_firmware.bin
6. Run the command to update the firmware:
   python.exe .\integro_sock_client.py -t update_firmware

Notes

• The default socket port is 8080.
• Firmware versions can be read using the read file command:
  • Use cversion to retrieve the firmware version.
  • Use bversion to retrieve the bootloader version.

Links

• Ethernet interface definition
• Ethernet protocol frame definitions
• InfoNotes-Ethernet Based Commissioning Tool V2
• Ethernet commissioning tool Design notes
• SocketCommunication scripts