Skip to content

Commit b16bd8f

Browse files
kurbatovkurbatov
committed
feat(doc): update documentation before release
1 parent ff2ac20 commit b16bd8f

File tree

3 files changed

+143
-41
lines changed

3 files changed

+143
-41
lines changed

‎README.md

+67-18
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,16 @@ Add the following dependency to `pom.xml` of your project:
2121
<dependency>
2222
<groupId>com.github.kurbatov</groupId>
2323
<artifactId>firmata4j</artifactId>
24-
<version>2.3.6</version>
24+
<version>2.3.7</version>
2525
</dependency>
2626
```
2727

2828
## Usage
2929
General scenario of usage is following:
3030
```java
31-
IODevice device = new FirmataDevice("/dev/ttyUSB0"); // construct the Firmata device instance using the name of a port
31+
// construct a Firmata device instance
32+
IODevice device = new FirmataDevice("/dev/ttyUSB0"); // using the name of a port
33+
// IODevice device = new FirmataDevice(new NetworkTransport("192.168.1.18:4334")); // using a network address
3234
// subscribe to events using device.addEventListener(...);
3335
// and/or device.getPin(n).addEventListener(...);
3436
device.start(); // initiate communication to the device
@@ -103,22 +105,6 @@ pin.setMode(Pin.Mode.OUTPUT); // our listeners will get event about this change
103105
pin.setValue(1); // and then about this change
104106
```
105107

106-
You can get visual representation of device's pins using `JPinboard` Swing component.
107-
108-
```java
109-
JPinboard pinboard = new JPinboard(device);
110-
JFrame frame = new JFrame("Pinboard Example");
111-
frame.add(pinboard);
112-
frame.pack();
113-
frame.setVisible(true);
114-
```
115-
116-
`JPinboard` allows setting the pin's mode by choosing one from a context menu of
117-
the pin. State of the output pin can be changed by double clicking on it.
118-
119-
An example of `JPinboard` usage can be found in
120-
[`org.firmata4j.Example` class](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/Example.java).
121-
122108
## I2C
123109
**firmata4j** supports working with I2C devices. You can obtain a reference to
124110
an I2C device in this way:
@@ -135,6 +121,69 @@ to facilitate communication with I2C device. Consider [`SSD1306`](https://github
135121
and [`I2CExample`](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/I2CExample.java)
136122
classes as an example of that approach.
137123

124+
## Low-Level Messages and Events
125+
126+
**firmata4j** allows sending an arbitrary binary message to the device. For
127+
example, setting sampling intervall using a low-level message:
128+
129+
```java
130+
device.sendMessage(FirmataMessageFactory.setSamplingInterval(12));
131+
```
132+
133+
Low-level event handlers are supported as well. Those may be useful for
134+
debugging or processing custom messages from a device with modified protocol
135+
implementation.
136+
137+
```java
138+
device.addProtocolMessageHandler(FirmataEventType.SYSEX_CUSTOM_MESSAGE, new Consumer<Event>() {
139+
@Override
140+
public void accept(Event evt) {
141+
byte[] message = (byte[]) evt.getBodyItem(FirmataEventType.SYSEX_CUSTOM_MESSAGE);
142+
byte messageType = message[0];
143+
// and so on
144+
}
145+
});
146+
```
147+
148+
## Watchdog
149+
150+
Low-level event handlers allow regestering a watchdog:
151+
152+
```java
153+
IODevice device = new FirmataDevice(port);
154+
//...
155+
FirmataWatchdog watchdog = new FirmataWatchdog(3000, new Runnable() {
156+
@Override
157+
public void run() {
158+
// do something when there were no low-level events during 3000 milliseconds
159+
}
160+
});
161+
device.addProtocolMessageHandler(FirmataEventType.ANY, watchdog);
162+
//...
163+
device.start();
164+
```
165+
166+
This watchdog implementation gets activated by the first received message since
167+
it subscribed. That's why it should be registered before communication starts.
168+
169+
## Visualization
170+
171+
You can get visual representation of device's pins using `JPinboard` Swing component.
172+
173+
```java
174+
JPinboard pinboard = new JPinboard(device);
175+
JFrame frame = new JFrame("Pinboard Example");
176+
frame.add(pinboard);
177+
frame.pack();
178+
frame.setVisible(true);
179+
```
180+
181+
`JPinboard` allows setting the pin's mode by choosing one from a context menu of
182+
the pin. State of the output pin can be changed by double clicking on it.
183+
184+
An example of `JPinboard` usage can be found in
185+
[`org.firmata4j.Example` class](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/Example.java).
186+
138187
## Versions
139188
**firmata4j** sticks to Firmata protocol versions. The first available version
140189
of **firmata4j** is 2.3.1.

‎README_ru.md

+70-19
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,16 @@ Java.
2222
<dependency>
2323
<groupId>com.github.kurbatov</groupId>
2424
<artifactId>firmata4j</artifactId>
25-
<version>2.3.6</version>
25+
<version>2.3.7</version>
2626
</dependency>
2727
```
2828

