soem-node/README.en.md

Bindings Node-API pour SOEM (Simple Open EtherCAT Master)

# SOEM-Nodejs

[![CI/CD](https://github.com/MXASoundNDEv/SOEM-Nodejs/actions/workflows/ci.yml/badge.svg)](https://github.com/MXASoundNDEv/SOEM-Nodejs/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/soem-node.svg)](https://badge.fury.io/js/soem-node)
[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)](https://github.com/MXASoundNDEv/SOEM-Nodejs)
[![Coverage](https://img.shields.io/badge/coverage-38%25-yellow)](./coverage/index.html)

High-performance Node.js bindings for [SOEM (Simple Open EtherCAT Master)](https://github.com/OpenEtherCATsociety/SOEM) featuring automatic network interface discovery and advanced management utilities.

## 🚀 Features

- ✅ **Automatic interface discovery** – finds optimal EtherCAT-capable interfaces
- ✅ **Multi-platform support** – Windows & Linux (x64, arm64)
- ✅ **Full TypeScript definitions** – rich typing & IntelliSense
- ✅ **Modern API** – clean, minimal, predictable
- ✅ **Built‑in utilities** – management & diagnostics helpers
- ✅ **Extensive tests** – unit + integration coverage
- ✅ **Real examples** – practical scripts & guidance

## 📦 Installation

```bash
npm install soem-node
```

### System prerequisites

- **Node.js** >= 18
- **C/C++ toolchain** (MSVC Build Tools on Windows, gcc or clang on Linux)
- **Python** (required by node-gyp)

> CMake is no longer required: the build uses `node-gyp` and `binding.gyp` only.

#### Windows
- **Npcap** (recommended) or **WinPcap** for raw network access
  - Download: https://npcap.com/#download
- **Visual Studio Build Tools** (or full VS install)

#### Linux
- `libpcap-dev` (Ubuntu/Debian) or `libpcap` for your distro
- Proper raw socket permissions (see below)

### Linux capabilities (avoid running as root)

```bash
sudo setcap cap_net_raw,cap_net_admin+eip $(which node)
```

## 🎯 Quick Start

### 1. List interfaces

```js
const { SoemMaster } = require('soem-node');
const interfaces = SoemMaster.listInterfaces();
console.log('Available interfaces:', interfaces);
```

### 2. Automatic master creation

```js
const { EtherCATUtils } = require('soem-node/examples/ethercat-utils');
const master = EtherCATUtils.createMaster();
if (master) {
  try {
    const slaves = master.configInit();
    console.log(`${slaves} EtherCAT slaves detected`);
  } finally {
    master.close();
  }
}
```

### 3. Full communication cycle

```js
const { SoemMaster } = require('soem-node');

async function main() {
  const master = new SoemMaster('eth0'); // or Windows interface name
  if (!master.init()) throw new Error('EtherCAT init failed');
  try {
    const slaves = master.configInit();
    if (slaves > 0) {
      master.configMapPDO();
      for (let i = 0; i < 100; i++) {
        master.sendProcessdata();
        const wkc = master.receiveProcessdata();
        console.log(`Cycle ${i}: WKC=${wkc}`);
        await new Promise(r => setTimeout(r, 10));
      }
      const deviceType = master.sdoRead(1, 0x1000, 0);
      if (deviceType) {
        console.log('Device type:', deviceType.readUInt32LE(0).toString(16));
      }
    }
  } finally {
    master.close();
  }
}

main().catch(console.error);
```

## Manual Build

Build invokes `node-gyp` and auto-generates `ec_options.h` via the script referenced in `binding.gyp` (`scripts/generate-ec-options.js`).

```
npm run build
```

Native binary output: `build/Release/soem_addon.node`.

## Electron Usage

Based on **Node-API (N-API)**: most Electron versions supporting the same N-API level will work without rebuilding. If you encounter an ABI error:

```bash
npm rebuild --runtime=electron --target=30.0.0 --dist-url=https://electronjs.org/headers
```

`electron-builder` config snippet:
```jsonc
{
  "asarUnpack": [
    "node_modules/soem-node/build/Release/*.node"
  ]
}
```

Checklist:
- Install Npcap (Windows) or libpcap (Linux)
- Confirm architecture (x64 / arm64)
- Adjust Linux capabilities (see above)

Reference: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron

## 🧪 Testing & Quality

### Run tests

```bash
npm test            # basic tests
npm run test:ci     # with coverage
npm run test:watch  # watch mode
npm run test:all    # full suite
npm run lint        # lint
npm run security    # security audit
```

### Coverage

Project maintains strong coverage:
- ✅ Core API unit tests
- ✅ Integration workflows
- ✅ Intelligent mocks for CI
- ✅ Performance & stability checks

### CI/CD

GitHub Actions provides:
- ✅ Cross-platform tests (Windows, Linux)
- ✅ TypeScript + ESLint validation
- ✅ Security audit
- ✅ Multi-platform build
- ✅ Automated npm publish

## 🔧 Development

### Setup

```bash
git clone https://github.com/MXASoundNDEv/SOEM-Nodejs.git
cd SOEM-Nodejs
npm install
npm run build
npm test
```

### Project structure

```
soem-node/
├── src/               # TypeScript source
├── examples/          # Example scripts & helpers
├── test/              # Test suite
├── types/             # Type definitions
├── external/          # SOEM submodule
├── docs/              # Documentation
└── scripts/           # Utility scripts (options generation, release, CI)
```

## Example script

```
node examples/scan-and-read.js eth0
```
Reads slaves, exchanges processdata and reads SDO `0x1000` from slave 1.

## Troubleshooting

| Issue | Hint |
|-------|------|
| Native module not found | Re-run `npm run build`; check `build/Release/soem_addon.node` |
| Build errors | Ensure Python + toolchain present |
| Network access denied | Install Npcap/libpcap & permissions |
| Need rebuild (Electron) | Use `npm rebuild --runtime=electron ...` |
| Low WKC | Check cabling, topology, slave power |

## License

GPL-2.0-or-later. SOEM itself is GPLv2 with exceptions. Shipping prebuilt binaries may require publishing your source. A commercial SOEM license is available for proprietary use.

---

## 📘 Full API (SoemMaster)

This section mirrors the French API doc for convenience. See also `docs/` for background (EtherCAT overview, glossary).

### Contents
1. Overview
2. Import & Typing
3. Lifecycle
4. Summary Table
5. Category Reference
6. Advanced Examples
7. Errors & Diagnostics
8. Performance Best Practices
9. Short FAQ

---
### 1. Overview
`SoemMaster` wraps native SOEM primitives (N-API). Provides:
- Slave discovery & configuration
- PDO mapping and cyclic exchange
- SDO / SoE / EEPROM access
- Low-level frame primitives
- Distributed Clocks (DC) helpers
- Recovery & reconfiguration utilities

### 2. Import & Typing
```ts
import { SoemMaster } from 'soem-node';
interface NetworkInterface { name: string; description: string }
```
CommonJS:
```js
const { SoemMaster } = require('soem-node');
```

### 3. Lifecycle
```
new SoemMaster(ifname) -> init() -> configInit() -> (slaves>0) -> configMapPDO() -> loop: send/receive -> close()
```

### 4. Summary Table
| Method | Returns | Category | Notes |
|--------|---------|----------|-------|
| constructor(ifname?) | instance | Init | Default `eth0` (adjust on Windows) |
| init() | boolean | Init | Opens interface |
| configInit() | number | Discovery | Slave count |
| configMapPDO() | void | PDO | Setup processdata map |
| state() | number | State | Cached value |
| readState() | number | State | Forces refresh |
| sdoRead(slave,i,sub,ca?) | Buffer\|null | SDO | Optional Complete Access |
| sdoWrite(slave,i,sub,data,ca?) | boolean | SDO | Optional Complete Access |
| sendProcessdata() | number | PDO | Cycle send |
| receiveProcessdata() | number | PDO | WKC / bytes |
| writeState(slave,state) | number | State | Workcounter/code |
| stateCheck(slave,req,timeout?) | number | State | Wait for state |
| reconfigSlave(slave,timeout?) | number | Recovery | Reconfigure slave |
| recoverSlave(slave,timeout?) | number | Recovery | >0 success |
| slaveMbxCyclic(slave) | number | Mailbox | Enables cyclic mailbox |
| configDC() | boolean | DC | Enable distributed clocks |
| getSlaves() | any[] | Info | Slave metadata |
| initRedundant(if1,if2) | boolean | Redundancy | Dual interface master |
| configMapGroup(group?) | Buffer\|null | PDO Group | Group mapping |
| sendProcessdataGroup(group?) | number | PDO Group | Group variant |
| receiveProcessdataGroup(group?,timeout?) | number | PDO Group | Group variant |
| mbxHandler(group?,limit?) | number | Mailbox | Mailbox processing |
| elist2string() | string | Diagnostic | Internal error log |
| SoEread(slave,driveNo,flags,idn) | Buffer\|null | SoE | Read element |
| SoEwrite(slave,driveNo,flags,idn,data) | boolean | SoE | Write element |
| readeeprom(slave,addr,timeout?) | number | EEPROM | Read word |
| writeeeprom(slave,addr,data,timeout?) | number | EEPROM | Write word |
| APRD(ADP,ADO,length,timeout?) | Buffer\|null | Low-level | Application Read |
| APWR(ADP,ADO,data,timeout?) | number | Low-level | Application Write |
| LRW(LogAdr,length,buf,timeout?) | number | Low-level | Logical Read/Write |
| LRD(LogAdr,length,timeout?) | Buffer\|null | Low-level | Logical Read |
| LWR(LogAdr,data,timeout?) | number | Low-level | Logical Write |
| dcsync0(slave,act,CyclTime,CyclShift) | boolean | DC | Single cycle sync |
| dcsync01(slave,act,CyclTime0,CyclTime1,CyclShift) | boolean | DC | Dual cycle sync |
| SoemMaster.listInterfaces() | NetworkInterface[] | Utility | Enumerate interfaces |

### 5. Category Reference
#### Initialization & Discovery
`init()`, `configInit()`, `configMapPDO()`, `initRedundant()`.

#### Process Data (PDO / Groups)
`sendProcessdata()`, `receiveProcessdata()`, plus `*Group()` variants for multiple groups / timings.

#### Object Access (SDO / SoE / EEPROM)
Use SDO for dictionary objects, SoE for supported drives, EEPROM for low-level device storage. Optional `ca` (Complete Access) for block reads/writes where supported.

#### State & Recovery
`state()`, `readState()`, `writeState()`, `stateCheck()`, `reconfigSlave()`, `recoverSlave()`. Use `stateCheck` after transitions (e.g. INIT -> PRE-OP -> SAFE-OP -> OP).

#### Distributed Clocks & Sync
`configDC()`, `dcsync0()`, `dcsync01()` for sub-microsecond synchronized cycles. `CyclTime*` are in nanoseconds.

#### Low-level Primitives
`APRD`, `APWR`, `LRW`, `LRD`, `LWR` for diagnostic frames or specialized control flows.

#### Utilities & Diagnostics
`elist2string()` for internal SOEM error/event list, `getSlaves()` for runtime bus inspection, `mbxHandler()` for periodic mailbox processing.

### 6. Advanced Examples
Real-time style loop (~1 kHz):
```js
const master = new SoemMaster('eth0');
if (!master.init()) throw new Error('init failed');
try {
  const slaves = master.configInit();
  if (!slaves) return;
  master.configMapPDO();
  master.configDC();
  const periodUs = 1000; // 1 kHz
  const start = process.hrtime.bigint();
  for (let i = 0; i < 5000; i++) {
    master.sendProcessdata();
    master.receiveProcessdata();
    const target = start + BigInt(i + 1) * BigInt(periodUs) * 1000n;
    while (process.hrtime.bigint() < target) {}
  }
} finally { master.close(); }
```

Batch SDO reads:
```js
function readU32(master, slave, index, sub) {
  const b = master.sdoRead(slave, index, sub);
  return b ? b.readUInt32LE(0) : null;
}
const items = [0x1000, 0x1001, 0x1008];
const results = Object.fromEntries(items.map(i => [i.toString(16), readU32(master, 1, i, 0)]));
```

DC sync enable:
```js
if (master.configDC()) {
  master.dcsync0(1, true, 1_000_000, 0); // 1 ms in ns
}
```

Redundancy:
```js
const redundant = new SoemMaster('eth0');
if (redundant.initRedundant('eth0', 'eth1')) {
  // proceed like a normal master
}
```

### 7. Errors & Diagnostics
- `false` / `null` return => non-fatal failure (e.g., SDO read timeout)
- Exceptions => severe init or binding errors
- Use `elist2string()` after anomalies
- Tune `timeout?` parameters for slower devices
- Abnormal WKC => check cabling, slave power, EMI, network adapter

### 8. Performance Best Practices
- Pre-allocate buffers for repeated `LRW`
- Avoid SDO operations inside tight cyclic loops (do them pre/post cycle)
- Enable DC to reduce jitter
- On Linux consider CPU isolation (isolcpus) & RT scheduling
- On Windows minimize background services on the target core

### 9. Short FAQ
**Q:** Why does `sdoRead` return null? **A:** Slave timeout or invalid index/sub.
**Q:** Need root on Linux? **A:** Not if capabilities are set.
**Q:** Electron support? **A:** Yes via N-API; rebuild only if ABI mismatch.
**Q:** How to debug WKC = 0? **A:** Check physical layer, interface selection, slave power, cabling path.

---
For contributions or deeper protocol background see `docs/`.