Shop OBEX P1 Docs P2 Docs Learn Events
New PNut-Term-TS downloader, debug application for P2 development on Windows, Mac, Linux (yes, RPi) — Parallax Forums

New PNut-Term-TS downloader, debug application for P2 development on Windows, Mac, Linux (yes, RPi)

Stephen MoracoStephen Moraco Posts: 384
in Propeller 2

PNut-Term-TS is the result of combining PST (Parallax Serial Terminal), PNut debug windows, and a downloader into a single application and porting it to a platform-agnostic language (in this case, TypeScript). It currently supports all nine debug windows, provides full logging, and has full PST functionality. It is built to handle debug traffic via serial at our full 2Mbit rate. The Single-Step debugger is still under development, so this is a v0.9.1 release.

v0.9.1
Initial release of PNut-Term-TS cross-platform debug terminal

  • Support for Parallax Propeller 2 debugging protocol
  • P2 download implementation with RAM and FLASH support
  • Serial communication up to 2Mb with DTR/RTS control line support

  • Nine Debug windows implemented:
    -- Terminal window with full ANSI escape sequence support
    -- Logic analyzer window for digital signal analysis
    -- Oscilloscope window for analog signal visualization
    -- XY scope display window for phase relationships
    -- Plot window for data graphing and visualization
    -- FFT spectrum analyzer window for frequency analysis
    -- Bitmap display window for image visualization
    -- MIDI interface window for musical data

  • Also features a logger window for message capture and analysis

  • Cross-platform packaging for Windows (x64, arm64), Linux (x64, arm64), and macOS (x64, arm64)
  • Command-line launcher pnut-term-ts for all platforms
  • Electron v33.3.1 runtime bundled in all packages

NOTE: As we were doing final testing, we found an issue on Windows. As a result of this late finding this release is for MacOS and Linux/RPi only. We'll need a couple of days to find and fix this.

We will officially release a v1.x.x PNut-Term-TS when we've completed the Debugger capability.

PNut-Term-TS is found at its new Public Repository (repo), while the latest Releases are also found there at the Releases Page

Issues with PNut-Term-TS can be filed at the repo issues page, or, of course, you can report issues here in this thread.

This is an early version. I've tried to be comprehensive in my testing, but there's a lot of functionality in this first release. I look forward to hearing about your successful use and any issues you may encounter. Thank you for helping test this early version!

