Configuring Visual Studio Code for Programming the P2 on Mac, Windows, and Linux

Share on facebook
Share on twitter
Share on linkedin
Share on email
Share on print
Table of Contents
Description

This Quick Byte details the setup to configure three open source software tools to program the Propeller 2 (the P2, or P2X8C4M64P) on Windows, Mac and Linux operating systems with Visual Studio Code (VSC). VSC and the Spin2 extensions provide syntax highlighting, automatic updates, and command-line downloads to the P2 — and the simplicity and familiarity of a very popular and stable programming environment. 

The software required includes Microsoft VSC, Total Spectrum Software’s FlexProp (an IDE package which includes the FlexSpin compiler), and the Spin2 extension from the VSC Marketplace from Iron Sheep Software. All software is open source, freely available, and easily configured to compile and download to the P2. Additionally, an ANSI-compliant terminal program of your choice (Parallax Serial Terminal, TerraTerm, CoolTerm, etc) may also be used for serial debug. You will also have access to other VSC Marketplace extensions [like Error Lens, one of my favorites].

These instructions are for Windows. We’d like this Quick Byte to reflect the minor differences for Mac and Linux operating systems, if they should also be documented. Post comments at the bottom of this Quick Byte and we will update this document for the differences/exceptions accordingly.

Note: the bottom of this document includes a summary of links to important resources. 

Thank You to the Contributors

The P2 open source community is motivated by user feedback from the Parallax forums, the Propeller 2 Live Forums and messages of appreciation. If you benefit from this Quick Byte, we encourage you to join Parallax and also recognize their contributions through their Patreon accounts:

Considerations Between PNut (Parallax) and FlexSpin (Total Spectrum Software) Compilers

PNut is the official Parallax compiler and was written in X86 assembly for use in the Propeller Tool for Windows. FlexSpin is the compiler created by Eric Smith of Total Spectrum Software, written in C. While efforts are made to ensure Parallax-published Quick Byte examples run in both compilers and that FlexSpin remains largely compatible, there are likely to be some small differences. PNut includes the graphical debug tools (`debug) and FlexSpin does not. Both compilers support Spin2 and PASM languages, but FlexSpin supports the mixing of objects with BASIC and C, along with some Propeller 1 (P1, or P8X32A) Spin 1 code. 

Details about FlexSpin are available on the Parallax forums FlexProp thread, and details about PNut are on the PNut thread. The PNut Tool is just a test-area for compiler changes before the compiler makes its way into the Propeller Tool for Windows, the official Parallax tool.

If you encounter compilation issues with FlexSpin used in VSC, you can report them on the FlexProp thread or to the Total Spectrum Software GitHub.      

Step1: Download and Unzip FlexProp 

Download FlexProp from the Total Spectrum Software Patreon page. Extract the zip and file place the folder in a location of your choice. FlexProp does not have a software installer that allows you to specify the location; you have control to do this manually. Take note of where you decide to locate the FlexProp directory.  

Step 2: Download and Install VSC

Download Visual Studio Code for your operating system from the Microsoft Visual Studio Code page. Install VSC.

Step 3: Launch VSC, Install the Spin2 Extension

Click on the Extensions icon and type “Spin2” in the search box. Install the extension and choose Set Color Scheme (at present, two exist from forum members Cluso99 and Iron Sheep). 

Step 4: JSON File Setup

Visual Studio Code uses a JSON data format to provide the paths to:

  • Compile the P2 Spin/PASM code
  • Download the P2 Spin/PASM code
  • Identify the location of the FlexSpin.exe compiler
  • Name the top object file, so VSC knows how to collect up the child objects and include them

To configure your JSON file, copy the following template and prepare to make modifications to the highlighted lines to match your installation.

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "compileP2",
            "type": "shell",
            "command": "/Applications/Flexprop/bin/flexspin.mac",
            "windows": {
                "command": "C:\\Program Files\\flexprop\\bin\\flexspin.exe",
            },
            "args": [
                "-2",
                "${fileBasename}"
            ],
            "problemMatcher": {
                "owner": "Spin2",
                "fileLocation": ["autoDetect", "${workspaceFolder}"],
                "pattern": {
                    "regexp": "^(.*):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "severity": 3,
                    "message": 4
                }
            },
            "presentation": {
                "panel": "new",
                "focus": true
            },
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "compileTopP2",
            "type": "shell",
            "command": "/Applications/Flexprop/bin/flexspin.mac",
            "windows": {
                "command": "C:\\Program Files\\flexprop\\bin\\flexspin.exe",           
            },
            "args": [
                "-2",
                "01_quadrature_demo.spin2"
            ],
            "problemMatcher": {
                "owner": "Spin2",
                "fileLocation": ["autoDetect", "${workspaceFolder}"],
                "pattern": {
                    "regexp": "^(.*):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "severity": 3,
                    "message": 4
                }
            },
            "presentation": {
                "panel": "new",
                "focus": true
            },
        },
        {
            "label": "downloadP2",
            "type": "shell",
            "command": "/Applications/Flexprop/bin/loadp2.mac",
            "windows": {
                "command": "C:\\Program Files\\flexprop\\bin\\loadp2.exe",
            },
            "problemMatcher": [],
            "presentation": {
                "panel": "new",
                "focus": true
            },
            "args": [
                "-b230400",
                "${fileBasenameNoExtension}.binary",
                "-t"
            ],
            "dependsOn": [
                "compileTopP2"
            ]
        }
    ]
}

Next, open the folder where your source code directory is located and you will create the JSON file in this location. Then, choose Terminal / Create Tasks and choose Others. This is where you will paste your personal JSON file. This process also saves it in your source code folder.

Step 5: Keymappings

You will need to map a few keys to compile and download to the P2. Again, here’s a text file you will use for the next step where I have chosen F10 and F11 for compile and download, respectively:

// Place your key bindings in this file to override the defaults

[
    {
        "key": "F10",
        "command": "workbench.action.tasks.build",
        "args": "compileP2"
    },

    {
        "key": "F11",
        "command": "workbench.action.tasks.runTask",
        "args": "downloadP2"
    },
 ]

Step 6: Compile and Download to the P2!

Using the keymappings identified above, F10 will compile and F11 will download. Close the terminal window after downloads are finished. 

Step 7: Maintain your Master JSON File for Each New Project

Every time you begin a new P2 project with VSC, you will repeat Step 4 and copy the contents of your master JSON file into the directory where your active P2 project is located. You will only need to change the name of your top file (line 45) since the directory and executable paths are not changing. 

Source Code
Document Author
Source Code Author
Table of Contents
5 2 votes
Article Rating
Subscribe
Notify of
guest
4 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Jaan Doh

The link for FlexProp Presentation by Eric Smith, Total Spectrum Software (YouTube Video) actually takes you to the P2 Google documentation

cockpit

Kudos! Excellent Quick Byte on Integrated FlexSpin with VSC. I was up and running in a matter of minutes. However, there seems to be a missing step. When I closed everything down and executed “Open with Code” directly from my blink1.spin2 file [the example file I was using] I was unable to compile it with F10. It was as if VSC no longer knew my tasks.json file or keybindings existed even though they were where they were suppose to be. After playing with VSC a while I discovered that if I created a workspace and added the source code directories to my workspace everything worked great if I opened the workspace first. I’ll continue to experiment with VSC and look for additional guidance on the forums. Thanks again for the Quick Byte.