GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Put back the Javadoc from the 2012-era Serial library · jekyllwrite/processing@7567bb8

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
  • java/libraries/serial/src/processing/serial
    • Serial.java
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎java/libraries/serial/src/processing/serial/Serial.java‎

Copy file name to clipboardExpand all lines: java/libraries/serial/src/processing/serial/Serial.java
+179-27Lines changed: 179 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -65,26 +65,40 @@ public class Serial implements SerialPortEventListener {
6565
// * state of the RING, RLSD line
6666
// * sending breaks
6767

68+
/**
69+
* @param parent typically use "this"
70+
*/
6871
public Serial(PApplet parent) {
6972
this(parent, "COM1", 9600, 'N', 8, 1);
7073
}
7174

72-
75+
76+
/**
77+
* @param baudRate 9600 is the default
78+
*/
7379
public Serial(PApplet parent, int baudRate) {
7480
this(parent, "COM1", baudRate, 'N', 8, 1);
7581
}
7682

77-
83+
84+
/**
85+
* @param portName name of the port (COM1 is the default)
86+
*/
7887
public Serial(PApplet parent, String portName) {
7988
this(parent, portName, 9600, 'N', 8, 1);
8089
}
8190

82-
91+
8392
public Serial(PApplet parent, String portName, int baudRate) {
8493
this(parent, portName, baudRate, 'N', 8, 1);
8594
}
8695

87-
96+
97+
/**
98+
* @param parity 'N' for none, 'E' for even, 'O' for odd, 'M' for mark, 'S' for space ('N' is the default)
99+
* @param dataBits 8 is the default
100+
* @param stopBits 1.0, 1.5, or 2.0 (1.0 is the default)
101+
*/
88102
public Serial(PApplet parent, String portName, int baudRate, char parity, int dataBits, float stopBits) {
89103
this.parent = parent;
90104
parent.registerMethod("dispose", this);
@@ -140,12 +154,15 @@ private Method findCallback(final String name) {
140154
return null;
141155
}
142156

143-
157+
158+
/**
159+
* Used by PApplet to shut things down.
160+
*/
144161
public void dispose() {
145162
stop();
146163
}
147164

148-
165+
149166
/**
150167
* Return true if this port is still active and hasn't run
151168
* into any trouble.
@@ -169,26 +186,44 @@ public void pre() {
169186
}
170187

171188

189+
/**
190+
* @generate Serial_available.xml
191+
* @webref serial:serial
192+
* @usage web_application
193+
*/
172194
public int available() {
173195
return (inBuffer-readOffset);
174196
}
175197

176-
198+
199+
/**
200+
* @generate Serial_buffer.xml
201+
* @webref serial:serial
202+
* @usage web_application
203+
* @param size number of bytes to buffer
204+
*/
177205
public void buffer(int size) {
178206
bufferUntilSize = size;
179207
}
180208

209+
181210
/**
182-
* @webref
183-
* @brief
184-
* @param inByte byte to buffer until it's reached
211+
* @generate Serial_bufferUntil.xml
212+
* @webref serial:serial
213+
* @usage web_application
214+
* @param inByte the value to buffer until
185215
*/
186216
public void bufferUntil(int inByte) {
187217
bufferUntilSize = 0;
188218
bufferUntilByte = (byte)inByte;
189219
}
190220

191-
221+
222+
/**
223+
* @generate Serial_clear.xml
224+
* @webref serial:serial
225+
* @usage web_application
226+
*/
192227
public void clear() {
193228
synchronized (buffer) {
194229
inBuffer = 0;
@@ -205,7 +240,7 @@ public boolean getCTS() {
205240
}
206241
}
207242

208-
243+
209244
public boolean getDSR() {
210245
try {
211246
return port.isDSR();
@@ -214,12 +249,21 @@ public boolean getDSR() {
214249
}
215250
}
216251

217-
252+
218253
public static Map<String, String> getProperties(String portName) {
219254
return SerialPortList.getPortProperties(portName);
220255
}
221256

222257

258+
/**
259+
* @generate Serial_last.xml
260+
* <h3>Advanced</h3>
261+
* Same as read() but returns the very last value received
262+
* and clears the buffer. Useful when you just want the most
263+
* recent value sent over the port.
264+
* @webref serial:serial
265+
* @usage web_application
266+
*/
223267
public int last() {
224268
if (inBuffer == readOffset) {
225269
return -1;
@@ -233,19 +277,34 @@ public int last() {
233277
}
234278
}
235279

236-
280+
281+
/**
282+
* @generate Serial_lastChar.xml
283+
* @webref serial:serial
284+
* @usage web_application
285+
*/
237286
public char lastChar() {
238287
return (char)last();
239288
}
240289

241-
290+
291+
/**
292+
* @generate Serial_list.xml
293+
* @webref serial
294+
* @usage web_application
295+
*/
242296
public static String[] list() {
243297
// returns list sorted alphabetically, thus cu.* comes before tty.*
244298
// this was different with RXTX
245299
return SerialPortList.getPortNames();
246300
}
247301

248-
302+
303+
/**
304+
* @generate Serial_read.xml
305+
* @webref serial:serial
306+
* @usage web_application
307+
*/
249308
public int read() {
250309
if (inBuffer == readOffset) {
251310
return -1;
@@ -261,7 +320,12 @@ public int read() {
261320
}
262321
}
263322

264-
323+
324+
/**
325+
* @generate Serial_readBytes.xml
326+
* @webref serial:serial
327+
* @usage web_application
328+
*/
265329
public byte[] readBytes() {
266330
if (inBuffer == readOffset) {
267331
return null;
@@ -277,6 +341,16 @@ public byte[] readBytes() {
277341
}
278342

279343

344+
/**
345+
* <h3>Advanced</h3>
346+
* Grab whatever is in the serial buffer, and stuff it into a
347+
* byte buffer passed in by the user. This is more memory/time
348+
* efficient than readBytes() returning a byte[] array.
349+
*
350+
* Returns an int for how many bytes were read. If more bytes
351+
* are available than can fit into the byte array, only those
352+
* that will fit are read.
353+
*/
280354
public int readBytes(byte[] dest) {
281355
if (inBuffer == readOffset) {
282356
return 0;
@@ -298,6 +372,12 @@ public int readBytes(byte[] dest) {
298372
}
299373

300374

375+
/**
376+
* @generate Serial_readBytesUntil.xml
377+
* @webref serial:serial
378+
* @usage web_application
379+
* @param inByte character designated to mark the end of the data
380+
*/
301381
public byte[] readBytesUntil(int inByte) {
302382
if (inBuffer == readOffset) {
303383
return null;
@@ -328,7 +408,15 @@ public byte[] readBytesUntil(int inByte) {
328408
}
329409
}
330410

331-
411+
412+
/**
413+
* <h3>Advanced</h3>
414+
* If dest[] is not big enough, then -1 is returned,
415+
* and an error message is printed on the console.
416+
* If nothing is in the buffer, zero is returned.
417+
* If 'interesting' byte is not in the buffer, then 0 is returned.
418+
* @param dest passed in byte array to be altered
419+
*/
332420
public int readBytesUntil(int inByte, byte[] dest) {
333421
if (inBuffer == readOffset) {
334422
return 0;
@@ -365,20 +453,41 @@ public int readBytesUntil(int inByte, byte[] dest) {
365453
}
366454
}
367455

368-
456+
457+
/**
458+
* @generate Serial_readChar.xml
459+
* @webref serial:serial
460+
* @usage web_application
461+
*/
369462
public char readChar() {
370463
return (char) read();
371464
}
372465

373-
466+
467+
/**
468+
* @generate Serial_readString.xml
469+
* @webref serial:serial
470+
* @usage web_application
471+
*/
374472
public String readString() {
375473
if (inBuffer == readOffset) {
376474
return null;
377475
}
378476
return new String(readBytes());
379477
}
380478

381-
479+
480+
/**
481+
* @generate Serial_readStringUntil.xml
482+
*<h3>Advanced</h3>
483+
* If you want to move Unicode data, you can first convert the
484+
* String to a byte stream in the representation of your choice
485+
* (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
486+
*
487+
* @webref serial:serial
488+
* @usage web_application
489+
* @param inByte character designated to mark the end of the data
490+
*/
382491
public String readStringUntil(int inByte) {
383492
byte temp[] = readBytesUntil(inByte);
384493
if (temp == null) {
@@ -389,6 +498,12 @@ public String readStringUntil(int inByte) {
389498
}
390499

391500

501+
/**
502+
* @generate serialEvent.xml
503+
* @webref serial:events
504+
* @usage web_application
505+
* @param serialPorttEvent the port where new data is available
506+
*/
392507
public void serialEvent(SerialPortEvent event) {
393508
if (event.getEventType() == SerialPortEvent.RXCHAR) {
394509
int toRead;
@@ -438,7 +553,10 @@ public void serialEvent(SerialPortEvent event) {
438553
}
439554
}
440555

441-
556+
557+
/**
558+
* Set the DTR line
559+
*/
442560
public void setDTR(boolean state) {
443561
// there is no way to influence the behavior of the DTR line when opening the serial port
444562
// this means that at least on Linux and OS X, Arduino devices are always reset
@@ -449,7 +567,10 @@ public void setDTR(boolean state) {
449567
}
450568
}
451569

452-
570+
571+
/**
572+
* Set the RTS line
573+
*/
453574
public void setRTS(boolean state) {
454575
try {
455576
port.setRTS(state);
@@ -458,7 +579,12 @@ public void setRTS(boolean state) {
458579
}
459580
}
460581

461-
582+
583+
/**
584+
* @generate Serial_stop.xml
585+
* @webref serial:serial
586+
* @usage web_application
587+
*/
462588
public void stop() {
463589
try {
464590
port.closePort();
@@ -469,7 +595,10 @@ public void stop() {
469595
readOffset = 0;
470596
}
471597

472-
598+
599+
/**
600+
* @param src data to write
601+
*/
473602
public void write(byte[] src) {
474603
try {
475604
// this might block if the serial device is not yet ready (esp. tty devices under OS X)
@@ -480,7 +609,12 @@ public void write(byte[] src) {
480609
}
481610
}
482611

483-
612+
613+
/**
614+
* <h3>Advanced</h3>
615+
* This will handle both ints, bytes and chars transparently.
616+
* @param src data to write
617+
*/
484618
public void write(int src) {
485619
try {
486620
port.writeInt(src);
@@ -489,7 +623,25 @@ public void write(int src) {
489623
}
490624
}
491625

492-
626+
627+
/**
628+
* @generate Serial_write.xml
629+
* <h3>Advanced</h3>
630+
* Write a String to the output. Note that this doesn't account
631+
* for Unicode (two bytes per char), nor will it send UTF8
632+
* characters.. It assumes that you mean to send a byte buffer
633+
* (most often the case for networking and serial i/o) and
634+
* will only use the bottom 8 bits of each char in the string.
635+
* (Meaning that internally it uses String.getBytes)
636+
*
637+
* If you want to move Unicode data, you can first convert the
638+
* String to a byte stream in the representation of your choice
639+
* (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
640+
*
641+
* @webref serial:serial
642+
* @usage web_application
643+
* @param src data to write
644+
*/
493645
public void write(String src) {
494646
try {
495647
port.writeString(src);

0 commit comments

Comments
0 (0)
You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.