Program PIC_CTRL
10 November 2006
pic_ctrl [options]
Control the target circuit and microcontroller via a PIC programmer
conforming to the Embed Inc PIC programmer protocol. The protocol is
described in the PICPRG_PROT documentation file. Conforming programmers
include the Embed Inc EasyProg, ProProg, and USBProg.
The programmer must be on, connected to the target, and connected to this
machine before this program is run.
The default operation is to report the programmer type, firmware version,
and the programmer name and state of the target chip control signals to
the extent this is supported by the programmer. No modifications are made
to the output signals unless specifically directed to do so by command
line options.
Command line options are processed in the order they are received except
as noted in the descriptions below. Waits are automatically inserted as
needed to ensure one operation completes before attempting the next. To
the extent possible, each operation is verified before proceeding to the
next. The program is aborted with error status if it can be determined
that an operation failed. In that case subsequent operations are not
attempted. When no errors are encountered, the state of the control lines
is reported as found after the last operation, to the extent this is
supported by the programmer.
The entire command line is read before any attempt is made to communicate
with the programmer. Command line syntax errors cause the program to
abort with error status without communicating with the programmer.
The command line options are:
-SIO n
Selects the system serial line number to use in communicating with
the programmer. Only that programmer is accessed.
The default is to use the first available programmer known to be
connected to the system. If no known connected programmer exists,
then the programmer connected to serial line 1 is used.
-N name
Selects the programmer by name.
If no other command line option specifies a connection means to the
programmer (like -SIO), then the first programmer of this name from
those known to be connected to the system is used. A programmer is
known to be connected to the system if it is connected and uses a
connection type that the system can enumerate, such as USB.
If a connection type is specified, the first programmer found with
that name and connection type is used. Note that some connection
types inherently specify a unique programmer, such as serial line,
since only a single device can be attached to any one serial line.
In that case it is an error if the programmer does not have the
indicated name or does not have a name.
The NAME parameter is case-sensitive. Programmer names can
generally be set by the user (see the -SETNAME option). It is
strongly recommended that all programmers connected to a system
have a unique name. Otherwise the choice of programmer used when a
non-unique name is given is arbitrary, and there is no way to
select between multiple programmers of the same name. All Embed
Inc programmers that have names are initially given globally unique
names by Embed Inc.
-VDD volts
Set the Vdd (target chip power) line to the indicated voltage. The
range of supported voltages may vary between programmers. It is an
error to request a voltage outside the capability of the
programmer. Voltages greater than 0 generally cause a programmer
to drive the line actively high. The special value of 0 causes the
programmer to drive the line low when the programmer has this
capability.
-VPP volts
Set the Vpp (target chip programming voltage) line to the indicated
voltage. The range of supported voltages may vary between
programmers. It is an error to request a voltage outside the
capability of the programmer. Voltages greater than 0 generally
cause a programmer to drive the line actively high. The special
value of 0 causes the programmer to drive the line low when the
programmer has this capability.
-CLKH
Set the serial data clock line (PGC) to the current Vdd level.
-CLKL
Set the serial data clock line (PGC) low.
-DATH
Set the serial data data line (PGD) to the current Vdd level.
-DATL
Set the serial data data line (PGD) low.
-OFF
Set all target chip lines to high impedence to the extent possible.
The result is dependent on the particular programmer.
-SETNAME name
Set the user-defined name of the programmer. NAME must be enclosed
in quotes ("") or apostrophies ('') if it contains blanks or any
other punctuation characters. The user-defined name is case-
sensitive.
The control processor in the programmer will be restarted if this
is supported. In this case the state of the programming control
lines will be the power up state, not whatever state is specified
with other command line options. In practice, the -SETNAME option
should not be used on the same command line with attempts to set
the persistent state of the programming lines.
To set the name of a programmer with an unknown name, connect it as
the only programmer to the host, or connect it via a serial line
since these can be specified on the command line.
The initial name of an Embed Inc programmer, when the user-defined
name is supported, is the type of the programmer followed by the
four digit serial number. For example, a USBProg with serial
number 123 will have its name set to "USBProg0123" initially.