eessppeelllloo/processing4
1
0
Fork 0
mirror of https://github.com/processing/processing4.git synced 2026-01-27 10:21:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated descriptions in comments for processing core and libraries

Browse Source
This commit is contained in:
Anadroid
2020-09-15 10:17:15 +02:00
parent ca77f527d5
commit 8a7c9571fa
26 changed files with 5190 additions and 4204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
java/libraries/io/src/processing/io/I2C.java
View File

@@ -30,7 +30,31 @@ import java.util.Arrays;
/**
* @webref
* Opens an I2C interface as master.<br/>
* <br/>
* I2C is a serial bus, commonly used to attach peripheral ICs (Integrated
* Circuits) to processors and microcontrollers. It uses two pins, SDA (for
* data) and SDL (for the clock signal). Multiple "slave" devices can be
* connected to the same bus, as long as they are responding to different
* addresses (see below).<br/>
* <br/>
* The I2C "master" device initiates a transmission, which includes sending the
* address of the desired "slave" device. I2C addresses consist of 7 bits plus
* one bit that indicates whether the device is being read from or written to.
* Some datasheets list the address in an 8 bit form (7 address bits + R/W bit),
* while others provide the address in a 7 bit form, with the address in the
* lower 7 bits.<br/>
* <br/>
* This library expects addresses in their 7 bit form, similar to Arduino's Wire
* library, and what is being output by the i2cdetect utility on Linux. If the
* address provided in a datasheet is greater than 127 (hex 0x7f) or there are
* separate addresses for read and write operations listed, which vary exactly
* by one, then you want to shift the this number by one bit to the right before
* passing it as an argument to
* <a href="I2C_beginTransmission_.html">beginTransmission()</a>.
*
* @webref
* @webBrief Opens an I2C interface as master
*/
public class I2C {
@@ -62,13 +86,22 @@ public class I2C {
}
/**
* Begins a transmission to an attached device
* @see write
* @see read
* @see endTransmission
* @webref
*/
/**
* Begins a transmission to an attached device.<br/>
* <br/>
* This function expects the address in the lower 7 bits, the same way as in
* Arduino's Wire library, and as shown in the output of the i2cdetect tool. If
* the address provided in a datasheet is greater than 127 (hex 0x7f) or there
* are separate addresses for read and write operations listed, which vary
* exactly by one, then you want to shift the this number by one bit to the
* right before passing it as an argument to this function.
*
* @see write
* @see read
* @see endTransmission
* @webref
* @webBrief Begins a transmission to an attached device
*/
public void beginTransmission(int slave) {
// addresses 120 (0x78) to 127 are additionally reserved
if (0x78 <= slave) {
@@ -81,10 +114,18 @@ public class I2C {
}
/**
* Closes the I2C device
* @webref
*/
/**
* Closes the I2C device<br/>
* </br>
* It is normally not necessary to explicitly close I2C interfaces, as they are
* closed automatically by the operating system when the sketch exits.</br>
* </br>
* Note: It is possible to have two or more object using the same interface at a
* time.
*
* @webref
* @webBrief Closes the I2C device.
*/
public void close() {
if (NativeInterface.isSimulated()) {
return;
@@ -104,12 +145,18 @@ public class I2C {
}
/**
* Ends the current transmissions
* @see beginTransmission
* @see write
* @webref
*/
/**
* Ends the current transmissions<br/>
* <br/>
* This executes any queued writes. <a href="I2C_read_.html">Read()</a>
* implicitly ends the current transmission as well, hence calling
* endTransmission() afterwards is not necessary.
*
* @see beginTransmission
* @see write
* @webref
* @webBrief Ends the current transmissions.
*/
public void endTransmission() {
if (!transmitting) {
// silently ignore this case
@@ -137,6 +184,7 @@ public class I2C {
* Lists all available I2C interfaces
* @return String array
* @webref
* @webBrief Lists all available I2C interfaces
*/
public static String[] list() {
if (NativeInterface.isSimulated()) {
@@ -161,15 +209,22 @@ public class I2C {
}
/**
* Reads bytes from the attached device
* @param len number of bytes to read
* @return bytes read from device
* @see beginTransmission
* @see write
* @see endTransmission
* @webref
*/
/**
* Read bytes from the attached device<br/>
* <br/>
* You must call beginTransmission() before calling this function. This function
* also ends the current transmission and sends any data that was queued using
* write() before. It is not necessary to call
* <a href="I2C_endTransmission_.html">endTransmission()</a> after read().
*
* @param len number of bytes to read
* @return bytes read from device
* @see beginTransmission
* @see write
* @see endTransmission
* @webref
* @webBrief Read bytes from the attached device.
*/
public byte[] read(int len) {
if (!transmitting) {
throw new RuntimeException("beginTransmisson has not been called");
@@ -195,14 +250,19 @@ public class I2C {
}
/**
* Adds bytes to be written to the device
* @param out bytes to be written
* @see beginTransmission
* @see read
* @see endTransmission
* @webref
*/
/**
* Add bytes to be written to the device<br/>
* <br/>
* You must call beginTransmission() before calling this function. The actual
* writing takes part when read() or endTransmission() is being called.
*
* @param out bytes to be written
* @see beginTransmission
* @see read
* @see endTransmission
* @webref
* @webBrief Add bytes to be written to the device.
*/
public void write(byte[] out) {
if (!transmitting) {
throw new RuntimeException("beginTransmisson has not been called");

31
java/libraries/io/src/processing/io/LED.java
View File

@@ -33,7 +33,19 @@ import java.util.Arrays;
/**
* @webref
* Opens a LED device.<br/>
* <br/>
* This class can control your computer's build-in LEDs, such as the ones
* commonly used to indicate the power status and disk activity.</br>
* <br/>
* Your operating system might not be set up to allow regular users to do this
* kind of modification. If this is the case you should install a so-called
* <i>udev rule</i> that relaxes the permissions for the files in
* /sys/class/leds. You can also try running Processing as root user using
* "sudo", but this is generally not recommended.
*
* @webref
* @webBrief Opens a LED device
*/
public class LED {
@@ -47,7 +59,7 @@ public class LED {
* Opens a LED device
* @param dev device name
* @see list
* @webref
* @webref Opens a LED device
*/
public LED(String dev) {
NativeInterface.loadLibrary();
@@ -107,6 +119,7 @@ public class LED {
* Sets the brightness
* @param bright 0.0 (off) to 1.0 (maximum)
* @webref
* @webBrief Sets the brightness
*/
public void brightness(float bright) {
if (bright < 0.0 || 1.0 < bright) {
@@ -126,10 +139,15 @@ public class LED {
}
/**
* Restores the previous state
* @webref
*/
/**
* Restores the previous state<br/>
* <br/>
* Without calling this function the LED will remain in the current state even
* after the sketch has been closed.
*
* @webref
* @webBrief Restores the previous state
*/
public void close() {
if (NativeInterface.isSimulated()) {
return;
@@ -154,6 +172,7 @@ public class LED {
* Lists all available LED devices
* @return String array
* @webref
* @webBrief Lists all available LED devices
*/
public static String[] list() {
if (NativeInterface.isSimulated()) {

39
java/libraries/io/src/processing/io/PWM.java
View File

@@ -33,7 +33,10 @@ import java.util.Arrays;
/**
* Opens a PWM channel
*
* @webref
* @webBrief Opens a PWM channel
*/
public class PWM {
@@ -45,7 +48,7 @@ public class PWM {
* Opens a PWM channel
* @param channel PWM channel
* @see list
* @webref
* @webref Opens a PWM channel
*/
public PWM(String channel) {
NativeInterface.loadLibrary();
@@ -90,7 +93,9 @@ public class PWM {
/**
* Disables the PWM output
*
* @webref
* @webBrief Disables the PWM output
*/
public void clear() {
if (NativeInterface.isSimulated()) {
@@ -105,10 +110,15 @@ public class PWM {
}
/**
* Gives ownership of a channel back to the operating system
* @webref
*/
/**
* Gives ownership of a channel back to the operating system<br/>
* <br/>
* Without calling this function the channel will remain in the current state
* even after the sketch has been closed.
*
* @webref
* @webBrief Gives ownership of a channel back to the operating system
*/
public void close() {
if (NativeInterface.isSimulated()) {
return;
@@ -134,6 +144,7 @@ public class PWM {
* Lists all available PWM channels
* @return String array
* @webref
* @webBrief Lists all available PWM channels
*/
public static String[] list() {
if (NativeInterface.isSimulated()) {
@@ -164,12 +175,16 @@ public class PWM {
}
/**
* Enables the PWM output
* @param period cycle period in Hz
* @param duty duty cycle, 0.0 (always off) to 1.0 (always on)
* @webref
*/
/**
* Enables the PWM output<br/>
* <br/>
* When no period is specified, a default 1 kHz (1000 Hz) is used.
*
* @param period cycle period in Hz
* @param duty duty cycle, 0.0 (always off) to 1.0 (always on)
* @webref
* @webBrief Enables the PWM output
*/
public void set(int period, float duty) {
if (NativeInterface.isSimulated()) {
return;
@@ -206,7 +221,7 @@ public class PWM {
/**
* Enables the PWM output with a preset period of 1 kHz
* @webref
* @nowebref
*/
public void set(float duty) {
set(1000, duty);

82
java/libraries/io/src/processing/io/SPI.java
View File

@@ -32,7 +32,29 @@ import java.util.Map;
/**
* @webref
* Opens an SPI interface as master<br/>
* </br>
* Serial Peripheral Interface (SPI) is a serial bus, commonly used to
* communicate with sensors and memory devices. It uses four pins: MOSI (Master
* Out Slave In), MISO (Master In Slave Out), and SCLK (clock signal) - those
* three are shared among all devices on the bus - as well as one or more SS
* (Slave Select) pins, that are used for the master to signal to the slave
* device that it is the desired respondent for the transmission.<br/>
* <br/>
* The "master" device initiates a transfer by pulling the SS pin of the "slave"
* low, and begins outputting a clock signal. In SPI, both the "master" as well
* as the "slave" device output data at the same time. It is hence not possible
* to read data without writing some (even if it means outputting zeros or other
* dummy data).</br>
* </br>
* There are multiple possible configuration settings for SPI, see
* <a href="SPI_settings_.html">settings()</a> for details.</br>
* <br/>
* This library supports multiple SPI objects making use of the same SPI
* interface.
*
* @webref
* @webBrief Opens an SPI interface as master
*/
public class SPI {
@@ -74,6 +96,7 @@ public class SPI {
* @param dev device name
* @see list
* @webref
* @webBrief Opens an SPI interface as master
*/
public SPI(String dev) {
NativeInterface.loadLibrary();
@@ -90,10 +113,18 @@ public class SPI {
}
/**
* Closes the SPI interface
* @webref
*/
/**
* Closes the SPI interface</br>
* </br>
* It is normally not necessary to explicitly close SPI interfaces, as they are
* closed automatically by the operating system when the sketch exits.</br>
* </br>
* Note: It is possible to have two or more objects using the same interface at
* a time.
*
* @webref
* @webBrief Closes the SPI interface
*/
public void close() {
if (NativeInterface.isSimulated()) {
return;
@@ -117,6 +148,7 @@ public class SPI {
* Lists all available SPI interfaces
* @return String array
* @webref
* @webBrief Lists all available SPI interfaces
*/
public static String[] list() {
if (NativeInterface.isSimulated()) {
@@ -141,13 +173,22 @@ public class SPI {
}
/**
* Configures the SPI interface
* @param maxSpeed maximum transmission rate in Hz, 500000 (500 kHz) is a resonable default
* @param dataOrder whether data is send with the first- or least-significant bit first (SPI.MSBFIRST or SPI.LSBFIRST, the former is more common)
* @param mode <a href="https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus#Clock_polarity_and_phase">SPI.MODE0 to SPI.MODE3</a>
* @webref
*/
/**
* Configures the SPI interface<br/>
* <br/>
* The default setting is: 500000, SPI.MSBFIRST, SPI.MODE0
*
* @param maxSpeed maximum transmission rate in Hz, 500000 (500 kHz) is a
* resonable default
* @param dataOrder whether data is send with the first- or least-significant
* bit first (SPI.MSBFIRST or SPI.LSBFIRST, the former is more
* common)
* @param mode <a href=
* "https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus#Clock_polarity_and_phase">SPI.MODE0
* to SPI.MODE3</a>
* @webref
* @webBrief Configures the SPI interface
*/
public void settings(int maxSpeed, int dataOrder, int mode) {
this.maxSpeed = maxSpeed;
this.dataOrder = dataOrder;
@@ -155,12 +196,17 @@ public class SPI {
}
/**
* Transfers data over the SPI bus
* @param out bytes to send
* @return bytes read in (array is the same length as out)
* @webref
*/
/**
* Transfers data over the SPI bus<br/>
* <br/>
* With SPI, data is simultaneously being exchanged between the master device
* and the slave device. For every byte that is being sent out, there's also one
* byte being read in.
*
* @param out bytes to send
* @return bytes read in (array is the same length as out)
* @webref Transfers data over the SPI bus
*/
public byte[] transfer(byte[] out) {
if (NativeInterface.isSimulated()) {
return new byte[out.length];

65
java/libraries/io/src/processing/io/SoftwareServo.java
View File

@@ -26,7 +26,17 @@ import processing.core.*;
/**
* @webref
* Opens an RC servo motor connected to a GPIO pin<br/>
* </br>
* This library uses timers to control RC servo motors by means of pulse width
* modulation (PWM). While not as accurate as dedicated PWM hardware, it has
* shown to be sufficient for many applications.<br/>
* <br/>
* Connect the signal wire (typically colored yellow) to any available GPIO pin
* and control the servo's angle as shown in the example sketch.
*
* @webref
* @webBrief Opens an RC servo motor connected to a GPIO pin
*/
public class SoftwareServo {
@@ -45,6 +55,7 @@ public class SoftwareServo {
* Opens a servo motor
* @param parent typically use "this"
* @webref
* @webBrief Opens a servo motor
*/
public SoftwareServo(PApplet parent) {
NativeInterface.loadLibrary();
@@ -54,6 +65,7 @@ public class SoftwareServo {
/**
* Closes a servo motor
* @webref
* @webBrief Closes a servo motor
*/
public void close() {
detach();
@@ -69,11 +81,20 @@ public class SoftwareServo {
}
/**
* Attaches a servo motor to a GPIO pin
* @param pin GPIO pin
* @webref
*/
/**
* Attaches a servo motor to a GPIO pin<br/>
* <br/>
* You must call this function before calling write(). Note that the servo motor
* will only be instructed to move after the first time write() is called.<br/>
* <br/>
* The optional parameters minPulse and maxPulse control the minimum and maximum
* pulse width durations. The default values, identical to those of Arduino's
* Servo class, should be compatible with most servo motors.
*
* @param pin GPIO pin
* @webref
* @webBrief Attaches a servo motor to a GPIO pin
*/
public void attach(int pin) {
detach();
this.pin = pin;
@@ -96,11 +117,19 @@ public class SoftwareServo {
}
/**
* Moves a servo motor to a given orientation
* @param angle angle in degrees (controls speed and direction on continuous-rotation servos)
* @webref
*/
/**
* Moves a servo motor to a given orientation<br/>
* <br/>
* If you are using this class in combination with a continuous rotation servo,
* different angles will result in the servo rotating forward or backward at
* different speeds. For regular servo motors, this will instruct the servo to
* rotate to and hold a specific angle.
*
* @param angle angle in degrees (controls speed and direction on
* continuous-rotation servos)
* @webref
* @webBrief Moves a servo motor to a given orientation
*/
public void write(float angle) {
if (attached() == false) {
System.err.println("You need to call attach(pin) before write(angle).");
@@ -137,16 +166,22 @@ public class SoftwareServo {
* Returns whether a servo motor is attached to a pin
* @return true if attached, false is not
* @webref
* @webBrief Returns whether a servo motor is attached to a pin
*/
public boolean attached() {
return (pin != -1);
}
/**
* Detatches a servo motor from a GPIO pin
* @webref
*/
/**
* Detatches a servo motor from a GPIO pin<br/>
* <br/>
* Calling this method will stop the servo from moving or trying to hold the
* current orientation.
*
* @webref
* @webBrief Detatches a servo motor from a GPIO pin
*/
public void detach() {
if (0 <= handle) {
// stop thread

16
java/libraries/net/src/processing/net/Client.java
View File

@@ -303,11 +303,11 @@ public class Client implements Runnable {
/**
*
* Returns true if this client is still active and hasn't run
* Returns <b>true</b> if this client is still active and hasn't run
* into any trouble.
*
* @webref client:client
* @webBrief Returns true if this client is still active
* @webBrief Returns <b>true</b> if this client is still active
* @usage application
*/
public boolean active() {
@@ -389,8 +389,8 @@ public class Client implements Runnable {
/**
*
* Returns the next byte in the buffer as a char. Returns -1 or 0xffff if
* nothing is there.
* Returns the next byte in the buffer as a char. Returns <b>-1</b> or
* <b>0xffff</b> if nothing is there.
*
* @webref client:client
* @usage application
@@ -422,7 +422,7 @@ public class Client implements Runnable {
*
* @webref client:client
* @usage application
* @webBrief Reads everything in the buffer
* @webBrief Reads a group of bytes from the buffer.
*/
public byte[] readBytes() {
synchronized (bufferLock) {
@@ -638,11 +638,13 @@ public class Client implements Runnable {
/**
*
* Writes data to a server specified when constructing the client.
* Writes data to a server specified when constructing the client, or writes
* data to the specific client obtained from the Server <b>available()</b>
* method.
*
* @webref client:client
* @usage application
* @webBrief Writes bytes, chars, ints, bytes[], Strings
* @webBrief Writes bytes, chars, ints, bytes[], Strings
* @param data data to write
*/
public void write(int data) { // will also cover char

2
java/libraries/net/src/processing/net/Server.java
View File

@@ -184,7 +184,7 @@ public class Server implements Runnable {
/**
*
* Returns true if this server is still active and hasn't run
* Returns <b>true</b> if this server is still active and hasn't run
* into any trouble.
*
* @webref server:server

1
java/libraries/serial/src/processing/serial/Serial.java
View File

@@ -724,7 +724,6 @@ public class Serial implements SerialPortEventListener {
/**
* Writes bytes, chars, ints, bytes[], Strings to the serial port
*
* @generate Serial_write.xml
* <h3>Advanced</h3>
* Write a String to the output. Note that this doesn't account
* for Unicode (two bytes per char), nor will it send UTF8