[Amforth] [PATCH] Update to "Arduino-HelloWorld.rst.txt" recipe

[Carsten S. <ca...@st...>]

Hi AmForth List,

on the weekend I've run the "Arduino Hello World" recipe and found 
two
issues:

a) the recipe jumps from pin 5 to pin 7 of Port B in the middle of 
the
recipe, that was confusing

b) modern AmForth does not seem to include the word "ms" in the 
kernel

Attached is a patch that changes to Port to use Digital-13 on the
Arduino all the time (to be consistent) and gives information 
where to
find the word "ms" (or how to quickly define it).


<https://git.sr.ht/~cstrotm/AmForth/commit/a2a968b7c02aff5afd622f842aeda9a21ddcdc92.patch>

Greetings

Carsten


>From a2a968b7c02aff5afd622f842aeda9a21ddcdc92 Mon Sep 17 00:00:00 
2001
From: Carsten Strotmann <ca...@st...>
Date: Mon, 1 Mar 2021 13:55:20 +0100
Subject: [PATCH] Fix port number in example and add information on 
word "ms"

---
 .../TG/recipes/Arduino-HelloWorld.rst.txt     | 52 
 +++++++++++--------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git 
a/doc/htdocs/_sources/TG/recipes/Arduino-HelloWorld.rst.txt 
b/doc/htdocs/_sources/TG/recipes/Arduino-HelloWorld.rst.txt
index 7de8045..93bb471 100644
--- a/doc/htdocs/_sources/TG/recipes/Arduino-HelloWorld.rst.txt
+++ b/doc/htdocs/_sources/TG/recipes/Arduino-HelloWorld.rst.txt
@@ -9,7 +9,7 @@ attached to the port Digital-13. For this recipe, 
the amforth system
 is already loaded onto the ardiuno. Instructions to do it are in 
 the
 :ref:`User Guide`.
 
-To quickly test the hardware start a terminal (e.g. screen 
 /dev/ttyACM0 38400) 
+To quickly test the hardware start a terminal (e.g. screen 
/dev/ttyACM0 38400)
 and enter the following commands (assuming an Arduino Uno)
 
 .. code-block:: forth
@@ -19,12 +19,12 @@ and enter the following commands (assuming an 
Arduino Uno)
    > $00 $25 c!
 
 The LED turned on until the last command is executed. The 
 character
-:command:`>` is the command prompt, if you see it, you can enter 
-any commands. You'll never enter that character yourselves. A 
+:command:`>` is the command prompt, if you see it, you can enter
+any commands. You'll never enter that character yourselves. A
 command line can be up to 80 characters long.
 
 The commands above are pretty obscure. To make them easier to
-understand we define labels for some numbers, so called 
+understand we define labels for some numbers, so called
 constants:
 
 .. code-block:: forth
@@ -35,24 +35,24 @@ constants:
 The arduino uses its own numbering schema for pins, but
 for now we use the atmega one: digial-13 is the same as
 bit 7 of port B. Port B has 8 pins and three registers to
-configure them. we need two of them: The Data Direction 
-Register (DDR) and the PORT (Output) Register. The third 
+configure them. we need two of them: The Data Direction
+Register (DDR) and the PORT (Output) Register. The third
 register is used for reading from the port (PIN).
 
 The above commands can now be written as
 
 .. code-block:: forth
 
-  > $20 DDRB c! 
+  > $20 DDRB c!
   > $20 PORTB c!
   > $00 PORTB c!
 
 Technically the same but easier to read.
 
 Next we do not want to enter all commands interactively. Forth
-has the reputation of an extendible command set. 
+has the reputation of an extendible command set.
 
-Good forth coding style means to have many small words which do 
 exactly 
+Good forth coding style means to have many small words which do 
exactly
 one thing. Most forth commands are built with only a handful 
 other commands.
 
 The first command in this example sets up the Data Direction 
 Register DDR
@@ -68,7 +68,7 @@ The same in Forth is:
 
 .. code-block:: forth
 
-   > : led-init  $80 DDRB c! ;
+   > : led-init  $20 DDRB c! ;
     ok
    >
 
@@ -81,17 +81,17 @@ With this command line the interpreter learns 
a new command:
     ok
    >
 
-It writes the number 128 (hex 80) to the register DDRB (hex 24)
-as defined above. This makes the 7th bit of PORTB an Output pin.
+It writes the number 32 (hex 20) to the register DDRB (hex 24)
+as defined above. This makes the 5th bit of PORTB an Output pin.
 
 Calling our newly defined word does not change anything
 visible. But with the next word, the LED will turn on:
 
 .. code-block:: forth
 
-  : led-on $80 PORTB c! ;
+  : led-on $20 PORTB c! ;
 
-Here the 7th bit will be set to 1, and that makes the led to be 
 connected
+Here the 5th bit will be set to 1, and that makes the led to be 
connected
 to VCC (5V) and it will turn on (the LED is connected to ground 
 already).
 
 If the led-on command does not turn on the LED just call the
@@ -123,9 +123,15 @@ Our next word will simplify this and gives 
the real blink experience:
 
   : led-blink led-on 500 ms led-off 500 ms ;
 
-Calling this command will turn on the led, waits for half a 
 second, turn it
-off again and waits another half a second before returning to the 
 command
-prompt.
+Calling this command will turn on the led, waits for half a 
second,
+turn it off again and waits another half a second before 
returning to
+the command prompt. If the word `ms` is not found, it can be 
loaded
+from `<AmForth>/common/lib/forth2012/facility/ms.frt` or defined
+assembler
+
+.. code-block:: forth
+
+  : ms 0 ?do 1ms loop ;
 
 With this command you can blink the led a few times
 
@@ -148,11 +154,11 @@ To make it blink "forever", we define 
another command word:
         led-blink
         key?
      until
-     key drop 
+     key drop
    ;
 
-Since this is our first command which needs more than 1 line, the 
-interpreter acts more complex. It changes the command prompt 
 until 
+Since this is our first command which needs more than 1 line, the
+interpreter acts more complex. It changes the command prompt 
until
 the end of the command definition is reached (the command ``;``)
 The ouput in the terminal window looks like
 
@@ -167,7 +173,7 @@ The ouput in the terminal window looks like
     okkey drop
     ok;
     ok
-   > 
+   >
 
 This word first prints some text ("press any key to stop") and 
 starts a loop.
 This loop lets the led blink once and checks for a keystroke. If 
 no key
@@ -185,7 +191,7 @@ Where to go next
 ................
 
 This example is very basic. Next steps may involve library code
-like :ref:`Digital Ports`. Related to it are the :ref:`Upload` 
 for 
+like :ref:`Digital Ports`. Related to it are the :ref:`Upload` 
for
 files with forth code.
 
-More Arduino related stuff is in :ref:`Arduino Analog`. 
+More Arduino related stuff is in :ref:`Arduino Analog`.
-- 
2.30.1