Butterfly BASIC is a BASIC interpreter specially written to run on the Texas Instruments MSP430 family. It is designed to be small, efficient, simple to use, yet flexible enough for prototype or simple production use.Butterfly BASIC takes inspiration from many different BASIC implementations, adds support for the special features for the MSP430, and provides a great means to get started with the MSP430 processor.
This manual is both a small tutorial and reference for Butterfly BASIC. If you can’t find what you’re looking for within this manual you can always contact us–see the Contacts section below.
The BASIC programming language is simple to understand. With a BASIC interpreter you can experiment with programs on the hardware and try things out immediately. All you need to construct programs for Butterfly BASIC is an MSP430 board, a serial cable, and a terminal emulator. In contrast, a compiler is somewhat removed from the hardware and needs a more sophisticated development environment.
Although compilers are more complex, they do offer advantages over an interpreter. A program written and run on an interpreter will be slower than an equivalent program compiled by a compiler. If you need the fastest possible execution speed using a high level language, choose a compiler. If you need a simple development environment to experiment with the MSP430, choose an interpreter.
Butterfly BASIC is written in assembly code for speed and compactness. It takes advantage of the extensive features of the MSP430 to offer rapid application development and swift program execution. The complete source code of Butterfly BASIC is released under the GNU Public License version 2. This means that you are free to modify and use Butterfly BASIC yourself.
Butterfly BASIC is available off-the-shelf for the SoftBaugh ES449 and HPA449 boards. If you would like to have Butterfly BASIC ported to your board, you can always contact me to see what I can do. If you port the interpreter to some other hardware yourself, please drop me a line so I can add a reference to your port.
Bug fixes and enhancements are always welcome. I maintain the source code for Butterfly BASIC in my own time, and I'll upgrade rovide the reference code for the interpreter at irregular intervals. Don't despair if your modifications don't make it into the Butterfly BASIC reference code, you can always re-integrate your changes when I release a new version of Butterfly BASIC.
If, after evaluating Butterfly BASIC, you decide that you do need a compiler, I recommend CrossWorks for MSP430 from Rowley Associates in the United Kingdom. The CrossWorks development environment supports all variants of the MSP430 and has example programs for the ES449. I have to come clean here, I wrote the MSP430 CrossWorks C and BASIC compilers and the MSP430 optimizer, and I'm the founder of Rowley Associates, so I am more than biased.
This section will get you started with the Butterfly BASIC interpreter for the MSP430. Even if you’re familiar with BASIC, it’s a good idea to go through this section because there are a number of differences between Butterfly BASIC and other dialects that are worth pointing out. We'll be using the standard distribution for the SoftBaugh ES449; if you have some other version, you should be able to adjust fairly quickly, but the parts that are specific to the ES449 will obviously be inappropriate, but entertaining, reading.
You should first build and flash your ES449 with Butterfly BASIC. Once you've done this, connect a serial cable from the ES449 to the PC and run HyperTerminal. Set the connection to 38400 baud, no stop bits, and no flow control.
Reset the ES449 and you will be greeted by the standard Butterfly BASIC sign-on message:
Butterfly BASIC Interpreter v1.0 for the SoftBaugh ES449
Copyright (c) Paul Curtis 2003, 2004. All rights reserved.
1892 RAM bytes free, 48124 FLASH bytes free
>_
If nothing appears in HyperTerminal, check the cable, your communications setting, and that HyperTerminal is connected. If you still have problems after checking these, you can use CrossWorks to figure out where the problem might lay.
Now that the interpreter is ready, you can start to use it. When the interpreter is ready for input, it prompts a greater than sign “>.” The interpreter is in immediate mode and commands that you type in are executed immediately you press the return key. For instance:
>PRINT 1+2*3
7
>_
All user input in this manual is shown in uppercase for consistency, but you may find lowercase is more convenient when entering commands yourself.
The ES449 is equipped with an advanced liquid crystal display (LCD) with starburst segments capable of displaying a wide range of characters. Displaying messages on the LCD using Butterfly BASIC is simplicity itself:
>PRINT #3, "BASIC"
>
This instructs the interpreter to print the string "BASIC" (without the quotation marks) to channel #3, which is the main part of the display. There are other channels available, such as channel #1 which is channel to the UART you use to communicate with the ES449.
You’ll find yourself using some commands again and again and wishing there was some way to speed entry of them. Well, the good news is that Butterfly BASIC allows you to shorten reserved words, not just commands, by using a full stop
For example, the PRINT command can be abbreviated to “P.”, “PR.”, “PRI.”, or “PRIN.” and NEXT to “N.”, “NE.”, or “NEX.”.
You need to enter enough characters to make the command unambiguous. For instance, “P.” is the abbreviation for PRINT whereas “PO.” is the abbreviation for POKE.
Some commands cannot be abbreviated because they have stems in common with other commands. For instance, both “N.” and “NE.” are abbreviations for NEXT which means that NEW cannot be abbreviated to “N.” or “NE.”.
Going back to the program that counts on the LCD, we could type this in using abbreviations and without spacing as follows:
>10F.I=1TO50 >20P.#3,"I=";I >25F.J=1TO100:N. >30N. >40END >_
That’s not pleasant to look at and isn’t that understandable. When you list the program, however, abbreviations are replaced with the full form of the reserved word and the listing is nicely spaced:
>LIST 10 FOR I = 1 TO 50 20 PRINT #3, "I="; I 25 FOR J = 1 TO 100: NEXT 30 NEXT 40 END >_
Using abbreviations when entering a program doesn’t save memory and entering commands in their full form and with extra spacing doesn’t use extra memory. The program is stored in a tokenized form ready for execution and abbreviations are only used as aid to rapid program entry.
Throughout this manual we will spell out reserved words in full.
One of the things that make a computer useful is its ability to tirelessly run repetitive tasks over and over again. There are a number of looping and conditional statements in Butterfly BASIC and we’ll cover them all in this section.
The simplest way to repeat a sequence of instructions over and over again is by using a FOR loop. You briefly met the FOR loop in the first program you typed in which displayed the numbers from 1 to 100 on the LCD. The loop is introduced by the FOR statement and is closed by the NEXT statement; the statements between the FOR and the NEXT are executed within the loop
Butterfly BASIC has 26 variables named A through Z, and each of these can hold a signed 32-bit value. All variables are cleared to zero when you run a program. You can assign a value to a variable using LET
>LET A=123 >PRINT A 123 >LET A=A+1 >PRINT A 124 >_
This part of the manual describes the internal structure of the Butterfly BASIC interpreter and how to customize it. We assume that you have used Butterfly BASIC or some other BASIC interpreter and are confident writing BASIC programs.
In this section we'll distinguish between porting the interpreter and customizing the interpreter.
Butterfly BASIC is programmed in MSP430 assembler using Rowley Associates' CrossWorks tools. To build Butterfly BASIC you load the solution "basic.hzp" into CrossStudio and build it. As supplied, the interpreter runs on a SoftBaugh ES449 board but can be customized to run on most MSP430 devices.
Programs are stored in the MSP430's flash memory. The interpreter itself is less than 6K of code, so 6K of flash is reserved for the interpreter's use. The remainder of the flash is free to store BASIC programs.
Each BASIC code line is stored in flash using a singly linked list with each line stored in line number order. The root of this list is the symbol program_start in RAM. If this symbol is zero, there is no program stored in flash; if it is non-zero, it points to the first line of the program, i.e. the line with the lowest line number. The list of lines is terminated by a zero pointer.
When a new line is entered, it's stored into memory at the first unused location in flash. The symbol flashtop contains a pointer to the first unused flash location. The linked list in flash is updated to reflect the new line entered without altering the contents of the existing lines. As such, when you enter a replacement line for one that already exists, or delete a line from the program, the space for that old line is not recycled for future use. The only way to compact a program is to use NEW to erase the flash and to enter the program again.
The interpreter is usually located at the bottom of flash memory so, on an F149, F449, or F169, the interpreter starts at 0x1100 and runs for 6K. Permanent storage for user programs is set to 0x4000 and is controlled by the equated symbol user_flash_begin which must be defined if you customize the interpreter.
To port the interpreter to new hardware you need to do the following:
The subroutine hw_init must initialise the hardware ready for execution. It does not initialise the BASIC interpreter, only the hardware. Its responsibilities are:
The example subroutine for the ES449 does this:
In this section I'll describe how to port the BASIC interpreter to another board. In this case it's Rice University's ELEC226 board which is based around an MSP430F169.
Firstly, we create a new CrossWorks project or the work we're doing.
We now have an empty solution and need to populate it. We start with the template files:
So far we have the boilerplate for the main.asm file and the two files that contain the core of the interpreter.
This sections deals with adding your own command or function to the interpreter. Usually you would write the command or function in MSP430 assembly code, but you can equally write the code in C. If you're writing the code in C, you need to be aware of the requirements of the interpreter and C runtime system.