From 3905200c574e1e9b9bdd44a4a843aa9c3beb31d2 Mon Sep 17 00:00:00 2001 From: gohai Date: Thu, 15 Oct 2015 22:49:55 +0200 Subject: [PATCH] I/O: Documentation changes --- java/libraries/io/src/processing/io/GPIO.java | 97 ++++++------------- java/libraries/io/src/processing/io/I2C.java | 44 +-------- java/libraries/io/src/processing/io/LED.java | 3 - java/libraries/io/src/processing/io/PWM.java | 7 -- java/libraries/io/src/processing/io/SPI.java | 20 +--- 5 files changed, 36 insertions(+), 135 deletions(-) diff --git a/java/libraries/io/src/processing/io/GPIO.java b/java/libraries/io/src/processing/io/GPIO.java index f0dcc0ed3..f8b972785 100644 --- a/java/libraries/io/src/processing/io/GPIO.java +++ b/java/libraries/io/src/processing/io/GPIO.java @@ -89,14 +89,9 @@ public class GPIO { /** - * Calls a function when the value of an INPUT pin changes - * - * Don't use enableInterrupt() and waitForInterrupt() in combination with - * this function, as they are orthogonal. The sketch method provided must - * accept a single integer (int) parameter, which is the number of the GPIO - * pin that the interrupt occured on. + * Calls a function when the value of an input pin changes * @param pin GPIO pin - * @param parent this + * @param parent typically use "this" * @param method name of sketch method to call * @param mode when to call: GPIO.CHANGE, GPIO.FALLING or GPIO.RISING * @see noInterrupts @@ -163,7 +158,6 @@ public class GPIO { * Board-specific classes, such as RPI, assign -1 to pins that carry power, * ground and the like. * @param pin GPIO pin - * @webref */ protected static void checkValidPin(int pin) { if (pin < 0) { @@ -174,9 +168,6 @@ public class GPIO { /** * Returns the value of an input pin - * - * You need to set the pin to INPUT by calling pinMode before calling - * this function. * @param pin GPIO pin * @return GPIO.HIGH (1) or GPIO.LOW (0) * @see pinMode @@ -207,14 +198,9 @@ public class GPIO { /** - * Sets an output pin to HIGH or LOW - * - * You need set the pin to OUTPUT by calling pinMode before calling this - * function. It is not possible to enable or disable internal pull-up - * resistors for inputs using this function, which is something that's - * supported on Arduino. + * Sets an output pin to be either high or low * @param pin GPIO pin - * @param value GPIO.HIGH or GPIO.LOW + * @param value GPIO.HIGH (1) or GPIO.LOW (0) * @see pinMode * @see digitalRead * @webref @@ -247,17 +233,7 @@ public class GPIO { /** - * Sets an output pin to HIGH or LOW - * - * You need set the pin to OUTPUT by calling pinMode before calling this - * function. It is not possible to enable or disable internal pull-up - * resistors for inputs using this function, which is something that's - * supported on Arduino. - * @param pin GPIO pin * @param value true or false - * @see pinMode - * @see digitalRead - * @webref */ public static void digitalWrite(int pin, boolean value) { if (value) { @@ -269,33 +245,24 @@ public class GPIO { /** - * Disables an interrupt for an INPUT pin - * - * Use this function only in combination with enableInterrupt() and - * waitForInterrupt(). This should not be called when attachInterrupt() - * is being used. + * Disables an interrupt for an input pin * @param pin GPIO pin * @see enableInterrupt * @see waitForInterrupt - * @webref */ - public static void disableInterrupt(int pin) { + protected static void disableInterrupt(int pin) { enableInterrupt(pin, NONE); } /** - * Enables an interrupt for an INPUT pin - * - * Use this function only when calling waitForInterrupt(). This should not - * be called when attachInterrupt() is being used. + * Enables an interrupt for an input pin * @param pin GPIO pin * @param mode what to wait for: GPIO.CHANGE, GPIO.FALLING or GPIO.RISING * @see waitForInterrupt * @see disableInterrupt - * @webref */ - public static void enableInterrupt(int pin, int mode) { + protected static void enableInterrupt(int pin, int mode) { checkValidPin(pin); String out; @@ -324,11 +291,6 @@ public class GPIO { /** * Allows interrupts to happen - * - * You can use noInterrupts() and interrupts() in tandem to make sure no interrupts - * are occuring while your sketch is doing a particular task. This is only relevant - * when using attachInterrupt(), not for waitForInterrupt(). By default, interrupts - * are enabled. * @see attachInterrupt * @see noInterrupts * @see releaseInterrupt @@ -341,11 +303,6 @@ public class GPIO { /** * Prevents interrupts from happpening - * - * You can use noInterrupts() and interrupts() in tandem to make sure no interrupts - * are occuring while your sketch is doing a particular task. This is only relevant - * when using attachInterrupt(), not for waitForInterrupt(). By default, interrupts - * are enabled. * @see attachInterrupt * @see interrupts * @see releaseInterrupt @@ -357,11 +314,7 @@ public class GPIO { /** - * Sets a pin to INPUT or OUTPUT - * - * While pins are implicitly set to input by default on Arduino, it is - * necessary to call this function for any pin you want to access later, - * including input pins. + * Configures a pin to act either as input or output * @param pin GPIO pin * @param mode GPIO.INPUT or GPIO.OUTPUT * @see digitalRead @@ -421,10 +374,7 @@ public class GPIO { /** - * Stops listening for interrupts on an INPUT pin - * - * Use this function only in combination with attachInterrupt(). This should - * not be called when enableInterrupt() and waitForInterrupt() are being used. + * Stops listening for interrupts on an input pin * @param pin GPIO pin * @see attachInterrupt * @see noInterrupts @@ -452,9 +402,6 @@ public class GPIO { /** * Gives ownership of a pin back to the operating system - * - * Without calling this function the pin will remain in the current - * state even after the sketch has been closed. * @param pin GPIO pin * @see pinMode * @webref @@ -477,7 +424,21 @@ public class GPIO { /** - * Waits for the value of an INPUT pin to change + * Waits for the value of an input pin to change + * @param pin GPIO pin + * @param mode what to wait for: GPIO.CHANGE, GPIO.FALLING or GPIO.RISING + * @param timeout don't wait more than timeout milliseconds (-1 waits indefinitely) + * @return true if the interrupt occured, false if the timeout occured + * @webref + */ + public static boolean waitForInterrupt(int pin, int mode, int timeout) { + enableInterrupt(pin, mode); + return waitForInterrupt(pin, timeout); + } + + + /** + * Waits for the value of an input pin to change * * Make sure to setup the interrupt with enableInterrupt() before calling * this function. A timeout value of -1 waits indefinitely. @@ -486,9 +447,8 @@ public class GPIO { * @return true if the interrupt occured, false if the timeout occured * @see enableInterrupt * @see disableInterrupt - * @webref */ - public static boolean waitForInterrupt(int pin, int timeout) { + protected static boolean waitForInterrupt(int pin, int timeout) { checkValidPin(pin); String fn = String.format("/sys/class/gpio/gpio%d/value", pin); @@ -509,7 +469,7 @@ public class GPIO { /** - * Waits for the value of an INPUT pin to change + * Waits for the value of an input pin to change * * Make sure to setup the interrupt with enableInterrupt() before calling * this function. This function will wait indefinitely for an interrupt @@ -517,9 +477,8 @@ public class GPIO { * @parm pin GPIO pin * @see enableInterrupt * @see disableInterrupt - * @webref */ - public static void waitForInterrupt(int pin) { + protected static void waitForInterrupt(int pin) { waitForInterrupt(pin, -1); } } diff --git a/java/libraries/io/src/processing/io/I2C.java b/java/libraries/io/src/processing/io/I2C.java index 76ab19635..96b62767b 100644 --- a/java/libraries/io/src/processing/io/I2C.java +++ b/java/libraries/io/src/processing/io/I2C.java @@ -42,9 +42,8 @@ public class I2C { /** - * Opens an I2C device as master - * - * @param dev device name + * Opens an I2C interface as master + * @param dev interface name * @see list * @webref */ @@ -60,19 +59,6 @@ public class I2C { /** * Begins a transmission to an attached 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. 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. - * @param slave 7 bit address of slave device * @see write * @see read * @see endTransmission @@ -111,8 +97,6 @@ public class I2C { /** * Ends the current transmissions - * - * This executes any queued writes. * @see beginTransmission * @see write * @webref @@ -137,7 +121,7 @@ public class I2C { /** - * Lists all available I2C devices + * Lists all available I2C interfaces * @return String array * @webref */ @@ -161,10 +145,6 @@ public class I2C { /** * Reads bytes from the attached device - * - * You must call beginTransmission() before calling this function. This function - * also ends the current transmisison and sends any data that was queued using - * write() before. * @param len number of bytes to read * @return bytes read from device * @see beginTransmission @@ -195,10 +175,6 @@ public class I2C { /** * Adds bytes to be written to the device - * - * 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 @@ -222,16 +198,11 @@ public class I2C { /** - * Adds bytes to be written to the device - * - * You must call beginTransmission() before calling this function. - * The actual writing takes part when read() or endTransmission() is being - * called. + * Adds bytes to be written to the attached device * @param out string to be written * @see beginTransmission * @see read * @see endTransmission - * @webref */ public void write(String out) { write(out.getBytes()); @@ -239,16 +210,11 @@ public class I2C { /** - * Adds a byte to be written to the device - * - * You must call beginTransmission() before calling this function. - * The actual writing takes part when read() or endTransmission() is being - * called. + * Adds a byte to be written to the attached device * @param out single byte to be written (0-255) * @see beginTransmission * @see read * @see endTransmission - * @webref */ public void write(int out) { if (out < 0 || 255 < out) { diff --git a/java/libraries/io/src/processing/io/LED.java b/java/libraries/io/src/processing/io/LED.java index 5f1245fc3..8114e58ee 100644 --- a/java/libraries/io/src/processing/io/LED.java +++ b/java/libraries/io/src/processing/io/LED.java @@ -119,9 +119,6 @@ public class LED { /** * Restores the previous state - * - * Without calling this function the LED will remain in the current - * state even after the sketch has been closed. * @webref */ public void close() { diff --git a/java/libraries/io/src/processing/io/PWM.java b/java/libraries/io/src/processing/io/PWM.java index 7eecccff8..37f1cf25f 100644 --- a/java/libraries/io/src/processing/io/PWM.java +++ b/java/libraries/io/src/processing/io/PWM.java @@ -99,9 +99,6 @@ public class PWM { /** * Gives ownership of a channel back to the operating system - * - * Without calling this function the channel will remain in the current - * state even after the sketch has been closed. * @webref */ public void close() { @@ -187,10 +184,6 @@ public class PWM { /** * Enables the PWM output with a preset period of 1 kHz - * - * This period approximately matches the dedicated PWM pins on - * the Arduino Uno, which have a frequency of 980 Hz. - * It is recommended to use set(period, duty) instead. * @param duty duty cycle, 0.0 (always off) to 1.0 (always on) * @webref */ diff --git a/java/libraries/io/src/processing/io/SPI.java b/java/libraries/io/src/processing/io/SPI.java index 279455e75..83b9b7a4c 100644 --- a/java/libraries/io/src/processing/io/SPI.java +++ b/java/libraries/io/src/processing/io/SPI.java @@ -70,7 +70,7 @@ public class SPI { /** - * Opens an SPI interface + * Opens an SPI interface as master * @param dev device name * @see list * @webref @@ -130,8 +130,8 @@ 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 SPI.MODE0 to SPI.MODE3 (see https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus#Clock_polarity_and_phase) + * @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 SPI.MODE0 to SPI.MODE3
* @webref */ public void settings(int maxSpeed, int dataOrder, int mode) { @@ -143,10 +143,6 @@ public class SPI { /** * Transfers data over the SPI bus - * - * 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 @@ -176,13 +172,8 @@ public class SPI { /** * Transfers data over the SPI bus - * - * 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 string to send * @return bytes read in (array is the same length as out) - * @webref */ public byte[] transfer(String out) { return transfer(out.getBytes()); @@ -191,13 +182,8 @@ public class SPI { /** * Transfers data over the SPI bus - * - * 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 single byte to send * @return bytes read in (array is the same length as out) - * @webref */ public byte[] transfer(int out) { if (out < 0 || 255 < out) {