{"id":17645778,"url":"https://github.com/retrodaredevil/io-lib","last_synced_at":"2025-05-07T05:12:06.936Z","repository":{"id":111427675,"uuid":"204330195","full_name":"retrodaredevil/io-lib","owner":"retrodaredevil","description":"A pure Java Modbus implementation with utilities to simplify serial communication","archived":false,"fork":false,"pushed_at":"2024-12-06T05:38:40.000Z","size":155,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T05:11:59.822Z","etag":null,"topics":["checksum","crc","lrc","master","modbus","modbus-master","modbus-rtu","modbus-serial","modbus-slave","rtu","serial","serial-communication","serial-port","slaves"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/retrodaredevil.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":"retrodaredevil"}},"created_at":"2019-08-25T17:54:15.000Z","updated_at":"2024-12-06T05:38:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"25982bd0-ec5e-4ba8-9379-a3804e7310f6","html_url":"https://github.com/retrodaredevil/io-lib","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retrodaredevil%2Fio-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retrodaredevil%2Fio-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retrodaredevil%2Fio-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retrodaredevil%2Fio-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/retrodaredevil","download_url":"https://codeload.github.com/retrodaredevil/io-lib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252817651,"owners_count":21808707,"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":["checksum","crc","lrc","master","modbus","modbus-master","modbus-rtu","modbus-serial","modbus-slave","rtu","serial","serial-communication","serial-port","slaves"],"created_at":"2024-10-23T10:59:31.641Z","updated_at":"2025-05-07T05:12:06.919Z","avatar_url":"https://github.com/retrodaredevil.png","language":"Java","funding_links":["https://github.com/sponsors/retrodaredevil"],"categories":[],"sub_categories":[],"readme":"# io-lib\nA pure Java Modbus implementation with utilities to simplify serial communication. Full Java 8 required.\n\n## Modbus Use\nThis can be used to send messages to slaves (acting as a master). You can also use this to receive messages\nfrom a master device and send a response back.\n\nThis library aims to provide an open source heavily object oriented approach to modbus mappings.\n\n## Serial Use\nThis library has an [IOBundle](core/src/main/java/me/retrodaredevil/io/IOBundle.java) interface which consists of\na getters for an InputStream and OutputStream. By importing the `jSerialComm` module, you can use the JSerialIOBundle class\nto create a serial port. Because IOBundle is a simple interface, you can easily create your own implementation\n\n## Modbus Features\n* Simple. Nothing is tightly coupled.\n* Modbus logic is not coupled to serial port logic or TCP logic. (Use YOUR own `InputStream` and `OutputStream`)\n* Create custom function codes by implementing `MessageHandler`.\n* Total freedom to extend any class and override its behavior.\n* Supports Ascii, RTU, and TCP encoding. Also create your own custom encoding by implementing `IODataEncoder` or creating your own `ModbusSlaveBus`\n* Supports CRC and LRC checksums. Automatically checks CRC while using RTU and LRC while using Ascii.\n* Parse request ModbusMessages (allows you to easily respond to a master).\n* Uses common interfaces. This makes it easy to **swap out implementations**. Decide to switch from Ascii encoding to using\nTCP? No problem.\n* Custom runtime exceptions for unexpected responses and for exception codes\n\n## Defined Modbus Function Codes\n\nHex  | Dec | Function\n---- | --- | --------\n0x01 | 1   | Read Coils\n0x02 | 2   | Read Discrete Inputs\n0x03 | 3   | Read Holding Registers\n0x04 | 4   | Read Input Registers\n0x05 | 5   | Write Single Coil\n0x06 | 6   | Write Single Register\n0x0F | 15  | Write Multiple Coils\n0x10 | 16  | Write Multiple Registers\n\nYou can also define more functions if you need to by extending `MessageHandler`. If you want to respond to other functions,\nyou can extend `MessageResponseCreator`, which is a subinterface of `MessageHandler`.\n\n## Modbus Drawbacks\n* Not set up for asynchronous requests\n* Not set up for multiple requests at once for TCP (you must request and wait for response)\n\n## Importing\n[![](https://jitpack.io/v/retrodaredevil/io-lib.svg)](https://jitpack.io/#retrodaredevil/io-lib)\n```groovy\nallprojects {\n    repositories {\n        ...\n        maven { url 'https://jitpack.io' }\n    }\n}\n\ndependencies {\n    implementation 'com.github.retrodaredevil.io-lib:core:\u003cLATEST RELEASE\u003e'\n    implementation 'com.github.retrodaredevil.io-lib:jSerialComm:\u003cLATEST RELEASE\u003e'\n}\n```\n\n\n## Examples\nBuilding a serial config:\n```java\nSerialConfig serialConfig = new SerialConfigBuilder(9600) // 9600 baud rate\n        .setDataBits(8) // 8 data bits, the default\n        .setParity(SerialConfig.Parity.NONE) // no parity, the default\n        .setStopBits(SerialConfig.StopBits.ONE) // one stop bit, the default\n        .build();\n```\nInitializing IOBundle with a serial connection\n```java\nSerialConfig serialConfig = ...;\nIOBundle ioBundle = JSerialIOBundle.createPort(\"/dev/ttyUSB0\", serialConfig);\n```\nInitializing modbus:\n```java\nIOBundle ioBundle = ...;\nModbusSlaveBus modbus = new IOModbusSlaveBus(ioBundle, new RtuDataEncoder(2000, 20, 4)); // 2 second initial timeout, 20ms timeout for end of message, 4ms sleep\nModbusSlave slave = new ImmutableAddressModbusSlave(options.getModbusAddress(), modbus);\n```\nUsing modbus:\n```java\nprivate static final MessageHandler\u003cint[]\u003e BATTERY_VOLTAGE = new ReadRegisters(0x0101, 1);\nprivate final ModbusSlave slave = ...;\npublic float getBatteryVoltage() {\n    return slave.sendRequestMessage(BATTERY_VOLTAGE)[0] / 10.0F;\n}\n```\nCatching exceptions:\n```java\nprivate static final MessageHandler\u003cint[]\u003e SOMETIMES_SUPPORTED = new ReadHoldingRegisters(0xE02B, 1);\nprivate final ModbusSlave slave = ...;\npublic Integer getSometimesSupportedData() {\n    try {\n        return slave.sendRequestMessage(SOMETIMES_SUPPORTED)[0];\n    } catch (ErrorCodeException ex) {\n        if (ex.getExceptionCode() == ExceptionCode.ILLEGAL_DATA_ADDRESS) {\n            return null; // This address must not be supported on this device\n        }\n        throw ex;\n    }\n}\n```\n\n## Modbus Exceptions\nThere are many places in this library where checked exceptions are thrown. Such as `MessageParseException`s, `SerialPortException`s.\nHowever, you should also be aware of `ModbusRuntimeException`s. These can pop up in just about any place that deals with Modbus.\nThese are runtime exceptions for convenience. You likely aren't able to deal with them when they first\npop up, so you usually handle them later up the call stack.\n\n## Dependencies\nIf you just import the `core` module, it doesn't have any dependencies. However, it is recommended to also import the\n`jSerialComm` module, which will make it easy to interact with serial ports.\n\nHowever, if you only need TCP Modbus, this library has 0 dependencies because you only need to import the `core` module.\n\n## Using Modbus Asynchronously\nThis library does not provide native support for performing a blocking action in a separate thread.\nIf you would like to execute requests asynchronously, you may put that request in its own thread.\nThis will work as long as you do not perform two requests at once on the same bus.\n\nNo Modbus library can support parallel requests for RTU/Ascii encodings,\nbut some may support parallel requests for TCP.\nThis library cannot be adapted for parallel requests with TCP, as that might require a big refactor of this library.\nAs long as you aren't looking to do parallel requests, this library has it all!\n\n\n## Modbus 8 Bit and 16 Bit\nSince this project deals with Modbus, there are times when code is dealing with 8 bit data or 16 bit data.\nSometimes it can be difficult to tell which one it is. If we wanted code to be most readable, we would make `byte` represent\n8 bit data and `short` represent 16 bit data, right? That would make sense, but it wouldn't be very practical because\nwe're always dealing with unsigned data, and both of those data types *could* be negative. So, this is why you will\nrarely see `short` being used.\n* `byte` is always 8 bit data\n* `short` is always 16 bit data\n* `int` could be either 8 bit or 16 bit\n\n## Testing this library\nIf you want to test this library, you can use https://www.modbusdriver.com/diagslave.html\n\n* Testing TCP: `sudo ./diagslave -m tcp -a 0 -p 502` (address of 0 is valid for TCP)\n\n## Projects using this\n* [SolarThing](https://github.com/wildmountainfarms/solarthing)\n\n## TODO\n* Support two byte slave addressing\n* Check out these serial libraries\n  * https://github.com/Gurux/gurux.serial.java\n  * https://github.com/NeuronRobotics/nrjavaserial\n  * https://github.com/fy-create/JavaSerialPort\n* Support a more standardized timeout implementation for RtuDataEncoder\n\n## References\n* http://modbus.org/docs/PI_MBUS_300.pdf\n* http://www.simplymodbus.ca/FAQ.htm\n\n## Alternatives to this library\nDon't like this library? That's cool. Here are some alternatives\n\n* https://github.com/digitalpetri/modbus\n* https://github.com/infiniteautomation/modbus4j\n* https://github.com/kochedykov/jlibmodbus\n* https://github.com/steveohara/j2mod\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretrodaredevil%2Fio-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fretrodaredevil%2Fio-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretrodaredevil%2Fio-lib/lists"}