SpinCore PulseBlaster Interpreter

Sections

Legal
Graphical User Interface
Language
Interpreter Special Features
Command Line
PulseBlaster ESR PRO Information

For help or information about other SpinCore products, please visit us at www.spincore.com

Legal

Copyright (c) 2024 SpinCore Technologies, Inc.

This software is provided 'as-is', without any expressed or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications.

Graphical User Interface

Upon launching the program, you will be presented with an interface for writing your PulseBlaster programs. The top white box is an editor. The bottom gray box is output that the Interpreter produces. At the bottom of the window are two boxes. One box is to put in the frequency your board uses and the other box to select the board to control. This frequency will be saved each time you shutdown the program and then reloaded the next time you launch. On the bottom right, you will notice Line # and Column # output. This tells you where the cursor is inside of the edit box for fixing errors and such.

At the top of the window is the menu bar and 5 buttons. The buttons perform many of the same functions that can be found on the menu bar but are provided as a convenience. Starting from left to right:

Open File
This button opens a file. You will be prompted to save any changes to the contents of the current file.

Save File
This button saves the file you are currently editing.

Load Board
This button loads the program that currently resides in the edit box onto the board. The file does not have to be saved beforehand. The program will take the contents of the edit box and interpret them. The output of this operation will be displayed in the output box. Upon success, a message will be displayed saying the board was successfully loaded. If this message is not displayed, it means that some error occurred and a message telling you the error should be the last thing displayed.

Start
This button starts execution of the program currently in the board's memory.

Stop
This button stops execution of the program current in the board's memory.

The menu bar is just above the 5 buttons. Starting from left to right:

File->New
This will erase the current contents of the edit box. You will be prompted to save changes to the
current file.

File->Open
Same as the Open File button.

File->Save
Same as the Save File button.

File->Exit
This will exit the program. You will be prompted to save changes to the current file.

Interpreter->Show Debug Information
This turns debug information from the Interpreter on and off. This might provide some insight into an error that you might not be able to resolve. The debug information will be shown next time the board is loaded.

Interpreter->Save Output
This saves the contents of the output box to a text file.

Interpreter->Clear Output
This clears the contents of the output box.

Board->Load
Same as Load Board button.

Board->Start
Same as Start button.

Board->Stop
Same as Stop button.

Help->Read Me
Opens this document in a web browser.

Help->About
This displays information about the program.

Language

The language of the Interpreter is very similar in appearance to that of an assembly language. Every line represents a single instruction. White space, such as tabs and spaces, is discarded. The language is case-insensitive. The following are instructions on the contents of a given line.

Labels

Labels come at the beginning of a line and are denoted by a : at the end. For instance:

Start: 0xFFFFFF, 200 ms

This line is labeled Start. Since the language is case insensitive though, the label is equal to any form of the word Start. Labels are optional and do not have to be contained on any line.

Output Pattern

This is the first required part for a given line. This field must exist on all lines or the Interpreter will fail while programming the board with the exception when using Natural Numbers. This field represents the pattern that the board will output for this instruction. This pattern may be represented in Hex, Binary, or simply Integer format. All output fields must begin with a number no matter what format they are represented in. This usually only matters for Hex and Binary representations. Hex and Binary representations should start with a 0 followed by an 'x' or a 'b'. The following are examples of valid output patterns for all bits on:

Hex: 0xFFFFFF

                  Binary: 0b1111 1111 1111 1111 1111 1111

                  Integer: 16777215

Notice how Hex and Binary begin with "0x" and "0b". The x or the b must be there otherwise the interpreter will fail while trying to program the board. Also notice that the binary output pattern contains white space. This is allowed. You may also use white space inside of hex values:

0x FF FF FF

The output pattern is read until a comma is reached. All white space is thrown away during the read.

Time Field

The time field consists of two parts, time value and time units. Time value can be any decimal number. Time units must be one of four options:

s	seconds
ms	milliseconds
us	microseconds
ns	nanoseconds

Examples of valid time fields are as follows:

White space is permitted inside of a time field.

Command Field

The command field tells the board what to do after producing the output pattern for the given amount of time. Valid commands are as follows:

CONTINUE or continue - Continue to next instruction
STOP or stop - Stop execution
LOOP or loop - Beginning of a loop
END_LOOP or end_loop - End of a loop
JSR or jsr - Jump to a sub routine
RTS or rts - Return from a sub routine
BRANCH or branch - Branch
LONG_DELAY or long_delay - Long delay
WAIT* or wait - Wait for a trigger
The command field is optional. If no command field is listed, the CONTINUE command will be assumed.
For more information on these commands see the SpinAPI reference.

