This is a step-by-step introduction into using IRTC, the editor SED, and the Smart-ICEPIC.
First we should enter SED, the Hypertext Sequential ASCII File Editor by using the Crtl-F1 key sequence. This enters into the on-line help. Now select '2.1 Edit&Forth' by pressing the Tab key until the cursor is on '2.1' and press Return. A similar text will now be showing in the edit window.
Around the editor window you will see several reverse video blocks. The arrow blocks indicate the use of the cursor keys but if you have a mouse clicking on the blocks will have the same effect. On the top line you will see the word BROWSE, this indicates that you may look but not modify the file. This is the mode used by the Help. Next is the current line number, the current cursor column, the page number, the number of lines in the file so far, and the number of characters in the file so far. At the end of the top line is a block with +1 in at the moment. This indicates that we are nested two deep in file selections. To be here we selected this file, TUTORIAL.TXT from IRTCHELP.TXT. To see this use Alt-F1, this will flip you to the first file and twice again to come back. Try it. You notice that the cursor retains its position in the file which is very useful when you are editing the source and documentation together. The maximum number of open files is 20!, enough for the most complex application. Rather than rolling through the open files Shift-F1 gives you a list from which to choose.
On the bottom line is a reminder that Editor Help is the F1 key, the file we are currently in and the Menu block which is available with the mouse right button, clicking on this block or the Esc key. Selecting the Menu changes the top line to a selector bar, moving along with the cursor keys and pressing à selects a pull-down window. The selections within each window use the same scheme. To select with the mouse click the right button to select the menu bar, hold down the left button and move the mouse to hi-light the window and then the item within the window, release the button to action the selection.
Now we are ready to create a new file. This file is to be the source for a simple application, to drive a 7-segment LED. We will assume that the PIC we are using is a PIC16C84 and that the application files will be in the directory \FPC\PIC84. This directory does not yet exist so we must create that first. SED does not allow the creation of directories directly but does allow us to shell out to DOS with Ctrl-Enter. Use this to MD \FPC\PIC84. Now we may use Ctrl-O to create a new file by specifying \FPC\PIC84\7-SEG. Try these now and return with Alt-F1.
If you use Shift-F1 to see the open file list you should see a file called 7-SEG.SEQ. The .SEQ, for sequential, extension was added by SED as we did not give one. If we had then that would have been used, it is better to leave the .SEQ as SED expects this and you save yourself some time. We now have a file ready for the source, now to work out what to put in it.
This simple application is going to scan a key and each time it is pressed increment the digit on the LED. The circuit is shown below:
When RA0 is set low the push-button will pull-down RB0s pull-up. When RA0 is high RB0-6 will drive the LED. This requires that PortB should have its pull-ups enabled and will be required to be a input or output depending on the mode. PortA bit0 has to be an output.
We will assume the above circuit is built and the Smart-ICEPIC inserted with a TLM programmed PIC84 in the ZIF socket. We can switch on the power to the ICEPIC and establish communication by typing ?ICE or using Alt-1 from the command line. To do this we must exit the editor, but before we do we will reduce the editor window with Alt-S,W. Make the window smaller with the up arrow key until 5 lines may be seen below the window, press Esc when finished. If you wish a large window later use Alt-S,Z to switch back and forth.
You may find this trick useful when using the simulator to display the source while stepping through the code below.
Now exit the editor with Alt-F10 with this line at the top of the window.
Use: OPEN TUTORIAL.TXT B
to re-enter this text and then PgDn back to here. Next time you exit you should see the cursor at the bottom of the screen but the edit window still visible.
Type:
?ICE 1 2 3 .S the reply should be
PIC84 Stack Empty (8)
$01 $02 $03 <- PIC16C84 Stack Top (8) ok
REQUIRED FC!
response Programming PIC16C84 ... ok
REQUIRED CAND
response Programming PIC16C84 ... ok
REQUIRED COR
response Programming PIC16C84 ... ok
REQUIRED CXOR
response Programming PIC16C84 ... ok
These are to help us with the testing and we may need them later.
Return to the Tutorial by typing HOST BROWSE and move this text to the top of the window.
Now to test the hardware exit again and type:
OPTION C@ $7F AND OPTION C! ok
$FE TRISA C! 1 PORTA C! ok
: TST 0 TRISB C! NOT PORTB C! FREEZE ;
$7F ICE.RUN TST
Use Alt-1 or ?ICE to reset the ICE
The PIC should freeze with an '8' on the LED display. Press Alt-1 to continue bring back the line above from the history stack and use the right arrow key to move over to $7F. Change this to $07 by overtyping and then press Return. The display should now show a '7'. This technique may be used over and over to work out the PORTB values for the digits.
If portB bit6 is set as an input your code may cause problems as this is the CLK for the communications and is used for the handshake. If you need to use this write a test word to control the port starting with a delay, FOR ... NEXT. The delay will give the ICEPIC time to switch over to the Target before reading PortB.
Having worked out the LED drive we may now write up the source. Use Ctrl-O to open the file 7-SEG.SEQ.
Enter the following:
IN-META FPATH+ \F-PC\PIC84 \ This tells
\ F-PC where to find our file later.
8BITS \ Use the 8 bit Forth stack
H: ANODE-DRIVE (S - m a ) 1 ?COMPILE PORTA ;
H: BUTTON-IN (S - m a ) 1 ?COMPILE PORTB ;
H: PORTB-INPUTS (S - m a ) | $FF ?COMPILE TRISB [[ TRANSITION ]] ON [META] ;
H: PORTB-OUTPUTS (S - m a ) | $FF ?COMPILE TRISB [[ TRANSITION ]] OFF [META] ;
: PORTS-INIT (S - )
$80 OPTION OFF \ PortB pull-ups
$01 TRISA OFF ; \ PortA bit0 output
TABLE 7-SEG.DIGITS
( 0 ) $3F TC, ( 1 ) $06 TC, ( 2 ) $5B TC,
( 3 ) $4F TC, ( 4 ) $66 TC, ( 5 ) $6D TC,
( 6 ) $7D TC, ( 7 ) $07 TC, ( 8 ) $7F TC,
( 9 ) $6F TC,
: SHOW-DIGIT (S c - ) PORTB-OUTPUTS ANODE-DRIVE ON
7-SEG.DIGITS ROT M+ TC@ NOT PORTB C! ;
Rather than having to type all this into 7-SEG.SEQ we can use the editor to do it for us. If you are not already in the editor this source is in the on-line help, Ctrl-F1, 2.1 Edit&Forth. Enter SED with Ctrl-F1 and locate the text. Move the cursor to the start of the IN-META line and press F3. This marks the beginning of the text to be copied. Use the down-arrow key to mark all the text to be transferred and then type Shift-ALT-C together. You will be prompted with the file TEMP.SEQ overwrite this with \FPC\PIC84\7-SEG.SEQ and press enter. The text will be copied to the file.
Now type Ctrl-O and specify 7-SEG.SEQ as the file to open. The above text should now be in the file. Exit from the editor to the command line and use Alt-1 to establish comms. with the ICEPIC. Now we can load the new source with
FLOAD \FPC\PIC84\7-SEG.
Explanation of some of these definitions is in order. The H: defined words are what are called compiler directives. These have an effect at compile time that will produce Target code. Words like ON, OFF and CHECK will try to optimise the code if they are preceded by literal code,
MOVLW xx DECF FSR MOVWF (FSR).
The first two compiler directives place literals in the Target at compile time ready for ON or OFF. The word ?COMPILE compiles the 8 bit stack value as a literal if it is run in a Target ':' definition, otherwise it leaves the value on the stack for command line interpretation.
The words like PORTB use ?COMPILE in there own definition and so its use is not required again. This way the compiler 'hides' the code without consuming stack space at run-time. The second two compile completely optimised in-line code. We could have made both these into Target definitions but the optimizer would only work for the last two and we would end up with more code and stack usage, which the PIC does not have in abundance.
The reason for the two is purely to enhance the code readability, also this technique of 'hiding' the bit-banging is encouraged in Forth.
To test the new code we may generate a test word:
: TST PORT-INIT SHOW-DIGIT FREEZE ;
This may then be run as before with:
5 ICE.RUN TST
A '5' should appear on the LED and you will be prompted with:
'Use Alt-1 or ?ICE to Reset the ICE'
You may now re-run TST with different values to check all the digits. Now add the following to 7-SEG.SEQ to complete the application.
: ?BUTTON (S - f )
ANODE-DRIVE OFF \ key drive low
PORTB-INPUTS \ PortB inputs
BUTTON-IN CHECK 0= ; \ key?
: SCAN (S - )
PORTS-INIT 0 \ set ports
BEGIN DUP SHOW-DIGIT \ show 0 first
255 FOR NEXT \ scan delay
?BUTTON IF 1+ DUP 9 > \ If key inc. digit
IF 10 - \ too large
THEN THEN
AGAIN ; \ go forever
.STATISTICS \ This tells us what we have used.
Again we can use the editor to mark the text above but this time use Shift-Alt-A to append the marked text to 7-SEG.SEQ. You may now exit the editor and FLOAD or INCLUDE the file again. This re-compiles the previous words and the two new ones but when we run only the most recent will be found. You may now try to run SCAN with:
ICE.RUN SCAN
The deliberate mistake will be apparent, the digits whiz round when the button is pressed. ?BUTTON will need to be modified to only flag a change of button status. Try this:
| VARIABLE LAST-BUTTON
: ?BUTTON (S - f )
ANODE-DRIVE OFF
PORTB-INPUTS
BUTTON-IN CHECK DUP
LAST-BUTTON C@ XOR
LAST-BUTTON C@ AND
SWAP LAST-BUTTON C! ;
There is still little de-bounce for the button and at high clock rates the selection is poor. Try reducing the clock with 300.0 KHZ the result is then acceptable. This is only an example, and not the best way to solve this problem but does give some insight into the functions available, the use of the editor and the interactive testing.
One last trick from this editor. Now you have compiled your program the words are known to IRTC. If you move the cursor to ?BUTTON above and press F9 or double-click with the mouse the file 7-SEG.SEQ will load into the editor with the cursor against the definition of ?BUTTON. This is one of the forms of Hypertext in SED. You may do the same to any word in 7-SEG.SEQ but only those you have just created will work. However, all is not lost, if you use Alt-H when on a word or click the mouse while holding down the Alt key, the Help file for that definition will show instead. It is then possible to navigate around your source in this way. If difficulty is experienced in finding the help files this either means the word is not yet compiled in the target or the vocabulary search order is for the Host and not the Remote. Ensure that 'Remote' is showing on the top right of the screen before entering the editor. This may be done with Alt-1 to establish contact with, and reset, the ICEPIC or just by typing ?ICE or REM.