(r5) MecrispCube < Cosmac

Tags: view all tags
%DASHBOARD{ section="dashboard_start" }%
%DASHBOARD{ section="banner"
 image="%PUBURLPATH%/Cosmac/ForthSTM32WB/nucleo-header.jpg"
 title="Mecrisp-Cube, Forth for the !STM32 Ecosystem"
 titlestyle="color:#F00000;"
}%
%DASHBOARD{ section="box_start" title="Intro" width="485" height="300"}%
Mecrisp-Stellaris Forth for the STM32 Cube ecosystem. 

Forth is an interactive and extensible language, with built-in lexical analysis (tokenizer, parser) and compiler, needs less than 20 !KiB Flash and 4 !KiB RAM, unbelievable for a self-contained system. 

Forth is perfect for embedded systems where some sort of user interactivity like CLI and extensibility (at runtime) are needed. 

C & Forth in the [[MecrispCube#21st_Century_Forth][21st Century]]. C and Forth are both about 50 years old. To combine the strength of this two worlds results in powerful system that outperforms other much newer systems like Python.

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start" title="Contents" width="460" height="300"}%
%TOC%
%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="700" }%
---+  Getting Started

These instructions will get you a copy of the project up and running on your local 
machine (STM32 Nucleo board) for development and testing purposes. 

---++ Prerequisites

   * [[https://www.st.com/en/evaluation-tools/p-nucleo-wb55.html][STM32WB Nucleo Board]] - The highly affordable STM32 Nucleo boards allow anyone to try out new ideas and to quickly create prototypes with any STM32 MCU. The STM32 Nucleo boards integrate an ST-Link debugger/programmer, so there is no need for a separate probe.
   * Terminal emulator application for PC, e.g.: 
      * [[http://www.putty.org/][PuTTY]] - Windows and Linux
      * [[http://en.sourceforge.jp/projects/ttssh2/][Tera Term]] - Windows
      * [[http://realterm.sourceforge.net/][Realterm]] - Windows
      * minicom, microcom, screen - Linux
      * Use the built in Eclipse console (but no LF)
 
Flash the Mecrisp-Cube [[https://github.com/spyren/Mecrisp-Cube/blob/master/Release/minimal.bin][binary]] to the Nucleo Board.

   1. Connect the Nucleo Board USB ST-LINK to the PC
   2. Copy [[https://github.com/spyren/Mecrisp-Cube/blob/master/Release/minimal.bin][binary]] (=minimal.bin=) to the USB mass storage NODE_WB55RG

Start the terminal emulator application on the PC. 
Check for the serial communication port (e.g. for Linux =/dev/ttyACM0=) 
and set the speed to 115200 baud. 
I set the putty terminal configuration to 

   * Implicit CR in every LF 
   * Local echo: Auto
   * Local line editing: Auto

<pre>
Mecrisp-Stellaris 2.5.2 for STM32WB55 by Matthias Koch
<b>23 5 / .[CR]</b> 4  ok.
<b>: hello ." World" ;[CR]</b>  ok.
<b>hello[CR]</b> World ok.
</pre>

---++ Installing

A step by step series of examples that tell you how to get a development env running

Install the IDE [[https://www.st.com/en/development-tools/stm32cubeide.html][STM32CubeIDE]], 
it is Eclipse and GCC based. 
[[https://www.st.com/en/development-tools/stm32cubemx.html][STM32CubeMX]]
is included in the IDE, you need a stand alone installation only if 
you do not want to use the !STM32CubeIDE.  

Get the sources from github:

<pre>
psi@homer:~> <b>git clone https://github.com/spyren/Mecrisp-Cube</b>
Klone nach 'Mecrisp-Cube' ...
remote: Enumerating objects: 106, done.
remote: Counting objects: 100% (106/106), done.
remote: Compressing objects: 100% (71/71), done.
remote: Total 106 (delta 33), reused 106 (delta 33), pack-reused 0
Empfange Objekte: 100% (106/106), 938.96 KiB | 2.39 MiB/s, Fertig.
Löse Unterschiede auf: 100% (33/33), Fertig.
</pre>

Import the project into the IDE:

<pre>
File -> Import -> General -> Existing Projects into Workspace -> Select root directory
Copy project into workspace
Browse to Mecrisp-Cube directory
</pre>

Generate code from the !STM32CubeMX =minimal.ioc= file:

<pre>
Project -> Generate Code 
</pre>

Select the Build Configuration (Debug if you want to debug the project) and Build the project:


<pre>
Project -> Build Configurations -> Set Active -> Debug/Reelease 
Project -> Build Project
</pre>

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="450" }%
---+ !STM32WB Nucleo Board

<img src="%PUBURLPATH%/Cosmac/ForthSTM32WB/stm32wb-nucleo.jpg" alt="stm32wb-nucleo.jpg" width="426" height="331" />


   * https://www.st.com/en/evaluation-tools/p-nucleo-wb55.html
   * [[https://www.st.com/content/ccc/resource/technical/layouts_and_diagrams/schematic_pack/group0/e3/a0/c8/d8/8d/da/4f/43/mb1355_schematics/files/MB1355-WB55RGV-C02_schematic.pdf/jcr:content/translations/en.MB1355-WB55RGV-C02_schematic.pdf][Schematic Nucleo Board MB1355]]
   * [[https://www.st.com/content/ccc/resource/technical/layouts_and_diagrams/schematic_pack/group0/6f/4a/27/3b/7d/c4/43/f8/mb1293_schematics/files/MB1293-WB55CGU-C02_schematic.pdf/jcr:content/translations/en.MB1293-WB55CGU-C02_schematic.pdf][Schematic Nucleo Dongle MB1293]]

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="200" }%
---+ Built With

   * [[https://www.st.com/en/development-tools/stm32cubeide.html][STM32CubeIDE]] is an all-in-one multi-OS development tool, which is part of the STM32Cube software ecosystem. The IDE is used for development, GCC tools are included.
   * [[https://www.st.com/en/development-tools/stm32cubemx.html][STM32CubeMX]] is a graphical tool that allows a very easy configuration of STM32 microcontrollers and microprocessors, as well as the generation of the corresponding initialization C code for the Arm® Cortex®-M core or a partial Linux® Device Tree for Arm® Cortex®-A core), through a step-by-step process. 
   * [[https://www.st.com/en/development-tools/stm32cubeprog.html][STM32CubeProg]] is an all-in-one multi-OS software tool for programming STM32 products. the Java GUI does not work for me, but the CLI does. See [[https://wiki.st.com/stm32mpu/wiki/STM32CubeProgrammer][STM Wiki]]

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="700" }%
---+ Flash Mecrisp-Cube to the Target

Alternate ways to flash Mecrisp-Cube to the target.


---++ Nucleo Board

Connect Nucleo's ST-LINK USB to you PC. Erase the flash e.g. by !openOCD, we use 768 !KiB %ICON{right}% 192 sectors. 
<pre>
$ <b>telnet localhost 4444</b>
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> <b>reset init</b>
Unable to match requested speed 500 kHz, using 480 kHz
Unable to match requested speed 500 kHz, using 480 kHz
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08003aae msp: 0x20000430
> <b>flash erase_sector 0 0 192</b>
erased sectors 0 through 192 on flash bank 0 in 4.583453s
> <b>flash write_image mecrisp-stellaris-stm32wb55.hex</b>
device idcode = 0x20016495 (STM32WB5x - Rev: 2.1)
flash size = 1024kbytes
flash mode : single-bank
Padding 4 bytes to keep 8-byte write size
block write succeeded
wrote 15404 bytes from file mecrisp-stellaris-stm32wb55.hex in 0.329747s (45.620 KiB/s)

> <b>shutdown</b>
shutdown command invoked
Connection closed by foreign host.
</pre>


---++ USB Dongle

The USB Dongle does not have a ST-Link interface, but the !STM32WB has a built-in boot-loader. This bootloader works over USB. As programmer I use the CLI from the [[https://www.st.com/en/development-tools/stm32cubeprog.html][STM32CubeProg]] package. 

<pre>
$ <b>alias cubepgmcli='/opt/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_Programmer_CLI'</b>
$ <b>cubepgmcli -c port=USB1 -ob displ</b>

</pre>


BTW you can flash the Nucleo Board in the same way. 


---++ Update BLE Stack

You can find the BLE Stack and FUS in 
[[https://www.st.com/en/embedded-software/stm32cubewb.html][STM32CubeWB]], in the directory =Projects/STM32WB_Copro_Wireless_Binaries=.

Using USB_USER and the built-in bootloader (activate with jumper between CN7.5 and CN7.7)
<pre>
$ <b>alias cubepgmcli='/opt/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_Programmer_CLI'</b>
STM32Cube_FW_WB_V1.4.0/Projects/STM32WB_Copro_Wireless_Binaries> <b>cubepgmcli -c port=USB1 -fwdelete</b>
STM32Cube_FW_WB_V1.4.0/Projects/STM32WB_Copro_Wireless_Binaries> <b>cubepgmcli -c port=USB1 -fwupgrade stm32wb5x_FUS_fw.bin 0x080EC000 firstinstall=0</b>
STM32Cube_FW_WB_V1.4.0/Projects/STM32WB_Copro_Wireless_Binaries> <b>cubepgmcli -c port=USB1 -fwupgrade stm32wb5x_BLE_Stack_fw.bin 0x080CB000 firstinstall=1</b>
</pre>

Using ST-LINK (here to show the option bytes, =SBRV : 0x32C00= means start address 4 * SBRV + 0x08000000 = 0x080CB000, 3D000 means there is no stack):
<pre>
psi@homer:~/Dropbox/wbForth/CubeWB> <b>cubepgmcli -c port=SWD -ob displ</b>
      -------------------------------------------------------------------
                        STM32CubeProgrammer v2.3.0                  
      -------------------------------------------------------------------

ST-LINK SN  : 066BFF313335415043141250
ST-LINK FW  : V2J35M26
Voltage     : 3,21V
SWD freq    : 4000 KHz
Connect mode: Normal
Reset mode  : Software reset
Device ID   : 0x495
Device name : STM32WBxx
Flash size  : 1 MBytes
Device type : MCU
Device CPU  : Cortex-M0+/M4


UPLOADING OPTION BYTES DATA ...

  Bank          : 0x00
  Address       : 0x58004020
  Size          : 104 Bytes

[==================================================] 100% 


OPTION BYTES BANK: 0

   Read Out Protection:

     RDP          : 0xAA (Level 0, no protection) 

   BOR Level:

     BOR_LEV      : 0x0 (BOR Level 0 reset level threshold is around 1.7 V) 

   User Configuration:

     nBOOT0       : 0x1 (nBOOT0=1 Boot from main Flash) 
     nBOOT1       : 0x1 (Boot from code area if BOOT0=0 otherwise system Flash) 
     nSWBOOT0     : 0x1 (BOOT0 taken from PH3/BOOT0 pin) 
     SRAM2RST     : 0x0 (SRAM2 erased when a system reset occurs) 
     SRAM2PE      : 0x1 (SRAM2 parity check disable) 
     nRST_STOP    : 0x1 (No reset generated when entering the Stop mode) 
     nRST_STDBY   : 0x1 (No reset generated when entering the Standby mode) 
     nRSTSHDW     : 0x1 (No reset generated when entering the Shutdown mode) 
     WWDGSW       : 0x1 (Software window watchdog) 
     IWGDSTDBY    : 0x1 (Independent watchdog counter running in Standby mode) 
     IWDGSTOP     : 0x1 (Independent watchdog counter running in Stop mode) 
     IWDGSW       : 0x1 (Software independent watchdog) 
     IPCCDBA      : 0x0  (0x0) 

   Security Configuration Option bytes:

     ESE          : 0x1 (Security enabled) 
     SFSA         : 0xCB  (0xCB) 
     FSD          : 0x0 (System and Flash secure) 
     DDS          : 0x1 (CPU2 debug access disabled) 
     C2OPT        : 0x1 (SBRV will address Flash) 
     NBRSD        : 0x0 (SRAM2b is secure) 
     SNBRSA       : 0xF  (0xF) 
     BRSD         : 0x0 (SRAM2a is secure) 
     SBRSA        : 0xA  (0xA) 
     <em>SBRV         : 0x32C00  (0x32C00)</em>

   PCROP Protection:

     PCROP1A_STRT : 0x1FF  (0x8000FF8) 
     PCROP1A_END  : 0x0  (0x8000008) 
     PCROP_RDP    : 0x1 (PCROP zone is erased when RDP is decreased) 
     PCROP1B_STRT : 0x1FF  (0x8000FF8) 
     PCROP1B_END  : 0x0  (0x8000008) 

   Write Protection:

     WRP1A_STRT   : 0xFF  (0x807F800) 
     WRP1A_END    : 0x0  (0x8000000) 
     WRP1B_STRT   : 0xFF  (0x807F800) 
     WRP1B_END    : 0x0  (0x8000000)
</pre>


%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="400" }%
---+ USB, BLE and other Middlewares

!STM32WB Forth without BLE, USB, Filesystems, RTOS etc. is not complete, to build this by myself from the scratch overwhelms me. I would like to go the reverse way and use the STM tools like !CubeIDE, HAL, !CubeMX and integrate the Mecrips Forth into it. Forth as an interactive extension for the STM ecosystem. Mecrisp Forth running as a CMSIS-RTOS thread.

   * USB-CDC for serial communication. Redirect console IO like =usb_emit=, =usb_key=
   * USB-MSC to make it possible to read and write blocks or include source files. INCLUDE vs BLOCK? [[https://www.complang.tuwien.ac.at/forth/gforth/Docs-html/Forth-source-files.html#Forth-source-files][Forth source files]]
   * Command line editing like [[https://www.complang.tuwien.ac.at/forth/gforth/Docs-html/Command_002dline-editing.html#Command_002dline-editing][Gforth]], buffered console IO.
   * BLE vSP profile is proprietary, there is no standard serial communication profile. Redirect console IO like =ble_emit=, =ble_key=
   * Calling HAL and other C functions
   * Calling forth words form C (prefix forth_ ?)
   * Event driven programming like LAIRD's smartBASIC, WAITEVENT ONEVENT. 
   * BLE GATT (Characteristics, Services, Profiles)
   * Support for the floating point unit, CMSIS-DSP

   * https://stackoverflow.com/questions/8422287/how-to-call-c-functions-from-arm-assembly
   * https://static.docs.arm.com/ihi0042/g/aapcs32.pdf

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="400" }%
---+ 21st Century Forth
http://www.forth.org/svfig/21st.html


---++ What's good about Forth
   * _small_
   * _easy to understand_
   * _extendable_
   * _adaptable to programmer_
   * _interactive_
   * open compiler/interpreter
   * simple architecture
   * source code available
   * helpful in learning about hardware and software

---++ What's bad about Forth
   * NIH (not invented here)
   * _cryptic reverse polish notation_ 
   * difficult to learn
   * documentation sometimes lacking or unavailable
   * _unconventional syntax_
   * _no linkage with other languages_
   * getting more complex
   * _lack of data typing_
   * source (proprietary protection problem)

---++ What 21st Century Forth should be
   * _work in embedded applications_
   * work with networks and Internet
   * work with large systems (operating systems, graphic user interface)
   * be able to be taught to programmers and engineers

---++ What Forth needs
   * reuseable binaries (other languages & headers)
   * more/better/useable libraries
   * safety (year 2000)
   * better documentation
   * more examples
   * workable standards
   * better gui/window editor w/more information
   * package confidence
   * more debugger integration
   * _works with newer CPUs_ (embedded systems, MCU)
   * publications
   * big daddy $$$
   * educational opportunities
   * _more types of multitasking/multiprocessing_ pre-emtive multitasking

---++ 21st Century Forth desires and vision
   * real/virtual machines/core
   * scriptmaking (language to taste)
   * real compile toggle (memory, speed, optimization)
   * integratable applications
   * "browser" environment *
   * environments (such as voice) interpretation (fuzzy)
   * pda's bases, smart cards, etc
   * servants (robots, etc) applications 


%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="400" }%
---+ Copyright
---++ Authors

   * *Matthias Koch* - _Forth on ARM Cortex M0/M4_ - [[http://mecrisp.sourceforge.net/][Mecrisp Stellaris]]
   * *Peter Schmid* - _Initial work_ - [[https://github.com/spyren/Mecrisp-Cube][Mecrisp-Cube]]

---++ License

This project *Mecrsip-Cube* is free software: you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

*Mecrsip-Cube* is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with *Mecrsip-Cube*. If not, see http://www.gnu.org/licenses/.

---++ Acknowledgments

   * http://mecrisp.sourceforge.net/ Original Mecrisp project, *Matthias Koch*
   * https://mecrisp-stellaris-folkdoc.sourceforge.io/ Mecrisp Stellaris Unofficial UserDoc, *Terry Porter*
   * https://jeelabs.org/article/1612b/ Forth in 7 easy steps, *Jean-Claude Wippler*
   * https://forth-ev.de/ Forth-Gesellschaft e.V.
   * https://forth-ev.de/wiki/res/lib/exe/fetch.php/vd-archiv:4d2015-arm.pdf ARM-Sonderheft


%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="dashboard_end" }%


-- %USERSIG{PeterSchmid - 2019-12-29}%
Topic revision: r5 - 2020-02-19 - PeterSchmid