*Please note that WAIT cannot be placed at the top of the program and there should be at least one instruction execution time between the start of the program and WAIT.

Data Field

The data field is also optional unless a branch or jsr command is used during an instruction. In this case, the Interpreter forces you to enter a label to jump to. The data field is used for different purposes depending on the command field. If no data field is specified, a value of 0 will be assumed. For more information see the SpinAPI reference.

Comments

Comments start with a // and the Interpreter just throws anything after that on the line away. Comments may be on a line my themselves or placed after an instruction as follows:

// Valid comment on a line by itself.

                  Label: 0xFFFFFF, 100 ms // Valid comment after a valid
                  instruction

                  0x000000, 100 ms, branch, Label // Another valid
                  comment

There are several example programs available. Please take a look at these.

Interpreter Special Features

The Interpreter provides some special features to make your life a little simpler when writing a
PulseBlaster program.

Stop

Stop is the only command allowed to be on a line by itself. When a line is found containing only the word stop, a program line will be generated with a 0 output pattern and a length of 0 ms. Stop is special in PulseBlaster boards in that the output pattern and the time field are ignored (firmware dependent). It is recommended that before issuing a Stop command your output pattern be set to 0. For instance:

0xFFFFFF, 100ms

                  STOP

This will result in all bits remaining on after the Stop command has been executed. We recommend doing the following:

0xFFFFFF, 100ms

                  0x000000, 100ms

                  STOP

This will ensure that all bits are off when program execution stops.

Loop Matching

The Interpreter will do loop matching for you. Example:

0x000000, 100ms, LOOP, 3 // Loop 3 times

                  0xFFFFFF, 100ms, END_LOOP // Interpreter will match
                  END_LOOP with the LOOP on the line above

Natural Numbers

Natural Numbers allows you to specify what bits to switch on for a given instruction. Begin the output field with "0n" and then you can specify which bits to switch on. Valid ranges are 0 thru 23, and each bit is separated by a '+'. See the examples below.

0n , 500ms // All bits off for 500 ms

                  0n 1 + 3, 500ms // Bits 1 and 3 on for 500ms

                  0n 2 + 4, 500ms // Bits 2 and 4 on for 500ms

                  0n 0 + 5, 500ms // Bits 0 and 5 on for 500ms

Variables

Variables allow you to change portions of your program with ease. Variables are denoted by a leading '$' and must be assigned a value
before they are used in your program. To assign a variable a value, type the name of the variable followed by an equal sign and the value you want to assign to that variable. For example:

$var = 1234 // Assign $var 1234

Assignments must be on a line by themselves. Once a variable has been assigned, it can be used anywhere in a program line. Variables can not be used to label lines. See the following example:

$output1 = 0xFFFFFF

                  $time1 = 100ms

                  $output2 = 0x000000

                  $time2 = 500ms

                  

                  start: $output1, $time1 // Translates to: 0xFFFFFF,
                  100ms

                         $output2, $time2,
                  branch, start // Translates to: 0x000000, 500ms,
                  branch, start

Variables are just replaced with the value they are assigned before program line values are parsed. They can also be changed once they are assigned a value.

$output = 0xFFFFFF // $output will be 0xFFFFFF
                  after this point

                  $output, 100ms

                  $output = 0x000000 // $output will be 0x000000 after
                  this point.

                  $output, 100ms

Command Line

The Interpreter can also be used from the command line using spbicl.exe. This is only recommended for users who are familiar with the usage of a command line and need to use the Interpreter from some other program. The usage of the command line program is as follows:

Usage:

spbicl <command> [file] [frequency]

Commands:
Load = Load [file] into memory using [frequency]
Start = Start execution of program currently in memory
Stop = Stop execution of program currently running

Examples:

spbicl load file.pb 100.0 Load file.pb at 100 MHz
spbicl start Start program execution
spbicl stop Stop program execution
The return value of the program is 0 if success and -1 if an error occurs.

PulseBlaster ESR PRO Information

The PulseBlaster Interpreter can be used to program the PulseBlaster ESR PRO boards.

The PulseBlaster ESR PRO boards use the upper three bits of the output pattern to determine different aspects about the output pattern. In some models, having the upper three bits of the output pattern set to 0 will cause no output for the entire instruction. Please consult the product manual for more information on the Short Pulse Feature.



                  

                  last modified
                    08/20/2024