tos-bsl ------- BootStrapLoader software for the flash devices MSP430F1xx (maybe F4xx too, but its not tested). Based on the example provided by TI but with more features. This version is a modification of Chris Liechti's original pybsl, with support for the telos, telosb and tmote devices from Moteiv (www.moteiv.com). It is released under a free software license, see tos-bsl-license.txt for more details. (C) 2001-2003 Chris Liechti (C) 2007-2010 Sporian Microsystems, Inc. and Titanium Mirror, Inc. Features -------- - new modular design supports multiple BSL interfacing techniques, currently including standard serial as defined by TI, methods used by the telosa and telosb platforms employing an FTDI usb/serial chip, and a new open technique using the cp2103 usb/serial chip. - understands TI-Text and Intel-hex - download to Flash and/or RAM, erase, verify - reset and wait for keypress (to run a device directly from the port power) - load addres 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 (other unices have other device names but should be faisible), Jython (Python in Java) - use per command line, or in a Python script - download a program, execute it, resynchronize and upload results. (for testing and callibration) - downladable BSL for larger devices - baudrate change for newer MSP430-BSLs - test and reset lines can be inverted for non standard BSL hardware Requirements ------------ - Linux, BSD, Un*x or Windows PC - Python 2.0 or newer (1.5.2 untested), 2.2 recomeded - win32all extensions to Python on Windows - BSL hardware with an MSP430 device connected to a serial port Installation ------------ Python installations are available from www.python.org. On Windows simply use the installer. The win32all package has an installer too. These installations should run fine with the deafults. On Linux just Python is needed. On many distributions is Python 1.5.2 incuded. I suggest that an upgrade to 2.2 or newer. There are rpm and deb binary packages and a source tarball availabe through the Python homepage. The pybsl archive can simply be unpacked to a directory, Windows users can use WinZip or WinRar among others to extract the gzipped tar file. If you want to run it from everywhere the directory where the file bsl.py is, should be added to the PATH. Look at "/etc/profile" on Linux, "autoexec.bat" on Win9x/ME, System Properties/Environment in Win2000/NT/XP. For Jython you need to have installed the "Java Communications API" (JavaComm). 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 programm can be used to communicate between the PC and the MSP430 device. The program can be started by typing "python tos-bsl" in a console. Often it works also with just "tos-bsl" or "./tos-bsl". USAGE: %s [options] [file] Version: %s If "-" is specified as file the data is read from the stdinput. A file ending with ".txt" is considered to be in TIText format, '.a43' and '.hex' as IntelHex and all other filenames are considered as ELF files. General options: -h, --help Show this help screen. -c, --comport=port Specify the communication port to be used. (Default is 0) 0->COM1 / ttyS0 1->COM2 / ttyS1 etc. -P, --password=file Specify a file with the interrupt vectors that are used as password. This can be any file that has previously been used to program the device. (e.g. -P INT_VECT.TXT). -f, --framesize=num Max. number of data bytes within one transmitted frame (16 to 240 in steps of 16) (e.g. -f 240). -m, --erasecycles=num Number of mass erase cycles (default is 1). Some old F149 devices need additional erase cycles. On newer devices it is no longer needed. (e.g. for an old F149: -m20) -U, --unpatched Do not download the BSL patch, even when it is needed. This is used when a program is downloaded into RAM and executed from there (and where flash programming is not needed.) -D, --debug Increase level of debug messages. This won't be very useful for the average user... -I, --intelhex Force fileformat to IntelHex -T, --titext Force fileformat to be TIText -N, --notimeout Don't use timeout on serial port (use with care) -B, --bsl=bsl.txt Load and use new BSL from the TI Text file -S, --speed=baud Reconfigure speed, only possible with newer MSP403-BSL versions (>1.5, read slaa089a.pdf for details). If the --bsl option is not used, an internal BSL replacement will be loaded. Needs a target with at least 2kB RAM! Possible values are 9600, 19200, 38400 (default 9600) -1, --f1x Specify CPU family, in case autodetect fails -2, --f2x Specify CPU family, in case autodetect fails -4, --f4x Specify CPU family, in case autodetect fails --f1x, --f2x and --f4x are only needed when the "change baudrate" feature is used and the autodetect feature fails. If the device ID that is uploaded is known, it has precedence to the command line option. --device=device Required device. Supported devices are: standard - Standard BSL programmer per TI specs telosa - Telos revA and compatible boards telosb - Telos revB and compatible boards cp2103 - Boards using cp2103 gpio for BSL support cp2103_old - The old cp2103 gpio format Most settings for a device are defined within the device specific bsl_{device} class. --no-BSL-download Do not download replacement BSL (disable automatic) --force-BSL-download Download replacement BSL even if not needed (the one in the device would have the required features) --slow Add delays when operating the conrol pins. Useful if the pins/circuit has high capacitance. Program Flow Specifiers: -e, --masserase Mass Erase (clear all flash memory) -M, --mainerase Erase main flash memory only (requires --password) -E, --erasecheck Erase Check by file -p, --program Program file -v, --verify Verify by file The order of the above options matters! The table is ordered by normal execution order. For the options "Epv" a file must be specified. Program flow specifiers default to "pvr" if a file is given. Don't forget to specify "e" or "eE" when programming flash! Data retreiving: -u, --upload=addr Upload a datablock (see also: -s). -s, --size=num Size of the data block do upload. (Default is 2) -x, --hex Show a hexadecimal display of the uploaded data. (Default) -b, --bin Get binary uploaded data. This can be used to redirect the output into a file. Do before exit: -g, --go=address Start program execution at specified address. This implies option --wait. -r, --reset Reset connected MSP430. Starts application. This is a normal device reset and will start the program that is specified in the reset vector. (see also -g) -w, --wait Wait for before closing serial port. If it says "NAK received" it's probably because you specified no or a wrong password. Examples -------- These exaples assume that you have added the installation directory to the PATH. type the full path to bsl.py otherwise and maybe use "python bsl.py". bsl.py -e Only erase flash. bsl.py -eErw 6port.a43 Erase flash, erase check, download an executable, run it (reset) and wait. Old F149 devices need addidional erase cycles! Use the -m option in this case (-m20 will be OK is most cases): "python bsl.py -eErwm20 6port.a43" bsl.py 6port.a43 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.) bsl.py -erwB BL_150S_14x.txt -S 38400 6port.a43 Erase device, change baudrate and download a new BSL, then download the specified file. After that, reset the device and wait for user input. bsl.py --go=0x220 ramtest.a43 Download a program into RAM and run it (on an erased device) bsl.py --go=0x200 -P 6port.a43 ramtest.a43 Download a program into RAM and run it (on a device that was previously programmed with 6port.a43 and therefore needs a specific password). For old devices that use the patch the above command gives a conflict with the patch. But as the patch is only needed to programm flash, it can be left out when running a program solely from RAM: "python bsl.py --go=0x200 -u -P 6port.a43 ramtest.a43" bsl.py -u 0x0c00 -s 1024 -P 6port.a43 Get a memory dump in HEX, from the bootstrap loader (on a device that was previously programmed with 6port.a43 and therefore needs a specific password): or on unix with the use of "hexdump": "python bsl.py -u 0x0c00 -s 1024 -P 6port.a43 -b | hexdump" or save the binary in a file: "python bsl.py -u 0x0c00 -s 1024 -P 6port.a43 -b >dump.bin" bsl.py --go=0x220 --upload=0x200 --size=256 ramtest.a43 Download the file ramtest.a43 to an empty device, execute its main function at 0x0220. The BSL then tries to reconnect to the device. This does only work when the program on the MSP430 does enter the BSL by jumping at address 0x0c00. It is not forced to enter the BSL by a reset as this would stop the program excution. When the reconnection was successful, the data, specified with the --upload and --size parameters, is loaded and printed. This configuration can be useful for software tests, getting callibration data, etc. PS: dont specify -r when using -g. A reset starts the user program which possibly destroys a program that was downloaded to RAM. bsl.py -rw Just start the user program (with a reset) and wait. bsl.py -rwc1 Reset the device on the second serial/COM port and wait. cat 6port.a43|bsl.py -eE - 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) bsl.py -e -S 38400 6port.a43 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. bsl.py -e -B BL_150S_14x.txt -S 38400 6port.a43 First download the given replacement BSL and then use it to program at 38400 baud. Only works with targets with more than 1kB of RAM. 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 V1.6 modular design uses --device option to select a communications method support for motes using a cp2103 usb/serial chip References ---------- - Python: http://www.python.org - Jython: http://www.jython.org - Serial Extension for Python: http://pyserial.sourceforge.net - win32all: http://starship.python.net/crew/mhammond/ and http://www.activestate.com/Products/ActivePython/win32all.html - slaa89.pdf: "Features of the MSP430 Bootstrap Loader in the MSP430F1121", TI - slaa96b.pdf: "Application of Bootstrap Loader in MSP430 With Flash Hardware and Software Proposal", TI - Texas Instruments MSP430 Homepage, links to Datasheets and Application Notes: http://www.ti.com/sc/docs/products/micro/msp430/msp430.htm