firmata4j is a client library of Firmata written in Java. The library allows controlling Arduino (or another board) which runs Firmata protocol from your java program.
Add the following dependency to pom.xml of your project:
<dependency>
<groupId>com.github.kurbatov</groupId>
<artifactId>firmata4j</artifactId>
<version>2.3.8</version>
</dependency>General scenario of usage is following:
// construct a Firmata device instance
IODevice device = new FirmataDevice("/dev/ttyUSB0"); // using the name of a port
// IODevice device = new FirmataDevice(new NetworkTransport("192.168.1.18:4334")); // using a network address
// subscribe to events using device.addEventListener(...);
// and/or device.getPin(n).addEventListener(...);
device.start(); // initiate communication to the device
device.ensureInitializationIsDone(); // wait for initialization is done
// sending commands to the board
device.stop(); // stop communication to the deviceSending commands to the board may cause the device to emit events. Registered listeners process the events asynchronously. You can add and remove listeners along the way.
You can subscribe to events of the device or its pin.
device.addEventListener(new IODeviceEventListener() {
@Override
public void onStart(IOEvent event) {
// since this moment we are sure that the device is initialized
// so we can hide initialization spinners and begin doing cool stuff
System.out.println("Device is ready");
}
@Override
public void onStop(IOEvent event) {
// since this moment we are sure that the device is properly shut down
System.out.println("Device has been stopped");
}
@Override
public void onPinChange(IOEvent event) {
// here we react to changes of pins' state
Pin pin = event.getPin();
System.out.println(
String.format(
"Pin %d got a value of %d",
pin.getIndex(),
pin.getValue())
);
}
@Override
public void onMessageReceive(IOEvent event, String message) {
// here we react to receiving a text message from the device
System.out.println(message);
}
});To obtain more fine grained control you can subscribe to events of a particular pin.
Pin pin = device.getPin(2);
pin.addEventListener(new PinEventListener() {
@Override
public void onModeChange(IOEvent event) {
System.out.println("Mode of the pin has been changed");
}
@Override
public void onValueChange(IOEvent event) {
System.out.println("Value of the pin has been changed");
}
});You can change the mode and value of a pin:
pin.setMode(Pin.Mode.OUTPUT); // our listeners will get event about this change
pin.setValue(1); // and then about this changefirmata4j supports working with I2C devices. You can obtain a reference to an I2C device in this way:
IODevice device = new FirmataDevice(port);
...
byte i2cAddress = 0x3C;
I2CDevice i2cDevice = device.getI2CDevice(i2cAddress);You may find convenient writing a wrapper for I2CDevice class
to facilitate communication with I2C device. Consider SSD1306
and I2CExample
classes as an example of that approach.
firmata4j allows sending an arbitrary binary message to the device. For example, setting sampling intervall using a low-level message:
device.sendMessage(FirmataMessageFactory.setSamplingInterval(12));Low-level event handlers are supported as well. Those may be useful for debugging or processing custom messages from a device with modified protocol implementation.
device.addProtocolMessageHandler(FirmataEventType.SYSEX_CUSTOM_MESSAGE, new Consumer<Event>() {
@Override
public void accept(Event evt) {
byte[] message = (byte[]) evt.getBodyItem(FirmataEventType.SYSEX_CUSTOM_MESSAGE);
byte messageType = message[0];
// and so on
}
});Low-level event handlers allow regestering a watchdog:
IODevice device = new FirmataDevice(port);
//...
FirmataWatchdog watchdog = new FirmataWatchdog(3000, new Runnable() {
@Override
public void run() {
// do something when there were no low-level events during 3000 milliseconds
}
});
device.addProtocolMessageHandler(FirmataEventType.ANY, watchdog);
//...
device.start();This watchdog implementation gets activated by the first received message since it subscribed. That's why it should be registered before communication starts.
You can get visual representation of device's pins using JPinboard Swing component.
JPinboard pinboard = new JPinboard(device);
JFrame frame = new JFrame("Pinboard Example");
frame.add(pinboard);
frame.pack();
frame.setVisible(true);JPinboard allows setting the pin's mode by choosing one from a context menu of
the pin. State of the output pin can be changed by double clicking on it.
An example of JPinboard usage can be found in
org.firmata4j.Example class.
firmata4j sticks to Firmata protocol versions. The first available version of firmata4j is 2.3.1.
firmata4j-2.3.x will work well with Fimata v. 2.3.x. Actually it should work with Firmata v. 2.x.x but not necessarily support all of the protocol features. The first digits of versions must be equal because those stand for incompatible changes of the protocol.
Arduino IDE is shipped with an implementation of Firmata protocol. You can upload it as follows:
File -> Examples -> Firmata -> StandardFirmata in IDE's menuTools -> BoardTools -> Port (it is already selected if you have uploaded something to your Arduino)Upload buttonNote that firmata4j is focused to be client for the StandardFirmata firmware.
Although there are several other firmwares that support Firmata protocol, those
may implement only a featured subset of the protocol. A firmware has to respond
to the following requests in order for firmata4j to initialize properly:
REPORT_FIRMWARECAPABILITY_QUERYPIN_STATE_QUERYANALOG_MAPPING_QUERYContributions are welcome. If you discover a bug or would like to propose a new feature, please, open a new issue.
If you have an improvement to share, please, do the following:
git clone https://github.com/<your_username>/firmata4j.git)git checkout -b my-new-feature)git commit -am 'Adds some feature')git push origin my-new-feature)firmata4j is distributed under the terms of the MIT License. See the LICENSE file.