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

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 version
  • python -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

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:
  1. 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.a43

Write 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

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

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