Skip to content

README.md

Latest commit

 

History

History
139 lines (96 loc) · 4.88 KB

README.md

File metadata and controls

139 lines (96 loc) · 4.88 KB

module_esl

Build and Publish Debian Package License: LGPL-V3 Linux Debian Ubuntu

A robotkernel module that creates a raw socket (SOCK_RAW) on a specified network interface and exposes it as a robotkernel stream device. This module provides low-level access to raw Ethernet frames, enabling direct packet capture and transmission for custom protocols, industrial communication, and network debugging.

Features

  • Creates a SOCK_RAW socket on a specified Ethernet interface
  • Exposes raw Ethernet frames via robotkernel stream interface
  • Supports configurable receive timeouts
  • Real-time capable with configurable thread priority and CPU affinity
  • Configurable via YAML for easy integration
  • Compatible with robotkernel architecture
  • Ideal for EtherCAT, PROFINET, custom protocols, and network monitoring

How It Works

The module opens a raw socket on the specified network interface and reads and writes raw Ethernet frames. These frames are then exposed as a robotkernel stream device, allowing other modules to process them in real-time. The module handles the low-level socket operations and provides a clean interface for higher-level protocol handlers.

Prerequisites

  • Root privileges OR the CAP_NET_RAW capability
  • The grant_cap_net_raw kernel module by Florian Schmidt (openethercat) can be used to grant the required capability without root access

Configuration

The module is configured via a YAML configuration file. Below is an example configuration:

# Configuration file for module_sock_raw.
#
# vi: set ft=yaml nowrap:
# -*- mode: yaml -*-

#########################################################
# network interface settings

# Defines the ethernet interface name to open.
ifname: eth0

# Sets the receive timeout in nanoseconds.
recv_timeout_ns: 1000000

# Protocols to listen on.
# protocol: 0xA488

#########################################################
# logging settings

# Standard robotkernel module local loglevel.
# loglevel: verbose

Configuration Parameters

Parameter Description Default Example
ifname The Ethernet interface name to open (e.g., eth0, enp3s0) required eth0
recv_timeout_ns Receive timeout in nanoseconds (0 = no timeout) 1000000 (1ms) 500000 (500μs)
protocol Specific protocol to filter (e.g., 0xA488 for EtherCAT) none 0xA488
loglevel Logging verbosity (optional) info verbose

Installation

  1. Clone the repository:

    git clone https://github.com/robotkernel-hal/module_sock_raw.git
cd module_sock_raw

  2. Build the module:

    ./bootstrap.sh
autoreconf -if
./configure
make -j$(nproc)

  3. Install the module:

    sudo make install

  4. Ensure robotkernel is properly configured to load the module.

Usage

  1. Start robotkernel with the module loaded.
  2. Configure the module using the provided YAML configuration.
  3. The module will open a raw socket on the specified interface and expose it as a stream device.
  4. Use the stream device (e.g., sock-raw-2-stream.sock_raw.stream) with other modules like module_esl for protocol processing.
  5. For production use, consider using grant_cap_net_raw to grant CAP_NET_RAW capability without root privileges.

Dependencies

  • robotkernel HAL framework
  • autotools
  • Linux kernel with real-time capabilities (PREEMPT_RT recommended)
  • Root privileges or CAP_NET_RAW capability for raw socket access

Security Note

Raw socket access is a privileged operation. Use one of the following approaches:

  • Run as root (not recommended for production)
  • Grant CAP_NET_RAW capability using grant_cap_net_raw (recommended): 
    sudo insmod grant_cap_net_raw.ko

Development

Contributions are welcome! Please follow the standard pull request workflow:

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Open a pull request

License

This project is licensed under the LGPL-V3 License - see the LICENSE file for details.

Contact

For questions, issues, or feature requests, please open an issue on GitHub or contact the maintainers.

Note: Raw socket access requires elevated privileges. Use grant_cap_net_raw (by Florian Schmidt) to grant the CAP_NET_RAW capability without running as root. Always follow security best practices when working with raw network access.