Commandline Tools¶
The following sections show the README files of the different command line tools.
Programming tools:
- msp430-bsl: F1x, F2x, F4x BSL
- msp430-bsl5: F5x, F6x BSL
- msp430-jtag: JTAG interface
Other Utilities:
- msp430-dco: clock calibration tool
- msp430-downloader: JTAG download wrapper (GUI)
msp430-bsl¶
MSP430 Boot Strap Loader software for F1xx, F2xx, F4xx.
Features¶
- Understands ELF, TI-Text and Intel-hex object files.
- Download to Flash and/or RAM, erase, verify, …
- Reset and wait for key press (to run a device directly from the port power).
- Load address into R0/PC and run.
- Password file can be any data file, e.g. the one used to program the device in an earlier session.
- Upload a memory block MSP->PC (output as binary data or hex dump).
- Written in Python, runs on Win32, Linux, BSD (and others).
- Use on command line, or in a Python script.
- Downloadable BSL for larger devices (integrated).
- Baud rate change for newer MSP430-BSLs.
- Test and reset lines can be inverted or exchanged for non standard BSL hardware. Test singal on TX line is also possible.
Requirements¶
- Linux, BSD, Un*x or Windows PC
- Python 2.5 or newer
- pySerial (2.4 or newer recommended)
- BSL hardware with an MSP430 device connected to a serial port
Short introduction¶
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”
Usage: msp430.bsl.target [OPTIONS] [FILE [FILE…]]
- Options:
-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 - Data input:
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) - Flash erase:
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 - Program flow specifiers:
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) - Data upload:
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 - Do before exit:
-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 - 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 --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.
Examples¶
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
.
msp430-bsl -e
- Only erase flash.
msp430-bsl -eErw led.txt
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-bsl led.txt
- Download of an executable to en empty (new or erased) device. (Note that in new devices, some of the first bytes in the information memory are random data. If data should be downloaded there, specify -e.)
msp430-bsl --upload 0x0c00/1024 --password led.txt
- Get a memory dump in HEX, from the bootstrap loader (on a device that was previously programmed with led.txt and therefore needs a specific password):
msp430-bsl -rw
- Just start the user program (with a reset) and wait.
cat led.txt|msp430-bsl -e -
- Pipe the data from “cat” to the BSL to erase and program the flash. (un*x example, don’t forget the dash at the end of the line)
msp430-bsl --replace-bsl -e -s 38400 led.txt
- First download the internal replacement BSL and then use it
to program at 38400 baud. Only works with targets with more
than 1kB of RAM. Newer devices with already know this command, in that
case omit the
--replace-bsl
History¶
- V1.4
- uses improved serial library, support for BSL download to MSP, support for higher baudrates (up to 38400)
- V1.5
- ELF file support, replacement BSLs are now internal
- V2.0
- New implementation. Some command line options have been renamed or replaced.
References¶
- Python: http://www.python.org
- pySerial: Serial port extension for Python http://pypi.python.org/pypi/pyserial
- slaa89.pdf: “Features of the MSP430 Bootstrap Loader in the MSP430F1121”, TI, http://www.ti.com/msp430
- slaa96b.pdf: “Application of Bootstrap Loader in MSP430 With Flash Hardware and Software Proposal”, TI
- Texas Instruments MSP430 Homepage, links to data sheets and application notes: http://www.ti.com/msp430
msp430-bsl5¶
MSP430 Boot Strap Loader software for F5xx, F6xx.
Features¶
- Understands ELF, TI-Text and Intel-hex object files.
- Download to Flash and/or RAM, erase, verify, …
- Reset and wait for key press (to run a device directly from the port power).
- Load address into R0/PC and run.
- Password file can be any data file, e.g. the one used to program the device in an earlier session.
- Upload a memory block MSP->PC (output as binary data or hex dump).
- Written in Python, runs on Win32, Linux, BSD (and others).
- Use on command line, or in a Python script.
- USB-HID BSL version:
- Automatic detection of HID device.
- UART BSL version:
- Baud rate change
- Test and reset lines can be inverted and/or exchanged for non standard BSL hardware. Test singal on TX line is also possible.
Requirements¶
- Linux, BSD, Un*x or Windows PC
- Python 2.6 or newer
- USB support requires:
- “pywinusb” library on Windows
- “rawhid” kernel driver on Linux
- other platforms are currently not supported
- pySerial (2.4 or newer recommended)
- MSP430 F5x / F6x with UART BSL connected to a serial port or a USB capable device connected to USB.
Short introduction¶
There are separate command line fontends for the USB and UART version:
python -m msp430.bsl5.uart
- UART versionpython -m msp430.bsl5.hid
- USB version
Usage: hid.py [OPTIONS] [FILE [FILE…]]
- Options:
-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 - Data input:
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) - Flash erase:
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 - Program flow specifiers:
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) - Data upload:
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 - Do before exit:
-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 - Communication settings:
-d DEVICE, --device=DEVICE device name (default: auto detection) - BSL settings:
--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
Examples¶
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
.
python -m msp430.bsl5.hid -e
- Only erase flash.
python -m msp430.bsl5.uart -eErw led.txt
- Erase flash, erase check, download an executable, run it (reset) and wait.
python -m msp430.bsl5.hid led.txt
- Download of an executable to en empty (new or erased) device. (Note that in new devices, some of the first bytes in the information memory are random data. If data should be downloaded there, specify -e.)
python -m msp430.bsl5.hid --upload 0xf000/1024 --password led.txt
- Get a memory dump in HEX, from a part of the memory (on a device that was previously programmed with led.txt and therefore needs a specific password):
- python -m msp430.bsl5.uart -rw`
- Just start the user program (with a reset) and wait.
cat led.txt|python -m msp430.bsl5.uart -e -
- Pipe the data from “cat” to the BSL to erase and program the flash. (un*x example, don’t forget the dash at the end of the line)
python -m msp430.bsl5.uart -e -s 38400 led.txt
- Change to faster baud rate for download.
Tips & Tricks¶
- USB-HID Linux permissions
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"
History¶
- V1.0
- New tool.
References¶
- Python: http://www.python.org
- pySerial: Serial port extension for Python http://pypi.python.org/pypi/pyserial
- pywinusb: USB HID library http://pypi.python.org/pypi/pywinusb/
- slau319a.pdf: “MSP430 Programming Via the Bootstrap Loader” http://www.ti.com/msp430
- Texas Instruments MSP430 Homepage, links to data sheets and application notes: http://www.ti.com/msp430
msp430-jtag¶
Software to talk to the parallel port and USB JTAG adapters for the MSP430.
Features¶
- understands ELF, TI-Text and Intel-hex object files
- download to Flash and/or RAM, erase flash, verify
- reset device
- upload a memory block MSP->PC (output as binary data or hex dump, ihex)
- written in Python, runs on Win32, Linux, BSD, …
- use on command line, or in a Python script
- reset and wait for key press (to run a device directly from the port power)
- TI/3rd party library support for USB JTAG adaptors
Requirements¶
- Linux, BSD, Un*x or Windows PC
- Python 2.5 or newer
- Parallel JTAG hardware with an MSP430 device connected
- or USB adapter with a corresponding [3rd party] MSP430 library
Short introduction¶
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…]]
- Options:
-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 - Data input:
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) - Flash erase:
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 - Program flow specifiers:
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) - Data upload:
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 - Do before exit:
-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 - Connection:
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) --unlock-bsl unlock Flash BSL (e.g. F5x) - JTAG fuse:
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 - Examples:
- Mass erase and program from file: “/home/lch/python-mspgcc- tools/msp430/jtag/target.py -e firmware.elf” Dump information memory: “/home/lch/python-mspgcc-tools/msp430/jtag/target.py –upload=0x1000-0x10ff”
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.
Note
–secure on F1x,F2x,F4x requires support by the JTAG interface for higher voltage.
Warning
–secure is irreversible and disabled JTAG access
Warning
–unlock-bsl enables writes to the BSL memory area on F5x/F6x devices. The user is responsible to erase and program appropriately, otherwise the device can be made unusable (JTAG disabled, BSL disabled, no user code running),
Backends¶
msp430-jtag can use different libraries to connect to the target. The backend can be chosen with the –backend command line option.
- “mspgcc”
- Using MSP430mspgcc.dll, the open source implementation from the mspgcc project.
- “ti” (default)
- Using MSP430.dll, the proprietary library from TI or a compatible one from a 3rd party supplier.
- “parjtag”
- Old way of using MSP430mspgcc.dll. Use “mspgcc” instead.
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
- Notes:
- Timing critical, may not work on all machines or at every try.
Examples¶
msp430-jtag -e
- Only erase flash.
msp430-jtag -eErw led.txt
- Erase flash, erase check, download an executable, run it (reset) and wait, the keep it powered (from the parallel port).
msp430-jtag led.txt
- Download of an executable to en empty (new or erased) device. (Note that in new devices some of the first bytes in the information memory are random data. If data should be downloaded there, specify -eE.)
msp430-jtag --go=0x220 ramtest.a43
- Download a program into RAM and run it, may not work with all devices.
msp430-jtag -u 0x0c00/1k
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
msp430-jtag
- Just start the user program (with a reset).
cat led.txt|msp430-jtag -e -
- Pipe the data from “cat” to msp430-jtag to erase and program the flash. (un*x example, don’t forget the dash at the end of the line)
msp430-jtag --unlock-bsl --erase 0x1000/2k
newbsl.a43Write a replacement BSL to a F5x or F6x device. This is a dangerous option, if it goes wrong, the device may become inaccessible (JTAG disabled, BSL disabled, no user code running). Never write new code without –erase as the BSL would end up being an AND combination of the previous Flash content and the new code, which is certainly not executing properly. Unfortunately does the BSL signature that is checked by the boot code of the CPU not guard against this mistake. However, it is allowed to erase but write no new BSL.
- NOTE: Only do this if you know how to write new BSL code. The BSL signature
- are in the binary must contain the correct data, otherwise the MCU may be rendered unusable.
NOTE: Works only with MSP430.dll as backend.
USB JTAG adapters¶
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:
- download a the MSP430.dll binary from the downloads section in http://mspgcc.sf.net
- copy MSP430.dll to
c:\mspgcc\bin
(substitute the source and destination folders according to you own setup)
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
History¶
- V1.0
- Public release.
- V1.1
- Fix of verify error.
- V1.2
- Use the verification during programming.
- V1.3
- Mainerase, progress options, ihex output.
- V2.0
- Updated implementation, new ctypes backend.
- V2.1
- F2xx support, improved options for funclets.
- V2.2
- Added –quiet and –secure. Try to use 3rd party MSP430 libraries so that USB adapters can be used. Allow multiple –upload with address ranges.
- V2.3
- Added support for F2xx and MSP430X architectures. Improved 3rd party library support for Linux and Windows.
- V3.0
- Rewrite command line frontend. Changed file type options, program flow specifiers.
References¶
- Python: http://www.python.org
- ctypes: http://starship.python.net/crew/theller/ctypes This module is included in the standard distribution since Python 2.5: http://docs.python.org/lib/module-ctypes.html
- Texas Instruments MSP430 homepage, links to data sheets and application notes: http://www.ti.com/msp430
msp430-dco¶
MSP430 clock calibration utility.
Features¶
- can handle F1xx, F2xx and F4xx devices, with or without external Rsel resistor
- measure calibration values for a given frequency
- restore calibration values of F2xx devices
- selectable clock tolerance
- can write measured values to the target flash, output C code or #defines
Requirements¶
- Linux, BSD, Un*x or Windows PC
- Python 2.5 or newer
- Parallel JTAG hardware with an MSP430 device connected (currently only the parallel port adapter with the MSP430mspgcc library is supported)
Short introduction¶
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.
- Examples:
- See min and max clock speeds:
- dco.py –measure
- Get clock settings for 2.0MHz +/-1%:
- dco.py –tolerance=0.01 2.0e6
- Write clock calibration for 1.5MHz to the information memory at 0x1000:
- dco.py 1.5e6 BCSCTL1@0x1000 DCOCTL@0x1000
Use it at your own risk. No guarantee that the values are correct.
- Options:
-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!
Variables¶
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.
Examples¶
msp430-dco 2.5e6
- Print the calibration values for 2.5MHz
msp430-dco 2.5e6 --define
- Same as above, but format the output as defines usable for C include files.
msp430-dco 1e6 --erase 0x1000 BCSCTL1@0x1000 DCOCTL@0x1001
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.
msp430-dco --measure
- Print frequency ranges of all DCO settings as well as minimal and maximal values. (Note: restricted functionality on F4xx devices)
msp430-dco --calibrate
- Recalculate the calibration values for 16MHz, 12MHz, 8MHz and 1MHz that are available in the information memory at 0x10f8-0x10ff. This is only possible for F2xx devices.
Known Issues¶
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.
History¶
- V1.0
- Public release.
- V1.1
- Can write values to target flash
References¶
- Python: http://www.python.org
- Texas Instruments MSP430 homepage, links to data sheets and application notes: http://www.ti.com/msp430
msp430-downloader¶
Software to talk to the parallel port and USB JTAG adapters as seen with the FET kits.
Features¶
- understands ELF, TI-Text and Intel-hex object files
- download to Flash and/or RAM, erase flash, verify
- reset device
- upload a memory block MSP->PC (output as binary data or hex dump, ihex)
- written in Python, runs on Win32, Linux, BSD, …
- use on command line, or in a Python script
- reset and wait for keypress (to run a device directly from the port power)
- TI/3rd party library support for USB JTAG adaptors (Windows only)
Short introduction¶
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