ioio.lib.api

Interface IcspMaster

All Superinterfaces:

Closeable

public interface IcspMaster
extends Closeable

An interface for controlling an ICSP channel, enabling Flash programming of an external PIC MCU, and in particular, another IOIO board.

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. IcspMaster instances are obtained by calling IOIO.openIcspMaster().

This interface is very low level: it allows direct access to the atomic operations of the ICSP protocol:

• Enter / exit programming mode ( enterProgramming() / exitProgramming(), respectively).
• Executing a single instruction on the slave MCU ( executeInstruction(int)).
• Reading the value of the VISI register of the slave MCU into a read queue (readVisi()).

The ICSP module uses fixed pins for its lines. See the user guide for details for your specific board. ICSP is a special feature, introduced for the purpose of programming a IOIO board with another IOIO board. It does not necessarily play nicely when used concurrently with other features, in the sense that it may introduce latencies in other modules. It is thus recommended not to use ICSP in conjunction with latency-sensitive features.

The instance is alive since its creation. If the connection with the IOIO drops at any point, the instance transitions to a disconnected state, in which every attempt to use it (except Closeable.close()) will throw a ConnectionLostException. Whenever Closeable.close() is invoked the instance may no longer be used. Any resources associated with it are freed and can be reused.

Typical usage:

 IcspMaster icsp = ioio.openIcspMaster();
 icsp.enterProgramming();
 icsp.executeInstruction(0x212340);  // mov #0x1234, w0
 icsp.executeInstruction(0x883C20);  // mov w0, 0x784 (VISI)
 icsp.executeInstruction(0x000000);  // nop
 icsp.readVisi();
 int visi = icsp.waitVisiResult();   // should read 0x1234
 icsp.exitProgramming();
 icsp.close();                       // free ICSP module and pins
 

See Also:

IOIO.openIcspMaster()

Method Summary

Methods

Modifier and Type	Method and Description
void	enterProgramming() Initiate a sequence that will put the slave device in programming mode.
void	executeInstruction(int instruction) Execute a single instruction on the slave MCU.
void	exitProgramming() Initiate a sequence that will put the slave device out of programming mode.
void	readVisi() Request a read of the VISI register on the slave MCU.
int	waitVisiResult() Wait and return a result of a call to readVisi().

Methods inherited from interface ioio.lib.api.Closeable

close

Method Detail

enterProgramming

void enterProgramming()
                      throws ConnectionLostException

Initiate a sequence that will put the slave device in programming mode. This sequence is necessary for executing instructions and reading register values.

Throws:

ConnectionLostException - Connection to the IOIO has been lost.

exitProgramming

void exitProgramming()
                     throws ConnectionLostException

Initiate a sequence that will put the slave device out of programming mode. It will be held in reset.

Throws:

ConnectionLostException - Connection to the IOIO has been lost.

executeInstruction

void executeInstruction(int instruction)
                        throws ConnectionLostException

Execute a single instruction on the slave MCU.

Parameters:

instruction - a 24-bit PIC instruction.

Throws:

ConnectionLostException - Connection to the IOIO has been lost.

readVisi

void readVisi()
              throws ConnectionLostException,
                     java.lang.InterruptedException

Request a read of the VISI register on the slave MCU. This is an asynchronous call, in which the 16-bit result is obtained by waitVisiResult(). This method may block if the read queue on the IOIO is full, but this should be for short periods only.

Throws:

ConnectionLostException - Connection to the IOIO has been lost.

java.lang.InterruptedException - Interrupted while blocking.

waitVisiResult

int waitVisiResult()
                   throws ConnectionLostException,
                          java.lang.InterruptedException

Wait and return a result of a call to readVisi(). Results will be returned in the same order as requested. The call will block until there is data, until interrupted, or until connection to the IOIO has been lost.

Returns:

The result - an unsigned 16-bit number.

Throws:

ConnectionLostException - Connection to the IOIO has been lost.

java.lang.InterruptedException - Interrupted while blocking.