(r24) TerminalIO < MecrispCube

Tags: view all tags
%DASHBOARD{ section="dashboard_start" }%
%DASHBOARD{ section="banner"
 image="%PUBURLPATH%/Cosmac/ForthSTM32WB/nucleo-header.jpg"
 title="Terminal I/O (Serial Communication)"
 titlestyle="color:#F00000;"
}%
%DASHBOARD{ section="box_start" title="Intro" width="485" height="250"}%
---+ Intro

To work interactively with a Forth system, you need some kind of [[https://en.wikipedia.org/wiki/System_console][console]]. A text [[https://en.wikipedia.org/wiki/Computer_terminal#Text_terminals][terminal]] with [[https://en.wikipedia.org/wiki/RS-232][RS-232]] port has been used for this purpose in the past. 
Today's PCs have software to emulate a terminal, but usually no longer have serial ports (RS-232 interfaces). 
Instead, there are usually USB interfaces. 

The [[https://en.wikipedia.org/wiki/USB_communications_device_class][USB-CDC]] appears as a traditional RS-232 port in your operating system (Linux =/dev/ttyACMx=, Windoze =COMx=). 
No need to bother with baud rates, handshaking, parity and other awkward things.
 
There is also a wireless console for PCs and mobile devices. The proprietary STM BLE Cable Replacement Service is used as communication protocol.
%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start" title="Contents" width="460" height="250"}%
%TOC%
%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="500" }%
---+ Terminal-IO

=emit= and =key= can block the calling thread, if the buffer is full (=emit=) or empty (=key=). The other threads are not affected (no busy-wait). The incoming characters (Rx) are buffered in a RTOS message queue, outgoing characters are also buffered.

Default console is USB-CDC, but if you press button SW2 on reset, the console is redirected to the UART [[https://en.wikipedia.org/wiki/RS-232][RS-232]] serial device (for details see [[https://github.com/spyren/Mecrisp-Cube/blob/master/Forth/cube/mecrisp.s][mecrisp.s]]). If you press button SW1 on reset, the console is redirected to the Bluetooth LE Cable Replacement Service.
<verbatim>
emit         ( char -- )        Emits a character
key          ( -- char )        Waits for and fetches the pressed key
emit?        ( -- flag )        Ready to send a character?
key?         ( -- flag )        Checks if a key is waiting

hook-emit?   ( -- addr )        Hooks for redirecting terminal IO on the fly
hook-key?    ( -- addr ) 
hook-key     ( -- addr ) 
hook-emit    ( -- addr ) 

uart         ( -- )             redirect console to serial interface (UART)
>uart        ( -- addr1 addr2 ) redirect console out (addr1 original =emit=, addr2 original =emit?=) to the serial interface (UART)
<uart        ( -- addr1 addr2 ) redirect console in (addr1 original =key=, addr2 original =key?=) to the serial interface (UART)
cdc          ( -- )             redirect console to USB-CDC
>cdc         ( -- addr1 addr2 )
<cdc         ( -- addr1 addr2 )
crs          ( -- )             redirect console to BLE CRS
>crs         ( -- addr1 addr2 )
<crs         ( -- addr1 addr2 )

>term        ( addr1 addr2 -- ) terminate (addr1 to restore =emit=, addr2 to restore =emit?=) redirection for console out
<term        ( addr1 addr2 -- ) terminate (addr1 to restore =key=, addr2 to restore =key?=) redirection for console in
</verbatim>

<pre>
: ascii ( -- ) 
  127 32 do 
    i emit 
  loop 
;

: crs-ascii ( -- ) 
  127 32 do 
    i crs-emit 
  loop 
  10 crs-emit / LF
;
</pre>

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="300" }%
---+ USB-CDC Serial Communication (API)
Buffered USB-CDC serial communication. The [[https://en.wikipedia.org/wiki/USB_communications_device_class][USB-CDC]] appears as a traditional RS-232 port in your operating system (Linux =/dev/ttyACMx=, Windoze =COMx=). No need to bother with baud rates, handshaking, parity and other awkward things. Under Linux I recommend to disable the !ModemManager, otherwise the !ModemManager tries to configure the ACM with some escape sequences.

After the first connect to the USB host, the green LED is switched on. Reset (and power cycle) enumerate the USB, this leads to a disconnect of the serial line. 

USB_USER CN1 Micro USB connector on the MB1355 Nucleo Board. <br>
USB_USER CN3 USB A plug on the MB1293 dongle.
<pre>
cdc-emit   ( char -- )   Emits one character to the USB-CDC interface. Blocking if the Buffer is full.
cdc-key    ( -- char )   Waits and gets one character from the USB-CDC interface. Blocking if the buffer is empty.
cdc-emit?  ( -- flag )   Ready to send a character. Buffer is not full.
cdc-key?   ( -- flag )   Checks if a character is in the buffer.
</pre>

%DASHBOARD{ section="box_end" }%
%DASHBOARD{ section="box_start"  width="992" height="400" }%
---+ UART Serial Communication (API)
The Rx buffer is 5 k, the Tx buffer 1 k. Copy and paste source code into the terminal is possible without buffer overrun.

   * USB-CDC on the ST-LINK Micro USB connector on the MB1355 Nucleo Board. Serial port UART1 on PB6/PB7 (remove jumper SB2, close jumper SB6) on the MB1293 dongle. 
   * USB to TTL Serial Cable for Raspberry Pi from [[https://www.adafruit.com/product/954][Adafruit]] (RX green, TX white, GND black). 
   * TTL-232R-RPi cable from FTDI Chip (RX orange, TX yellow, GND black).

Do not forget to set the baud rate. The default baud rate for the !MecrispCube is 115200 baud, e.g. =microcom -D /dev/ttyACM1 -s 115200= .

<pre>
serial-emit  ( char -- )  Emits one character to the UART interface. Blocking if the Buffer is full.
serial-key   ( -- char )  Waits and gets one character from the UART interface. Blocking if the buffer is empty.
serial-emit? ( -- flag )  Ready to send a character. Buffer is not full.
serial-key?  ( -- flag )  Checks if a character is in the buffer.

baudrate!    ( u -- )     sets baud rate (e.g. 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, <b>115200</b>)
paritybit!   ( u -- )     sets parity bit <b>0 none</b>, 1 odd, 2 even
wordlength!  ( u -- )     sets word length 7, <b>8</b>, 9 (including parity)
stopbits!    ( u -- )     sets stop bits <b>0 1 bit</b>, 1 1.5 bit, 2 2 bit
</pre>

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="500" }%
---+ BLE Cable Replacement Serial Communication (API)

Classic Bluetooth has a Serial Port Profile (SPP). It emulates a serial cable to provide a simple substitute for existing RS-232, including the familiar control signals. But for BLE there is no official/standard service for serial communication. Many chip manufactures have their own proprietary service.

   * LAIRD vSP, Rx and Tx FIFO characteristics. For details see [[http://cdn.lairdtech.com/home/brandworld/files/Application%20Note%20-%20Using%20VSP%20with%20smartBASIC.pdf][Using VSP with smartBASIC]]
   * TI SPS, Rx and Tx use the same characteristic for read and write. For details see [[http://www.ti.com/lit/ug/tidua63/tidua63.pdf?ts=1590183153410][TI Serial Port Service (SPS)]]
   * Silicon Labs [[https://www.silabs.com/documents/public/application-notes/AN1033-LE-Serial-Cable-Replacement.pdf][AN1033 LE Serial Cable Replacement]]
   * STM CRS Cable Replacement Service.
 
My own CRS Terminal is derived from [[https://medium.com/@loginov_rocks/how-to-make-a-web-app-for-your-own-bluetooth-low-energy-device-arduino-2af8d16fdbe8][Danila Loginov's]] Progressive Web App [[https://github.com/loginov-rocks/Web-Bluetooth-Terminal][Web-Bluetooth-Terminal]] and is based on Web Bluetooth. 

https://spyr.ch/crs-terminal/

This Progressive Web App works in the Chrome browser on Linux, OSX, and Windows operating systems. It also works on Android devices, you can download the App and use it offline.

[[https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal][Serial Bluetooth Terminal]] works great. You have to configure the the STM CRS to Custom, choose the default UUIDs (Service =0000fe60-cc7a-482a-984a-7f2ed5b3e58f=, Read Characteristic =0000fe62-8e22-4541-9d4c-21edae82ed19=, Write Characteristic =0000fe61-8e22-4541-9d4c-21edae82ed19=).

<pre>
crs-emit   ( char -- )  Emits one character to the BLE Cable Replacement Service. Blocking if the Buffer is full.
crs-key    ( -- char )  Waits and gets one character from the BLE Cable Replacement Service. Blocking if the buffer is empty.
crs-emit?  ( -- flag )  Ready to send a character. Buffer is not full.
crs-key?   ( -- flag )  Checks if a character is in the buffer.
</pre>

The blue LED indicates a connection to a central device.

---++ Real Web-Terminal with ANSI Escape Sequences

My CRS-Terminal and the [[https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal][Serial Bluetooth Terminal]] have only a command line and no real terminal emulation e.g. ANSI escape sequences and therefore can't be used for the vi.

The JavaScript library "termlib.js" provides a `Terminal' object, which facillitates a simple and object oriented approach to generate and control a terminal-like interface for web services.

"termlib.js" features direct keyboard input and powerful output methods for multiple and simultanious instances of the `Terminal' object.

https://www.masswerk.at/termlib/index.html

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="box_start"  width="992" height="300" }%
---+ Terminal Emulators

Terminal emulator applications for PCs, 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, miniterm, microcom, !CuteCom, screen - Linux

Terminal emulator for Android devices:
   * [[https://play.google.com/store/apps/details?id=de.kai_morich.serial_usb_terminal][Serial USB Terminal]]
   * [[https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal][Serial Bluetooth Terminal]] 

Settings
   * Terminal: Display mode Terminal
   * Receive: Newline CR+LF
   * Send: Newline CR, Local echo off

openSUSE GNU/Linux: add your account (user name) to the =dialout= group (for Raspi it's the =tty= group) otherwise you do not have permission to access the serial line. Disable the modem manager too (yast Service Manager).

%DASHBOARD{ section="box_end" }%

%DASHBOARD{ section="dashboard_end" }%


-- %USERSIG{PeterSchmid - 2020-04-20}%

<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>.
Topic revision: r24 - 2021-06-27 - PeterSchmid