MecrispCubeFlipper < MecrispCube

%DASHBOARD{ section="dashboard_start" }%
%DASHBOARD{ section="banner"
 image="%PUBURLPATH%/MecrispCube/MecrispCubeFlipper/flipper-header.jpg"
 title="Mecrisp-Cube for the Flipper Zero"
 titlestyle="color:#F00000;"
}%
%DASHBOARD{ section="box_start" title="Intro" width="485" height="300"}%

Instant real-time programming with Forth. 
The [[https://flipperzero.one/][Flipper Zero]] is an excellent portable tool for interaction with access control systems. 
But the display, the buttons, LIPO (2.1 Ah), GPIO, BLE, SD-Card, RTC, etc. make it also an ideal tool for programming on the go.

This page is no longer updated regularly, the current documentation can be found at 
[[https://github.com/spyren/Mecrisp-Cube/tree/Flipper][GitHub]] (Flipper branch on Mecrisp-Cube). Sources are also there.

%IMAGE{"%PUBURLPATH%/MecrispCube/BoardSupportPackageFlipper/flipper-stlink-2.jpg" type="thumb" caption=""}%


%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="550" }%
---+ Features

The standard [[WebHome#Already_done][Mecrisp-Cube features]] like RTOS, Filesystem, USB, etc.

   * 63 !KiB RAM dictionary 
   * 128 !KiB Flash Forth dictionary 
   * 50 !KiB for C code 
   * Internal Flash drive 0:, 384 !KiB (for details see [[MicroSdBlocks#Built_in_flash][Nucleo]])
   * Serial console UART / USB CDC / BLE
   * microSD drive 1: 
   * Control (5-button joystick, Back button, Reboot)
   * LCD display 128x64 pixel
   * RGB LED
   * Power (LIPO charger and fuel gauge)
   * Vibration Motor
   * GPIO

Not supported yet:
   * Sub-1 GHz Transceiver
   * 125kHz RFID
   * NFC
   * Infrared Transceiver
   * iButton
   * Buzzer/Speaker

For more BSP details see BoardSupportPackageFlipper.

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="800" }%
---+  Getting Started

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

---++ Prerequisites

   * [[https://flipperzero.one/][Flipper Zero]] with !STM32WB55 MCU (Cortex ARM M4) runs at a 32 MHz (the Bluetooth stack runs on a Cortex ARM M0+ core). 
   * Optional: [[https://docs.flipper.net/development/hardware/devboard-stlinkv3][ST-Link V3 Developer Board]] or you can build your own e.g. with a [[https://www.st.com/en/development-tools/stlink-v3mini.html][STLINK-V3MINI]] and some cables, see BoardSupportPackageFlipper#JTAG_SWD_Adaptor
   * 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)
      * for details see TerminalIO
   * !STM32CubeProgrammer or [[https://docs.flipper.net/qflipper][qFlipper]]

---++ Flash the Mecrisp-Cube Firmware

Flash the Mecrisp-Cube [[https://github.com/spyren/Mecrisp-Cube/raw/Flipper/Release/MecrispCubeFlipper.bin][binary]] (=MecrispCubeFlipper.bin=) or better the [[https://github.com/spyren/Mecrisp-Cube/raw/Flipper/sdcard/boot/MecrispCubeFlipperFS.bin][fs-util-binary]] (=MecrispCubeFlipperFS.bin=) to the Flipper Zero. Using the built-in USB DFU bootloader, see also [[https://docs.flipper.net/basics/firmware-update/firmware-recovery][firmware recovery]].

   1. Press and hold the OK and the back buttons for 30 s (you should see a blank screen)
   1. Connect the Flipper Zero USB to the PC
   1. Program the binary (=MecrispCubeFlipper.bin= or =MecrispCubeFlipperFS.bin=) with 
      A. the !STMCubeProgrammer (select USB Device), for Linux %BR%
         =sudo /usr/local/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32CubeProgrammer=
      A. or the [[https://docs.flipper.net/qflipper][qFlipper]] with _install from file_
   1. Reboot your device by pressing and holding the left and back buttons 


---++ Switch On/Off, Buttons, LED

   $ *Switch Off*: press and hold the BACK-Button for 5 s or type in the command =halt=
   $ *Switch On*: press the BACK-Button 
   $ *Reset*: press and hold the BACK- and LEFT-Button


---+++ Special Functions on Startup 
[[TerminalIO#USB_CDC_Serial_Communication_API][USB-CDC]] is the default console.
   $ *Button UP*: [[TerminalIO#BLE_Cable_Replacement_Serial_Com][CRS]] (Bluetooth Cable Replacement Service) is standard console
   $ *Button DOWN*: [[TerminalIO#UART_Serial_Communication_API][UART]] is standard console
   $ *Button RIGHT*: do not include =0:/etc/rc.local=

---+++ RGB LED as Status Indicator
The RGB LED  displays the status
   $ *dimmed Green*: LIPO fully charged
   $ *dimmed Red*: LIPO charging
   $ *dimmed Blue*: BLE connected
   $ *flashing Red*: "disk" (serial flash or SD) write operation
   $ *flashing Yellow*: "disk" (serial flash or SD) read operation



---++ Use the Terminal (USB CDC)

Connect the Flipper Zero USB to the PC. Start the terminal emulator application on the PC. 
Check for the serial communication port (e.g. for Linux =/dev/ttyACM0=).
I set the putty terminal configuration to 

   * Implicit CR in every LF 
   * Local echo: Auto
   * Local line editing: Auto
   * Keyboard Backspace: Control-H
   * Keyboard Function: Keys VT100
   * Remote character set: CP850

You should see something like this in your terminal:
<pre>
Mecrisp-Stellaris RA 2.5.4 by Matthias Koch.

Mecrisp-Cube 1.5.0 for STM32WB Flipper, 63/128  KiB RAM/FLASH dictionary (C) 2023 peter@spyr.ch
  * Firmware Package STM32Cube FW_WB V1.17.3, USB-CDC, BLE Stack 5.3 (C) 2023 STMicroelectronics
  * CMSIS-RTOS V2 FreeRTOS wrapper, FreeRTOS Kernel V10.3.1 (C) 2020 Amazon.com
  * FatFs for internal flash and microSD - Generic FAT fs module  R0.12c (C) 2017 ChaN
include 0:/etc/rc.local
</pre>

Use the interpreter:
<pre>
<b>23 5 / .[CR]</b> 4  ok.
</pre>

Type in your first Forth program:
<pre>
<b>: hello ." World" ;[CR]</b>  ok.
<b>hello[CR]</b> World ok.
</pre>


---++ Additional Tools and Local Filesystem
Populate a microSD with the contents of [[https://github.com/spyren/Mecrisp-Cube/tree/Flipper/sdcard][sdcard]]. Put the microSD into the uSD Card slot and reset or power cycle the board.

The directory should look like this:
<pre>
<b>ls -l 1:[CR]</b>
drw-         0 2021-04-18T18:12:38 boot
drw-         0 2021-03-21T18:47:52 etc
drw-         0 2021-03-21T18:47:54 fsr
drw-         0 2021-03-21T18:47:54 home
drw-         0 2021-03-21T18:47:56 man
-rwa      7219 2021-01-08T19:42:36 README.md
ok.
</pre>

You can use the local CLI commands like =mkfs=, =mkdir= and =cp= to create a filesystem on the serial flash and fill it with files and folders. But this is tedious job because I haven't yet implemented a recursive copy for !MecrispCube. But there is prepared disk image 
(for details see MicroSdBlocks#Serial_Flash) on microSD and the tool =dd=. You can copy the disk image to the drive 0: (this takes about 8 Minutes):
<pre>
<b>dd 1:/boot/fd-384KiB.img 0:[CR]</b>
 ok.
<b>mount 0:[CR]</b>
 ok.
<b>ls 0:[CR]</b>
man                     fsr                     README.md               boot
etc                     home
 ok.
</pre>

The Mecrisp have some tools bundled in its distribution e.g. assembler, disassembler, dump, float. I put those tools and some more into the folder =/fsr=. With the "init.fs script" I compile my favorite ones into the flash directory (if you use the [[https://github.com/spyren/Mecrisp-Cube/raw/Flipper/sdcard/boot/MecrispCubeFlipperFS.bin][fs-util-binary]] binary, these tools are already compiled in):
<pre>
<b>compiletoflash[CR]</b>  ok.
<b>include /etc/init.fs[CR]</b>
init.fs Loading started
RAM Dictionary: 392991 KiB
utils.fs loading ...
conditional.fs loading ...
dump.fs loading ...
disassembler-m3.fs loading ...
float.fs loading ...
threads.fs loading ...
RAM Dictionary: 392981 KiB
init.fs finished  ok.
</pre>

For example, the word disassember is available now:
<pre>
<b>see dump[CR]</b>
080405F0: B500  push { lr }
080405F2: F7C2  bl  08002A3E  --> cr
080405F4: FA24
080405F6: CF08  ldmia r7 { r3 }
080405F8: F013  ands r2 r3 #F
080405FA: 020F
080405FC: F847  str r3 [ r7 #-4 ]!
080405FE: 3D04
08040600: 2A00  cmp r2 #0
08040602: D000  beq 08040606
08040604: 3610  adds r6 #10
08040606: CF08  ldmia r7 { r3 }
08040608: F847  str r6 [ r7 #-4 ]!
</pre>

---++ Flash the original Flipper Firmware

If you want to go back to the original firmware, do the following

   1. Press and hold the OK and the back buttons for 30 s (you should see a blank screen)
   1. Connect the Flipper Zero USB to the PC
   1. Flash the Flipper firmware with [[https://docs.flipper.net/qflipper][qFlipper]] _REPAIR_
   1. Reboot your device by pressing and holding the left and back buttons 

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="800" }%

---+ Installing Development Environment

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 --branch Flipper https://github.com/spyren/Mecrisp-Cube</b>
Klone nach 'Mecrisp-Cube' ...
remote: Enumerating objects: 1157, done.
remote: Counting objects: 100% (1157/1157), done.
remote: Compressing objects: 100% (620/620), done.
remote: Total 3183 (delta 720), reused 934 (delta 525), pack-reused 2026
Empfange Objekte: 100% (3183/3183), 41.60 MiB | 6.96 MiB/s, Fertig.
Löse Unterschiede auf: 100% (2100/2100), 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 =MecrispCubeFlipper.ioc= file:
<pre>
Project -> Generate Code 
</pre>

Restore changed source files
<pre>
$ git status
{list of changed files}
$ git restore {files to restore} 
</pre>


Select the Build Configuration (Debug if you want to debug the project) and Build the project:
<pre>
Project -> Build Configurations -> Set Active -> Debug/Release 
Project -> Build Project
</pre>


%DASHBOARD{ section="box_end" }%


%DASHBOARD{ section="dashboard_end" }%


-- %USERSIG{PeterSchmid - 2023-10-18}%

<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />This work by <a xmlns:cc="http://creativecommons.org/ns#" href="http://spyr.ch" property="cc:attributionName" rel="cc:attributionURL">Peter Schmid</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.

Sitronix ST7567
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
jpg	flipper-header.jpg	r1	manage	47.3 K	2023-12-02 - 09:42	PeterSchmid
This topic: MecrispCube > WebHome > MecrispCubeFlipper
Topic revision: r20 - 2023-12-31 - PeterSchmid