--- /dev/null
+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 <cliechti@gmx.net>
+
+Features
+--------
+
+- 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 bsl.py" in a console. Often
+it works also with just "bsl.py" or "./bsl.py".
+
+USAGE: bsl.py [options] [file]
+
+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
+ -4, --f4x Specify CPU family, in case autodetect fails
+ --F1x and --f2x 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.
+ --invert-reset Invert signal on RST pin (used for some BSL hardware)
+ --invert-test Invert signal on TEST/TCK pin (used for some BSL
+ hardware)
+ --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)
+ -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 programm 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 programm that is specified in the reset
+ vector. (see also -g)
+ -w, --wait Wait for <ENTER> 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
+
+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
+
projects / tinyos-2.x.git / blobdiff