The following sections show the README files of the different command line tools.
Programming tools:
Other Utilities:
MSP430 Boot Strap Loader software for F1xx, F2xx, F4xx.
First the MSP430 BSL hardware is needed. An example schematics can be found in the application note “slaa96b” from TI (see references). Then this program can be used to communicate between the PC and the MSP430 device.
The program can be started by typing “msp430-bsl” in a console. To run it in the source directory, use “python msp430-bsl.py”
Usage: msp430.bsl.target [OPTIONS] [FILE [FILE...]]
-h, --help | show this help message and exit |
-d, --debug | print debug messages and tracebacks (development mode) |
-v, --verbose | show more messages (can be given multiple times) |
-q, --quiet | suppress all messages |
--time | measure time |
-S, --progress | show progress while programming |
File format is auto detected, unless –input-format is used. Preferred file extensions are “.txt” for TI-Text format, “.a43” or “.hex” for Intel HEX. ELF files can also be loaded.
Multiple files can be given on the command line, all are merged before the download starts. “-” reads from stdin.
-i TYPE, --input-format=TYPE | |
input format name (titext, ihex, bin, hex, elf) |
Multiple –erase options are allowed. It is also possible to use address ranges such as 0xf000-0xf0ff or 0xf000/4k.
NOTE: SegmentA on F2xx is NOT erased with –mass-erase, that must be done separately with –erase=0x10c0 or –info-erase”.
-e, --mass-erase | |
mass erase (clear all flash memory) | |
-m, --main-erase | |
erase main flash memory only | |
--info-erase | erase info flash memory only (0x1000-0x10ff) |
-b, --erase-by-file | |
erase only Flash segments where new data is downloaded | |
--erase=ADDRESS | |
selectively erase segment at the specified address or address range |
All these options work against the file(s) provided on the command line. Program flow specifiers default to “-P” if a file is given.
“-P” usually verifies the programmed data, “-V” adds an additional verification through uploading the written data for a 1:1 compare.
No default action is taken if “-P”, “-V” or “-E” is given, say specifying only “-V” does a “check by file” of a programmed device without programming.
Don’t forget to erase (“-e”, “-b” or “-m”) before programming flash!
-E, --erase-check | |
erase check by file | |
-P, --program | program file |
-V, --verify | verify by file |
-U, --upload-by-file | |
upload the memory that is present in the given file(s) |
This can be used to read out the device memory. It is possible to use address ranges such as 0xf000-0xf0ff or 0xf000/256, 0xfc00/1k.
Multiple –upload options are allowed.
-u ADDRESS, --upload=ADDRESS | |
upload a data block, can be passed multiple times | |
-o DESTINATION, --output=DESTINATION | |
write uploaded data to given file | |
-f TYPE, --output-format=TYPE | |
output format name (titext, ihex, bin, hex), default:hex |
-x ADDRESS, --execute=ADDRESS | |
start program execution at specified address, might only be useful in conjunction with –wait | |
-r, --reset | perform a normal device reset that will start the program that is specified in the reset interrupt vector |
-w, --wait | wait for <ENTER> before closing the port |
--no-close | do not close port on exit |
-p PORT, --port=PORT | |
Use com-port | |
--invert-test | invert RTS line |
--invert-reset | invert DTR line |
--swap-reset-test | |
exchenage RST and TEST signals (DTR/RTS) | |
--test-on-tx | TEST/TCK signal is muxed on TX line |
--no-start | no not use ROM-BSL start pattern on RST+TEST/TCK |
-s SPEED, --speed=SPEED | |
change baud rate (default 9600) | |
--password=FILE | |
transmit password before doing anything else, password is given in given (TI-Text/ihex/etc) file | |
--ignore-answer | |
do not wait for answer to BSL commands | |
--control-delay=CONTROL_DELAY | |
set delay in seconds (float) for BSL start pattern | |
--replace-bsl | download replacement BSL (V1.50) for F1x and F4x devices with 2k RAM |
--erase-cycles=EXTRA_ERASE_CYCLES | |
configure extra erase cycles (e.g. very old F149 chips require this for –main-erase) |
If it says command failed (DATA_NAK) it’s probably because no or a wrong password was specified, while a ERROR:BSL:Sync failed, aborting... is typical when the BSL could not be started at all.
led.txt in the following examples is a place holder for some sort of binary for the MSP430. A led.txt that contains an example in TI-Text format can be built from the code in examples/asm/led.
Erase flash, erase check, download an executable, run it (reset) and wait.
Old F149 devices need additional erase cycles! Use the --erase-cycles option in this case (--erase-cycles 20 will be OK is most cases)
MSP430 Boot Strap Loader software for F5xx, F6xx.
There are separate command line fontends for the USB and UART version:
Usage: hid.py [OPTIONS] [FILE [FILE...]]
-h, --help | show this help message and exit |
--debug | print debug messages and tracebacks (development mode) |
-v, --verbose | show more messages (can be given multiple times) |
-q, --quiet | suppress all messages |
--time | measure time |
-S, --progress | show progress while programming |
File format is auto detected, unless –input-format is used. Preferred file extensions are “.txt” for TI-Text format, “.a43” or “.hex” for Intel HEX. ELF files can also be loaded.
Multiple files can be given on the command line, all are merged before the download starts. “-” reads from stdin.
-i TYPE, --input-format=TYPE | |
input format name (titext, ihex, bin, hex, elf) |
Multiple –erase options are allowed. It is also possible to use address ranges such as 0xf000-0xf0ff or 0xf000/4k.
NOTE: SegmentA on F2xx is NOT erased with –mass-erase, that must be done separately with –erase=0x10c0 or –info-erase”.
-e, --mass-erase | |
mass erase (clear all flash memory) | |
-m, --main-erase | |
erase main flash memory only | |
--info-erase | erase info flash memory only (0x1000-0x10ff) |
-b, --erase-by-file | |
erase only Flash segments where new data is downloaded | |
--erase=ADDRESS | |
selectively erase segment at the specified address or address range |
All these options work against the file(s) provided on the command line. Program flow specifiers default to “-P” if a file is given.
“-P” usually verifies the programmed data, “-V” adds an additional verification through uploading the written data for a 1:1 compare.
No default action is taken if “-P”, “-V” or “-E” is given, say specifying only “-V” does a “check by file” of a programmed device without programming.
Don’t forget to erase (“-e”, “-b” or “-m”) before programming flash!
-E, --erase-check | |
erase check by file | |
-P, --program | program file |
-V, --verify | verify by file |
-U, --upload-by-file | |
upload the memory that is present in the given file(s) |
This can be used to read out the device memory. It is possible to use address ranges such as 0xf000-0xf0ff or 0xf000/256, 0xfc00/1k.
Multiple –upload options are allowed.
-u ADDRESS, --upload=ADDRESS | |
upload a data block, can be passed multiple times | |
-o DESTINATION, --output=DESTINATION | |
write uploaded data to given file | |
-f TYPE, --output-format=TYPE | |
output format name (titext, ihex, bin, hex), default:hex |
-x ADDRESS, --execute=ADDRESS | |
start program execution at specified address, might only be useful in conjunction with –wait | |
-r, --reset | perform a normal device reset that will start the program that is specified in the reset interrupt vector |
-w, --wait | wait for <ENTER> before closing the port |
--no-close | do not close port on exit |
-d DEVICE, --device=DEVICE | |
device name (default: auto detection) |
--password=FILE | |
transmit password before doing anything else, password is given in given (TI-Text/ihex/etc) file |
The UART version only differs in the options controlling the “Communication” and “BSL” settings:
- Communication settings:
-p PORT, --port=PORT Use com-port --invert-test invert RTS line --invert-reset invert DTR line --swap-reset-test exchenage RST and TEST signals (DTR/RTS) --test-on-tx TEST/TCK signal is muxed on TX line - BSL settings:
--no-start no not use ROM-BSL start pattern on RST+TEST/TCK -s SPEED, --speed=SPEED change baud rate (default 9600) --password=FILE transmit password before doing anything else, password is given in given (TI-Text/ihex/etc) file --ignore-answer do not wait for answer to BSL commands --control-delay=CONTROL_DELAY set delay in seconds (float) for BSL start pattern
led.txt in the following examples is a place holder for some sort of binary for the MSP430. A led.txt that contains an example in TI-Text format can be built from the code in examples/asm/led5x.
The USB HID device simply works when plugged in under Linux and the tool can use the device when the “rawhid” kernel module is present. It will create /dev/rawhid* devices. However, those devices are usually only writeable by root. To automatically change the permissions of the device, the following udev rule can be applied.
Create a file, e.g. /etc/udev/rules.d/20-msp430-hid.rules with the following contents:
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="2047", ATTRS{idProduct}=="0200" , MODE="0666"
Software to talk to the parallel port and USB JTAG adapters for the MSP430.
This software uses the JTAG hardware that comes with the FET kits. It is connected to the parallel port. Using 3rd party backends it is also possible to use USB programmers.
The program can be started by typing msp430-jtag when installed correctly If it’s used from the source directory use “python -m msp430.jtag.target”.
Usage: msp430.jtag.target [OPTIONS] [FILE [FILE...]]
-h, --help | show this help message and exit |
-d, --debug | print debug messages and tracebacks (development mode) |
-v, --verbose | show more messages (can be given multiple times) |
-q, --quiet | suppress all messages |
--time | measure time |
-S, --progress | show progress while programming |
--help-backend | show help about the different backends |
-l LIBRARY_PATH, --library-path=LIBRARY_PATH | |
search for libMSP430.so or libMSP430mspgcc.so in this place first |
File format is auto detected, unless –input-format is used. Preferred file extensions are “.txt” for TI-Text format, “.a43” or “.hex” for Intel HEX. ELF files can also be loaded.
Multiple files can be given on the command line, all are merged before the download starts. “-” reads from stdin.
-i TYPE, --input-format=TYPE | |
input format name (titext, ihex, bin, hex, elf) |
Multiple –erase options are allowed. It is also possible to use address ranges such as 0xf000-0xf0ff or 0xf000/4k.
NOTE: SegmentA on F2xx is NOT erased with –mass-erase, that must be done separately with –erase=0x10c0 or –info-erase”.
-e, --mass-erase | |
mass erase (clear all flash memory) | |
-m, --main-erase | |
erase main flash memory only | |
--info-erase | erase info flash memory only (0x1000-0x10ff) |
-b, --erase-by-file | |
erase only Flash segments where new data is downloaded | |
--erase=ADDRESS | |
selectively erase segment at the specified address or address range |
All these options work against the file(s) provided on the command line. Program flow specifiers default to “-P” if a file is given.
“-P” usually verifies the programmed data, “-V” adds an additional verification through uploading the written data for a 1:1 compare.
No default action is taken if “-P”, “-V” or “-E” is given, say specifying only “-V” does a “check by file” of a programmed device without programming.
Don’t forget to erase (“-e”, “-b” or “-m”) before programming flash!
-E, --erase-check | |
erase check by file | |
-P, --program | program file |
-V, --verify | verify by file |
-U, --upload-by-file | |
upload the memory that is present in the given file(s) |
This can be used to read out the device memory. It is possible to use address ranges such as 0xf000-0xf0ff or 0xf000/256, 0xfc00/1k.
Multiple –upload options are allowed.
-u ADDRESS, --upload=ADDRESS | |
upload a data block, can be passed multiple times | |
-o DESTINATION, --output=DESTINATION | |
write uploaded data to given file | |
-f TYPE, --output-format=TYPE | |
output format name (titext, ihex, bin, hex), default:hex |
-x ADDRESS, --execute=ADDRESS | |
start program execution at specified address, might only be useful in conjunction with –wait | |
-r, --reset | perform a normal device reset that will start the program that is specified in the reset interrupt vector |
-w, --wait | wait for <ENTER> before closing the port |
--no-close | do not close port on exit |
NOTE: On Windows, use “USB”, “TIUSB” or “COM5” etc if using MSP430.dll from TI. On other platforms, e.g. Linux, use “/dev/ttyUSB0” etc. if using libMSP430.so. If a libMSP430.so is found, it is preferred, otherwise libMSP430mspgcc.so is used.
NOTE: –slowdown > 50 can result in failures for the RAM size auto detection (use –ramsize option to fix this). Use the –verbose option and watch the outputs. The DCO clock adjustment and thus the Flash timing may be inaccurate for large values.
--backend=BACKEND | |
select an alternate backend. See –help-backend for more information | |
-p PORT, --port=PORT | |
specify an other parallel port or serial port for the USBFET (the later requires libMSP430.so instead of libMSP430mspgcc.so). (defaults to “LPT1” (“/dev/parport0” on Linux)) | |
--spy-bi-wire-jtag | |
interface is 4 wire on a spy-bi-wire capable device | |
--spy-bi-wire | interface is 2 wire on a spy-bi-wire capable device |
--slowdown=MICROSECONDS | |
artificially slow down the communication. Can help with long lines, try values between 1 and 50 (parallel port interface with mspgcc’s HIL library only). (experts only) | |
-R BYTES, --ramsize=BYTES | |
specify the amount of RAM to be used to program flash (default: auto detected) |
WARNING: This is not reversible, use with care! Note: Not supported with the simple parallel port adapter (7V source required).”,
--secure | blow JTAG security fuse |
Note
Some versions of the Texas Instruments MSP430 Development Tool require that you give the ‘–no-close’ option to msp430-jtag. This is because the Texas Instruments tool is powered via the JTAG adapter; the ‘–no-close’ option prevents msp430-jtag from powering the adapter off. You may also need to restart the program with msp430-jtag (using the ‘–no-close’ and ‘-r’ options is sufficient) after rebooting your machine.
Other development kits that rely on the parallel port for their power source may also need the ‘–no-close’ option. It is preferable to try programming the device without the ‘–no-close’ option first, and introduce this option only if the uploaded code fails to start.
Alternatively, it is possible run msp430-jtag -w to power the eval board from the JTAG interface.
msp430-jtag can use different libraries to connect to the target. The backend can be chosen with the –backend command line option.
Compatibility of backends:
Feature mspgcc ti 4 Wire JTAG yes yes 4 Wire JTAG on devices with spy-bi-wire yes(1) no using –spy-bi-wire option no yes support for USB JTAG adapters no yes unsing –funclet option yes no
Get a memory dump in HEX, from the bootstrap loader. Or save the binary in a file:
msp430-jtag -u 0x0c00 -s 1024 -f bin >dump.bin
or as an intel-hex file:
msp430-jtag -u 0x0c00 -s 1024 -f ihex >dump.a43
This section only applies to Windows. On Linux replace MSP430.dll with libMSP430.so etc.
USB JTAG adapters are supported through the MSP430.dlls from the adaptor vendor. To enable its use, copy MSP430.dll to the bin\lib folder, where shared.zip is located. Optionally copy HIL.dll to the bin folder.
For example for MSP-FET430UIF from TI:
The windows installer already includes this library.
To use the first available MSP-FET430UIF:
msp430-jtag -p TIUSB --upload=0x0ff0
The MSP-FET430UIF is registered as serial port. If more than one MSP-FET430UIF is connected, find out which COM port the desired adapter is using with the Device Manager. Then for example run:
msp430-jtag -p COM5 --upload=0x0ff0
Linux users have to specify the serial port differently:
msp430-jtag -p /dev/ttyUSB0 --upload=0x0ff0
MSP430 clock calibration utility.
This software uses the JTAG hardware that comes with the FET kits. It is connected to the parallel port.
The program can be started by typing msp430-dco when installed correctly If it’s used from the source directory use python -m msp430.jtag.dco.
Usage: msp430.jtag.dco [options] frequency
MSP430 clock calibration utility V1.1
This tool can measure the internal oscillator of F1xx, F2xx and F4xx devices, display the supported frequencies, or run a software FLL to find the settings for a specified frequency.
The target device has to be connected to the JTAG interface.
Use it at your own risk. No guarantee that the values are correct.
-h, --help | show this help message and exit |
-o FILE, --output=FILE | |
write result to given file | |
--dcor | use external resistor |
-d, --debug | print debug messages |
-l LPT, --lpt=LPT | |
set the parallel port | |
-m, --measure | measure min and max clock settings and exit |
-c, --calibrate | |
Restore calibration values on F2xx devices | |
-t TOLERANCE, --tolerance=TOLERANCE | |
set the clock tolerance as factor. e.g. 0.01 means 1% (default=0.005) | |
--define | output #defines instead of assignments |
--erase=ERASE | erase flash page at given address. Use with care! |
Arguments in the form variable@address are used to write the corresponding values to the target device. Variable names are case insensitive, addresses can be specified in decimal, octal or hexadecimal format.
The available variables depend on the target type and executed operation. All variables that are written all caps in the table below are in unsigned char format, others in unsigned short format. The later should be written to even addresses only, as the code reading these values could have problems otherwise.
Frequencies are in kHz.
Operation MCU Variables frequency F1xx BCSCTL1 BCSCTL2 DCOCTL freq F2xx BCSCTL1 BCSCTL2 DCOCTL freq F4xx SCFI0 SCFI1 SCFQCTL FLL_CTL0 FLL_CTL1 freq –measure F1xx fmax fmin rsel0_fmax rsel0_fmin rsel1_fmax rsel1_fmin rsel2_fmax rsel2_fmin rsel3_fmax rsel3_fmin rsel4_fmax rsel4_fmin rsel5_fmax rsel5_fmin rsel6_fmax rsel6_fmin rsel7_fmax rsel7_fmin F2xx fmax fmin rsel0_fmax rsel0_fmin rsel1_fmax rsel1_fmin rsel2_fmax rsel2_fmin rsel3_fmax rsel3_fmin rsel4_fmax rsel4_fmin rsel5_fmax rsel5_fmin rsel6_fmax rsel6_fmin rsel7_fmax rsel7_fmin rsel8_fmax rsel8_fmin rsel9_fmax rsel9_fmin rsel10_fmax rsel10_fmin rsel11_fmax rsel11_fmin rsel12_fmax rsel12_fmin rsel13_fmax rsel13_fmin rsel14_fmax rsel14_fmin rsel15_fmax rsel15_fmin F4xx fmax fmin –calibrate F1xx not supported F2xx f16MHz_dcoctl f16MHz_bcsctl1 f12MHz_dcoctl f12MHz_bcsctl1 f8MHz_dcoctl f8MHz_bcsctl1 f1MHz_dcoctl f1MHz_bcsctl1 F4xx not supported
When the msp430-dco tool is run with the --debug option it provides an output with all the possible variables and their values.
Measure calibration values for 1MHz, then erase the information memory flash page at 0x1000. These values are then written to the flash at 0x1000 and 0x1001.
This can be useful in combination with firmware downloads. For example make a mass erase, write firmware, then write clock calibration for this device:
msp430-jtag -e my_firmware.elf
msp430-dco 1e6 BCSCTL1@0x1000 DCOCTL@0x1001
The firmware can then read the values from the flash and configure the Basic Clock System using these values.
The algorithm does not search for the best match, it stops when the frequency is within the window. Therefore it’s not unlikely that the frequency is at the border of the tolerance window and not in the center.
Software to talk to the parallel port and USB JTAG adapters as seen with the FET kits.
The tool is intended to be assigned to .a43 and .elf files.
Without configuration file a dialog box is shown, first to ask for the programmer type, USB or parallel, and then the erase mode. These settings and some additional options can be preconfigured in a configuration file.
The configuration file together with the binary can be bundled into a single ZIP archive (extension must be renamed to .z43). The name of the configuration file is irrelevant as the first one with the ending .m43 is loaded. The binary is referenced in the configuration file, its name must match.
Example configuration file downloader-demo.m43:
##########################################################################
# This is a configuration file for msp430-download
# It shows and describes all available options.
#
# When used as separate file:
# - copy a binary to the destination folder
# - copy this file to the destination folder
# - edit configuration for your needs
#
# When used with a ZIP file:
# - as above copy binary and configuration file, edit config
# - add all files to a zip file and rename it with to a .z43 ending
#
##########################################################################
[modes]
##########################################################################
## Erase modes:
## "all" or "mass" erase all memory
## "main" leave information memory
## "ask" ask the user
erase_mode = mass
##########################################################################
## Interface selection:
## "ask" ask the user
## "1" or "parallel" parallel port. hint: numbers: LPT1, LPT2 etc
## "TIUSB" or "COMn" USB interface
interface = parallel
##########################################################################
## Program in a loop, so that several targets can easily be programmed
## Single run and exit if not set.
#loop = Yes
##########################################################################
## Ask again before programming.
## Recommended if no ther questions before programming are enabled, so
## that the user has a chance to abort. It is forced on if "loop"
## programming is on.
#ask_start = Yes
##########################################################################
## Fake the progress bar and increment depending on state, not depending
## on data. Automatically set if the USB JTAG is used.
fake_progess = No
##########################################################################
## For developers only. Remove key or set it to "no" for releases.
## When enabled, some diagnostic messages are printed to stdout.
#debug = Yes
##########################################################################
## Backend selection:
## "mspgcc" use MSP430mspgcc.dll
## "parjtag" use _parjtag + MSP430mspgcc.dll (not recommended)
## "ti" use MSP430.dll from TI ord 3rd party
## Autodetect if key is not given.
#backend = mspgcc
[data]
##########################################################################
## A filename can be predefined.
## File open dialog will not be shown in this case.
filename = leds.a43
##########################################################################
## If defined, a question is displayed, asking the user if he wants to
## see the readme.
#readme = readme.txt
##########################################################################
## Select the viewer for the readme. Possible values are:
## "browser" the default web browser or text editor, depending
## on file ending
## "internal" use a message box (only for very short texts)
viewer = browser