Controlling Arduino with DX-Forth

Forth is a very powerful programming language. It can scale from very low level, near-assembly code, which you can run on Arduino Uno with 2 kilobytes of RAM, to very high level, domain-specific language, suitable for modern home computers (you can even implement object-oriented Forth in the Forth itself).

Due to its inherently low-level nature, Forth is not very popular among contemporary programmers. It is often considered a high level assembly - it stores and manipulates data using anonymous data stack (and optional floating point stack), and variables are nothing more than labelled memory cells. But at the same time Forth provides a set of tools to create building blocks, which can be used to make even the most sophisticated software (like satellite antenna controllers). Developers who understand how a CPU works and are not afraid to juggle with bytes, usually have no fear of Forth and find it a very smart and productive tool.

There are many implementations of Forth for almost all existing operating systems (many of them are self-contained and can run without an operating system at all, like amForth or Jupiter ACE's Forth). Among them there is excellent, and still actively maintained, DX-Forth for CP/M. Thanks to amazing work of Marcelo Dantas and his fantastic CP/M emulator for Arduino Due, and my humble contribution in the form of CP/M Arduino Interface, you can now enjoy writing software for Arduino using DX-Forth.

RunCPM emulator contains an example Forth application, PHOTOLED.4TH. It begins with a couple of Forth words, which define the Arduino interface. The first one is pinmode:

: pinmode ( val pin -- ) 8 lshift + 220 bdos drop ;

From its declaration, pinmode expects two bytes on a stack, the first one being a value to assign to the pin, and the pin number. It uses a word bdos, which DX-Forth defines as follows:

BDOS ( DE u -- A )
Perform CP/M BDOS call number u. DE is the value passed to the DE register. Return the contents of the A register.

So first we need to put on the stack some value, which will then be passed to CPU register DE, and then a BDOS function number. Question is, what should be passed as DE and the call number? The answer can be found in the Arduino interface description:

BDOS function 220 (0xDC) - PinMode:
LD C, 220
LD D, pin_number
LD E, mode (0 = INPUT, 1 = OUTPUT, 2 = INPUT_PULLUP)

By convention, you pass BDOS function number in CPU register C, and arguments in registers D and E. All those registers are 8-bit, but can be combined in 16-bit pairs: BC, DE and HL. So for the Forth word bdos we need two numbers to be put on the stack:
- First, a 16-bit number with pin number in high 8-bits and mode (0, 1 or 2) in low 8-bits. This number will be passed to CP/M through CPU register pair DE.
- Second, number 220 as the function call.
For example, to set pin 13 into output mode, we need the following command in Forth:

3329 220 bdos

3329 is a product of 13 * 256 + 1. Multiplication by 256 is the same as shifting 8 bits left. The pinmode does exactly that: it takes the pin number from the stack, shifts it 8 bits left, add the next value from the stack (val) and calls BDOS function 220:

: pinmode ( val pin -- ) 8 lshift + 220 bdos drop ;

The result of the call can be ignored, so the return value is simply dropped.

All the next Arduino interface words follow the same schema:

: dout ( val pin -- ) 8 lshift + 222 bdos drop ;
: aout ( val pin -- ) 8 lshift + 224 bdos drop ;

With din we want to preserve the result of bdos call on the stack, so we don't drop it:

: din ( pin -- n ) 8 lshift 221 bdos ;

Additionally, with word ain, we use fdos instead of bdos:

: ain ( pin -- n ) 8 lshift 223 fdos drop ;

It's because function number 223 makes a call to AnalogRead, which returns a 10-bit value and needs more than one 8-bit register to pass the result back to Forth. The value of AnalogRead is returned by the Arduino interface in register pair HL, and fdos returns this pair along with register A, unlike bdos, which returns only A:

FDOS ( DE u -- HL A )
Perform CP/M BDOS call number u. DE is the value passed to the DE register. Return the contents of the HL and A registers.

Since we need HL only, we can drop what has been returned in A, and leave only HL on the stack.

Now we can define words which use pinmode, din, dout, ain and aout. For example to turn a led on and off we can define the following words:

: ledon ( pin -- ) 1 over pinmode 1 swap dout ;
: ledoff ( pin -- ) 1 over pinmode 0 swap dout ;

Both words require the pin number to be on the stack. They both put the pin to output using pinmode and then set its state to HIGH (1) or LOW (0) respectively.

A more complicated example requires a simple circuit to be built. It should consist of a LED and a LDR (photoresistor) according to the following diagram:

The LED is connected to pin D9 (it can't be any digital pin, it must be PWM capable) through a 68 ohm resistor (unlike Uno, Arduino Due outputs 3.3V), and the LDR is connected to pin A8 and uses a 10k ohm pull-down resistor. We want a LED to light up when it gets darker, and get dim when it's not. Because, as you remember, analog input can return values with 10-bit resolution, and digital output accepts only 8-bit values, we need to calculate the LED intensity according to the following formula:

LED = 255 - (LDR / 4)

This can be achieved through a new word fade (it uses shifting 2 bits to the right to do a division by 4):

: fade ( led ldr -- ) ain 2 rshift 255 swap - swap aout ;

Now when you run the following command in DX-Forth:

9 8 fade

the LED intensity gets adjusted according to the current value returned by the LDR.

Of course it is tedious to run it by hand. We can define a new word, which will run fade in a loop:

: run begin 9 8 fade 100 ms key? until ;

It runs 9 8 fade with 100 millisecond delay until any key gets pressed. The final result looks like this:



If the LED responds too slow, or flickers, you should try tuning the delay. You can also get rid of it completely:

: run begin 9 8 fade key? until ;

The first operating system for Arduino

RunCPM, a CP/M emulator for Arduino Due, can now use Arduino's analog and digital pins thanks to five additional BDOS calls, which virtually makes it the first (and so far the only one) fully fledged, professional operating system for Arduino. You can write brand new, or modify any existing, CP/M software, using any programming language available for CP/M platform, to interface Arduino devices. The only requirement is that it should allow you to call arbitrarily chosen BDOS functions (natively or via inline assembly code), because RunCPM uses newly defined routines (220 - 224), unused by standard CP/M implementations.

RunCPM includes a few sample programs in Assembly, Microsoft Basic, Hi-Tech C, Turbo Pascal and DX-Forth to get you started. I also prepared a short video tutorial showing the Turbo Pascal example in action:



A few tips:

Because analogRead returns values that won't fit in a single byte, when calling function 223 in Turbo Pascal you should use BdosHL instead of Bdos to get the value returned in HL register pair, like this:

writeln(BdosHL(223, pin shl 8);

The same applies to Hi-Tech C - see PHOTO.C and PHOTO.PAS examples.

Also, since MBasic does not allow direct BDOS calls, I used USR functions to call small assembly procedures encoded in DATA lines.

Happy coding on Arduino!