nsprog - NSDS Command Line Programmer

nsprog is a command line programmer, which can be used to erase, program, verify, or read PIC device through NSDSP.

You can use the following parameters

Parameter	Description
operation	Mandatory. Must be the first parameter. Operation to be performed. One of the following: c - Check USB connection and device id. If the device name is not specified, only the USB connection check is performed. e - Completely erase the device w - Program the device without verification. This may be faster than programming with verification. p - Program and verify the device. Everything written to the device is independently read back and compared to the original. b - Check if the device is blank r - Read the device and store the result as a hex file v - Verify the device against the existing hex file. Only memory ranges contained in the hex file are read and compared.
-s serial	Specifies the serial number of the NSDSP chip. This lets you select a particular NSDSP when several ones are connected. This parameter is optional. If not specified, NSDSP will be selected randomly. You can use nsenum to display the list of serial numbers of the NSDSPs connected to the computer.
-d device	Full name of the target defice, for example dsPIC30F1010. Mandatory for most operations except the following cases: p,w,v - The device name may be specified within HEX file with a special line starting with semicolon and containing the full device name. c - If the device name is missing only the USB connection between the Computer and NSDSP is checked.
-i file	Specifies the input hex file. Mandatory for p, w, and v operations. "stdin"(lower case) may be used to read the file from standard input.
-o file	Specifies the output hex file. Mandatory for r operation. "stdout"(lower case) may be used to write the file to standard output. If "stdout" is used, -q option is forced to suppress regular output.
-t voltage	Target voltage between 1.5 and 5.5V. Allows NSDSP to decide whether or not the bulk erase operation can be used. This setting may be omitted if the actual target voltage is above the bulk erase threshold. However, this setting is mandatory for programming at voltages below bulk erase threshold because such voltages require special programning algorithms. If the voltage is not specified, NSDSP assumes that the voltage is high enough for bulk erase operations. Thus it applies regular programming algorithms which rely on bulk erase and will fail if the actual target voltage is below the bulk erase threshold.
-r rate	The maximum allowed rate of communucations between NSDSP and target device in kHz. Must be between 50 and 6000. Default is 6000kHz. Lower values may result in more reliable communications.
-a	Use AMCLR pin instead of MCLR. For this option to work, the NSDSP must be configured to use PGM/RTS/AMCLR pin as AMCLR.
-h	High voltage programming. Requires an HVP capable programmer, NSHVX or a external high voltage circuit.
-e	Ignore EEPROM memory. Depending on the operation: e - EEPROM is preserved. w,p - all the references to EEPROM in the HEX file are ignored. EEPROM is preserved. b,v - EEPROM is not read and/or verified. r - EEPROM is not read and is not recorded in the resulting HEX file. This setting has no effect for the devices which do not have EEPROM. If the chip is protected, the process of removing protection will force EEPROM erase regardless of the setting.
-u	Ignore User ID memory. Depending on the operation: e - UID memory is preserved. w,p - all the references to UID in the HEX file are ignored. UID memory is preserved. b,v - UID memory is not verified. r - UID memory is not read and is not recorded in the resulting HEX file. If the chip is protected, the process of removing protection may force UID erase regardless of the setting.
-W (upper case)	Allow OTP. If not specified, all OTP operations are suppressed.
-z	Specifies NSZ file for serial programming.
-x sub	Substitute. Up to 5 substitutes may be specified. Intended to be used by a calling script. The specified text is programmed directly into the specified memory location regardless of the contents of the HEX file. Substitute uses the following format: address:length:bytes[:{b,t}string] address - hexadecimal number. Specifies the memory address length - specifies the number of instructions to be written bytes - specifies the number of bytes per instruction to be taken from the supplied string. If "1" is specified, nsprog stores the number as a part of retlw command. string - specifies the contents to be written. If the length of the supplied string is not equal to (length x bytes) then it is truncated or padded as needed. If the string is not specified, the memory is filled with random contents. The first character of the string must be either t to specify a text (ascii) string, or b to specify a binary (hexadecimal) string. See examples below.
-b bits	Force configuration bits to the specified value. The configuration bits are specified with 2 characters. The first character specifies the bit to be forced as follows: L - LVP configuration bit D - DEBUG configuration bit J - JTAGEN configuaration bit The second character specifies the value. For example -bL1 will force the LVP configuatation bit to one (LVP enabled). PIC32 microcontrollers use 2-bit debug configuration. Therefore, to disable DEBUG both bits need to be set: -bD3 This option is ignored if the HEX file does not contain configuration bits. If the device has sevaral configuration sets (such as multiple partition devices), the -b option only affects the configuration sets which are already present in the HEX file. The -b option never affects slave configuration in dual core devices.
-c calibration	Can only be specified for baseline PIC devices. Specifies the calibration word to be programmed to the backup calibration location. May be used to restore lost calibration data. This can only be used when programming or erasing the target.
-p duration	After successful programming, produces a pulse on the PGM/RTS pin of the specified duration (between 10 and 10000 µs). The accuracy is within 20 µs at 6 MHz programming speed and decreases when lower programming speeds are used. However the pulse duration is never less than the specified value. The presense of the pulse may be used in automated programming systems to detect whether the programming was succssful or not. Note that some of the old PIC devices require the PGM pin for LVP programming.
-k	Keep the target in reset. The NSDSP programmer will be left in programming mode keeping the device in reset. Some devices may run for a short period of time before being reset.
-q	Quiet. Do not print anything except errors.
-v	Verbose. Produces extensive messaging.

 

