{"id":13559557,"url":"https://github.com/yaacov/node-modbus-serial","last_synced_at":"2025-05-14T01:05:10.558Z","repository":{"id":38803947,"uuid":"45757800","full_name":"yaacov/node-modbus-serial","owner":"yaacov","description":"A pure JavaScript implemetation of MODBUS-RTU (and TCP) for NodeJS","archived":false,"fork":false,"pushed_at":"2024-08-22T10:20:51.000Z","size":751,"stargazers_count":636,"open_issues_count":99,"forks_count":239,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-10-29T17:12:07.346Z","etag":null,"topics":["modbus-rtu","modbus-serial","modbus-tcp","node-serialport"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yaacov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"yaacovzamir","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-11-07T22:41:18.000Z","updated_at":"2024-10-28T10:46:42.000Z","dependencies_parsed_at":"2023-11-17T08:52:09.254Z","dependency_job_id":"72ed69da-1062-4ac4-9a03-4d5680c7c917","html_url":"https://github.com/yaacov/node-modbus-serial","commit_stats":{"total_commits":563,"total_committers":89,"mean_commits":6.325842696629214,"dds":0.7122557726465364,"last_synced_commit":"cbd4379bed9672c13ec3a8517d622b728a737a5e"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaacov%2Fnode-modbus-serial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaacov%2Fnode-modbus-serial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaacov%2Fnode-modbus-serial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaacov%2Fnode-modbus-serial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yaacov","download_url":"https://codeload.github.com/yaacov/node-modbus-serial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248353135,"owners_count":21089562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["modbus-rtu","modbus-serial","modbus-tcp","node-serialport"],"created_at":"2024-08-01T13:00:29.112Z","updated_at":"2025-04-11T06:25:05.357Z","avatar_url":"https://github.com/yaacov.png","language":"JavaScript","funding_links":["https://ko-fi.com/yaacovzamir"],"categories":["Packages","包"],"sub_categories":["Hardware","硬件"],"readme":"# modbus-serial\n\nA pure JavaScript implementation of MODBUS-RTU (Serial and TCP) for NodeJS.\n\n[![NPM download](https://img.shields.io/npm/dm/modbus-serial.svg)](http://www.npm-stats.com/~packages/modbus-serial)\n[![NPM version](https://badge.fury.io/js/modbus-serial.png)](http://badge.fury.io/js/modbus-serial)\n![Build Status](https://github.com/yaacov/node-modbus-serial/workflows/ci/badge.svg)\n\n\nModbus is a serial communications protocol, first used in 1979.\nModbus is simple and robust, openly published, royalty-free and\neasy to deploy and maintain.\n\n**This package makes Modbus calls and serve fun and easy.**\n\n----\n\n- [What can I do with this module ?](#what-can-i-do-with-this-module-)\n- [Compatibility](#compatibility)\n- [Examples](#examples)\n- [Methods](https://github.com/yaacov/node-modbus-serial/wiki/Methods)\n\n----\n\n#### Install\n\n    npm install modbus-serial\n\ntry these options on npm install to build, if you have problems to install\n\n    --unsafe-perm --build-from-source\n\n\n#### What can I do with this module ?\n\nThis class makes it fun and easy to communicate with electronic\ndevices such as irrigation controllers, protocol droids and robots.\nIt talks with devices that use a serial line (e.g. RS485, RS232).\nMany industrial electronic devices implement modbus.\nArduino can also talk modbus and you can control your projects and robots\nusing modbus.\n\nArduino libraries for modbus slave:\n* https://github.com/yaacov/arduino-modbus-slave\n* https://github.com/smarmengol/Modbus-Master-Slave-for-Arduino\n\nArduino sketch for irrigation timer with modbus support:\n* https://github.com/yaacov/arduino-irrigation-timer\n\nNode Modbus-WebSocket bridge:\n* https://github.com/yaacov/node-modbus-ws\n\n#### Compatibility\n\n###### Version of NodeJS:\nThis module has not been tested on every single version of NodeJS. For best results you should stick to LTS versions, which are denoted by even major version numbers e.g. 4.x, 6.x, 8.x.\n\n###### These classes are implemented:\n\n| Class | Function |\n|-------|----------|\n| FC1 \"Read Coil Status\" | `readCoils(coil, len)` |\n| FC2 \"Read Input Status\" | `readDiscreteInputs(addr, arg)` |\n| FC3 \"Read Holding Registers\" | `readHoldingRegisters(addr, len) ` |\n| FC4 \"Read Input Registers\" | `readInputRegisters(addr, len) ` |\n| FC5 \"Force Single Coil\" | `writeCoil(coil, binary) //NOT setCoil` |\n| FC6 \"Preset Single Register\" | `writeRegister(addr, value)` |\n | FC15 \"Force Multiple Coil\" | `writeCoils(addr, valueAry)` |\n| FC16 \"Preset Multiple Registers\" | `writeRegisters(addr, valueAry)` |\n| FC22 \"Mask Write Register\" | `maskWriteRegister(addr, andMask, orMask)` |\n| FC43/14 \"Read Device Identification\" (supported ports: TCP, RTU) | `readDeviceIdentification(id, obj)` |\n\n###### Client Serial:\n\n* modbus-RTU (SerialPort): Over serial line [require node serialport].\n* modbus-RTU (RTUBufferedPort): Over buffered serial line [require node serialport].\n* modbus-ASCII (AsciiPort): Over serial line [require node serialport].\n\n###### Client TCP:\n\n* modbus-TCP (TcpPort): Over TCP/IP line.\n* modbus-RTU (UdpPort): Over C701 server, commercial UDP to serial bridge.\n* modbus-RTU (TcpRTUBufferedPort): Over TCP/IP line, TCP/IP serial RTU buffered device.\n* modbus-RTU (TelnetPort): Over Telnet server, TCP/IP serial bridge.\n\n###### Server\n\n* modbus-TCP (ServerTCP): Over TCP/IP line.\n\n\n#### Examples\n\n###### Read and Write\n``` javascript\n// create an empty modbus client\nconst ModbusRTU = require(\"modbus-serial\");\nconst client = new ModbusRTU();\n\n// open connection to a serial port\nclient.connectRTUBuffered(\"/dev/ttyUSB0\", { baudRate: 9600 }, write);\n\nfunction write() {\n    client.setID(1);\n\n    // write the values 0, 0xffff to registers starting at address 5\n    // on device number 1.\n    client.writeRegisters(5, [0 , 0xffff])\n        .then(read);\n}\n\nfunction read() {\n    // read the 2 registers starting at address 5\n    // on device number 1.\n    client.readHoldingRegisters(5, 2)\n        .then(console.log);\n}\n```\n----\n###### Read on multiple slaves\n``` javascript\nconst ModbusRTU = require(\"modbus-serial\");\n// create an empty modbus client\nconst client = new ModbusRTU();\n// open connection to a serial port\nclient.connectRTUBuffered(\"/dev/ttyS0\", { baudRate: 9600 });\n// set timeout, if slave did not reply back\nclient.setTimeout(500);\n\n// list of meter's id\nconst metersIdList = [10, 11, 12, 13, 14];\n\nconst getMetersValue = async (meters) =\u003e {\n    try{\n        // get value of all meters\n        for(let meter of meters) {\n            // output value to console\n            console.log(await getMeterValue(meter));\n            // wait 100ms before get another device\n            await sleep(100);\n\t}\n    } catch(e){\n        // if error, handle them here (it should not)\n        console.log(e)\n    } finally {\n        // after get all data from slave, repeat it again\n        setImmediate(() =\u003e {\n            getMetersValue(metersIdList);\n        })\n    }\n}\n\nconst getMeterValue = async (id) =\u003e {\n    try {\n        // set ID of slave\n        await client.setID(id);\n        // read the 1 registers starting at address 0 (first register)\n        let val =  await client.readInputRegisters(0, 1);\n        // return the value\n        return val.data[0];\n    } catch(e){\n        // if error return -1\n        return -1\n    }\n}\n\nconst sleep = (ms) =\u003e new Promise(resolve =\u003e setTimeout(resolve, ms));\n\n\n// start get value\ngetMetersValue(metersIdList);\n\n```\n----\n###### Logger Serial\n``` javascript\n// create an empty modbus client\nconst ModbusRTU = require(\"modbus-serial\");\nconst client = new ModbusRTU();\n\n// open connection to a serial port\nclient.connectRTUBuffered(\"/dev/ttyUSB0\", { baudRate: 9600 });\nclient.setID(1);\n\n// read the values of 10 registers starting at address 0\n// on device number 1. and log the values to the console.\nsetInterval(function() {\n    client.readHoldingRegisters(0, 10, function(err, data) {\n        console.log(data.data);\n    });\n}, 1000);\n```\n----\n###### Logger TCP\n``` javascript\n// create an empty modbus client\nconst ModbusRTU = require(\"modbus-serial\");\nconst client = new ModbusRTU();\n\n// open connection to a tcp line\nclient.connectTCP(\"127.0.0.1\", { port: 8502 });\nclient.setID(1);\n\n// read the values of 10 registers starting at address 0\n// on device number 1. and log the values to the console.\nsetInterval(function() {\n    client.readHoldingRegisters(0, 10, function(err, data) {\n        console.log(data.data);\n    });\n}, 1000);\n```\n----\n###### Logger UDP\n``` javascript\n// create an empty modbus client\nconst ModbusRTU = require(\"modbus-serial\");\nconst client = new ModbusRTU();\n\n// open connection to a udp line\nclient.connectUDP(\"127.0.0.1\", { port: 8502 });\nclient.setID(1);\n\n// read the values of 10 registers starting at address 0\n// on device number 1. and log the values to the console.\nsetInterval(function() {\n    client.readHoldingRegisters(0, 10, function(err, data) {\n        console.log(data.data);\n    });\n}, 1000);\n```\n----\n###### ModbusTCP Server\n``` javascript\n// create an empty modbus client\nconst ModbusRTU = require(\"modbus-serial\");\nconst vector = {\n    getInputRegister: function(addr, unitID) {\n        // Synchronous handling\n        return addr;\n    },\n    getHoldingRegister: function(addr, unitID, callback) {\n        // Asynchronous handling (with callback)\n        setTimeout(function() {\n            // callback = function(err, value)\n            callback(null, addr + 8000);\n        }, 10);\n    },\n    getCoil: function(addr, unitID) {\n        // Asynchronous handling (with Promises, async/await supported)\n        return new Promise(function(resolve) {\n            setTimeout(function() {\n                resolve((addr % 2) === 0);\n            }, 10);\n        });\n    },\n    setRegister: function(addr, value, unitID) {\n        // Asynchronous handling supported also here\n        console.log(\"set register\", addr, value, unitID);\n        return;\n    },\n    setCoil: function(addr, value, unitID) {\n        // Asynchronous handling supported also here\n        console.log(\"set coil\", addr, value, unitID);\n        return;\n    },\n    readDeviceIdentification: function(addr) {\n        return {\n            0x00: \"MyVendorName\",\n            0x01: \"MyProductCode\",\n            0x02: \"MyMajorMinorRevision\",\n            0x05: \"MyModelName\",\n            0x97: \"MyExtendedObject1\",\n            0xAB: \"MyExtendedObject2\"\n        };\n    }\n};\n\n// set the server to answer for modbus requests\nconsole.log(\"ModbusTCP listening on modbus://0.0.0.0:8502\");\nconst serverTCP = new ModbusRTU.ServerTCP(vector, { host: \"0.0.0.0\", port: 8502, debug: true, unitID: 1 });\n\nserverTCP.on(\"socketError\", function(err){\n    // Handle socket error if needed, can be ignored\n    console.error(err);\n});\n```\n----\n###### Read and Write Modbus ASCII\n``` javascript\n// create an empty modbus client\nconst Modbus = require(\"modbus-serial\");\nconst client = new Modbus();\n\n// open connection to a serial port\nclient.connectAsciiSerial(\n    \"/dev/ttyUSB0\", \n    {\n        baudRate: 9600,\n        startOfSlaveFrameChar: 0x3A  // optional: slave frame delimiter\n    }, \n    write);\n\nfunction write() {\n    client.setID(1);\n\n    // write the values 0, 0xffff to registers starting at address 5\n    // on device number 1.\n    client.writeRegisters(5, [0 , 0xffff])\n        .then(read);\n}\n\nfunction read() {\n    // read the 2 registers starting at address 5\n    // on device number 1.\n    client.readHoldingRegisters(5, 2)\n        .then(console.log);\n}\n```\n----\n##### \"modbusdb\" is an elegant wrapper over the Modbus protocol\n\n###### Check modbusdb github repo at https://github.com/yarosdev/modbusdb for more information, feedback is welcome!\n\nHere is an example of using `modbusdb` wrapper over `modbus-serial`:\n\n``` typescript\nimport Modbus from 'modbus-serial';\nimport { Modbusdb, ModbusSerialDriver, Datamap, createRegisterKey, TypeEnum, ScopeEnum } from \"modbusdb\";\n\n// create an empty modbus client\nconst client = new Modbus();\n\nclient.connectTcpRTUBuffered(\"127.0.0.1\", { port: 8502 }, app) // or use any other available connection methods\n\nfunction app() {\n\n  // First you need to define a schema for a database:\n  // createRegisterKey(UNIT_ADDRESS, MODBUS_TABLE, REGISTER_ADDRESS, BIT_INDEX)\n  const schema = [\n    { key: createRegisterKey(1, ScopeEnum.InternalRegister, 10),    type: TypeEnum.Int16 },\n    { key: createRegisterKey(1, ScopeEnum.InternalRegister, 11),    type: TypeEnum.Int32 },\n    { key: createRegisterKey(1, ScopeEnum.PhysicalRegister, 99),    type: TypeEnum.UInt16 },\n    { key: createRegisterKey(1, ScopeEnum.InternalRegister, 15, 2), type: TypeEnum.Bit },\n  ];\n  \n  // Define unit-scoped config if needed:\n  const units = [\n    {\n      address: 1, // This is unit address\n      forceWriteMany: true, // Use 15(0x0f) and 16(0x10) functions for single register, default: false\n      bigEndian: true, // You can use BigEndian for byte order, default: false\n      swapWords: false, // This is applicable only for multi-registers types such as int32, float etc, default: false\n      requestWithGaps: true, // If you are requesting addresses 10 and 13, allow to send one request to the device, default: true\n      maxRequestSize: 32, // How many registers to be requested in one round-trip with device, default: 1\n    }\n  ];\n  \n  // Let`s create an instance of a database:\n  const db = new Modbusdb({\n    driver: new ModbusSerialDriver(client),\n    datamap: new Datamap(schema, units)\n  });\n\n  // Now we can request three registers:\n  // NOTICE: Modbusdb under the hood will make all needed requests for you in using an optimal plan\n  //         If registers can be requested using a single request, be sure it will\n  db.mget([\n    createRegisterKey(1, ScopeEnum.InternalRegister, 10),\n    createRegisterKey(1, ScopeEnum.InternalRegister, 11),\n    createRegisterKey(1, ScopeEnum.PhysicalRegister, 99)\n  ]).then(result =\u003e {\n    console.log('mget', result)\n  })\n\n  // You can store register`s key to be used later:\n  const speedSetPoint = createRegisterKey(1, ScopeEnum.InternalRegister, 10);\n  const workingMode = createRegisterKey(1, ScopeEnum.InternalRegister, 11);\n  \n  // Write values directly into modbus device as easy as possible:\n  // NOTICE: Modbusdb under the hood will make all needed requests for you\n  //         Write operations have higher priority over the read operations\n  db.mset([\n    [speedSetPoint, 60],\n    [workingMode, 10],\n  ]).then(result =\u003e {\n    console.log('mset', result)\n  })\n}\n```\nEnums:\n```\nScopeEnum: (Modbus Table)\n  1 = PhysicalState = Discrete Input\n  2 = InternalState = Coil Status\n  3 = PhysicalRegister = Input Register\n  4 = InternalRegister = Holding Register\n  \nTypeEnum: (Available Data Types)\n  1 = Bit,\n  4 = Int16,\n  5 = UInt16,\n  6 = Int32,\n  7 = UInt32,\n  8 = Float\n```\n\n----\n\n\nto get more see [Examples](https://github.com/yaacov/node-modbus-serial/wiki)\n\n###### Serial connection\n\nnode-modbus-serial use node-serialport for serial communication, for serial port options settings\nit passes to serial port the [openOptions](https://node-serialport.github.io/node-serialport/global.html#openOptions) object,\ndefault serial port settings are 9600,8,n,1.\n\n``` javascript\nclient.connectRTUBuffered(\"/dev/ttyUSB0\", { baudRate: 9600, parity: 'even' });\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaacov%2Fnode-modbus-serial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyaacov%2Fnode-modbus-serial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaacov%2Fnode-modbus-serial/lists"}