ricky/ioiolib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
40c2ec2e9b6ebedb3086878c8e79d85616a2f635
ioiolib/IOIOLib/doc/ioio/lib/api/IcspMaster.html
Ricky Barrette d0434145ab Initial commit
2012-01-24 13:04:09 -05:00

404 lines
17 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.6.0_29) on Mon Nov 28 00:50:34 PST 2011 -->
<TITLE>
IcspMaster
</TITLE>
<META NAME="date" CONTENT="2011-11-28">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="IcspMaster";
}
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<HR>
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/IcspMaster.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-files/index-1.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../ioio/lib/api/DigitalOutput.Spec.Mode.html" title="enum in ioio.lib.api"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../ioio/lib/api/IOIO.html" title="interface in ioio.lib.api"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../index.html?ioio/lib/api/IcspMaster.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="IcspMaster.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
ioio.lib.api</FONT>
<BR>
Interface IcspMaster</H2>
<DL>
<DT><B>All Superinterfaces:</B> <DD><A HREF="../../../ioio/lib/api/Closeable.html" title="interface in ioio.lib.api">Closeable</A></DD>
</DL>
<HR>
<DL>
<DT><PRE>public interface <B>IcspMaster</B><DT>extends <A HREF="../../../ioio/lib/api/Closeable.html" title="interface in ioio.lib.api">Closeable</A></DL>
</PRE>
<P>
An interface for controlling an ICSP channel, enabling Flash programming of
an external PIC MCU, and in particular, another IOIO board.
<p>
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 <A HREF="../../../ioio/lib/api/IOIO.html#openIcspMaster()"><CODE>IOIO.openIcspMaster()</CODE></A>.
<p>
This interface is very low level: it allows direct access to the atomic
operations of the ICSP protocol:
<ul>
<li>Enter / exit programming mode ( <A HREF="../../../ioio/lib/api/IcspMaster.html#enterProgramming()"><CODE>enterProgramming()</CODE></A> /
<A HREF="../../../ioio/lib/api/IcspMaster.html#exitProgramming()"><CODE>exitProgramming()</CODE></A>, respectively).</li>
<li>Executing a single instruction on the slave MCU (
<A HREF="../../../ioio/lib/api/IcspMaster.html#executeInstruction(int)"><CODE>executeInstruction(int)</CODE></A>).</li>
<li>Reading the value of the VISI register of the slave MCU into a read queue
(<A HREF="../../../ioio/lib/api/IcspMaster.html#readVisi()"><CODE>readVisi()</CODE></A>).</li>
</ul>
<p>
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.
<p>
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 <A HREF="../../../ioio/lib/api/Closeable.html#close()"><CODE>Closeable.close()</CODE></A>) will throw a
<A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception"><CODE>ConnectionLostException</CODE></A>. Whenever <A HREF="../../../ioio/lib/api/Closeable.html#close()"><CODE>Closeable.close()</CODE></A> is invoked the
instance may no longer be used. Any resources associated with it are freed
and can be reused.
<p>
Typical usage:
<pre>
<code>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
</code></pre>
<P>
<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../ioio/lib/api/IOIO.html#openIcspMaster()"><CODE>IOIO.openIcspMaster()</CODE></A></DL>
<HR>
<P>
<!-- ========== METHOD SUMMARY =========== -->
<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Method Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../ioio/lib/api/IcspMaster.html#enterProgramming()">enterProgramming</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Initiate a sequence that will put the slave device in programming mode.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../ioio/lib/api/IcspMaster.html#executeInstruction(int)">executeInstruction</A></B>(int&nbsp;instruction)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Execute a single instruction on the slave MCU.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../ioio/lib/api/IcspMaster.html#exitProgramming()">exitProgramming</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Initiate a sequence that will put the slave device out of programming
mode.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../ioio/lib/api/IcspMaster.html#readVisi()">readVisi</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Request a read of the VISI register on the slave MCU.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../ioio/lib/api/IcspMaster.html#waitVisiResult()">waitVisiResult</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Wait and return a result of a call to <A HREF="../../../ioio/lib/api/IcspMaster.html#readVisi()"><CODE>readVisi()</CODE></A>.</TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_ioio.lib.api.Closeable"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TH ALIGN="left"><B>Methods inherited from interface ioio.lib.api.<A HREF="../../../ioio/lib/api/Closeable.html" title="interface in ioio.lib.api">Closeable</A></B></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><A HREF="../../../ioio/lib/api/Closeable.html#close()">close</A></CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>
<!-- ============ METHOD DETAIL ========== -->
<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
<B>Method Detail</B></FONT></TH>
</TR>
</TABLE>
<A NAME="enterProgramming()"><!-- --></A><H3>
enterProgramming</H3>
<PRE>
void <B>enterProgramming</B>()
throws <A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></PRE>
<DL>
<DD>Initiate a sequence that will put the slave device in programming mode.
This sequence is necessary for executing instructions and reading
register values.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></CODE> - Connection to the IOIO has been lost.</DL>
</DD>
</DL>
<HR>
<A NAME="exitProgramming()"><!-- --></A><H3>
exitProgramming</H3>
<PRE>
void <B>exitProgramming</B>()
throws <A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></PRE>
<DL>
<DD>Initiate a sequence that will put the slave device out of programming
mode. It will be held in reset.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></CODE> - Connection to the IOIO has been lost.</DL>
</DD>
</DL>
<HR>
<A NAME="executeInstruction(int)"><!-- --></A><H3>
executeInstruction</H3>
<PRE>
void <B>executeInstruction</B>(int&nbsp;instruction)
throws <A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></PRE>
<DL>
<DD>Execute a single instruction on the slave MCU.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>instruction</CODE> - a 24-bit PIC instruction.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></CODE> - Connection to the IOIO has been lost.</DL>
</DD>
</DL>
<HR>
<A NAME="readVisi()"><!-- --></A><H3>
readVisi</H3>
<PRE>
void <B>readVisi</B>()
throws <A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A>,
java.lang.InterruptedException</PRE>
<DL>
<DD>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
<A HREF="../../../ioio/lib/api/IcspMaster.html#waitVisiResult()"><CODE>waitVisiResult()</CODE></A>.
This method may block if the read queue on the IOIO is full, but this
should be for short periods only.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></CODE> - Connection to the IOIO has been lost.
<DD><CODE>java.lang.InterruptedException</CODE> - Interrupted while blocking.</DL>
</DD>
</DL>
<HR>
<A NAME="waitVisiResult()"><!-- --></A><H3>
waitVisiResult</H3>
<PRE>
int <B>waitVisiResult</B>()
throws <A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A>,
java.lang.InterruptedException</PRE>
<DL>
<DD>Wait and return a result of a call to <A HREF="../../../ioio/lib/api/IcspMaster.html#readVisi()"><CODE>readVisi()</CODE></A>.
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.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Returns:</B><DD>The result - an unsigned 16-bit number.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../ioio/lib/api/exception/ConnectionLostException.html" title="class in ioio.lib.api.exception">ConnectionLostException</A></CODE> - Connection to the IOIO has been lost.
<DD><CODE>java.lang.InterruptedException</CODE> - Interrupted while blocking.</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/IcspMaster.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-files/index-1.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../ioio/lib/api/DigitalOutput.Spec.Mode.html" title="enum in ioio.lib.api"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../ioio/lib/api/IOIO.html" title="interface in ioio.lib.api"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../index.html?ioio/lib/api/IcspMaster.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="IcspMaster.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink