Mecrisp-Stellaris Forth: Creating a New UF2

5 minute read
, ,

Where I describe how to edit, assemble, link, and UF2 Mecrisp-Stellaris for the RP2040 and specifically, the Adafruit Feather RP2040 and Pico/Pico W.

Sources

Updated

Now that I have gone through over 20 assemble/link/UF2 cycles, I have a better understanding of what needs to be done, specific to macOS Big Sur.

  1. Follow the comments as to “The process…” particularly as it regards getting macOS to run the ARM toolchain. This has to happen first.
  2. Reduce the complexity of Mecrisp-Stellaris. Matthias has performed a remarkable job in getting so many processors to run this version of Forth. This achievement needs to be applauded and appreciated. That said, unless you are running a significant number of versions, delete those that you aren’t using. In my case, I used the 128k/128K version to determine what was required for the RP2040. This is my base moving forward. Note In reviewing version 2.6.5, the new model is 128K/128K from Matthias.
  3. Terry’s directions below (Understatement), however, its even easier. If you have performed point 2, then the solution is simply:
cd mecrisp-stellaris-x.x.x
./release
# put board in USB mode, drag/drop UF2 file and go to work

Really important things to do: (Instructions below)

  1. Implement Terry’s improvement on Stair-Stepping by adding a CR to the OK prompt.
  2. Implement Piotr’s improvement on uploading

Understatement

(With apologies to Terry Porter) Terry’s page above as Mecrisp Patching was extremely helpful and contained this nugget. Which is true, however, it takes a little bit of additional work to get there with the RP2040.

  • cd mecrisp-stellaris-x.x.x/mecrisp-stellaris-source
  • ./assemble
  • ./tidyup
  • The new image is now available in mecrisp-stellaris-x.x.x/your-mcu/mecrisp-stellaris-your-mcu.bin (except Linux)

Let the journey begin…

The process (and pitfalls) on macOS

Note As of April 5, 2023, much of the problems described below seem to be rectified. I will leave the notes as is, as its better to over-explain than remove information which might be helpful. I’ve found in both my Pico C SDK work and this Forth exercise, that the ARM toolchain installation works much better, now. I recommend reviewing these instructions as to how to install the ARM toolchain and associated tools.

(DEPRECATED, see note above, first.)

In order to assemble the ARM code, one must have the [GCC ARM toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm). As I have I have macOS, I chose to install it using homebrew as in
```bash
brew install gcc-arm-embedded
```

I then attempted to ./assemble and was faced with an incredible number of "macOS malware messages". Long story, short:
```bash
# find the offending ARM applications, for example...
which arm-none-eabi-ld
/opt/homebrew/bin//arm-none-eabi-ld
# using Finder Shift-CMD-G /opt/homebrew/bin/
# right-click on the offending app, select Open and answer the question "macOS cannot verify the developer of “arm-none-eabi-gcc”. Are you sure you want to open it?"  click on Open.
# You will need to do this several times, I didn't capture the specific ones I required
# I suggest you run to confirm each command works, replacing the app below with the one in question
arm-none-eabi-ld --help
# if it displays help contents for the app named, you are good to go
```
(*One more helpful hint, would be to remove all but one of the processor-specific assemble instructions in ./assemble and run it. See #2 in Updated above.*)

Another app which isn't on macOS is md5sum. And if md5sum doesn't run, then you have problems. I replaced md5sum with md5 in the ./assemble program and I believe it works. *The MD5sum issue was for processors other than the RP2040. Do this only if you notice you are having an issue with MD5sum, not being found.*

Now you have the right .bin files, now you need the .uf2 file to perform the simple drag-drop operation of loading Forth on your board.

In this case, the RP2040 has a second program to run called release and it is in:
```bash
mecrisp-stellaris-2.5.9a/rp2040-ra/
```
Run release and it will create the required UF2 file.

A note regarding command-line

  • I use Sublime Text (ST3) as my editor and when I’m on the command-line, “st” invokes the ST3.
  • I’m using macOS Big Sur and use applications installed by Homebrew. If your system is different, your commands may differ.

Important Note!

If you had added via .init the ability to automatically add a CR to every OK (to fix stair-stepping), you must delete it if you are going to use the above method of adding via the compiled code AND the below method of checking for “ok.\r\n”. For if you do both, you will end up with “OK.\r\r\n” which will cause a compilation error!

An Example - Fix Stairstepping

Using Terry’s suggestion let’s fix the problem and attempt to create a new uf2 image.

1. Edit the file

Open mecrisp-stellaris-source/common/datastackandmacros.s and change two lines by adding a \r : (‘st’ opens by editor, use the editor you feel comfortable with)

st mecrisp-stellaris-source/common/datastackandmacros.s 
# Option-CMD-f (Find/Replace)
\Meldung\n
\Meldung\r\n
# 5 lines are changed

2. One step command to assemble/link/UF2 code, very, very nice!

cd mecrisp-stellaris-x.x.x/
./release

3. Download uf2 file to board and test.

It worked!!!

Example - Speed Up Serial Port in Python

Source: Piotr Wiszowaty Note

“I’ve written the following little script to send programs. The script waits for an “ok.” before sending consecutive lines so the transmission is somewhat faster than when using a fixed delay per line.”

Uses: picocom -b 115200 /dev/ttyACM0 –imap lfcrlf,crcrlf –omap delbs,crlf –send-cmd “./xfr.py”

#!/usr/bin/env python3
# tested with Pico W and dict0.fs and works at 921600
import sys
import serial


ser = serial.Serial(port='/dev/cu.usbserial-0001', baudrate=921600)
for line in open(sys.argv[1], "rt"):
    ser.write(str.encode(line))
    r = ser.readline()
    print(str(r))
    if not r.endswith(b'ok.\n'):
        sys.exit(1)

The above version works extremely well and could be a finished product. Great job, Piotr! However, Piotr continued to work on it and released this version.

I did make the change above which changed the response from “ok.\n” to “ok.\r\n”, this needs to be changed in xfr as well (line 69) as in:

if not response.endswith("ok.\r\n"):

Not working: Enable Color Output

Color Terminal Error Messages

For the color switch, add “ .equ color,1 “ to your .s file in the mecrisp-stellaris-source/your-cpu directory as below and rebuild your kernel.

@ ————————————————————————
@ Switches for capabilities of this chip
@ ————————————————————————
.equ color,1

cd mecrisp-stellaris-source/rp2040-ra
st mecrisp-stellaris-pico-core.s
# Add line under @ Switches for...
.equ color, 1
# close file
cd ../..

Comments powered by Talkyard.