|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface IOIO
This interface provides control over all the IOIO board functions.
An instance of this interface is typically obtained by using the
IOIOFactory
class. Initially, a connection should be established, by
calling waitForConnect()
. This method will block until the board is
connected an a connection has been established.
During the connection process, this library verifies that the IOIO firmware
is compatible with the required version. If not, waitForConnect()
will throw a IncompatibilityException
, putting the IOIO
instance in a "zombie" state: nothing could be done with it except calling
disconnect()
, or waiting for the physical connection to drop via
waitForDisconnect()
.
As soon as a connection is established, the IOIO can be used, typically, by calling the openXXX() functions to obtain additional interfaces for controlling specific function of the board.
Whenever a connection is lost as a result of physically disconnecting the
board or as a result of calling disconnect()
, this instance and all
the interfaces obtained from it become invalid, and will throw a
ConnectionLostException
on every operation. Once the connection is
lost, those instances cannot be recycled, but rather it is required to create
new ones and wait for a connection again.
Initially all pins are tri-stated (floating), and all functions are disabled. Whenever a connection is lost or dropped, the board will immediately return to the this initial state.
Typical usage:
IOIO ioio = IOIOFactory.create(); try { ioio.waitForConnect(); DigitalOutput out = ioio.openDigitalOutput(10); out.write(true); ... } catch (ConnectionLostException e) { } catch (Exception e) { ioio.disconnect(); } finally { ioio.waitForDisconnect(); }
IOIOFactory.create()
Nested Class Summary | |
---|---|
static class |
IOIO.VersionType
A versioned component in the system. |
Field Summary | |
---|---|
static int |
INVALID_PIN
An invalid pin number. |
static int |
LED_PIN
The pin number used to designate the on-board 'stat' LED. |
Method Summary | |
---|---|
void |
disconnect()
Closes the connection to the board, or aborts a connection process started with waitForConnect(). |
java.lang.String |
getImplVersion(IOIO.VersionType v)
Query the implementation version of the system's components. |
void |
hardReset()
Equivalent to disconnecting and reconnecting the board power supply. |
AnalogInput |
openAnalogInput(int pin)
Open a pin for analog input. |
DigitalInput |
openDigitalInput(DigitalInput.Spec spec)
Open a pin for digital input. |
DigitalInput |
openDigitalInput(int pin)
Shorthand for openDigitalInput(new DigitalInput.Spec(pin)). |
DigitalInput |
openDigitalInput(int pin,
DigitalInput.Spec.Mode mode)
Shorthand for openDigitalInput(new DigitalInput.Spec(pin, mode)). |
DigitalOutput |
openDigitalOutput(DigitalOutput.Spec spec,
boolean startValue)
Open a pin for digital output. |
DigitalOutput |
openDigitalOutput(int pin)
Shorthand for openDigitalOutput(new DigitalOutput.Spec(pin), false). |
DigitalOutput |
openDigitalOutput(int pin,
boolean startValue)
Shorthand for openDigitalOutput(new DigitalOutput.Spec(pin), startValue). |
DigitalOutput |
openDigitalOutput(int pin,
DigitalOutput.Spec.Mode mode,
boolean startValue)
Shorthand for openDigitalOutput(new DigitalOutput.Spec(pin, mode), startValue). |
IcspMaster |
openIcspMaster()
Open an ICSP channel, enabling Flash programming of an external PIC MCU, and in particular, another IOIO board. |
PulseInput |
openPulseInput(DigitalInput.Spec spec,
PulseInput.ClockRate rate,
PulseInput.PulseMode mode,
boolean doublePrecision)
Open a pin for pulse input. |
PulseInput |
openPulseInput(int pin,
PulseInput.PulseMode mode)
Shorthand for openPulseInput(new DigitalInput.Spec(pin), rate, mode, true), i.e. |
PwmOutput |
openPwmOutput(DigitalOutput.Spec spec,
int freqHz)
Open a pin for PWM (Pulse-Width Modulation) output. |
PwmOutput |
openPwmOutput(int pin,
int freqHz)
Shorthand for openPwmOutput(new DigitalOutput.Spec(pin), freqHz). |
SpiMaster |
openSpiMaster(DigitalInput.Spec miso,
DigitalOutput.Spec mosi,
DigitalOutput.Spec clk,
DigitalOutput.Spec[] slaveSelect,
SpiMaster.Config config)
Open a SPI master module, enabling communication with multiple SPI-enabled slave modules. |
SpiMaster |
openSpiMaster(int miso,
int mosi,
int clk,
int[] slaveSelect,
SpiMaster.Rate rate)
Shorthand for {@link #openSpiMaster(ioio.lib.api.DigitalInput.Spec, ioio.lib.api.DigitalOutput.Spec, ioio.lib.api.DigitalOutput.Spec, ioio.lib.api.DigitalOutput.Spec[], ioio.lib.api.SpiMaster.Config), where the pins are all open with the default modes and default configuration values are used. |
SpiMaster |
openSpiMaster(int miso,
int mosi,
int clk,
int slaveSelect,
SpiMaster.Rate rate)
Shorthand for {@link #openSpiMaster(ioio.lib.api.DigitalInput.Spec, ioio.lib.api.DigitalOutput.Spec, ioio.lib.api.DigitalOutput.Spec, ioio.lib.api.DigitalOutput.Spec[], ioio.lib.api.SpiMaster.Config), where the MISO pins is opened with pull up, and the other pins are open with the default modes and default configuration values are used. |
TwiMaster |
openTwiMaster(int twiNum,
TwiMaster.Rate rate,
boolean smbus)
Open a TWI (Two-Wire Interface, such as I2C/SMBus) master module, enabling communication with multiple TWI-enabled slave modules. |
Uart |
openUart(DigitalInput.Spec rx,
DigitalOutput.Spec tx,
int baud,
Uart.Parity parity,
Uart.StopBits stopbits)
Open a UART module, enabling a bulk transfer of byte buffers. |
Uart |
openUart(int rx,
int tx,
int baud,
Uart.Parity parity,
Uart.StopBits stopbits)
Shorthand for #openUart(ioio.lib.api.DigitalInput.Spec, ioio.lib.api.DigitalOutput.Spec, int, Parity, StopBits)
, where the input pins use their default specs. |
void |
softReset()
Resets the entire state (returning to initial state), without dropping the connection. |
void |
waitForConnect()
Establishes connection with the IOIO board. |
void |
waitForDisconnect()
Blocks until IOIO has been disconnected and all connection-related resources have been freed, so that a new connection can be attempted. |
Field Detail |
---|
static final int INVALID_PIN
static final int LED_PIN
Method Detail |
---|
void waitForConnect() throws ConnectionLostException, IncompatibilityException
This method is blocking until connection is established. This method can
be aborted by calling disconnect()
. In this case, it will throw
a ConnectionLostException
.
ConnectionLostException
- An error occurred during connection or disconnect() has been
called during connection. The instance state is disconnected.
IncompatibilityException
- An incompatible board firmware of hardware has been detected.
The instance state is disconnected.disconnect()
,
waitForDisconnect()
void disconnect()
Once this method is called, this IOIO instance and all the instances obtain from it become invalid and will throw an exception on every operation.
This method is asynchronous, i.e. it returns immediately, but it is not
guaranteed that all connection-related resources has already been freed
and can be reused upon return. In cases when this is important, client
can call waitForDisconnect()
, which will block until all
resources have been freed.
void waitForDisconnect() throws java.lang.InterruptedException
java.lang.InterruptedException
- When interrupt() has been called on this thread. This might
mean that an immediate attempt to create and connect a new
IOIO object might fail for resource contention.disconnect()
,
waitForConnect()
void softReset() throws ConnectionLostException
It is equivalent to calling Closeable.close()
on every interface
obtained from this instance. A connection must have been established
prior to calling this method, by invoking waitForConnect()
.
ConnectionLostException
- Connection was lost before or during the execution of this
method.hardReset()
void hardReset() throws ConnectionLostException
The connection will be dropped and not reestablished. Full boot sequence
will take place, so firmware upgrades can be performed. A connection must
have been established prior to calling this method, by invoking
waitForConnect()
.
ConnectionLostException
- Connection was lost before or during the execution of this
method.softReset()
java.lang.String getImplVersion(IOIO.VersionType v) throws ConnectionLostException
v
- The component whose version we query.
ConnectionLostException
- Connection was lost before or during the execution of this
method.DigitalInput openDigitalInput(DigitalInput.Spec spec) throws ConnectionLostException
A digital input pin can be used to read logic-level signals. The pin will
operate in this mode until close() is invoked on the returned interface.
It is illegal to open a pin that has already been opened and has not been
closed. A connection must have been established prior to calling this
method, by invoking waitForConnect()
.
spec
- Pin specification, consisting of the pin number, as labeled on
the board, and the mode, which determines whether the pin will
be floating, pull-up or pull-down. See
DigitalInput.Spec.Mode
for more information.
ConnectionLostException
- Connection was lost before or during the execution of this
method.DigitalInput
DigitalInput openDigitalInput(int pin) throws ConnectionLostException
ConnectionLostException
openDigitalInput(ioio.lib.api.DigitalInput.Spec)
DigitalInput openDigitalInput(int pin, DigitalInput.Spec.Mode mode) throws ConnectionLostException
ConnectionLostException
openDigitalInput(ioio.lib.api.DigitalInput.Spec)
DigitalOutput openDigitalOutput(DigitalOutput.Spec spec, boolean startValue) throws ConnectionLostException
A digital output pin can be used to generate logic-level signals. The pin
will operate in this mode until close() is invoked on the returned
interface. It is illegal to open a pin that has already been opened and
has not been closed. A connection must have been established prior to
calling this method, by invoking waitForConnect()
.
spec
- Pin specification, consisting of the pin number, as labeled on
the board, and the mode, which determines whether the pin will
be normal or open-drain. See DigitalOutput.Spec.Mode
for more information.startValue
- The initial logic level this pin will generate as soon at it
is open.
ConnectionLostException
- Connection was lost before or during the execution of this
method.DigitalOutput
DigitalOutput openDigitalOutput(int pin, DigitalOutput.Spec.Mode mode, boolean startValue) throws ConnectionLostException
ConnectionLostException
openDigitalOutput(ioio.lib.api.DigitalOutput.Spec, boolean)
DigitalOutput openDigitalOutput(int pin, boolean startValue) throws ConnectionLostException
ConnectionLostException
openDigitalOutput(ioio.lib.api.DigitalOutput.Spec, boolean)
DigitalOutput openDigitalOutput(int pin) throws ConnectionLostException
ConnectionLostException
openDigitalOutput(ioio.lib.api.DigitalOutput.Spec, boolean)
AnalogInput openAnalogInput(int pin) throws ConnectionLostException
An analog input pin can be used to measure voltage. Note that not every pin can be used as an analog input. See board documentation for the legal pins and permitted voltage range.
The pin will operate in this mode until close() is invoked on the
returned interface. It is illegal to open a pin that has already been
opened and has not been closed. A connection must have been established
prior to calling this method, by invoking waitForConnect()
.
pin
- Pin number, as labeled on the board.
ConnectionLostException
- Connection was lost before or during the execution of this
method.AnalogInput
PwmOutput openPwmOutput(DigitalOutput.Spec spec, int freqHz) throws ConnectionLostException
A PWM pin produces a logic-level PWM signal. These signals are typically used for simulating analog outputs for controlling the intensity of LEDs, the rotation speed of motors, etc. They are also frequently used for controlling hobby servo motors.
Note that not every pin can be used as PWM output. In addition, the total number of concurrent PWM modules in use is limited. See board documentation for the legal pins and limit on concurrent usage.
The pin will operate in this mode until close() is invoked on the
returned interface. It is illegal to open a pin that has already been
opened and has not been closed. A connection must have been established
prior to calling this method, by invoking waitForConnect()
.
spec
- Pin specification, consisting of the pin number, as labeled on
the board, and the mode, which determines whether the pin will
be normal or open-drain. See DigitalOutput.Spec.Mode
for more information.freqHz
- PWM frequency, in Hertz.
ConnectionLostException
- Connection was lost before or during the execution of this
method.
OutOfResourceException
- This is a runtime exception, so it is not necessary to catch
it if the client guarantees that the total number of
concurrent PWM resources is not exceeded.PwmOutput
PwmOutput openPwmOutput(int pin, int freqHz) throws ConnectionLostException
ConnectionLostException
openPwmOutput(ioio.lib.api.DigitalOutput.Spec, int)
PulseInput openPulseInput(DigitalInput.Spec spec, PulseInput.ClockRate rate, PulseInput.PulseMode mode, boolean doublePrecision) throws ConnectionLostException
The pulse input module is quite flexible. It enables several kinds of timing measurements on a digital signal: pulse width measurement (positive or negative pulse), and frequency of a periodic signal.
Note that not every pin can be used as pulse input. In addition, the total number of concurrent pulse input modules in use is limited. See board documentation for the legal pins and limit on concurrent usage.
The pin will operate in this mode until close() is invoked on the
returned interface. It is illegal to open a pin that has already been
opened and has not been closed. A connection must have been established
prior to calling this method, by invoking waitForConnect()
.
spec
- Pin specification, consisting of the pin number, as labeled on
the board, and the mode, which determines whether the pin will
be floating, pull-up or pull-down. See
DigitalInput.Spec.Mode
for more information.rate
- The clock rate to use for timing the signal. A faster clock
rate will result in better precision but will only be able to
measure narrow pulses / high frequencies.mode
- The mode in which to operate. Determines whether the module
will measure pulse durations or frequency.doublePrecision
- Whether to open a double-precision pulse input module. Double-
precision modules enable reading of much longer pulses and
lower frequencies with high accuracy than single precision
modules. However, their number is limited, so when possible,
and if the resources are all needed, use single-precision. For
more details on the exact spec of single- vs. double-
precision, see PulseInput
.
PulseInput
, which can be used to
obtain the data.
ConnectionLostException
- Connection was lost before or during the execution of this
method.
OutOfResourceException
- This is a runtime exception, so it is not necessary to catch
it if the client guarantees that the total number of
concurrent PWM resources is not exceeded.PulseInput
PulseInput openPulseInput(int pin, PulseInput.PulseMode mode) throws ConnectionLostException
ConnectionLostException
#openPulseInput(ioio.lib.api.DigitalInput.Spec,
ioio.lib.api.PulseInput.ClockRate, PulseMode, boolean)
Uart openUart(DigitalInput.Spec rx, DigitalOutput.Spec tx, int baud, Uart.Parity parity, Uart.StopBits stopbits) throws ConnectionLostException
UART is a very common hardware communication protocol, enabling full- duplex, asynchronous point-to-point data transfer. It typically serves for opening consoles or as a basis for higher-level protocols, such as MIDI RS-232, and RS-485.
Note that not every pin can be used for UART RX or TX. In addition, the total number of concurrent UART modules in use is limited. See board documentation for the legal pins and limit on concurrent usage.
The UART module will operate, and the pins will work in their respective
modes until close() is invoked on the returned interface. It is illegal
to use pins that have already been opened and has not been closed. A
connection must have been established prior to calling this method, by
invoking waitForConnect()
.
rx
- Pin specification for the RX pin, consisting of the pin
number, as labeled on the board, and the mode, which
determines whether the pin will be floating, pull-up or
pull-down. See DigitalInput.Spec.Mode
for more
information. null can be passed to designate that we do not
want RX input to this module.tx
- Pin specification for the TX pin, consisting of the pin
number, as labeled on the board, and the mode, which
determines whether the pin will be normal or open-drain. See
DigitalOutput.Spec.Mode
for more information. null can
be passed to designate that we do not want TX output to this
module.baud
- The clock frequency of the UART module in Hz.parity
- The parity mode, as in Uart.Parity
.stopbits
- Number of stop bits, as in Uart.StopBits
.
ConnectionLostException
- Connection was lost before or during the execution of this
method.
OutOfResourceException
- This is a runtime exception, so it is not necessary to catch
it if the client guarantees that the total number of
concurrent UART resources is not exceeded.Uart
Uart openUart(int rx, int tx, int baud, Uart.Parity parity, Uart.StopBits stopbits) throws ConnectionLostException
#openUart(ioio.lib.api.DigitalInput.Spec, ioio.lib.api.DigitalOutput.Spec, int, Parity, StopBits)
, where the input pins use their default specs. INVALID_PIN
can
be used on either pin if a TX- or RX-only UART is needed.
ConnectionLostException
#openUart(ioio.lib.api.DigitalInput.Spec,
ioio.lib.api.DigitalOutput.Spec, int, Parity, StopBits)
SpiMaster openSpiMaster(DigitalInput.Spec miso, DigitalOutput.Spec mosi, DigitalOutput.Spec clk, DigitalOutput.Spec[] slaveSelect, SpiMaster.Config config) throws ConnectionLostException
SPI is a common hardware communication protocol, enabling full-duplex, synchronous point-to-multi-point data transfer. It requires MOSI, MISO and CLK lines shared by all nodes, as well as a SS line per slave, connected between this slave and a respective pin on the master. The MISO line should operate in pull-up mode, using either the internal pull-up or an external resistor.
Note that not every pin can be used for SPI MISO, MOSI or CLK. In addition, the total number of concurrent SPI modules in use is limited. See board documentation for the legal pins and limit on concurrent usage.
The SPI module will operate, and the pins will work in their respective
modes until close() is invoked on the returned interface. It is illegal
to use pins that have already been opened and has not been closed. A
connection must have been established prior to calling this method, by
invoking waitForConnect()
.
miso
- Pin specification for the MISO (Master In Slave Out) pin,
consisting of the pin number, as labeled on the board, and the
mode, which determines whether the pin will be floating,
pull-up or pull-down. See DigitalInput.Spec.Mode
for
more information.mosi
- Pin specification for the MOSI (Master Out Slave In) pin,
consisting of the pin number, as labeled on the board, and the
mode, which determines whether the pin will be normal or
open-drain. See DigitalOutput.Spec.Mode
for more
information.clk
- Pin specification for the CLK pin, consisting of the pin
number, as labeled on the board, and the mode, which
determines whether the pin will be normal or open-drain. See
DigitalOutput.Spec.Mode
for more information.slaveSelect
- An array of pin specifications for each of the slaves' SS
(Slave Select) pin. The index of this array designates the
slave index, used later to refer to this slave. The spec is
consisting of the pin number, as labeled on the board, and the
mode, which determines whether the pin will be normal or
open-drain. See DigitalOutput.Spec.Mode
for more
information.config
- The configuration of the SPI module. See
SpiMaster.Config
for details.
ConnectionLostException
- Connection was lost before or during the execution of this
method.
OutOfResourceException
- This is a runtime exception, so it is not necessary to catch
it if the client guarantees that the total number of
concurrent SPI resources is not exceeded.SpiMaster
SpiMaster openSpiMaster(int miso, int mosi, int clk, int[] slaveSelect, SpiMaster.Rate rate) throws ConnectionLostException
ConnectionLostException
openSpiMaster(ioio.lib.api.DigitalInput.Spec,
ioio.lib.api.DigitalOutput.Spec, ioio.lib.api.DigitalOutput.Spec,
ioio.lib.api.DigitalOutput.Spec[], ioio.lib.api.SpiMaster.Config)
SpiMaster openSpiMaster(int miso, int mosi, int clk, int slaveSelect, SpiMaster.Rate rate) throws ConnectionLostException
ConnectionLostException
openSpiMaster(ioio.lib.api.DigitalInput.Spec,
ioio.lib.api.DigitalOutput.Spec, ioio.lib.api.DigitalOutput.Spec,
ioio.lib.api.DigitalOutput.Spec[], ioio.lib.api.SpiMaster.Config)
TwiMaster openTwiMaster(int twiNum, TwiMaster.Rate rate, boolean smbus) throws ConnectionLostException
TWI is a common hardware communication protocol, enabling half-duplex, synchronous point-to-multi-point data transfer. It requires a physical connection of two lines (SDA, SCL) shared by all the bus nodes, where the SDA is open-drain and externally pulled-up.
Note that there is a fixed number of TWI modules, and the pins they use are static. Client has to make sure these pins are not already opened before calling this method. See board documentation for the number of modules and the respective pins they use.
The TWI module will operate, and the pins will work in their respective
modes until close() is invoked on the returned interface. It is illegal
to use pins that have already been opened and has not been closed. A
connection must have been established prior to calling this method, by
invoking waitForConnect()
.
twiNum
- The TWI module index to use. Will also determine the pins
used.rate
- The clock rate. Can be 100KHz / 400KHz / 1MHz.smbus
- When true, will use SMBus voltage levels. When false, I2C
voltage levels.
ConnectionLostException
- Connection was lost before or during the execution of this
method.TwiMaster
IcspMaster openIcspMaster() throws ConnectionLostException
ICSP (In-Circuit Serial Programming) is a protocol intended for programming of PIC MCUs. It is a serial protocol over three wires: PGC (clock), PGD (data) and MCLR (reset), where PGC and MCLR are controlled by the master and PGD is shared by the master and slave, depending on the transaction state.
Note that there is only one ICSP modules, and the pins it uses are static. Client has to make sure that the ICSP module is not already in use, as well as those dedicated pins. See board documentation for the actual pins used for ICSP.
ConnectionLostException
- Connection was lost before or during the execution of this
method.IcspMaster
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |