nshex Commands

nshex operates on HEX images. The HEX images can be loaded, manipulated with commands, and saved. Each HEX image has a unique identifier.

HEX images are manipulated with special commands. nshex reads the commands from a special command file. The command file must be specified when running nshex. For example:

nshex -s cmd.txt

The command line may also contain one or more positional parameters, which can be used to modify the commands. If a combination of a precentage sign and a digit from 1 to 9 is found anywhere in the command file, it is replaced with the corresponding parameter. For example, if the command line is:

nshex -s copy.txt copy_from copy_to

and the copy.txt file contains

hex_image = read(%1.hex)
write(hex_image,%2.hex)

then nshex will replace %1 and %2 with parameters as follows:

hex_image = read(copy_from.hex)
write(hex_image,copy_to.hex)

There may be only one command per line. Empty lines are ignored. If a pound sign occurs anywhere on the line, the rest of the line is ignored and treated as a comment. For example:

#this is a comment
device PIC16F1704 #this is a comment too

Commands may be in one of two forms:

target = command(arguments)

or

command(arguments)

Here "command" is the command name, "target" is the identifier of the HEX image produced by the command. Some of the commands produce targets, others don't. "arguments" is a comma separated list of arguments. Some of the arguments are mandatory, others are optional. If there is no arguments, the parantheses around the argument list should be omitted.

If the text of an argument contains spaces, commas, slashes or pound sign, the whole argument must be enclosed in quotes.

An example of a program:

user_program = read("User Program.hex")
user_program = remove(user_program,config)
bootloader = read(Bootloader.hex)
user_program = merge(user_program,bootloader)
serial = NSZ(Serial.nsz)
user_program = merge(user_program,serial)
write(user_program,Production.hex)

This sequence of commands reads HEX file "User Program.hex", removes configuration bits, merges it with another hex file "Bootloader.hex", adds a unique serial number from NSZ file, and saves the result as the "Production.hex" file.

 

Below is the list of nshex commands in alphabetical order. Click on the command name for more information.

Command	Description
cd	Changes current working directory.
device	Specifies the PIC device name.
diff	Creates a differential HEX image based on two other HEX images.
expand	Expands a HEX image so that it contains only whole words, rows, or pages. The command can also expand it to fill all the memory of the device.
extract	Extracts a part of the HEX image. The command can extract a specified range or specified type of memory - code, configuration, EEPROM etc.
merge	Merges two HEX images into one.
NSZ	Obtains one instance of serial information from the specified NSZ file.
partition	Partitions the specified device. This only work with dual-partition devices.
read	Reads the HEX image from the specified HEX file.
remove	Removes a part of the HEX image. The command can remove a specified range or specified type of memory - code, configuration, EEPROM etc.
shift	Shifts the specified HEX image.
shrink	Shrinks the specified HEX image by removing blank areas.
write	Saves the specified HEX image as a HEX file.