Entering a character string

published: 21 November 2020 / updated 23 November 2020

The word STRINPUT

Even on a microcontroller, you may need to enter a character string from the terminal or another source.

Here, we use the pad buffer which goes through the corresponding tib to the input area of the FORTH interpreter.

When you use the terminal to communicate with FlashForth, the characters entered go through the buffer pointed to by tib

-input
marker -input
 
\ accept n characters from terminal FORTH buffer
\ leave addr n 
: strinput  ( n --- addr n)
    pad swap
    accept
    pad swap
  ;

The execution of strinput must be preceded by the maximum number of characters to enter:

if this maximum number of expected characters is entered, the entry stops and strinput returns the address and the length of the entered string;
if the entry is completed by pressing the ENTER key, the entry is interrupted and returns the address and length of the entered string.

Timed text entry

In principle, in an ARDUINO assembly, once the application has been finalized, there is no no longer supposed to communicate with the terminal. However, some device, a LoRa transmitter for example, connected to the serial port rx0 / tx0, will feed itself to the terminal.

If a signal or a string is transmitted over this serial link, the device can respond. For the case of a LoRa transmitter, a transmission by AT + SEND may be subject to a response that will be retrieved by strinput. But if the transmission is poorly received, you can wait a very long time, if ever, for a response on the serial port.

The idea is therefore to delay this entry attempt:

2000 value IN_DELAY \ increase or decrase if necessary
: temp.rx0
    IN_DELAY
    begin
        1- 1 ms
        rx0?    \ char recevied from rx0 ?
        if  
            drop
            rx0  exit
        then
    dup 0= until
    drop 13     \ if no char, leave $0a (cr)
  ;
 
\ temporised input
: tempInput ( n --- addr n)
    [']  temp.rx0 'key !
    strinput
    ['] rx0 'key !
  ;

The word temp.rx0 acts like the word rx0 except that the wait is limited in time by the content of the IN_DELAY value. You can modify the content of this value if necessary.

The word tempInput will act like the word strinput. If the waiting time is exceeded at the start or during entry, this entry string is interrupted.

In the scenario of a LoRa transmission for example:

if sending a message expects a response and the response does not arrive in within the time limit, we will get an empty string.
if the answer is not completed with a 'cr' character, the entry will be interrupted after the time limit and the characters received are recovered from the string.

Interpretation of a character string

FORTH is an interpreter AND a compiler !

FlashForth is no exception to the rule. It has both features in 12 KB of flash memory, excluding user application.

When you install FlashForth on an ARDUINO card, then you plug this card on the USB port of your computer, the interpreter is accessible from the terminal. Voir: Install and use the Tera Term terminal

The terminal goes through the USB interface which is connected to the USB port rx0 / tx0 and managed by FlashForth.

What does that mean?

This means that, to receive characters from the serial port rx0 / tx0, there is no nothing to do!

If you create a stand-alone application, i.e. disconnected from the terminal, any reception of characters from serial port rx0 / tx0 will be interpreted by FlashForth exactly as if this chain of catacères were transmitted by the terminal!

Ahhh .....

We can have several cases:

the application is NOT waiting for ANY serial transmission. So there is no problem;
the application is waiting for data from the serial transmission. This data will have to be managed:
- by decoding the content of the string received
- by managing a transmission of commands in FORTH language

This is the solution that will be preferred when you can transmit data and commands in FORTH language.

A very practical example

We have an ARDUINO board connected to a loRa transmitter. This card must activate or deactivate a relay.

Without going into the details of a FORTH program, when you have the card connected to the terminal, you can activate or deactivate the relay with:

RELAY high
RELAY low

Once the assembly is operational, if you want to activate the relay remotely, the transmitter will only have to send the string RELAY high

The receiver application will receive this string in the receive buffer managed by strinput. To run the contents of the buffer, just run interpret after receiving the string. The word interpret just needs the address and number of characters in the string to parse.

Here is a test to do with the terminal:

: test ( ---)
    s" words" ;
test interpret      \ execute words

Executing the word test drops the coordinates of the string on the stack characters containing words .

The word interpret will act exactly the same on a string transmitted via the serial port received in a serial buffer.