                                 ARMForth32
                                 ----------

ARMForth32 is the updated version of ARMForth, originally written by 
Rob Turner.  It works on the Raspberry Pi, ARMini and Iyonix, which 
are all 32-bit computers.

I have separated the compiled version from the assembly process into
two application directories:  !ARMforth32  and  !ForthAssemble.  The
source code is in BASIC-V ("BARMForth32"), so is easy to modify.  
Once assembled, and a new !RunImage file created within !ForthAssemble,
it needs to be dragged and dropped to within the !ARMforth32 directory.

I think I have arranged things so that it will run without the need
to run the assembler.  However, it is important to have the correct
'GPIO' module copied to the Support directory, since the Pi_Bplus
requires an updated version.

After double-clicking on the !ARMforth32 icon, the same icon appears on
the icon bar.  Clicking on this icon launches the application which runs
in a window by default.  It also loads the !Startup file, if it exists,
so that the current user program can be loaded.  I have included a directory
called StartUps, which has a variety of different programs to launch -
one of these can be copied and renamed to !Startup if required.

After loading the !Startup file, the current directory would normally be
set to the Support directory, which contains some more Forth programs.
These are all in text form.  When they are loaded (eg  FLOAD" FFT_App")
the Forth compiler takes the text and compiles (adds) the defined words
into its dictionary, which is a linked list of all the words currently
defined.  Once loaded, all these are accessible via the keyboard in
interpretive mode, and so may be used, checked and/or recombined with
other existing words.

The !Startup file should always load the files: Misc_words, Colour 
and Float, which are all inside the Support directory.

There is quite a comprehensive manual (written by Rob Turner) which is
essential to read in order to use the program effectively.  There are 
a few mistakes in the manual, but none serious (eg C@ and C! act on 8 
bits, not 16, as stated).

The main problem in updating this version of Forth has been in accommodating
the requirements of the code and data caches.  Self-modifying code (which
Forth happily performs frequently) can result in the caches becoming
'incoherent', necessitating an SWI call to synchronise them again.  This
appears to affect only the compilation process rather than the run-time 
behaviour, so that the run-time speed of the application is unaffected.

There are undoubtedly a few bugs lurking in the code (eg loading files
from a compiled word can fail, even though VLIST shows them to have loaded).
Using the same word via the keyboard is successful, however.

Code Examples
=============
The examples provided by Rob Turner are in the "Examples" directory.  I
haven't checked these recently, so cannot guarantee that they will work
correctly.

The !Startup file supplied for demonstration purposes allows the user to
load 3 example programs (non-Pi), or 7 if the Pi is being used.  This is
because the interfacing of the SPI, IIC busses etc was debugged using the
Pi.  I started this process using a Gertboard and moved on to using 
individual ICs on a breadboard and linking directly to the GPIO pins.
(See the Jpegs in "pix" directory).  The following text has some brief 
notes on each application.

1) FPTPtable
============
This is the Floating Point (FP) version of the Temperature and Pressure (TP)
corrections required when using an ionisation chamber to measure radiation
dose using an unsealed air chamber.  I wrote it to compare the results with 
an integer arithmetic version I had written many years ago i.e. to check my
use of floating point routines, which I added to the original Forth.  It is
useful in showing how to apply floating point generally.  After loading, type
"show_corrs" and 3 tables of correction factors should appear on the screen.

2)  FFT_App
===========
This is a program to calculate the "Fast Fourier Transform" (FFT) of a 
waveform.  It uses complex arithmetic (i.e real and imaginary values) and
so required an extension of words to handle complex quantities.  Listing
FFT_App on the screen shows that 4 additional files are loaded:
Complex - the words for complex arithmetic (definition and manipulation of)
FFT_Rob - the FFT calculation method (I am indebted to Julian Noble's book:
          "Scientific Forth" for the method)
FFT_Plot & FFT_test - supporting files for display and testing FFTs

The Complex file introduces the fact that Forth is an extensible language
i.e. it can define new data types as required.  This has been called
"The jewel of Forth" (Julian Noble).  The appropriate line is:
      : zVARIABLE <BUILDS SWAP , , DOES> ;   ( a,b ...)
The sequence <BUILDS .... DOES> represents the "compile-time" behaviour, with
the "run-time" behaviour following DOES>.  In this case, the compile action
makes space for 2 variables (floating point real and imaginaries) and the
run-time just puts the start address of this pair of values on the data stack.
The subsequent words to manipulate this pair of numbers are designed to treat
them as a single structure (eg complex multiplication etc).

