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: 387
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,175

    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: 387

    @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: 387
    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: 950
    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: 387

    @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: 950

    @"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: 387

    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: 950
    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: 387

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

  • Stephen MoracoStephen Moraco Posts: 387

    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.

  • maccamacca Posts: 950

    @"Stephen Moraco" said:
    @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.

    The sandbox issue is not resolved:

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

[1463872:1120/152327.012930: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.

    Out of curiosity, I tried the linux-arm64 version on a Raspberry Pi and it doesn't have the same problem with the sandbox, it works without touching the permissions, I'm starting to think that there may be something with my Ubuntu 24.04 settings.

    Using the -p parameter with a non-esistant device it exits with an error (good), however seems that the device is still checked for VID/PID, I need to use the -m parameter even with -p (I think would be better to not check the device VID/PID in this case).

  • maccamacca Posts: 950

    @macca said:
    Out of curiosity, I tried the linux-arm64 version on a Raspberry Pi and it doesn't have the same problem with the sandbox, it works without touching the permissions, I'm starting to think that there may be something with my Ubuntu 24.04 settings.

    Aha... looks like the effect of Ubuntu AppArmor, I have the same problem with the Arduino IDE (wasn't using it for a while), it too uses the Electron framework for the UI.
    Here is the Github issue https://github.com/arduino/arduino-ide/issues/2429 in case you want to look at the discussion.

    For me, I'm fine with adjusting the permissions.

  • Stephen MoracoStephen Moraco Posts: 387

    @macca said:
    Using the -p parameter with a non-esistant device it exits with an error (good), however seems that the device is still checked for VID/PID, I need to use the -m parameter even with -p (I think would be better to not check the device VID/PID in this case).

    So far, this is by design. I suppose it wouldn't be too hard to marry the -m behavior with the normal flow. Look for all FTDI devices, then qualify with Parallax to know that it uses DTR... and let RTS be a manual adjustment to then "known" device. Thoughts?

    I'm so glad to know that AppArmor causes the Sandbox issue. I hadn't been able to see any working cases in my test systems. ;-)

    I'll document the adjustment needed on Linux machines running AppArmor. Thanks for the link to the issue.

  • Stephen MoracoStephen Moraco Posts: 387

    NEW:

    v0.9.5: Tiny fixes in support of use with VSCode

    Added

    • Baud rate status indicator in main window status bar (both IDE and Standard modes)

    Fixed

    • Case-insensitive device serial number matching for -p/--plug option
    • Device selection now accepts serial numbers in any case (e.g., p6yh4spg, P6yh4spg, P6YH4SPG)

    This is the final update enabling use of pnut-term-ts with our Spin2 VSCode extension v2.5.0, which is now also released.

  • maccamacca Posts: 950

    @"Stephen Moraco" said:

    @macca said:
    Using the -p parameter with a non-esistant device it exits with an error (good), however seems that the device is still checked for VID/PID, I need to use the -m parameter even with -p (I think would be better to not check the device VID/PID in this case).

    So far, this is by design. I suppose it wouldn't be too hard to marry the -m behavior with the normal flow. Look for all FTDI devices, then qualify with Parallax to know that it uses DTR... and let RTS be a manual adjustment to then "known" device. Thoughts?

    Well, my concept is that the command line arguments overrides all default or configured options. If I specify -p /dev/ttyUSB0 I expect the program use that device regardless if it is an FTDI device or not, if the device is already configured then use the settings, if not use the defaults. Other command line parameters like --rts (or --dtr) overrides the default or configured settings, as well as debugBaud or anything that may be configured. Priority should be command line -> configuration -> default.

    The -m parameter is not really a problem, I could point out that I have prop-plug that is not dected as such without the -m parameter, but I can live with it. :smile:
    The main problem may be that it is limiting the usable devices, AFAIK, currently, there is no way to use a serial adapter that is not FTDI (a sort of "vendor lock-in" from a certain point of view). What if someone uses a CH340 adapter ? Or something completely different like a dedicated microcontroller ? I built a serial adapter with a PIC microcontroller, I'm using it mainly with a P1 but it also works with the P2.

    In my IDE I don't have access to USB details, I can't filter by device type (but I don't think I would have done that anyway), I had to add a blacklist to exclude certain devices from the auto-detection process to prevent unwanted access to devices detected by the OS as serial devices but actually not serial adapters (like, if I'm not mistaken, some Bluetooth audio devices).

    Of course, checking the device type allows to use the serial number instead of the device name, this is certainly an advantage, maybe the best of both worlds would be to check the device type as a default for auto-detection or if the -p parameter is not a device pathname.

Sign In or Register to comment.