A Cross-Platform Debug Terminal for Parallax Propeller 2
Originally Chip's Debug listener, now available on all platforms
This is our PNut Debug Windows and terminal ported to Typescript and now available on all platforms. This tool aims to make building, downloading, and running as simple as editing and saving a file in VS Code.
NOTE: For now the Windows arm64 build is not correctly opening the seral port. This, so far, appears to be an npm serialport issue. We filed a bug report to get clarification and/or a fix.
SPECIAL REQUEST: If you have a native arm64 Windows machine please test this build and let me know if it works. I'm running Windows 11 Pro under Parallels on a macOS (Apple Silicon) machine and this problem may be limited to my context!
PNut Term TS is the 3rd component in the P2 Multi-platform Development Environment. The components are:
- VSCode Spin2 Extension for editing P1 and P2 code - supports running external compilers/downloaders
- PNut-TS compiler, which is the PNut compiler rewritten in Typescript for Multi-platform use
- PNut-Term-TS (this tool) is a terminal replacement for Propeller Serial Terminal with download and full debug display support.
On this Page:
- Documentation - Quick start and user guides
- PNut-Term-TS Features - key features of this implementation
- Installing PNut-Term-TS - installation notes for the supported platforms
- Repository Configuration - more about this Repo.
Additional pages:
- Quick Start Guide - Get up and running in 2 minutes
- User Guide - Complete reference documentation
- PNut-Term-TS Command-line - command line reference
- PNut-Term-TS ChangeLog - history of releases (Including what's new in this release!)
- PNut-TS - The companion PNut-TS compiler
- P2_PNut_Public - Pnut (for Windows) source is currently found in the Parallax Repo
- Quick Start Guide - Get PNut-Term-TS running in 2 minutes
- User Guide - Complete reference for all features
The Quick Start Guide covers:
- First session setup
- Three operating modes (Interactive, Command-Line Download, IDE Integration)
- Essential keyboard shortcuts
- Recording and playback basics
The User Guide provides:
- Comprehensive feature documentation
- Debug window reference
- Settings and preferences
- Troubleshooting guide
- Tips and best practices
- Replacement for Propeller Serial Terminal
- Downloads a compiled file to the P2 RAM or FLASH
- Switches to PST behavior after download
- Built-in support for all debug displays supported by PNut
- Single-Step debugger support coming Soon!
- Full logging support for all traffic to/from P2
- Automatic time-stamped log names for each new download
- PropPlug can be selected from the command line or within the application.
- The last PropPlug used is remembered
- "Only" PropPlug will automatically be used if none is specified
We are implementing the Graphical Debug Display support over time. Here's a full list of the displays and the current support status of each:
| Display | Status |
|---|---|
| Term | ✅ Implemented, v51a |
| Plot | ✅ Implemented, v51a |
| Logic | ✅ Implemented, v51a |
| Scope | ✅ Implemented, v51a |
| Scope_XY | ✅ Implemented, v51a |
| FFT | ✅ Implemented (noise floor issue), v51a |
| Bitmap | ✅ Implemented, v51a |
| MIDI | ✅ Implemented, v51a |
| Spectro | ✅ Implemented, v51a |
| Debugger | !!! Started, not ready for Use |
Install .zip files available for each release:
| Archive Name | Operating System | Architecture | Unpack Leaves |
|---|---|---|---|
| pnut-term-ts-linux-arm64-{MMmmpp}.zip | Linux, RPi | Arm 64 bit | pnut_term_ts/ |
| pnut-term-ts-linux-x64-{MMmmpp}.zip | Linux | Intel x86-64 bit | pnut_term_ts/ |
| pnut-term-ts-macos-arm64-{MMmmpp}.zip | MacOS | Apple Silicon | .dmg |
| pnut-term-ts-macos-x64-{MMmmpp}.zip | MacOS | Intel x86-64 bit | .dmg |
| pnut-term-ts-win-arm64-{MMmmpp}.zip | Windows | Arm 64 bit | pnut_term_ts/ |
| pnut-term-ts-win-x64-{MMmmpp}.zip | Windows | Intel x86-64 bit | pnut_term_ts/ |
NOTE: where -MMmmpp is the release version. (E.g., -010001.zip means v1.0.1.)
Installation is pretty easy for PNut-Term-TS. Here are the general steps: (more specific instructions links are below.)
- Identify and download the .zip file for your platform and architecture (from the latest release.)
- unzip the file, create a folder (or .dmg)
- On Windows, Linux move the folder to the install location.
On macOS move the folder to the /Applications folder. (This is a signed application so it should run without unknown developer warnings.) - Set up an environment variable (typically PATH) so that the pnut_term_ts executable can be referenced from anywhere.
- Run VSCode with the Spin2 v2.5.0 extension (when it's released) to ensure that the installed pnut_term_ts was found.
See detailed installation instructions for; macOS, Windows, and Linux/RPi.
That's really all there is to it!
This project is configured to run in a Docker container. Docker is essentially a way to run stuff in a local sandboxed environment. The environment is specified by a Docker image, and its main component is a snapshot of all files that are needed to run.
Wanting to clone the PNut-Term-TS repository locally? Then start by Installing Docker Desktop on your machine. See Overview of Docker Desktop at the Docker website.
In general, if you've not used Docker before, you'll follow these steps to get up and running:
- Install docker desktop - see install links on left panel
- Clone our repository
- Open the repo in VSCode
VSCode will tell Docker which image needs to be downloaded, start the container, and then ask you to [Reopen in Container]. Once you do reopen, VSCode will then install the NPM packages to get your local copy ready to build and run.
Linting and formatting of TypeScript is set up using Prettier formatter and ESLint. See How to use Prettier with ESLint and TypeScript in VSCode
If you like my work and/or this has helped you in some way then feel free to help me out for a couple of ☕'s or 🍕 slices or support my work by contributing at Patreon!
Licensed under the MIT License.
Follow these links for more information:
