This article contains examples on using the WIZnet W5100 Ethernet controller to provide TCP communications for MV4th16. The examples include; support for a TCP console for MV4th16, a simple TCP terminal, a TCP terminal server, and a simple WEB server example. The examples are configured for the Parallax Spinneret board. The Spinneret board contains a Parallax Propeller chip, WIZnet W5100 Ethernet device, Epson RTC with large backup capacitor for date/time retention, and a Micro SD card slot. The examples make heavy used of the LOAD and THRU forth words to allow each of the examples to be loaded from the Forth block device, executed then unloaded from the limited system RAM memory. These examples apply to MV4th16 version 0.94b and higher. The example project can be found in the "Forth\PerBuilt" folder in the latest version of the MV4th16 project.
I used the Parallax Spinneret board so that the examples would be based on a known hardware platform.
Parallax Spinneret Board, Propeller, W5100, RTC, and Micro SD card slot
Preparing The Target System and Development Tools
To begin using the Spinneret board you must first load MV4th16 on the target system. MV4th16 should be configured to use the SD card as the Forth block device. You can download the current version of MV4th16 from the MV4th16 Downloads section of the website. For the examples in this article you will require a freshly formatted Micro SD card formatted with FAT16 or FAT32. See the article, Configure MV4th16 version 0.94 or higher for information on how to configure MV4th16. You will also require the ForthTerm terminal program to follow the examples in this article. You can download the current version of ForthTerm from the ForthTerm Downloads section of the website. For information on how to configure the ForthTerm terminal program see the article Configuring the ForthTerm Terminal Program.
Loading the Examples on to Target System
Connect your target system to ForthTerm terminal program and reset the target system. When the target system starts up answer "N" to the auto load prompt. Locate the file "SpinneretTcpDemo.blk" in the "Forth\Prebuilt" folder from the zip file that contains the latest build of MV4th16 (version 0.94b or higher). This example block file is @ 112Kb in size.
In the ForthTerm program select the "Upload Block File" command under the "Communication" menu. When prompted select the file "SpinneretTcpDemo.blk" in the "Forth\PreBuilt" folder of the MV4th16 project. Make sure the file type is set to "Block File" in the select file dialog. Because we are working with a blank target system the ForthTerm program will need to paste the block transfer software to the target system. Answer yes when prompted to upload the transfer software. When the transfer software is loaded on the target system you are ready to transfer the block file to the target system.
Confirm upload of transfer software to forth target system
In the "Upload Forth Blocks" dialog set the "First Block" setting to 0. Make sure the "Pad Block With Space Character" option is selected. Press the "Upload" button to start the block file transfer. If all went well the example forth block file will be copied to the target board block storage device. Next time the target restarts the forth code will be auto loaded. At this point select the "Terminal" tab in the ForthTerm program and reset the target system.
Upload block(s) to target system dialog.
Configure Forth Network TCP Settings
The simplest way to configure the network settings is to set them while the target system is loading. When you are prompted to "Update network settings (Y or N)?", answer "Y" to the prompt. If you do not answer the prompt in @ 3 seconds the system will continue loading using the current setting.
Network setting on target system, answer "Y" to edit
Editing network settings on target system
Set the target system IP address, gateway address, and sub-net mask to match your network settings. The port setting configures the default TCP port number used when the system is listening as a server for connections. Once you are happy with the network settings, select the "Q" option to save the settings and start the network interface using the supplied settings.
The WIZnet Ethernet devices do not have a default MAC address. The one included in the example block file should work for testing the examples. If you intend on running the examples on more then one target system you will need to make certain that all the target systems have a unique MAC address value.
Once you have completed editing the TCP settings select the "Q" option to exit editing mode and save your settings. The system should continue to load and then display the help screen. If the TCP setting need to be changed you can reboot the target system or use the Forth word NetConsole to change network settings and restart the Ethernet device with new settings. The TCP settings are saved in block number 36 on the Forth block device. Once the target board is configured you should be able to Ping the system using the IP address you set in the TCP settings.
Example 1 -- Connecting MV4th16 Console Using TCP Terminal
It can be very handy to access your MV4th16 target board using a TCP terminal. The example block file contains forth code to do just that. The main dictionary in MV4th16 defines the main console I/O forth words; EMIT? EMIT for console output, and KEY KEY? EMPTY-KEYS for console input. These console I/O words are defined as deferred. These deferred words can be assigned to execute any Forth word that takes and returns the same parameters. This allows a Forth program to redefine these words and redirect console I/O to any virtual device. When MV4th16 starts up it executes the forth word, COM1>CON to assign the console I/O functions to the COM1 device (default 2 wire com port on propeller chip).
At start up the example block file initializes the W5100 then loads and initializes the Forth library "NetConsole.forth". The Forth library "NetConsole.forth" defines replacement forth words for all the deferred console I/O words. The TCP I/O Forth words are; nc-tx nc-tx? nc-rx nc-rx? nc-rxclr. The new TCP Forth words can be assigned to the base library Forth console I/O words using the Forth word NET>CON or can be used directly. When the demo code starts the NetConsole library is set to listen for connections on a TCP socket using the TCP port set in the network configuration. The NetConsole library is configured to automatically re-spawn the listening socket when the connection from the current TCP client is closed.
To redirect the Forth console from serial to TCP:
- Connect the target MV4th16 system to the ForthTerm terminal program using a serial connection (via PropPlug).
- In the ForthTerm terminal window type the Forth command NET>CON and press enter.
- Close the serial connection in the ForthTerm program.
- Connect to the target system using the TCP connection option in ForthTerm or any other TCP terminal program.
- Once a connection is established press the Enter key in the Terminal, the target system should respond with "OK".
To redirect the Forth console from TCP back to serial:
- Connect to the target system using the TCP connection option in ForthTerm or any other TCP terminal program.
- Type the Forth command COM1>CON and press enter.
- Close the TCP connection to the target system in the terminal program.
- Connect to the target system in ForthTerm using a serial connection (via PropPlug).
- Once a connection is established press the Enter key in ForthTerm, the target system should respond with "OK".
If you disconnect the TCP terminal while the target system console is redirected to TCP you will not be able to reconnect using the serial port. You will need to reconnect via TCP and execute the Forth word COM1>CON on the target system or reset the target system. If you are connected to the target system via TCP and you execute the Forth word NET>CON the TCP connection will be closed by the target system and you will have to reconnect your terminal program.
If you connect to the target system via TCP and the device connected to the target system does not properly close the TCP connection you will not be able to reconnect to the target system. This is caused by the fact that the target system will likely be in a read loop waiting for input from the TCP connection and has no way of knowing that the device it was connected to is gone. The target system would either have to attempt a write to the TCP connection or send a TCP keep alive packet to detect that the connected device is not there. There is no way to enable automatic transmission of keep alive packets on the WIZnet Ethernet devices.
When the ForthTerm program is connected using TCP to a target MV4th16 system you can upload and download Forth blocks, and paste text to the target system just as you would using the serial com port. The only function you cannot perform when connected via TCP is to remote reset the target system. If you have console access to a remote system you can execute the Forth word REBOOT from the TCP terminal to reset the remote target system.
If the target system is connected via TCP and running a program that outputs data to the console, closing the TCP connection will cause the Forth program to be suspend until the next TCP transmission times out and the connection to the TCP target system is reestablished. As an example type the Forth statement; 0 8192 DUMP and press the Enter key. As soon as the target system starts to send text to your terminal close the TCP connection in the terminal program. Wait at least 2 minutes (default WIZnet tx time out) for the target system's last TCP write to time out. Reconnect to the target system with the terminal program. As soon as the connection to the target system is established the remainder of the memory dump will be sent to your terminal program.
While redirecting the target Forth system console to a TCP connection has its problems it is very handy while debugging a target system that is not beside you. For a 24/7 program it would be better to handle the TCP I/O using the NetConsole I/O functions directly as is done in the web server example. You may also choose to use the functionality of the W5100/W5200 Forth driver directly.
Example 2 -- Simple TCP client TTY Terminal Example
The TCP client terminal examples uses the "NetConsole.forth" library to make a TCP client connection instead of listening as server. This is done by disabling the "NetConsole.forth" library auto connect feature and using the tcp-connect Forth word to connect to a TCP server. The terminal examples do not redirect the console I/O, instead the Forth words nc-tx nc-tx? nc-rx nc-rx? nc-rxclr.are used directly to perform TCP I/O. The target MV4th16 system uses the COM1 device as the console.
To run the Forth terminal program connect to the Target board using a serial connection. If you are currently connected to the target system using a TCP connection, redirect the console using the COM1>CON Forth word then close the TCP connection to the target system.
With the target system connected to ForthTerm via a serial connection (PropPlug) execute the Forth word Term or EchoTerm the latter will turn on local echo mode. When the Forth terminal program starts you will be prompted to enter the IP address of the host to connect to. Once the IP address is entered you will next be prompted for the host TCP port number. After the port number is entered the Forth terminal will attempt to the make a TCP connection to the specified host. To close the target system TCP connection press the ESC key. When the terminal program completes it will be unloaded from system memory. The source code for the terminal examples can be found in the "Forth\W5100" folder in the MV4th16 install directory under the file name "TcpForthTerm.forth".
Example 3 -- Simple TCP TTY Terminal Server Example
The TCP server terminal example uses the "NetConsole.forth" library to listen for a TCP client connection. The terminal server example does not redirect the console I/O, instead the NetConsole Forth words nc-tx nc-tx? nc-rx nc-rx? and nc-rxclr are used directly to perform TCP I/O. The target MV4th16 system uses the COM1 device as the console.
To run the Forth terminal server program connect to the Target board using a serial connection. If you are currently connected to the target system using a TCP connection redirect the console using the COM1>CON Forth word then close the TCP connection to the target system.
With the target system connected to the ForthTerm program using a serial connection (PropPlug) execute the Forth word Listen or EchoListen the latter will turn on local echo mode. When the Forth terminal program on the target system starts you will be prompted to enter the TCP port number the server should listen for connections on. After the port number is entered the Forth terminal will listen for a TCP connection to the specified TCP port. To close the target system TCP connection press the ESC key. When the terminal program completes it will be unloaded from system memory. The source code for the terminal examples can be found in the "Forth\W5100" folder in the MV4th16 install directory under the file name "TcpForthTerm.forth".
As an example; type the Forth word Listen and when you are prompted for the port number enter 80. Next open a web browser and connect to the address you assigned to the target board. The HTTP request from the browser should be displayed on the serial terminal.
Example 4 -- Simple HTTP Web Server Example
The Web server example uses the "NetConsole.forth" library by supplying a connected socket when activating a net console session. When the Web server code initializes all sockets available from the Wiznet (W5100, W5200) Ethernet device are set to listen mode. The server then waits for a socket connection from a client system on any of the available listening sockets. If any socket receives a connection from a client system and has data to read the socket is used to start a net console session. The active net console TCP session is redirected to the standard Forth console input words. The Web server code contains custom console output words that directly use the NetConsole words. The Forth console output is redirected to the Web server custom output function. This allows the HTTP request from the client connection to be parsed using the standard Forth console input words. The HTTP response can likewise be written using the standard Forth console output words.
Requests made to the web server can either use the HTTP method GET or POST. An HTTP GET request can pass parameters using the HTTP query request format. An HTTP POST request must pass parameters as "x-www-form-urlencoded" content. The URI portion of the HTTP request is used to determine the name of the forth word that should be executed to handle the client request. The URI is stripped of leading file separator characters then the string "WEX-" is added as a prefix to the URI to form the name of the forth word to execute. The forth dictionary is searched for a match and if the forth word is found it is executed. As an example the HTTP request; GET /date HTTP/1.1 would attempt to execute the forth word WEX-date. The URI to forth word mapping is case sensitive.
The Web server can also be used to expand special tags embedded in an HTML document. Tags of the form "#XXXXX", where "XXXXX" is any ASCII character sequence are replaced by executing a field executable forth word named "FEX-XXXXX". The field executable forth word output will replace the "#XXXXX" tag. One interesting use of the forth tag expansion is to initialize java script variables. The web server demo uses the tag, "" to show the time and date the demo web page was loaded by invoking the forth word FEX-getdate. The field executable forth words used in the demo are found in the file, "\Forth\W5100\WebServer\WebDemo.WebDemoPages.forth". The "WebDemoPages.forth" file is dynamically loaded by the main "WebDemo.forth" code.
Web demo page displays date and time page loaded
Request parameters can be accessed using the name of the parameter. Parameter values can either be a string or a numeric value. In the case of a numeric value the number is assumed to be a base ten numeric string. If the numeric value is prefixed by a hash tag character "#", then the parameter value string is assumed to be a base sixteen hex number. Parameters names are not case sensitive.
Due to the limited memory available on the target propeller systems there are a number of limitations to the Web server example:
- The entire HTTP request sent to the Web server is limited to 254 characters.
- HTTP character tokens such as amp; and nbsp; are not supported in the parameter names or value strings.
- After the response is sent by the server, the TCP client connection is always closed.
- Multiple parameters passed to the server with the same name are not supported.
The Web server supports basic authentication. Up to 15 user name/password pairs can be saved in the user authentication database. The user information includes the user name, password and authentication level. The authentication level is a number from 1 to 99. The meaning of the authentication level is program dependent. For this example the "admin" account is always user authentication level 99. All system user accounts have an authentication level 10 or higher. All user accounts with a user level less then 10 are treated as guest accounts. The user information for this example is saved on the block device in block number 83.
The examples contain three forth words to manage the user database. The user database words can be execute from the console on the target system. Each of these forth words will prompt for the required information after they are executed;
- user-add -- add or change a users settings (note: user name and password may not contain full colon character).
- user-delete -- remove a user from the database.
- user-list -- list all user names and there authentication level.
HTTP basic authentication is not secure on its own. This is due to the fact that the user name and password are not encrypted. However on a local LAN it will keep your device free from family members who do not know the password. If you use a real Web server to proxy requests from the internet then pass them on to the target MV4th16 Web server and the Proxy Web server uses an SSL connection then the basic authentication can be used in a secure manner on the open internet.
The Web server example can be run by executing the forth word WEB on the target system console while connected via a serial connection. After the Web server starts pressing the ESC key at the console will stop the web server. The Web server will display debug information on the serial console if debug mode is enabled. You can enable/disable debug mode by pressing the TAB key. Once the server on the target system starts it will begin to listen for TCP connections on the port number specified in the network settings (default 9999).
To connect to the web server use your favorite HTML5 capable web browser and navigate to the URL "http://[IP address]:[port]/demo". So if your target system IP address is 192.168.0.88 and the port is set to 9999 you would enter the URL "http://192.168.0.88:9999/demo" in to you browser address bar. When you connect you will be asked for the user name and password to log on to the site. Set the user name to "admin" and the password to "password". If you have changed the admin user password supply the new password. The example has three accounts; "admin", "user" and "guest". The admin and user accounts have a default password of "password" and the guest account has no password. The account passwords can be changed by executing the forth word user-add from the target system console. Guest accounts should have there authentication level set to less then 10 (1..9). System user accounts should have an authentication level of 10 or higher (10..98).
The web server example limits each level of user (admin, system user, guest) to a specified set of restrictions;
- admin -- can access all web server features.
- user -- can not change target system clock, or list content of block page containing user database.
- guest -- can not alter user account password, can only view status of target system.
Log on using guest account limits access to target system status
Log on using admin account for full access to site features
