Forth-eV Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 4E4th -  the New Version 2018 ====== 

4E4th is a small Forth running on TI's **LaunchPad**, residing inside the MSP430G2553 Flash memory.

Communication with the 4E4th works with its line editor - accessed by a terminal  emulator. 

4E4th((4e4th05a May 2018)) is based on MSP430 CamelForth version 0.5a written by B. J. Rodriguez for the TI MSP430G2553 Launchpad board. http://www.camelforth.com/ 

It covers an ANS Forth subset, needs 6K of the MSP430G2553 MCU FLASH (0xE000-0xFFFF). 
There are 8K (0xC000-0xDFFF) free for your own Experiments.

4E4th is, as CamelForth is, free software (GNU General Public License). 

//All hardware remarks of the following text are related to TI's LaunchPad MSP-EXP430G2 Rev.1.5// 


===== Bootstrap Loading =====

  * If you have a LaunchPad with TI's MSP430G2553 MCU and **4E4th inside** you have nothing further to do before starting.

  * In case you have a new LaunchPad with an MSP430G2553 on it, then you need to FLASH the [[https://github.com/mikalus/4e4th05a|4e4th05a.hex]] Image, Intel Hex Format. Section "Programmer" below will tell you how.  



===== LaunchPad Adjustments ===== 

Starting with Rev1.5, TI's LaunchPad has jumpers to switch the Rx and Tx pins from the interface between a Software UART and Hardware UART function. The LaunchPad TXD and RXD jumpers on J3 at the LaunchPad board when delivered are set to the SW UART position by TI. 4E4th needs the hardware UART function, so the position of the TXD and RXD jumpers on J3 have to be changed as shown in the image of the MSP-EXP430G2 LaunchPad Quick Start Guide (SLAC432) to ensure that the Rx and Tx pins are properly configured for the HW UART.\\ 
{{:projects:4e4th:start:rxd-txd-launchpad-rev15.png?100|}} {{:projects:4e4th:start:rxd-txd-launchapd-rev15-schema.png?100|}}

In case you are using 4E4th on an older LaunchPad version, remove the TXD and RXD jumpers and connect the TXD and RXD pins crosswise. \\  {{:projects:4e4th:start:txt-rxt-launchpad-rev13.png?200|}} {{:projects:4e4th:start:txt-rxt-launchpad-rev13-schema.png?200|}}
  

===== What Terminal is the right one? =====

Adjust your terminal to 9600 8N1. This is the fixed speed with which 4E4TH's RS232 communicates with the USB interface. 
However Linux, talking to USB, seems to ignore all settings that make no sense for USB and still work. 

   9600 Baud  
   8N1: 8 data bits, no parity bit, 1 stop bit 
    Hardware flow control: OFF  
   

== Windows XP, 7 and 10 ==

Here, the LaunchPad Windows USB Drivers have to be installed. 
  Further information is found at TI's document slau278h.pdf, page 139, Hardware Installation Guide. 

  * TeraTerm will work fine. http://www.heise.de/download/teraterm-pro.html 
  * HyperTerminal does, too. 
  If HyperTerminal doesn't work properly with 4E4th, check 
  File / Properties / Settings / ASCII Setup: 
  Only "Wrap lines that exceed terminal width" may be checked. 
  Line Feeds and Echo are not allowed. 
  * 4E4th-IDE is a special Terminal Emulation for Forth Applications. http://www.4e4th-ide.org/ 

== macOSX ==

LaunchPad OSX USB driver (CDC /VCP) must be installed.
  MSP430LPCDC 1.0.3b.pkg - starting with Mac OSX Version 1.5 
  See at http://code.google.com/p/msp430lpcdc/downloads/detail?name=MSP430LPCDC%201.0.3b.pkg&can=2&q= 
  More information at 
  http://processors.wiki.ti.com/index.php/MSP430_LaunchPad_Mac_OS_X 

  * ZTerm 

  Settings>Modem Preferences...  Serial Port (choose uart-40FF42C59D89223A or similar) 
  Settings>Connection... Data Rate 9600 
   

  * Kermit 

  % kermit 
  kermit> set line /dev/tty.uart-40FF42C59D89223A  or similar 
  kermit> set speed 9600 
  kermit> connect 

== Linux == 

Seems to be working without special drivers. Disconnecting and reconnecting USB is an almost foolproof way to set the serial communication connection.  Note: on most GNU/Linux distributions ''screen'' is installed by default while ''kermit'' requires manual installation.

Tested on:

Debian squeeze, on i386 and on PPC (Gerald).
Ubuntu 10.04 LTS - Lucid Lynx i686 Desktop PC (Martin).
Ubuntu 10.04 LTS - AMD 64 bit (Albert).
Ubuntu 11.04 - Natty Narwhal i386 Laptop HP Compaq 615 (Martin).
  

  * screen  

  % screen /dev/ttyACM0

  * Kermit 

   % kermit 
   kermit> set line /dev/ttyACM0  # or similar 
   kermit> connect 


===== Starting 4E4th ===== 

As first step start with connecting the LaunchPad to your PC or laptop, using the USB cable out of the LaunchPad box. This USB connection is at the same time the LaunchPad's power supply and as well the serial Interface to your Terminal emulator.

As soon as the LaunchPad is connected, Forth is started (both LEDs are switched on) - assuming your Laptop or PC is switched on. For testing and to start Forth again, use the LaunchPad's Reset button. 

4E4th starts with its latest saved status. To get back to the status at delivery, push and hold LaunchPad's button S2 and push the Reset button while holding S2. Reflashing is done over the USB cable, too. 

//Attention: 
The USB connection sometimes may be tricky. It is important that your PC recognizes the USB connection. Windows makes a special sound every time a new USB connection is recognized, and it makes a special sound in case the USB connector is pulled out. If you don't listen to these sounds, it may happen that the USB connection doesn't work, and the Terminal software doesn't recognize the LaunchPad's USB port. This is equally important when using TI's MSP-FET430UIF. 
Please do this: 
Switch on your speaker and listen to this special sound coming up when connecting the LaunchPad to USB, and start your Terminal after this. 
Please always first connect the USB cable at the LaunchPad board side, then to your computer. 
//
  

===== Communication with 4E4th ===== 


Terminal settings are 9600Baud 8N1. To be sure that communication is started, push <Enter> several times. 4E4th answers with ok. 
By the way, every input ends with pushing <Enter> to be executed. 

To become familiar with 4E4th, try this: 
Type   
      red cclrb
      red csetb  
or   
      green cclrb 
      green csetb
and <Enter>, of course. The red or the green LED will be lit, respectively. 

Type 
      11 22 33 
The answer ''ok'' tells you that these numbers are on the data stack now - as soon as you have pressed <Enter>. 

Type ''.s'' (a dot and character "s") and <Enter>.
4E4th will show the typed values which are on the stack.  
You may repeat the ''.S'' command several times. You should always get the same result. 

4E4th is capable of different number bases. 4E4th starts in DECIMAL mode and then accepts only decimal numbers. To make Embedded Systems programming easier, you may switch to HEX mode, and 4E4th only accepts hex numbers then. Typing DECIMAL switches back to decimal mode. Using hex numbers A B C D E F in decimal mode will produce an error message.

Here another Test. Type this text – and end with <enter>:

  : TEST ." I am here " ; 

4E4th answers with ok as usual, to show that your input has been accepted. 
You have just created a new command, and this command has as well been added to the 4E4th system. 

Now type 

   TEST <Enter> 

and look what this command does. You just learned that for creating of a new command you first 
type a colon '':'', and at the end of this definition you type a semicolon '';''. 

See chapter 11a, b and c in A Start With Forth https://wiki.forth-ev.de/doku.php/en:projects:a-start-with-forth:start0

More examples you will find in Forth Tutorials - for example look at the classic "Starting Forth online edition" which you will find at http://www.forth.com/starting-forth/ 

//All Forth words in the examples are written in CAPITAL letters. The 4e4th does not care whether you type CAPITAL or small letters uses. This behavior is called case insensitive. //   

===== Saving your Program ===== 

The only thing you have to do to save your program is: type SAVE <Enter>. 
SAVE saves your program on the MSP430G2553 FLASH memory.

It is possible to upload and save the MCUs image using a Programmer. 

To remove your program, type WIPE. Be careful. This is a powerful instruction. When typing WIPE, your work of may be several hours will be gone. That's why 4E4th-IDE logs all your typing, and you will be able to download your work again. 

Another way to remove your programs is by pressing the LaunchPad's S2 button and then the RESET button while holding S2. 

//There is a special characteristic in handling the FLASH in MSP430 MCUs, and FLASH memory in general: The FLASH always can be correctly written to only once! It is thus not as comfortable as RAM or FRAM. Practically seen, that means, if you forget to erase the FLASH properly before you start programming (compiling) again, the program crashes. Or, with other words: If there is no $FFFF at IHERE nothing can be written there. Use WIPE to compile into the fresh FLASH.//   


===== Troubleshooting =====

If 4e4th staopped working completely, the ultima ratio is to ReFLASH the MCU.

Assuming Windows, start the Programmer and the same source again, using the FET-Pro430 and AUTOPROG. Jumpers stay as they are.

The Programmer uses Port USB HID00xx to connect to LaunchPad using the same USB Port the Terminal uses. The Terminal may stay connected.

When Flashing is done, end this process by clicking "RESET" at the FET-Pro430. 4E4th then boots immediately.


===== Making your own Forth Kernel =====

In case you like to edit the 4E4th kernel, clone this project https://github.com/mikalus/4e4th05a.

There is a readme.430 file and some other documentation which tells you how to get your own special Forth done. 

Github contains all the code and programs you need to generate your Forth. The binary image 4e4th05a.hex you can directly load into the LaunchPad's MSP430G2553 chip. The *.asm files hold the complete 4E4th source code.


===== Glossary ===== 

 Memory 
  SAVE ( -- )  Saves the typed additions. Stacks are unchanged. Saves actual uarea. Defines as well the last definition for autostart. 
  WIPE ( -- )  Back to original status. Stacks unchanged. uarea back to original. 


 Peripherals - Port1 and Port2  
  csetb          m addr --                    set port pins at address with mask 
  cclrb          m addr --                    clear port pins at address with mask 
  red           -- m addr                    red LED mask and port1 address 
  green         -- m addr                    green LED mask and port1 address
  S?            -- f                        test button S2, true when pressed 


The complete 4E4th vocabulary you will find in the Glossary.pdf 

== How can I switch a LED on and off again? ==

Both LEDs LED1 and LED2 are connected to Port1 of the MCU.

  P1.0 = LED1 = red
  P1.6 = LED2 = green
  
The Forth words ''csetb'' and ''cclrb'' are working bit wise. ''csetb'' needs a bit-mask and address on stack, ''cclrb'', too. 
Such a mask is a byte with the needed bits set. The Forth Words ''red'' and ''green'' put such masks onto data stack along with an address to work on:

  red     0x01 = 00000001   0x21 = Port1 output register
  green   0x40 = 01000000   0x21 = Port1 output register

Here some examples how to switch the LEDs on and off using these masks. (In case you don't know how to use the Forth' command line, do some exercise first, see http://www.forth.com/starting-forth/ online edition).
Anyway, here are the commands:

  red cclrb     --> turns red LED off.
  green cclrb   --> turns green LED off. 
  red csetb     --> turns red LED on.
  green csetb   --> turns green LED on.

Next step: Blinking the LEDs!

  DECIMAL
  : blink BEGIN 
    red csetb green cclrb 100 MS
    red cclrb green csetb 100 MS
    KEY? UNTIL ; 

This is a simple and a complete program. To make your LaunchPad running this program when switched on again, type

  SAVE
  
It is good practice to have an exit from your app back to Forth. Otherwise a WIPE is due in case you like to interact with 4e4th again: press S2 + reset buttons. 
 
We hope we soon will have a nice 4E4th collection of [[projects:4e4th:4e4th:start:beispiele|example programms]] and you are allowed to add your examples there to be used by the 4E4th community.

----



====== Requirements ======
To communicate with the LaunchPad's MCU, you need a Terminal or a Terminal Emulator on your PC. It is important to have a Programmer Software too, to reFLASH the chip. All these programs need the correct drivers for the LaunchPad. These drivers must have been installed in your Operating System first.

Ti's engineers assume that you program your LaunchPad using C or Assembler. Therefore TI offers so called Integrated Development Environment (IDE) software - the IAR "Kickstart" and Code Composer are downloadable as free but limited versions. The free Code Composer can be used for free for a limited time, the free IAR Kickstart is free only for projects up to 4k. For now (March 2012) there is no special free TI-IDE.

We used Naken Assembler instead. https://www.mikekohn.net/micro/naken_asm.php



===== Drivers =====

=== Windows 7 ===

There is an exe for installation offered by TI for the LaunchPad: ''http://www.ti.com/litv/zip/slac490''
Inside this zip you will find a subfolder ''LaunchPad_Driver'' with three files ''430cdc.cat'', ''430cdc.inf'' and ''LaunchPad_Driver.exe''
Start LaunchPad_Driver.exe (mouse double click).
There seems to be no result, but after this action LaunchPad will be recognized and is ready to go. This works for 32 bit  and 64 bit systems.

Connect your LaunchPad to USB (remember: connect cable to LaunchPad first), you should get a ready to go message.
You may check it using the Device Manager. There you should find at COM-Ports the "MSP430 Application UART".

Source:
http://e2e.ti.com/support/microcontrollers/msp43016-bit_ultra-low_power_mcus/f/166/t/105756.aspx

== Alternative Source ==

   LaunchPad_Driver.zip at www.forth-ev.de download area,  other.
   http://www.forth-ev.de/filemgmt/singlefile.php?lid=410

== Alternative Path ==

   - Click on the Windows Icon at the bottom left of your Windows 7 desktop. This opens the System Control.
   - Open Devices and Printers
   - Connect LaunchPad - a new Icon with yellow exclamation mark will show up.
   - Click on this new Icon. A window "Properties of Texas Instruments MSP-FET430UIF" will open.
   - Click on the "Hardware" tab to open and click on the button "Properties" bottom right.
   - Another Window "Properties of HID conforming Device" will open.
   - At this state click on button "Change Settings", a similar window opens.
   - Select "Driver"
   - To update the driver, look for the right folder, which contains the 430cdc.inf file and driver software, and go on!
   - It is reported (Martin) that from then on everything works by itself.

//Tip: This inf file is a script which tells Windows what to do to install a virtual COM port for the LaunchPad USB Interface. A inf file is not direct executable.//

=== Windows XP ===

Search for file ''WinDriver_for_TI-LaunchPad_USB_serial.inf'' using the Hardware Wizard or the Device Manager and let it execute. This will provide a virtual COM port for the LaunchPad.
You may download this inf file from http://www.forth-ev.de/repos/CF430G2553/

Some people say you may use the Win7 exe-file method written about above, alternatively.

  You will find documentation in slau278h.pdf at TI.COM, page 139, Hardware Installation Guide.
Source: http://www.ti.com/lit/ug/slau278h/slau278h.pdf

Using this method you will avoid installing IAR's "Kickstart" - some people like this.

=== Linux ===

Connection to TI LaunchPad and 4E4th worked successfully on several platforms.

=== Mac OSX (intel) ===

===== Programmer =====

You find the 4E4th binary image at GitHub, see section Bootstrap Loading for a link. It has to be loaded into the MCU using a suitable programmer.

== Windows XP and Windows 7 ==

FET-Pro430 Lite version FREE. http://www.elprotronic.com/fetpro430.html

Set the 4E4th image (//open code file//) and path, choose the MSP430G2553 MCU (//Microcontroller Type//). Activate the box //reload code file//. Choose the right connection at menu //setup connections//. Click on //AUTOPROG// - programming starts.

Here a screen shot:

 {{:projects:4e4th:fet-pro430.jpg?200|fet-pro430.jpg}}

== Linux ==
At Linux the TI LaunchPad should come up with ''/dev/ttyACM0''. 
This entry in the /dev directory should appear, irrespective of whether your Launchpad
is able to communicate or contains a useful program.

Under Linux you can use the program ''mspdebug'' to flash and debug the LaunchPad MCU.
With some luck, your distribution knows the package and you can use a command such as

    $ apt-get install mspdebug
to install it.

Version 0.19 or higher is preferred, http://mspdebug.sourceforge.net/ has the latest sources if 
it comes to this.

Loading the hex file image  onto the LaunchPad MCU can be done script-style:

    $ mspdebug rf2500 "prog 4e4th.a43"

Alternatively you can use mspdebug interactively:
        $ mspdebug rf2500
Safest is the combination of
        (mspdebug) erase all
        (mspdebug) prog 4e4th.a43
Then -- still in mspdebug -- you can check the content of the flash memory.
   
Potential problems:
   - Some modern Linux Systems Background Programs (one example is the ModemManager) immediately occupy the Interface installed for Launchpad and try to talk to LaunchPad as to a modem (See Linux today: too much plug and play; http://fedetft.wordpress.com/2011/01/07/linux-today-too-much-plug-and-play/). (cas)
   - In some distributions user might not have access rights to ''/dev/ttyACM0'' so mspdebug should be run via ''sudo'' as shown below.
   - If you have an older version (0.13) of ''mspdebug'' the model name rf2500 will not be recognized and the command will be rejected. You can force the loading with:

   $ sudo mspdebug --fet-force-id "prog 4e4th.a43" rf2500



== Mac OSX (intel) ==

There is a group which is collecting tools:
http://processors.wiki.ti.com/index.php/MSP430_LaunchPad_Mac_OS_X

===== Source Upload via Terminal =====

Terminal programs have been mentioned before. There are standard Terminal programs available and there are Forth specific Terminals under development.

  * TeraTerm is for Windows. TeraTerm may be used to execute macros. Using a Forth specific macro makes it easier to download source files to the 4e4th micro. Such a macro transmits line by line, waiting for each line to be compiled by the 4e4th. The next line will be sent when this compiling is done. {{:projects:4e4th:terapatchxon.ttl.zip|TeraTerm macro für Forth}}

  * For Linux there is the //minicom//. Using Ctrl+<A>, <S> the „Send file“ Dialogue will be opened. Any utility may be used to transmit, configured with Ctrl+<A>, <O>, //"File transfer protocols"//. A small Tcl script allows to send Forth sources with flow control:   \\ {{:projects:4e4th:minicom-4e4th-up.tgz|Source Upload-Script for minicom}}. \\ The appropriate setting has to look like this: <code>
  J  4e4th      /path/to/minicom-4e4th-up   Y    U    N       Y       Y </code>  
  
  * The following Tcl script may be used to upload sources with Linux, Windows, or Mac: \\ <file 4e4th-up>
#! /usr/bin/tclsh
set uart /dev/ttyACM0

set h [open $uart r+]
fconfigure $h -mode 9600,n,8,1 -handshake none -timeout 1000 \
    -translation cr -buffering none

foreach name $argv {
    foreach line [split [exec cat $name] "\r\n"] {
	puts -nonewline $h "$line\r"
	while {[string compare [set c [read $h 1]] "\x11"]} {
	    puts -nonewline stderr $c
	}
    }
}</file> \\ 
  * The following non-standard Forth script (http://home.hccnet.nl/a.w.m.van.der.horst/lina.html) may be used to upload sources with Linux: \\ <file 4e4th-up1>
#! /usr/bin/lina -s

REQUIRE R/W             REQUIRE NEW-IF          REQUIRE $-PREFIX
0 HANDLER !     \ Bug!
: ?ERR   ( ior -- ) -1 SWAP ?ERROR ;

"/dev/ttyACM0" R/W OPEN-FILE ?ERR CONSTANT msp

BEGIN ARGC 1 > WHILE    1 ARG[] GET-FILE
  BEGIN   OVER WHILE    ^J $S -TRAILING
     msp WRITE-FILE ?ERR     ^M DSP@ 1 msp WRITE-FILE ?ERR DROP
     BEGIN 0 DSP@ 1 msp READ-FILE ?ERR DROP DUP $11 <> WHILE EMIT REPEAT DROP
  REPEAT 2DROP
SHIFT-ARGS REPEAT</file> \\

 When using Windows or Mac the serial port name finally has to be adapted with //set uart// (Windows: comN, Mac: ??).    Usage is really simple:
<code> $ ./4e4th-up sourcefile...</code>
(When using Linux don't forget chmod a+x !)


   

====== Troubleshooting ======

===== Endless-Reset =====

Martin Bitter wrote:

There are special not explainable circumstances when the LaunchPad Forth doesn't do what it should do.
One example: It sends its starting message again and again.
I observed this with Windows and TeraTerm, but Linux may do the same or gives the message "File or Folder not found) at start.
Using a "Hardreset" by pressing S2 and then pressing the Resetbutton while holding S2, or pressing the Resetbutton for a minute helped.

Our Answer:

This error came up after flashing the MCU with mspdebug.
The "Hardreset", pressing S2 and then pressing the Resetbutton while //holding// S2, confirming with S1 reset, does the following: bringing 4E4th back to delivery state.
When booting 4E4th checks pointers IHERE (warmstart user area at infoB) if these are conform with the user flash writings (Further details: See source code). If this is //not// the case, for security the complete user FLASH will be erased, and the user area of the Forth kernel will be loaded instead and will be copied to infoB. (mk)

Settings for mspdebug (in preparation).


===== Ghost Characters ===== 

My Terminal shows //Ghost Characters//. How does this happen? 
{{ :projects:4e4th:geisterzeichen4e4th.jpg?|Ghost Characters}} 

A: The debug-mode of your Terminal is switched on. In this case Control Characters are displayed. The little box with 0011 inside says that a hex value of 0x11 has been sent by 4e4th to  
your Terminal. 0x11 means XON. 

To activate TeraTerms debug mode, shift-esc has to be pressed. 
Press shift-esc again to see the screen content as hex dump. 
Press shift-esc again to end the hex dump display. And press shift-esc again to go back to normal. 
  TeraTerm debug-mode: 
  1x shift-esc = Control Chars are shown: 11 22 33 . . . 33 22 11 ok ^Q^M^J ok ^Q^M^J ok 
  2x shift-esc = screen hex dump: 11 22 33 . . . 20 33 33 20 32 32 20 31 31 20 6F 6B 20 11 0D 0A ok 


===== Terminal does not react ===== 
====  TeraTerm ====

  The terminal does not get the USB connection made available by the Windows XP.   It happened to me everytime when I do not follow the rules for connection. Here how it will be done right:    
   A Establishing the Connection     
     1. Connect LaunchPad to USB - first connect the USB-cable to the LaunchPad, then connect the USB cable to the PC. Wait for the answering sound of Windows.     
     2. Open TeraTerm. (Sometimes 2 or three times - no notion why.)   
   B Disconnect     
     1. Close TeraTerm.     
     2. Disconnect LaunchPad. 
     
   If I remove the LaunchPad from the USB while TeraTerm still is running, the connection of the two remains disturbed. Thus Hotplug does not go. So far it only helps to close TeraTerm. Afterwards (!) disconnect LaunchPad from USB, wait for the sound sequence, connect again, and wait for the sound sequence again, then open the terminal.   When using the FET-Pro430 Programmer, follow those instructions, too. I had good experiences to connect the terminal first and then start the Programmer. The MCU can be flashed even when terminal is active. mk 

Looks like the newest TeraTerm can hot plug the Launchpad. mk 20180510

====== Acknowledgements ======

Many thanks to the groundbreaking work creating CamelForth done by Brad Rodriguez. 
Thanks to Dirk Bruehl for his untiring and altruistic support of the 4E4th Project, by ordering the appropriate hardware and encouraging with many hints and ideas to go on until CamelForth was running on the LaunchPad. 
mk 20120314 

Thank you again, Brad Rodriguez, for transferring CamelForth to Naken Assembler! And thanks to Jürgen Pintaske, who persuaded me to transfer 4e4th to the Naken Assembler. mk 20180512

====== Links ======

  * Fundamental Experiments with a MCU\\
http://www.forth-ev.de/wiki/doku.php/projects:4e4th:4e4th:start:msp430g2553_experimente 

  * Advanced Experiments\\
http://www.forth-ev.de/wiki/doku.php/projects:4e4th:start:boosterpacks\\
http://processors.wiki.ti.com/index.php/BoosterPacks

  * Documentation\\
http://www.ti.com/product/msp430g2553

revisions mk20121224 mk20180512 mk20180513

4e4th05a May 2018