Exit Code

If successful, nsprog returns with exit code 0. If an error occurs, nsprog prints an error message, which always starts from "ERROR:" and returns with exit code 1.

 

Examples

nsprog c

This example checks if the USB connection between the computer and NSDSP functions properly. This may be used for troubleshooting.

 

nsprog c -d PIC16F1454

This example checks the USB connection and verifies the device id.

 

nsprog p -d dsPIC30F1010 -i test.hex

This example programs the contents of the test.hex file into the selected target device and verifies the results.

 

nsprog p -i test.hex

This example programs the contents of the test.hex file into the target device and verifies the results. Since the device is not specified on the command line, the hex file must contain the device name at the end of the file:

:00000001FF
;dsPIC30F1010

 

nsprog v -v -d dsPIC30F1010 -i test.hex

This example verifies the contents of the chip against the the test.hex file. -v option is used to produce detailed report if differences are found.

 

nsprog r -d dsPIC30F1010 -o result.hex -u

This exmple reads the contents of the chip and saves it as the result.hex file. The content of the UID flash area is not read..

 

nsprog p -d dsPIC30F1010 -i test.hex -z test.nsz

This example reads the contents of the test.hex file, adds a record obtained from the test.nsz file, writes to the selected target device and verifies the results.

 

nsprog p -d dsPIC30F1010 -i test.hex -x 950:3:1:t123

This example programs the contents of the hex file, and also programs 3 instructions starting from 0x950. Each instruction stores 1 byte of useful information taken from the supplied text string:

0x000950  0x050310  retlw ’1’
0x000952  0x050320  retlw ’2’
0x000954  0x050330  retlw ’3’

 

nsprog p -i test.hex -x 950:5:2:b00112233445566778899

This example programs the contents of the hex file, and also programs 5 instructions starting from 0x950. Each instruction stores 2 bytes of useful information taken from the supplied hexadecimal string:

0x000950  0x001100  nop
0x000952  0x003322  nop
0x000954  0x005544  nop
0x000956  0x007766  nop
0x000958  0x009988  nop

 

nsprog p -i test.hex -x 950:5:2

This example programs the contents of the hex file, and also fills 5 instructions starting from 0x950 with random bits. Only 2 bytes of each instruction are filled:

0x000950  0x009952  nop
0x000952  0x00affd  nop
0x000954  0x005303  nop
0x000956  0x00645a  nop
0x000958  0x008b5d  nop