Comments

  • roglohrogloh Posts: 6,166

    Sounds really good Stephen. I've been somewhat limited in the past with the Mac platform and all the fancy debugging stuff possible on the P2 (trying out Wine only ever gave me problems with serial ports etc) so if your new debugger tools works on the Mac platform too now that'd be nice to finally try out. I typically tend to use simple editors like Vim with flexspin command line stuff so hopefully the binaries created by that environment would still work out nicely with your own tools as well.

  • KaioKaio Posts: 276
    edited 2025-11-11 23:22

    Hi Stephen,

    thank you for this new tool and all your work done so far developing cross-platform tools for the Propeller. Nice to have a debugging tool supported on all OS platforms. I'm also using a Mac and tried the arm64 version.

    1. First I want to make a hint regarding installation. As macOS is a Unix like system there are some directories of executables already present in the PATH variable.
      Instead of adding each individual application directory to the PATH one should add the application to an appropriate existing directory which exists already in the PATH.
      For third party tools I suggest to use /usr/local/bin where e.g. Python and NPM are located if installed.
      You can install PNut-Term-TS in the application directory as you did and then make a link to the pnut-term-ts script in the directory /usr/local/bin with this command.

    ln -s /Applications/PNut-Term-TS.app/Contents/Resources/bin/pnut-term-ts /usr/local/bin/pnut-term-ts

    You need root rights for this but you have this already during installation or let the user it do. Afterwards pnut-term-ts is ready to use.

    1. The pnut-term-ts script must be enhanced to work correctly if it is linked in this way. I have attached my changes (added .txt to allow upload).

    2. For my test I have used a binary which was build with Spin Tools IDE. The little program uses two cogs. I used 2Mbit for communication. The logging of debug was working fine but for cog 0 it shows unexpected output and that 4 times the same.

    There is some hex output instead, but it looks like this is from the missing message for cog 0.
    The same binary shows the expected debug logs with Spin Tools IDE and FlexProp. On FlexProp you can use "Run binary on device..." from Commands menu to try.

    1. In the debug window and in the log file the message from the program is shown with the used control characters (line feed and new line) instead of doing it. This is not the case for messages coming from debug kernel.
      On the other used tools it is printed as expected.

    2. In the log file the timestamps are shown as UTC but the file name uses local time.

    Overall I can say it is working so far but differ from the output of other tools.

    log
    log
    debug_251111-005759.log
    2K
    binary
    binary
    coginit_delay-gST.binary
    3K
    txt
    txt
    pnut-term-ts.txt
    383B
  • Stephen MoracoStephen Moraco Posts: 384

    @Kaio said:

    thank you for this new tool and all your work done so far developing cross-platform tools for the Propeller. Nice to have a debugging tool supported on all OS platforms. I'm also using a Mac and tried the arm64 version.

    Thank you! I'm happy to hear that it's been useful.

    Regarding "make a hint regarding installation"— I, too, am a longtime Mac user. I'm trying to make the app install for us as standard as possible, hence, the drag to applications/ method. I'm reluctant to make this change, but I'll study what you sent and see what you are proposing.

    For my test I have used a binary which was build with Spin Tools IDE. The little program uses two cogs. I used 2Mbit for communication. The logging of debug was working fine but for cog 0 it shows unexpected output and that 4 times the same.

    There is some hex output instead, but it looks like this is from the missing message for cog 0.
    The same binary shows the expected debug logs with Spin Tools IDE and FlexProp. On FlexProp you can use "Run binary on device..." from Commands menu to try.

    In the debug window and in the log file the message from the program is shown with the used control characters (line feed and new line) instead of doing it. This is not the case for messages coming from debug kernel.
    On the other used tools it is printed as expected.

    We handle many message forms in this app. So there is some pretty sophisticated detection and routing. I'll run your case and see what I need to adjust/fix. The control char display should only happen for non-CogN messages, so it's likely a detection problem here too. More soon.

    In the log file, the timestamps are shown as UTC, but the file name uses local time.

    I hadn't noticed. Thanks for pointing this out. I'll use local time for all timestamps.

    Thanks again, watch for an updated version coming soon.

  • KaioKaio Posts: 276

    @"Stephen Moraco" said:
    Regarding "make a hint regarding installation"— I, too, am a longtime Mac user. I'm trying to make the app install for us as standard as possible, hence, the drag to applications/ method. I'm reluctant to make this change, but I'll study what you sent and see what you are proposing.

    Only for clarification, the installation to the applications directory is fine. Only how to have the pnut-term-ts script be able to execute, without modifying the PATH variable, should be changed.

  • Stephen MoracoStephen Moraco Posts: 384
    edited 2025-11-12 23:57

    @Kaio, I ran your application. The binary with a PNut term to see what you were seeing in the logging. Here's what I saw:

    You can see that your message (undecorated) is shown in the main window, which interprets CR, LF, PST Commands, etc.
    But in the logger, the control codes are shown, so we can actually see what we are receiving from or sending to the P2. This way, we can actually see ANSI sequences, clear-screens, and similar things being sent from the P2 appear in the log. We see what they are, so you can verify that you're sending them in correctly, even when the display in the main window isn't painting as you expected.

    This is a design choice, not an error. Does this make sense?

  • maccamacca Posts: 947
    edited 2025-11-13 12:14

    I'm trying to use this with Linux and get this error:

    [1241300:1113/092159.842875:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /home/marco/pnut_term_ts/chrome-sandbox is owned by root and has mode 4755.

    The fix is fairly easy as it tells you what to do, however I'm a bit reluctant to have an executable with setuid privileges...

    Anyway, I find very interesting how you handle the debug messages... I think I'll borrow the idea for my IDE... :smile:

    Edit: after fixing the permissions, there is another issue:

    * Propeller Debug Terminal 'pnut-term-ts' (c) 2025 Iron Sheep Productions, LLC.
* Version 0.9.1, Build date: 11/10/2025

pnut-term-ts:  USB  - no PropPlug Serial Devices Found!
pnut-term-ts: Done

    I have an old prop-plug (not sure which version), lsusb reports this:

    Bus 001 Device 017: ID 0403:6001 Future Technology Devices International, Ltd FT232 Serial (UART) IC
  • KaioKaio Posts: 276

    @"Stephen Moraco" said:
    You can see that your message (undecorated) is shown in the main window, which interprets CR, LF, PST Commands, etc.
    But in the logger, the control codes are shown, so we can actually see what we are receiving from or sending to the P2. This way, we can actually see ANSI sequences, clear-screens, and similar things being sent from the P2 appear in the log. We see what they are, so you can verify that you're sending them in correctly, even when the display in the main window isn't painting as you expected.

    This is a design choice, not an error. Does this make sense?

    I didn't notice that the message was also printed on the main window. I was only inspecting the debug logger window as it is used on other tools.
    If it is a design choice to show the message in this way it's fine for me. I was comparing the logs with the output of other tools and not aware of this.

    But with the version I have tested the output in the debug logger window was different from yours. Maybe you have it already fixed.

  • Stephen MoracoStephen Moraco Posts: 384

    @macca said:
    I'm trying to use this with Linux and get this error:

    However, I'm a bit reluctant to have an executable with setuid privileges...

    This is fixed in v0.9.2 and later. Unneeded security was enabled by default. It isn't anymore.

    Anyway, I find very interesting how you handle the debug messages... I think I'll borrow the idea for my IDE... :smile:

    Macca, always feel free to use. It's open source. I'm pleased that you liked it. Having similar features is only a good thing for our community.

    Edit: after fixing the permissions, there is another issue:

    * Propeller Debug Terminal 'pnut-term-ts' (c) 2025 Iron Sheep Productions, LLC.
* Version 0.9.1, Build date: 11/10/2025

pnut-term-ts:  USB  - no PropPlug Serial Devices Found!
pnut-term-ts: Done

    I have an old prop-plug (not sure which version), lsusb reports this:

    Bus 001 Device 017: ID 0403:6001 Future Technology Devices International, Ltd FT232 Serial (UART) IC

    I solved this for VSCode, but I hadn't thought to apply the fix here. This will take me a day or two to noodle... (how best to apply what I did in VSCode.) Do you have another you can use in the meantime?

  • maccamacca Posts: 947

    @"Stephen Moraco" said:
    This is fixed in v0.9.2 and later. Unneeded security was enabled by default. It isn't anymore.

    Good.

    I solved this for VSCode, but I hadn't thought to apply the fix here. This will take me a day or two to noodle... (how best to apply what I did in VSCode.) Do you have another you can use in the meantime?

    I have another but is of same type (purchased together).
    No rush, I can wait for the next release with the fixes, no problem.

  • Stephen MoracoStephen Moraco Posts: 384

    NEW:

    General Fixes - Linux, VSCode, Logging, MacOS
    We're continuing to prepare Pnut-term-ts for direct use by VSCode as a downloader/debugger. This build now allows VSCode to select VendorMatchOnly when using non-Parallax FTDI prop-plug-like devices. It also adds missing features with initial --IDE support.

    Also, fixed all date-time stamps to be in local time.

    v0.9.3:
    - Add -m, --match-vendor-only option to match any FTDI device (VID 0x0403), ignoring product ID

    v0.9.2:
    - Improve main window layout when --IDE mode (used by VSCode)
    - BUGFIX: Use Local time within debug and USB log files, not UTC
    - Linux: Disable Chromium sandbox to prevent Linux runtime error requiring root permissions

    NOTE: As we were doing final testing, we found an issue on Windows. As a result of this late finding, this release is for macOS and Linux/RPi only. We're still working to find and fix this.

    We will officially release a v1.x.x PNut-Term-TS when we've completed the Debugger capability.

    PNut-Term-TS is found at its new Public Repository (repo), while the latest Releases are also found there at the Releases Page

    Issues with PNut-Term-TS can be filed at the repo issues page, or, of course, you can report issues here in this thread.

    This is an early version. I've tried to be comprehensive in my testing, but there's a lot of functionality in this first release. I look forward to hearing about your successful use and any issues you may encounter. Thank you for helping test this early version!

    @macca , @Kaio please try the v0.9.3 build. It now fixes logging, and @macca, both of your issues. Please let me know if these are now resolved issues.

  • maccamacca Posts: 947
    edited 2025-11-18 16:01

    @"Stephen Moraco" said:
    @macca , @Kaio please try the v0.9.3 build. It now fixes logging, and @macca, both of your issues. Please let me know if these are now resolved issues.

    The sandbox issue is still present:

    $ ./bin/pnut-term-ts 
* Propeller Debug Terminal 'pnut-term-ts' (c) 2025 Iron Sheep Productions, LLC.
* Version 0.9.3, Build date: 11/18/2025

[1378401:1118/085738.066099:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /home/marco/pnut_term_ts/chrome-sandbox is owned by root and has mode 4755.

    After fixing the permissions it works, I have to use the -m switch but works, thank you.

    I don't understand the -p parameter, it seems that is ignored or falls back to the auto detection when there is only one Prop-plug connected, I tried -p /dev/ttyUSB1 (non existant) and still falls back to the Prop-plug on /dev/ttyUSB0). Wouldn't be better to display an error instead of falling back to the auto-detected device, even if there is only one adapter ?

    Also, I would like to suggest to use the specified device regardless of whether it is actually a Prop-plug or not. I guess the Prop-plug VID/PID are Parallax own, I think this may cause problems with custom boards that may use FDTI adapters (or not) but don't have the corresponding VID/PID, if I understand correctly the -m switch ignores VID but still check PID and will still fail. In other words, -p should not make additional checks on .

    Also, just noticed that if I have more than one adapter connected and don't specify a device, it say to use File -> Select PropPlug but there is no "Select" menu in File.

    Edit: just realized that the VID/PID are the FTDI default, nevermind, anyway I think that using the specified device without additional checks would be better.

  • Stephen MoracoStephen Moraco Posts: 384

    @macca, good test results. Thank you! I'm looking into all of this, more soon.

  • Stephen MoracoStephen Moraco Posts: 384

    NEW:

    v0.9.4 PropPlug Management + Windows Packages
    Significant update to how we interact with PropPlugs

    Added

    • Added Windows builds, as the issue may be with Windows running under Parallels on macOS.
    • PropPlug device management system with persistent per-device settings
    • PropPlug Management tab in Preferences dialog for viewing/editing known devices
    • Per-device DTR/RTS control line settings (automatically determined by device type with manual override)
    • Project-level PropPlug selection in Preferences
    • Automatic discovery and tracking of new PropPlug devices
    • Friendly name support for PropPlug devices

    Changed

    • Exit with error if -p specifies a device that is not found (previously would silently proceed to UI)
    • Control line (DTR/RTS) now determined per-device instead of global setting
    • Device selection now matches by serial number in addition to path
    • Another attempt at fixing the Chrome Sandbox issue

    NOTE: Our latest findings are that the windows issue is only on arm64 (or arm64 running under Parallels on macOS.) So we've added the Windows builds now. So one or more of us on Windows can determine if it's working and report back.

    We will officially release a v1.x.x PNut-Term-TS when we've completed the Debugger capability.

    PNut-Term-TS is found at its new Public Repository (repo), while the latest Releases are also found there at the Releases Page

    Issues with PNut-Term-TS can be filed at the repo issues page, or, of course, you can report issues here in this thread.

    This is an early version. I've tried to be comprehensive in my testing, but there's a lot of functionality in this first release. I look forward to hearing about your successful use and any issues you may encounter. Thank you for helping test this early version!

    @macca , please try the v0.9.4 build. It now fixes both of your issues. Please let me know if these issues are now resolved.

Sign In or Register to comment.