2929
## Использование
3030
Основной сценарий использования:
3131
```java
32-
IODevice device = new FirmataDevice("/dev/ttyUSB0"); // создать экземпляр устройства Firmata используя имя порта
32+
// создать экземпляр устройства Firmata
33+
IODevice device = new FirmataDevice("/dev/ttyUSB0"); // используя имя порта
34+
// IODevice device = new FirmataDevice(new NetworkTransport("192.168.1.18:4334")); // используя сетевой адрес
3335
// подписаться на события при помощи device.addEventListener(...);
3436
// и/или device.getPin(n).addEventListener(...);
3537
device.start(); // начать обмен сообщениями с устройствами
@@ -105,23 +107,6 @@ pin.setMode(Pin.Mode.OUTPUT); // наши обработчики получат
105107
pin.setValue(1); // ... а после и об этом изменении
106108
```
107109

108-
Визуальное представление состояний портов устройства можно получить при помощи
109-
компонента `JPinboard`.
110-
111-
```java
112-
JPinboard pinboard = new JPinboard(device);
113-
JFrame frame = new JFrame("Pinboard Example");
114-
frame.add(pinboard);
115-
frame.pack();
116-
frame.setVisible(true);
117-
```
118-
119-
`JPinboard` позволяет установить режим порта из контекстного меню. Состояние
120-
порта вывода может быть изменено двойным щелчком на его изображении.
121-
122-
Пример использования `JPinboard` может быть найден в классе
123-
[`org.firmata4j.Example`](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/Example.java).
124-
125110
## I2C
126111
**firmata4j** поддерживает взаимодействие с I2C устройствами. Получить ссылку на
127112
I2C устройство можно следующим способом:
@@ -140,6 +125,72 @@ I2CDevice i2cDevice = device.getI2CDevice(i2cAddress);
140125
и
141126
[`I2CExample`](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/I2CExample.java).
142127

128+
## Низкоуровневые сообщения и события
129+
130+
**firmata4j** позволяет отослать произвольное бинарное сообщение устройству.
131+
Например, установка интервала измерений значения аналоговых портов (sampling
132+
intervall) с использованием низкоуровневого сообщения:
133+
134+
```java
135+
device.sendMessage(FirmataMessageFactory.setSamplingInterval(12));
136+
```
137+
138+
Также поддерживаются обработчики низкоуровневых событий. Они могут быть полезны
139+
для отладки или обработки сообщений от устройства с модифицированной
140+
имплементацией Firmata.
141+
142+
```java
143+
device.addProtocolMessageHandler(FirmataEventType.SYSEX_CUSTOM_MESSAGE, new Consumer<Event>() {
144+
@Override
145+
public void accept(Event evt) {
146+
byte[] message = (byte[]) evt.getBodyItem(FirmataEventType.SYSEX_CUSTOM_MESSAGE);
147+
byte messageType = message[0];
148+
// и так далее
149+
}
150+
});
151+
```
152+
153+
## Контроль подключения
154+
155+
Обработчики низкоуровневых событий помогают имплементировать контроль
156+
подключения к устройству:
157+
158+
```java
159+
IODevice device = new FirmataDevice(port);
160+
//...
161+
FirmataWatchdog watchdog = new FirmataWatchdog(3000, new Runnable() {
162+
@Override
163+
public void run() {
164+
// действия, если в течение 3000 мс не произошло ни одного низкоуровневого события
165+
}
166+
});
167+
device.addProtocolMessageHandler(FirmataEventType.ANY, watchdog);
168+
//...
169+
device.start();
170+
```
171+
172+
`FirmatWatchdog` активируется первым с момента регистрации сообщением. Поэтому
173+
экземпляр `FirmatWatchdog` должен быть зарегистрирован до начала взаимодействия
174+
с устройством.
175+
176+
## Визуализация
177+
Визуальное представление состояний портов устройства можно получить при помощи
178+
компонента `JPinboard`.
179+
180+
```java
181+
JPinboard pinboard = new JPinboard(device);
182+
JFrame frame = new JFrame("Pinboard Example");
183+
frame.add(pinboard);
184+
frame.pack();
185+
frame.setVisible(true);
186+
```
187+
188+
`JPinboard` позволяет установить режим порта из контекстного меню. Состояние
189+
порта вывода может быть изменено двойным щелчком на его изображении.
190+
191+
Пример использования `JPinboard` может быть найден в классе
192+
[`org.firmata4j.Example`](https://github.com/kurbatov/firmata4j/blob/master/src/main/java/org/firmata4j/Example.java).
193+
143194
## Версии
144195
**firmata4j** придерживается версий протокола Firmata. Первая доступная версия
145196
**firmata4j** - 2.3.1.

‎src/main/java/org/firmata4j/firmata/FirmataWatchdog.java

+6-4
Original file line numberDiff line numberDiff line change
@@ -36,18 +36,20 @@
3636
*
3737
* It gets activated by the first event received since the watchdog subscribed.
3838
*
39-
* Example:
39+
* <p>Example:
4040
* <pre>
41+
* IODevice device = new FirmataDevice(port);
42+
* //...
4143
* FirmataWatchdog watchdog = new FirmataWatchdog(3000, new Runnable() {
42-
* @Override
4344
* public void run() {
4445
* // do something when there were no low-level events during 3000 milliseconds
45-
* }
46-
* });
46+
* }
47+
* });
4748
* device.addProtocolMessageHandler(FirmataEventType.ANY, watchdog);
4849
* //...
4950
* device.start();
5051
* </pre>
52+
* </p>
5153
*
5254
* @author Oleg Kurbatov &lt;[email protected]&gt;
5355
*/

0 commit comments

Comments
 (0)