@ap-atiruj/node-red-contrib-mc-protocol 1.0.0
Node-RED nodes for Mitsubishi MC Protocol (MELSEC) — FX3, FX5, iQ-R, Q series — by AP Atiruj
node-red-contrib-mc-protocol
Production-grade Node-RED nodes for Mitsubishi MC Protocol (MELSEC Communication Protocol) over TCP/UDP.
Supports 3E / 4E binary and ASCII frame formats for direct device-level read/write access to MELSEC PLCs — no middleware required.
Supported PLC Series
| Series | Connection |
|---|---|
| MELSEC iQ-R | 3E / 4E Binary + ASCII |
| MELSEC iQ-F (FX5) | 3E Binary + ASCII |
| MELSEC Q series | 3E / 4E Binary + ASCII |
| MELSEC L series | 3E Binary + ASCII |
Nodes
| Node | Description |
|---|---|
mc-connection |
Shared config node – manages TCP/UDP socket, auto-reconnect, keep-alive |
mc-read |
Read consecutive device values (word / bit / dword) |
mc-write |
Write consecutive device values |
mc-batch-read |
Read multiple non-contiguous ranges in one operation |
mc-batch-write |
Write multiple non-contiguous ranges in one operation |
mc-monitor |
Poll devices at a configured interval; emit on change |
Installation
cd ~/.node-red
npm install node-red-contrib-mc-protocol
Restart Node-RED after installation.
Requirements: Node.js ≥ 18, Node-RED ≥ 3.0
Quick Start
1. Configure the PLC connection
Add any MC Protocol node to the canvas → click the pencil icon beside Connection → fill in your PLC's IP, port, and frame type.
2. Read D0–D9
[Inject] ──► [mc-read D0 × 10 WORD] ──► [Debug]
The debug node will receive:
{ "payload": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], "topic": "D0" }
3. Write D100 = 42
[Inject 42] ──► [mc-write D100 WORD] ──► [Debug]
4. Monitor M0–M15 every 500 ms
[mc-monitor M0 × 16 BIT 500 ms] ──► [Debug]
Supported Devices
| Symbol | Type | Access | Description |
|---|---|---|---|
| X | Input relay | Bit | Physical inputs |
| Y | Output relay | Bit | Physical outputs |
| M | Internal relay | Bit | General-purpose coils |
| B | Link relay | Bit | MELSECNET link relay |
| D | Data register | Word | General-purpose registers |
| W | Link register | Word | MELSECNET link register |
| R | File register | Word | Extended file register |
| TN | Timer current | Word | Timer current value |
| CN | Counter current | Word | Counter current value |
| SM | Special relay | Bit | System status bits |
| SD | Special register | Word | System status words |
Connection Configuration
| Property | Default | Description |
|---|---|---|
| Host | — | PLC IP address |
| Port | 5007 | TCP/UDP port (5006 for ASCII) |
| Transport | TCP | TCP or UDP |
| Frame Type | 3E Binary | 3E_BINARY / 3E_ASCII / 4E_BINARY / 4E_ASCII |
| Connect Timeout | 5000 ms | TCP connect timeout |
| Request Timeout | 3000 ms | Per-request response timeout |
| Auto Reconnect | true | Reconnect on disconnect |
| Reconnect Interval | 5000 ms | Delay between reconnects |
| Max Reconnect Attempts | 0 (∞) | 0 = unlimited |
| Keep-Alive Interval | 0 (off) | Heartbeat ping interval |
Dynamic Message Overrides
Device address, count, and values can be set dynamically via msg:
// mc-read: override address at runtime
msg.payload = { device: 'D', address: 500, count: 10 };
// mc-write: override address via topic
msg.topic = 'D200';
msg.payload = [1, 2, 3];
Development
Setup
git clone https://github.com/your-org/node-red-contrib-mc-protocol.git
cd node-red-contrib-mc-protocol
npm install
Build
npm run build # compile TypeScript → dist/
npm run build:watch # watch mode
Test
npm test # all unit tests
npm run test:coverage # with coverage report
npm run test:unit # unit tests only
npm run test:integration # requires MC_TEST_HOST env var
Lint & Format
npm run lint # eslint + fix
npm run format # prettier + fix
npm run type-check # tsc --noEmit
Integration Test Against a Live PLC
MC_TEST_HOST=192.168.1.1 MC_TEST_PORT=5007 npm run test:integration
Project Structure
node-red-contrib-mc-protocol/
├── src/
│ ├── nodes/ # Node-RED node implementations
│ │ ├── mc-connection/ # Config node (TCP/UDP manager)
│ │ ├── mc-read/ # Read node
│ │ ├── mc-write/ # Write node
│ │ ├── mc-batch-read/ # Batch read node
│ │ ├── mc-batch-write/ # Batch write node
│ │ └── mc-monitor/ # Polling monitor node
│ ├── protocol/ # Core protocol layer
│ │ ├── types.ts # All TypeScript types and enums
│ │ ├── constants.ts # Frame magic bytes, device codes, defaults
│ │ ├── frame-builder.ts # Request frame serialisation
│ │ ├── frame-parser.ts # Response frame deserialisation
│ │ ├── connection-manager.ts # TCP/UDP socket + reconnect logic
│ │ └── mc-protocol.ts # High-level client API
│ └── utils/
│ ├── logger.ts # Structured logger
│ ├── retry.ts # Exponential back-off retry
│ └── validators.ts # Input validation
├── test/
│ ├── unit/ # Unit tests (no PLC required)
│ ├── integration/ # Integration tests (live PLC)
│ └── fixtures/ # Pre-built frame buffers
├── docs/
│ ├── protocol/ # MC Protocol reference
│ ├── guides/ # Getting started, configuration, nodes
│ └── api/ # Generated TypeDoc output
├── examples/ # Import-ready Node-RED flow JSON files
└── .github/workflows/ # CI, publish, CodeQL
Contributing
- Fork and clone the repository.
- Create a feature branch from
develop. - Write code + tests (coverage ≥ 80%).
- Run
npm run lint && npm test && npm run build. - Open a Pull Request using the provided template.
See CONTRIBUTING for detailed guidelines.
References
- MELSEC Communication Protocol Reference Manual (SH-080008)
- iQ-R MELSEC Communication Protocol Reference Manual (SH-081263ENG)
- FX5 MELSEC Communication Protocol Reference Manual (JY997D53401)
License
MIT © 2026 AP