The FFT is calculated by the word of the same name in FFT_Rob.  For 1024 points,
the time to calculate the FFT on the Pi is about 4.5msec.

After loading, type: "FFT_examples".  The system will jump out of the windowing
and step through some test waveforms, displaying the original waveform, the
real and imaginary parts and the reconstructed waveform from the FFT (which
should be the same as the original waveform).  When finished, type "WIMPS" to
get back to the original window display.


3)  Simple Tasks Demo
=====================
This option shows a simple example of the use of Forth's multitasking functions.
There are several multitasking methods available in different Forths - in our case
the method is similar to RiscOS's own i.e. cooperative multitasking.

It is essential that the manual is read before attempting to program using this 
feature. It is not difficult to use, but may need some fine-tuning in using the word
PAUSE to optimise the performance of a given application.

When loaded, type "FFT+Shapes" to obtain a display of 3 programs running at
the 'same' time:  the previous FFT software plus 2 graphics applications (drawing
a moving square and a moving circle). I have had a stepper motor and flashing LEDs
working in addition to this display - an exercise for the user!

4)  IIC with ADS1115 ADC   ( start of Pi-only software examples)
========================
The file "ADS1115" is the result of my first experience of using the IIC (or I2C)
bus.  In this case, the subject is the ADC board which has been fitted to a breadboard
and linked directly to the Pi's GPIO lines (see pix directory).  I'm afraid that it
is essential to read the datasheet for this device, as there is a wide variation in
programming requirements for each IC.  Basically, the ADS1115 is a slow-ish 15-bit 
ADC which has up to 4 inputs and can be used in either a continuous or single-shot
mode.  The demo software uses the continuous mode, which is slightly faster as there 
are fewer starts and stops.

It would be possible to program the IIC bus using the registers on the ARM chip directly.
However, there are SWI calls in RiscOS which are designed to take some of the hassle out
of this, and I was successful (eventually) with the "SWI IIC_Control" command.  There is
the command "SWI OS_IICop" which supersedes this, but I couldn't get it to work properly.
In order to help the reader decode the values in the required data structures I have
put the binary values in brackets next to hex values - these should be compared with the
datasheet.

The channel number is set by the variable "channel" (currently 1).  To change to, say, 0
type "0 channel !".  To read and display 100 values, type "100 rd_continuous".

5)  SPI with MCP3208 ADC
========================
This task also uses an ADC, but using the SPI bus on the PI (GPIO pins 7 to 11) rather 
than the IIC bus (pictures in "pix" directory).  There appears to be no current RiscOS
SWIs to fall back on, so it is a case of setting the registers on the BCM2835 processor
to perform appropriate actions.  The MCP3208 is a fast 8-channel 12-bit ADC, and is a single
chip rather than a circuit board (see photos).  The basic routine in the file "MCP3208" is
"read_adc", which shows the initial setup, followed by the command transfers and the subsequent
reading of the 2 bytes which form the 12-bit value. Access to the datasheet is essential in
order to understand the method.

If the results from channel 2 (say) are required, this may be tested by typing " 2 ADC", which
puts 500 values on the screen.

In my opinion, this ADC is preferable to the ADS1115 for, although it has slightly lower
precision (12 rather than 15 bits), it is much faster and therefore lends itself better
to real-time control - particularly if using a DC motor servo'd by an ADC (see next demo).

6)  DC Motor (with PWM)
=======================
For controlling the speed and direction of a brushed DC motor I have used the L293D IC
on a breadboard - see "pix" directory.  This IC is capable of driving 2 DC motors or one
stepper motor.  To start, type "0 rampup&down" and then "1 rampup&down".  The motor should 
accelerate and decelerate in one direction using the first command, and in the other
direction using the second command.

The Pulse-Width-Modulation (PWM) is used to control the speed of the motor:  the longer
one of the 2 inputs to the motor is 'high' the faster the motor rotates (the other control 
line should be 'low').  This is accomplished using software controlling the general GPIO pins 
(17 & 18) rather than setting up the in-built PWM pins on the Pi GPIO pins.

Inside the directory "MCP3208" there is a file "DCservo" which combines this and the 
previous demo to apply a servo to a DC motor.  This is left as an exercise.
Typing "0 pot_servo" should drive the motor until the ADC reading is in the middle of
the range (2048 is the "zero" in this case).

7)  Stepper Motor
=================
The file "Step_Motor" contains the software to drive a stepper motor - either using full
or half-steps (if the motor is designed for this).

Type "step_demo" to try it - it should rotate one way and then the other.


R.J.Wilks
October 2014

Enquiries/comments to:  rjw4th@orpheusmail.co.uk




















                                                                            
