FlexBASIC on the P2
The BASIC programming language was developed in 1964 as a simple language for teaching programming to beginners. Over the years it has evolved into many different dialects with many different uses. BASIC was extremely popular in the early years of the microcomputer revolution and with the BASIC Stamp, and still enjoys success as a scripting language on PCs.
FlexBASIC is the BASIC language accepted by the FlexProp programming suite for the P2. The FlexBASIC version of BASIC is designed to be mostly compatible with popular PC BASIC versions like QuickBasic and FreeBASIC, as well as older BASIC’s such as Commodore BASIC for the C64.
FlexBASIC is part of FlexProp. FlexProp runs on Windows, Mac OS X, and Linux. The instructions below are for Windows. For the Mac you would use very similar instructions. For Linux, it’s probably easiest to clone the FlexProp git source repository and do “make install”.
FlexBASIC has most of the features of any modern BASIC, such as:
- Structured programming constructs (IF/THEN/ELSE, WHILE/WEND, DO/LOOP)
- Functions and subroutines
- Data types: integer, floating point, strings, classes
- Support for old-style line numbers and GOTO/GOSUB
- Functional programming features (closures and first-class functions)
FlexBASIC also has some notable extensions for programming the P2, including:
- Inline assembly
- Support for calling Spin2 objects directly from BASIC
- cpu functions for running functions in another COG
- Builtin intrinsics for accessing P2 instructions
Getting FlexBASIC / FlexProp
To download the FlexProp GUI, go to the FlexProp releases page and download the flexprop.zip file. Unzip this somewhere convenient, e.g. to your desktop.
Do not put it in a system folder (like the Program Files folder; the FlexProp configuration file is stored next to the executable, so the folder it is in must be writable.
Connecting the P2 Eval Board
Plug a micro-USB cable in to the “PC USB” socket on the P2 Eval board; connect the other end to a USB socket in your PC. Either USB-2 or USB-3 will work.
Running and Configuring FlexProp
Navigate to the flexprop folder where you unzipped flexprop.zip. Double click on flexprop.exe. You may receive a warning about an unknown publisher; you may ignore this warning.
(On MacOS and Linux, you should run the flexprop.tcl file instead of flexprop.exe. This requires the Tcl/Tk language to be installed. It is installed by default on MacOS. On Linux make sure to install Tcl and Tk with your Linux package manager.)
You should see a window come up with a top and bottom section.
The top section of the window is the editor. This will contain a number of tabs (one for each file you have open).
The lower section, labelled Compiler Output, contains messages from the compiler, including any error messages.
Initially there are no open tabs in the editor. To get started, you’ll have to either start a new file (File > New File) or load one of the samples (File > Open File). For this quick start guie we will try a new file.
Running Hello World
Select File > New File. This will open a New File tab, into which you may type your program. Let’s start with the classic “hello world” program.
print "hello, world"
As you can see, this is very simple. print is the BASIC command for printing a message to the serial terminal. The message to print is enclosed in double quotation marks.
Now select File > Save File As… and enter a name for your program (like hello.bas). *.bas is the traditional file extension for BASIC programs. FlexProp uses this file extension to determine what language your program is written in; this is necessary because FlexProp supports a number of languages such as Spin2 and C in addition to BASIC.
Now click on the Compile & Run on P2 button. You should see some compilation messages and then a terminal window labelled Propeller Output should pop up, which will show:
Select File > Save File As… and enter a name for your program (like hello.c). The FlexProp window should now look something like:
Hello World program
Now click on the Compile & Run on P2 button. You should see some compilation messages and then a terminal window labelled Propeller Output should pop up, like:
Anything printed by the BASIC program with print will show up in the Propeller Output window. This is a standard ANSI console window (it uses the default terminal program appropriate for your platform, whether it is Windows, Mac, or Linux) and so you can use ANSI escape sequences to do things like clear screen, move the cursor, change text color, and so on.
The Propeller Output window is in fact an interactive terminal, so if your program requires terminal input you would type it in that window as well.
By default BASIC programs use a baud rate of 230400 on P2 pins 63 and 62, and this output is captured in the terminal. You may change the baud rate by adding a line like _setbaud(_BAUD) right at the beginning of your BASIC program, before any prints. This line will set the baud rate to whatever the value of _BAUD is. The FlexProp GUI automatically adds a define for _BAUD that matches what you’ve selected in the Ports menu.
When you have finished interacting with the program, you must close the Propeller Output window. If you do not, then future attempts to run on the P2 will fail with a Could not find a P2 error (see the Troubleshooting section below). Closing the window does not actually terminate the program on the propeller; it just closes the serial connection and leaves the P2 running.
Instead of printing messages we may want to blink an LED. Select File > New and enter the following program:
const ledpin = 56
direction(ledpin) = output ' make the pin an output
output(ledpin) = 1 ' set pin high
pausems 500 ' wait 1/2 second
output(ledpin) = 0 ' set pin low
pausems 500 ' wait 1/2 second
Select File > Save File As… and choose a name like blink.bas. Now press the Compile & Run on P2 button again. The terminal window will again appear, but no output will show in it (so you may as well just close it). Instead, you’ll see the LED attached to pin 56 blink on and off once each second.
Note that a Propeller Output window will pop up in all cases (where you aren’t expecting to interact with the P2). You may close this window immediately. Closing it does not terminate the program running on the P2; the LED will keep blinking. In any case, you must close the window before trying to run another P2 program.
Multi-core blinking LEDs
Here’s a sample program that blinks multiple LEDs, using one CPU core (“cog”) for each LED. This is of course overkill, and in a practical program you would use smartpins or would at most use just one cog for all of the LEDs, but it illustrates the principle of running code in another CPU.
' multi-core led blinker
const STACKSIZE=10 ' small stack for each COG
const NUMCOGS = 4
' each independent core (cog) needs some stack space
' to work with. The minimum stack size is 8; more
' complicated subroutines may need more (count on one
' additional long per local variable, at least)
dim stack(STACKSIZE*(NUMCOGS+1)) as integer
' subroutine to blink an led on a pin
' delay is the milliseconds to delay between toggles
' note that parameters, like all variables, default
' to integer; to get a string or single, either the variable
' name has to end in $ or % respectively, or else you have
' to give an explicit type like "as string"
sub blinkit(pin, delay)
' declare a variable to hold which CPU got started
' the "as integer" could be left off, as noted above, since
' integer is the default variable type
dim cog as integer
for i = 1 to NUMCOGS
cog = cpu(blinkit(55+i, 200*i), @stack(i*STACKSIZE))
print "started cog "; cog
print "sleeping now"
Could not find a P2
If you get a “Could not find a P2” error message in the Propeller Output window, check and make sure that you’ve closed all other Propeller Output windows. Only one Propeller session may be open at a time, and if you try to run a program while a Propeller Output (terminal) window is open then it will not work and the P2 will not be found.
If that isn’t the problem, check the connection to your P2, and look under the Ports menu to see which port is selected. If you know which port the P2 is connected to, you may manually select that one to force FlexProp to use it.
If you have multiple P2 devices connected to your computer, you may select a specific port to connect to by finding it under the Ports menu in FlexProp. If the port you want does not show up, click on Ports > Scan for ports.
If there’s a syntax error in your program, you’ll get a dialog box like:
Click on OK, and then examine the error messages in the Compiler Output window. For example, if we forget a semicolon, there might be a syntax error message. The error message provides a link to the line where the compiler first noticed a problem. If you click on the link, it will take you to the line and hilight it.
The compiler can’t always figure out there’s a problem until it sees the next line, so always look at the surrounding code.
FlexBASIC Language Documentation
Documentation for the BASIC language used in FlexProp is found under the Help > BASIC Language menu item. This will bring open a web browser with documentation for FlexBASIC. This document is also found in PDF form in the file basic.pdf inside the doc folder in the FlexProp distribution.
Using Spin2 objects from FlexBASIC
Spin2 objects may be used directly in FlexBASIC programs. This is discussed in the FlexBASIC documentation, but it is important enough that we should probably highlight it here. A Spin2 object may be defined as a FlexBASIC class using the special class using syntax. A good example is in the Turtle demo that comes with FlexProp. This may be found in the file samples\Multi-Language\turtle_demo.bas. It uses a P2 video object written in Spin2 by Roger Loh. This is declared with:
dim vid as class using “video/p2videodrv.spin2”
This creates an object named vid which uses the Spin2 code from the file p2videodrv.spin2 located in the video subfolder. The Spin2 methods of this object may be invoked with the usual BASIC syntax, like:
vid.initDisplay(@display1, vid.VGA, VGA_BASE_PIN, VGA_VSYNC_PIN, vid.RGBHV, @lineBuffer, LINEBUFSIZE, 0);
The multi-language turtle demo also illustrates some other features of FlexBASIC, such as the use of C functions from BASIC, and the mount command for accessing files on the PC or an SD card.
The FlexProp Help menu has pages which discuss various features of the languages supported by FlexProp. The Help > General Compiler Reference menu has information applicable to all of the languages, including FlexBASIC. The Help > BASIC Language menu has a lot of information about FlexBASIC.
For further information about FlexProp in general and FlexBASIC in particular, see the Parallax forums.
Supporting FlexProp and FlexBASIC development
FlexProp and FlexBASIC are community-developed and supported open source projects. The source code is at https://github.com/totalspectrum/flexprop. Your bug reports and bug fixes help to improve it.
Financial support for FlexProp development is greatly appreciated. You may donate to FlexProp development at https://patreon.com/totalspectrum. Patreon supports get early access to beta releases, and priority in bug fixing. Donations are also accepted via PayPal at https://www.paypal.com/paypalme/totalspectrum.