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: 381
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,142

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

    @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: 381
    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: 946
    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: 381

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

    @"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.

Sign In or Register to comment.