{"id":14962109,"url":"https://github.com/kurbatov/firmata4j","last_synced_at":"2025-05-07T15:21:37.895Z","repository":{"id":20933194,"uuid":"24221426","full_name":"kurbatov/firmata4j","owner":"kurbatov","description":"Firmata client written in Java.","archived":false,"fork":false,"pushed_at":"2023-10-31T16:18:39.000Z","size":262,"stargazers_count":88,"open_issues_count":14,"forks_count":45,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-31T11:21:10.138Z","etag":null,"topics":["arduino","firmata","firmata-client","firmata-protocol","internet-of-things","java","robotics"],"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/kurbatov.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":"maven/firmata4j","community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.paypal.me/OlegKurbatov"]}},"created_at":"2014-09-19T08:01:33.000Z","updated_at":"2024-11-14T06:25:55.000Z","dependencies_parsed_at":"2023-02-18T06:31:08.089Z","dependency_job_id":"735c0c86-016b-45f0-84f1-590db93ba831","html_url":"https://github.com/kurbatov/firmata4j","commit_stats":{"total_commits":96,"total_committers":17,"mean_commits":5.647058823529412,"dds":0.3125,"last_synced_commit":"308dba36e3b202b78b4642e30f3ebfa130b70c67"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurbatov%2Ffirmata4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurbatov%2Ffirmata4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurbatov%2Ffirmata4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurbatov%2Ffirmata4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kurbatov","download_url":"https://codeload.github.com/kurbatov/firmata4j/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252902728,"owners_count":21822292,"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":["arduino","firmata","firmata-client","firmata-protocol","internet-of-things","java","robotics"],"created_at":"2024-09-24T13:29:09.828Z","updated_at":"2025-05-07T15:21:37.873Z","avatar_url":"https://github.com/kurbatov.png","language":"Java","funding_links":["https://tidelift.com/funding/github/maven/firmata4j","https://www.paypal.me/OlegKurbatov"],"categories":[],"sub_categories":[],"readme":"[![Get help on Codementor](https://cdn.codementor.io/badges/get_help_github.svg)](https://www.codementor.io/@olegkurbatov?utm_source=github\u0026utm_medium=button\u0026utm_term=olegkurbatov\u0026utm_campaign=github)\n\n## firmata4j\n**firmata4j** is a client library of [Firmata](https://github.com/firmata/protocol)\nwritten in Java. The library allows controlling Arduino (or another board) which\nruns Firmata protocol from your java program.\n\n## Capabilities\n- Interaction with a board and its pins in object-oriented style\n- Communication over serial port, network or custom transport layer\n- Abstraction over details of the protocol\n- Provides a UI component that visualize the current state of pins and allows\nchanging their mode and state\n- Allows communicating with I2C devices connected to the board\n\n## Installation\n\n### Maven\nAdd the following dependency to `pom.xml` of your project:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.kurbatov\u003c/groupId\u003e\n    \u003cartifactId\u003efirmata4j\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.9\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nIf you want to connect to the device via serial port (which is the most probable\ncase), please include one of the following libraries as a dependency into\nthe `pom.xml`:\n\n```xml\n\u003c!-- only one of the following --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.fazecast\u003c/groupId\u003e\n    \u003cartifactId\u003ejSerialComm\u003c/artifactId\u003e\n    \u003cversion\u003e2.6.2\u003c/version\u003e\n\u003c/dependency\u003e\n\u003c!-- or --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.java-native\u003c/groupId\u003e\n    \u003cartifactId\u003ejssc\u003c/artifactId\u003e\n    \u003cversion\u003e2.9.4\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**jssc** is an older library that worked just fine until recently. Now it reveals\n[issues on **GraalVM** and latest updates of **Windows 10**](https://github.com/kurbatov/firmata4j/issues/42).\n**firmata4j** was using **jssc** by default in versions prior to **2.3.9**.\n\n**jSerialComm** has proven itself to be working on **GraalVM** and latest\nupdates of **Windows 10**.\n\n## Usage\nGeneral scenario of usage is following:\n```java\n// construct a Firmata device instance\nIODevice device = new FirmataDevice(\"/dev/ttyUSB0\"); // using the name of a port\n// IODevice device = new FirmataDevice(new NetworkTransport(\"192.168.1.18:4334\")); // using a network address\n// subscribe to events using device.addEventListener(...);\n// and/or device.getPin(n).addEventListener(...);\ndevice.start(); // initiate communication to the device\ndevice.ensureInitializationIsDone(); // wait for initialization is done\n// sending commands to the board\ndevice.stop(); // stop communication to the device\n```\n\nSending commands to the board may cause the device to emit events.\nRegistered listeners process the events asynchronously. You can add and remove\nlisteners along the way.\n\nYou can subscribe to events of the device or its pin.\n\n```java\ndevice.addEventListener(new IODeviceEventListener() {\n    @Override\n    public void onStart(IOEvent event) {\n        // since this moment we are sure that the device is initialized\n        // so we can hide initialization spinners and begin doing cool stuff\n        System.out.println(\"Device is ready\");\n    }\n\n    @Override\n    public void onStop(IOEvent event) {\n        // since this moment we are sure that the device is properly shut down\n        System.out.println(\"Device has been stopped\");\n    }\n\n    @Override\n    public void onPinChange(IOEvent event) {\n        // here we react to changes of pins' state\n        Pin pin = event.getPin();\n        System.out.println(\n                String.format(\n                    \"Pin %d got a value of %d\",\n                    pin.getIndex(),\n                    pin.getValue())\n            );\n    }\n\n    @Override\n    public void onMessageReceive(IOEvent event, String message) {\n        // here we react to receiving a text message from the device\n        System.out.println(message);\n    }\n});\n```\n\nTo obtain more fine grained control you can subscribe to events of a particular\npin.\n\n```java\nPin pin = device.getPin(2);\npin.addEventListener(new PinEventListener() {\n    @Override\n    public void onModeChange(IOEvent event) {\n        System.out.println(\"Mode of the pin has been changed\");\n    }\n\n    @Override\n    public void onValueChange(IOEvent event) {\n        System.out.println(\"Value of the pin has been changed\");\n    }\n});\n```\n\nYou can change the mode and value of a pin:\n\n```java\npin.setMode(Pin.Mode.OUTPUT); // our listeners will get event about this change\npin.setValue(1); // and then about this change\n```\n\n## I2C\n**firmata4j** supports working with I2C devices. You can obtain a reference to\nan I2C device in this way:\n\n```java\nIODevice device = new FirmataDevice(port);\n...\nbyte i2cAddress = 0x3C;\nI2CDevice i2cDevice = device.getI2CDevice(i2cAddress);\n```\n\nYou may find convenient writing a wrapper for [`I2CDevice` class](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/I2CDevice.java)\nto facilitate communication with I2C device. Consider [`SSD1306`](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/ssd1306/SSD1306.java)\nand [`I2CExample`](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/I2CExample.java)\nclasses as an example of that approach.\n\n## Low-Level Messages and Events\n\n**firmata4j** allows sending an arbitrary binary message to the device. For\nexample, setting sampling intervall using a low-level message:\n\n```java\ndevice.sendMessage(FirmataMessageFactory.setSamplingInterval(12));\n```\n\nLow-level event handlers are supported as well. Those may be useful for\ndebugging or processing custom messages from a device with modified protocol\nimplementation.\n\n```java\ndevice.addProtocolMessageHandler(FirmataEventType.SYSEX_CUSTOM_MESSAGE, new Consumer\u003cEvent\u003e() {\n    @Override\n    public void accept(Event evt) {\n        byte[] message = (byte[]) evt.getBodyItem(FirmataEventType.SYSEX_CUSTOM_MESSAGE);\n        byte messageType = message[0];\n        // and so on\n    }\n});\n```\n\n## Watchdog\n\nLow-level event handlers allow regestering a watchdog:\n\n```java\nIODevice device = new FirmataDevice(port);\n//...\nFirmataWatchdog watchdog = new FirmataWatchdog(3000, new Runnable() {\n    @Override\n    public void run() {\n        // do something when there were no low-level events during 3000 milliseconds\n    }\n});\ndevice.addProtocolMessageHandler(FirmataEventType.ANY, watchdog);\n//...\ndevice.start();\n```\n\nThis watchdog implementation gets activated by the first received message since\nit subscribed. That's why it should be registered before communication starts.\n\n## Visualization\n\nYou can get visual representation of device's pins using `JPinboard` Swing component.\n\n```java\nJPinboard pinboard = new JPinboard(device);\nJFrame frame = new JFrame(\"Pinboard Example\");\nframe.add(pinboard);\nframe.pack();\nframe.setVisible(true);\n```\n\n`JPinboard` allows setting the pin's mode by choosing one from a context menu of\nthe pin. State of the output pin can be changed by double clicking on it.\n\nAn example of `JPinboard` usage can be found in\n[`org.firmata4j.Example` class](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/Example.java).\n\n## Versions\n**firmata4j** sticks to Firmata protocol versions. The first available version\nof **firmata4j** is 2.3.1.\n\n**firmata4j**-2.3.x will work well with Fimata v. 2.3.x. Actually it should work\nwith Firmata v. 2.x.x but not necessarily support all of the protocol features.\nThe first digits of versions must be equal because those stand for incompatible\nchanges of the protocol.\n\n## Uploading Firmata To Arduino\nArduino IDE is shipped with an implementation of Firmata protocol. You can\nupload it as follows:\n\n- Plug your Arduino to the computer\n- Launch Arduino IDE\n- Select `File -\u003e Examples -\u003e Firmata -\u003e StandardFirmata` in IDE's menu\n- Select your board in `Tools -\u003e Board`\n- Select the port in `Tools -\u003e Port` (it is already selected if you have uploaded something to your Arduino)\n- Click on `Upload` button\n\nNote that **firmata4j** is focused to be client for the `StandardFirmata` firmware.\nAlthough there are several other firmwares that support Firmata protocol, those\nmay implement only a featured subset of the protocol. A firmware has to respond\nto the following requests in order for **firmata4j** to initialize properly:\n\n- `REPORT_FIRMWARE`\n- `CAPABILITY_QUERY`\n- `PIN_STATE_QUERY`\n- `ANALOG_MAPPING_QUERY`\n\n## Cases\n\n- [Easy Peripherals for the Internet of Things](https://repositorio-aberto.up.pt/bitstream/10216/84433/2/138208.pdf)\n- [Modelovanie a Riadenie Hybridných Systémov s Využitím Petriho Sietí Vyšších Úrovní](http://www.fei.stuba.sk/docs/2016/autoreferaty/autoref_Kucera.pdf)\n- [Programmazione di Sistemi Embedded con Linguaggi ad Agenti: un Caso di Studio basato su Jason e Arduino](https://amslaurea.unibo.it/9188/1/cozzolino_francesco_tesi.pdf)\n- [Using **firmata4j** in Clojure](https://github.com/cowlike/firmata4j-samples-clojure)\n\n## Contributing\nContributions are welcome. If you discover a bug or would like to propose a new\nfeature, please, [open a new issue](https://github.com/kurbatov/firmata4j/issues/new).\n\nIf you have an improvement to share, please, do the following:\n\n1. Fork this repository\n2. Clone your own fork to your machine (`git clone https://github.com/\u003cyour_username\u003e/firmata4j.git`)\n3. Create a feature branch (`git checkout -b my-new-feature`)\n4. Change the code\n5. Commit the changes (`git commit -am 'Adds some feature'`)\n6. Push to the branch (`git push origin my-new-feature`)\n7. Create new Pull Request\n\n## License\n**firmata4j** is distributed under the terms of the MIT License. See the\n[LICENSE](https://github.com/kurbatov/firmata4j/blob/master/LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurbatov%2Ffirmata4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkurbatov%2Ffirmata4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurbatov%2Ffirmata4j/lists"}