# # # @(#) GS3 Technologies Inc. Embedded TCP/IP Software FAQ and user manual. # About this file $Revision: 2.0.0.1 $ $Date: 2005/12/13 16:46:17 $ Maintained-by: GS3 Technologies Inc. This file is both a user manual and a FAQ. Some sections are composed of Q&A while others just offer information. Note 1. All hardware related information, provided below, is specific to the GS3 Technologies, M8722NF system board. Note 2. The M8722NF system board could run any software that is compiled for the Microchip architecture. However, all software related information, provided below, is specific to the GS3 Technologies TCP/IP Software. This software is only available with the MB8722NF-D Development System. GS3 also provides a slightly modified version of the Microchip TCP/IP stack. This software has only a few changes needed to run on the M8722NF board. This version of the software is available to everyone, as a download, from the GS3 Web Site. GS3 Technologies strives to create perfect documentation. However, if you think that we should add or change something, please contact us at support@gs3tech.com. Thank you for using our products! --------------------------------------------------------------------- 1. General Questions 1.1. What do I need to compile the software? 1.2. Is Linux the only platform supported? 1.3. What Linux Distribution is the software supported under? 1.4. Why do you use the Hitech Compiler? 1.5. Do I need Salvo? 1.6. Why did you use the Microchip stack as a base? 1.7. How much of the original software is still there? 1.8. Why not start from scratch? 1.9. Does the license mean that you cannot GPL the software? 1.10. How do you build the software? 1.11. What editor do you use? 1.12. The source files are not formatting correctly when I use vi/vim. Why? 2. Hardware Architecture Questions 2.1. What hardware does the software support? 2.2. Is the Microchip PICDEM.net board supported? 2.3. How many timers are supported and used? 2.4. How many I/O lines are free? 2.5. How do I access the I/O ports and lines which are free? 2.6. How do I access the system LEDs and what is their function? 2.7. Can the system LEDs and switches be accessed from a front panel? 3. Configuration, compilation and getting started with the software 3.1. Configuration 3.2. User modifications 3.3. Compilation information and analysis 3.4. Making changes to the Salvo source code and the "buildit" script. 3.5. Adding user modules 3.6. How is the cdbx utility used for debugging? 3.7. What other utilities are available? 4. Serial port communications 4.1. How is the serial port I/O implemented? 4.2. Where do I change the default baud rate? 4.3. Can RTS/CTS handshaking be disabled? 4.4. What do the different USARTx functions do? 4.5. How do I add more commands? 5. I2C Bus Services 5.1. What services are available for I2C Bus access? 5.2. Is there a sample program I can look at? 6. TCP/IP services. How does the networking system work? 6.1. Overview 6.2. Where do I start in understanding the source code? 6.3. Low level access 6.4. Higher level access 6.5. Network servers 6.6. Network clients 7. NTP Timing services 7.1. Timing system details 7.2. Timing system commands 7.3. Timing related hardware features 8. Web/HTTP Services 8.1. How does the HTTP Server work? 8.2. How much memory does it use? 8.3. What variables are defined for substitution in the HTTP response? 8.4. Where is the web site update software? 9. Telnet and FTP services 9.1. Overview of the Telnet server 9.2. What is the default telnet userid and password? 9.3. How do I change the Telnet password? 9.4. How do I add more commands? 9.5. How do stress test the Telnet server? 9.6. Where is FTP? 10. MB87222NF-D Development System questions 10.1. Overview of the Development System 10.2. Providing power to the MBDEV-A Development Board 10.3. MBDEV-A - Accessing the I/O pins 10.4. MBDEV-A - I2C Bus pins 10.5. MBDEV-A - INTX, SYNC and DCD pins 11. Complete List of System Commands --------------------------------------------------------------------- 1. General Questions 1.1 What do I need to compile the software? The software build requirements are: 1. Hitech PICC-18 Compiler Version 8.35PL3 or later. 2. Salvo Version 3.2.3 PRO (the full source code version) or later. 3. A Microchip Development or Programming environment where the MCU will be programmed after the software has been compiled. The Microchip ICD2 programmer is perfect for this purpose. GS3 Provides the appropriate Linux based tools to compile the software but you still need the hardware programmer. 1.2. Is Linux the only platform supported? GS3 Technologies Inc, uses Linux for all internal software development. We made a choice, a long time ago, to use Linux as our primary environment. In the future we might provide support for Windows users, but at the present we are concentrating our resources on Linux. 1.3. What Linux Distribution is the software supported under? We have tested the software under Slackware and Fedora Linux. Our testing and day-to-day work is done on Slackware. Actually, any Linux distribution that is supported by Hitech should also work. 1.4. Why do you use the Hitech Compiler? First, Hitech PICC-18 is an excellent compiler. It allows us to build a very custom software system in a very efficient way. The other reason is that it supports Linux. 1.5. Do I need Salvo? The GS3 Software distribution uses Salvo extensively. Salvo provides the RTOS to multitask and as a result we get high performance from our hardware. The original, Microchip provided, stack used a different method to multitask (namely a State machine). We decided that Salvo provided a superior way to accomplish our multitasking needs. 1.6. Why did you use the Microchip stack as a base? We believe that Microchip created a very good product which served their developers well. We needed more from the software so we decided to do a re-write. 1.7. How much of the original software is still there? The IP, ARP, DHCP and ICMP modules have a small(to medium) number of modifications. The rest of the system has been mostly re-written. 1.8. Why not start from scratch? There was no need to do so. The Microchip stack is a very good place to start. Why re-invent the wheel? 1.9. Does the license mean that you cannot GPL the software? GPL is not always the right license. We agree with Microchip that the software should only be used on products that we develped. All we are saying is: We give you the software for free, please use it on our boards and systems. And as far as GPL based TCP/IP stacks are concerned, we think that the best stack is Linux itself. We are not about to compete with that! 1.10. How do you build the software? We use all command line tools: make, bash scripts etc. We program the MCU from Windows using the Microchip MPLAB IDE development environment. 1.11. What editor do you use? Vim 1.12. The source files are not formatting correctly when I use vi/vim. Why? To fix this, use the command: :tabstop=4 in your editor settings --------------------------------------------------------------------- 2. Hardware Architecture Questions 2.1. What hardware does the software support? Currently, our software only supports the M8722NF Board. However, we also provide a patched version of the Microchip Stack (V2.20.01.01)which can be used instead. 2.2. Is the Microchip PICDEM.net board supported? The Microchip board is not currently supported. The main problem is that the 18F452 MCU (used by the PICDEM.net) does not have enough resources for the GS3 software. However, it might be possible to support a scaled down version. We have not tested this. 2.3. How many timers are supported and used? The 18F8722 MCU has 5 timers(0-4). When the software uses NTP and local synchronization, we use 4 timers(0-3). TIMER0 - Is the multitasking timer. TIMER1 - Is the Real Time Clock(RTC) timer. TIMER2 - Is used as the 1PPS pulse generator. TIMER3 - Is used as the system clock timer. The time sync module is the biggest user of timers. 2.4. How many I/O lines are free? The following ports and I/O lines are free: PORTA - 5 PORTB - 3,5 PORTC - 0,1 PORTE - 7 PORTF - 5,6,7 PORTG - 0,1,2,3,4 PORTJ - 0-7 PORTH - 0-7 2.5. How do I access the I/O ports and lines which are free? All the I/O lines and I2C bus are accessed from the I/O connectors on the right side of the board. The development board (MBDEV-A) has a breakout section for all free I/O pins. 2.6. How do I access the system LEDs and what is their function? User defined LEDs are PORTA lines 0-2. By default the software uses these LEDs as follows: LED0 - System heartbeat LED1 - System sync LED. This LED will light when the system has synced with NTP. LED2 - System Error LED. System errors will make this LED blink. There are a few macros that are specific to LED control. LEDx_light - Will light the particular LED. LEDx_kill - Will turn off the particular LED. LEDx_blink - Will switch status of the particular LED. These macros are defined in the machine.h file. Note: The LEDs that are located next to the NIC connector, are controlled by the RTL8019AS chip. The System Power LED is always on when power is applied to the system. It cannot be turned off. 2.7. Can the system LEDs and switches be accessed from a front panel? Yes! The board can be custom ordered with no system LEDs and no switches. Instead, a 10 pin connector will be installed (right over the System LED area). As a result, the LEDs and switches can be accessed externally, like from a front panel. --------------------------------------------------------------------- 3. Configuration, compilation and getting started with the software 3.1 Configuration The software has been written to be used with the M8722NF system board. We have not tested the software with the Microchip Development Board since some hardware dependencies (namely I/O port availability) are completely different. The software is controlled by the following files: sysconfig.h - Start from here! Most system options are here. System clock frequency, baud rate, and I/O peripheral availability can be set by the user. The file is heavily commented. global.h - A few important system variables can be set from here. Namely: GTEMPBUF_SIZE. For the most part this file does not need to be changed. compiler.h - Some system defines are here. For the most part this file does not need to be changed. machine.h - Some system defines are here. For the most part this file does not need to be changed. macrtl.h - If the ports that control the NIC chip ever need to be changed, check here. For the most part this file does not need to be changed. 3.2 User modifications We strongly suggest that you use RCS for your checkin/checkout. When the software installs, it creates the RCS directory and pre-initializes the source files to the latest version. 3.3 Compilation information and analysis. The sequence of events that get executed, for each compilation, are as follows: 1. "make" is invoked with a file name (for a single file compilation) or "make" by itself compiles and links the software. 2. The ccpicc wrapper script runs and the following steps are performed: 2.1 The compiler environment is prepared via the proper command line arguments. 2.2 The file gets preprocessed by the cdbx utility which expands the "!dxxx" statements. 2.3 The current lastrun.txt file gets copied to the LASTRUN directory. The lastrun.txt file holds the output from the link process. 2.4 The source file gets compiled. 2.5 If a link is also required, the software gets linked together. 3. Then, from Windows and using MPLAB, the project .coff file is imported and then the device is programmed. 4. Next, we test the software and repeat the build process if needed. 3.4 Making changes to the Salvo source code and the "buildit" script When a change is made to the Salvo code, in the salvo directory, the "buildit" script needs to be run so the Salvo library can be re-built. This is a simple process where all you need to do is: From the GS3Stack/source directory: $cd salvo $./buildit This procedure needs to be run whenever you modify the Salvo source code and, most importantly, the "salvocfg.h" file in the GS3Stack/source directory. 3.5 Adding user modules To add your own modules, follow these steps: 1. Create your .c and .h source files. 2. Add your .h files in the Makefile "include files section" 3. Add your .c files in the Makefile "c source files section" 4. Add your initialization routines in the main.c "User Module Initialization" section. 5. If you are using Salvo routines, make sure that you add your task and message queue initialization code in the mxinit.c file. Look for the "User Task Initialization" and "User Message Initialization" sections. 6. If you are not using Salvo and still want to multitask, put your multitask function calls in the main.c multitasking loop. That is all you need. If you will be using any of the system services, provided by the hardware, make sure you use the proper software interface. For example, serial port I/O should be done via the USARTPutChar or USARTPutString functions. If you need I2C bus services, you should use the appropriate message queue to communicate with the I2C bus master handler. Please see the appropriate sections below for more information. 3.6. How is the cdbx utility used for debugging? The cdbx utility is used when we need to add serial output debugging lines to the code. The debugging code exists in the source file as comments so we don't have to alter the source code and add bugs. The first thing to do is put a: // !dbgen on line on the top of the source file. If this line reads: // !dbgen off the file will not be preprocessed. Now, when we get to a line that we need debug info on, we can do this: // // This is a normal c statement line i = 0; // Now we print the value of i before and after the function call //!dbi i i++; //!dbi i When the program gets to this section the following will be printed on the serial port: [0000][0001] Note the four digit representation of the value which is in brackets. // We can even do something more complex //!dbs "Value of of i before,after is: " //!dbi i i++; //!dbs "," //!dbi i //!dbs "\r\n" When the program gets to this section the following will be printed on the serial port: Value of i before,after is: [0000],[0001] The ccpicc program will use the cdbx utility to prepossess the source file and then perform the compile. Please note that the source program is never changed. 3.7. What other utilities are available? The following utilities are included: SM - This is the utility that prints out the size of each object file, sorted in ascending order. It usually invoked as: SM main lmap - This utility prints out the memory map of the project. It usually invoked as: lmap main smap - This file prints out the raw size of each object file unsorted. SM is the front end for this utility. This is not usually invoked directly. The USART I/O functions (in the usartutils.c file) are also quite useful when debugging a program. See Section 4.4 below for examples. --------------------------------------------------------------------- 4. Serial port communications 4.1. How is the serial port I/O implemented? Serial I/O is implemented as follows: Transmit and receive I/O is done via interrupts. When a character is to be sent, it is put on a circular buffer and the TXI bit is set. This interrupts the system and the interrupt routine puts the character in the TXREG. When transmission is complete, the MCU interrupts again and another character is put in the TXREG. When the circular buffer is empty, the system waits for more input. The transmit circular buffer size(TX_BUFF_SIZE) is defined in serial.h. By default it set to 70 characters. For some debugging situations, it might be necessary to increase this number. When a character is received, it is put on the receive message queue and is read via the OS_WaitMsg(MSG_GOT_SERIAL,,,,) function in the serial.c source file. 4.2. Where do I change the default baud rate? The BAUD rate is changed in the sysconfig.h file. This will require a re-compile to take effect. 4.3. Can RTS/CTS handshaking be disabled? Currently the serial I/O functions rely on RTS/CTS handshaking to properly work. In any system, it is always best to know when a receiver can accept more data. Without RTS/CTS we would blindly send data and as a result, some data would get lost. 4.4. What do the different USARTx functions do? All serial I/O functions are defined in the usartutils.c source file. Below is a brief description of the functions. USARTPut - This is the low level function that sends a character to the serial port. This function is not normally used. Instead the USARTPutChar and USARTPutString are used. USARTPutChar - Send a character to the serial port. Possibly block. USARTPutString - Send a string to the serial port. Possibly block. This function returns a pointer to the part of the string that was not sent or NULL if everything was sent. USARTPutByte - This function sends a BYTE to the serial port and optionally, puts brackets around the number. The BYTE is printed as a 2 digit hex number. The number could look like: [00] or 00 USARTPutWord - This function sends a BYTE to the serial port and optionally, puts brackets around the number. The BYTE is printed as a 4 digit hex number. The number could look like: [0000] or 0000 4.5. How do I add more commands? To add another command, you must do the following: From the cmdproc.h file, add the new command to the SYS_COMMAND enum structure. Then, add the new single letter command to the SYSCommandString structure. Then, increment the #define SYS_CNUM 18 line. Now add the appropriate code to the serial.c (or telnet.c) source file which processes the command. --------------------------------------------------------------------- 5. I2C Bus Services 5.1. What services are available for I2C Bus access? I2C Bus is accessed via message queues and semaphores. At first this might seem a bit difficult but the system works quite well. The services provided allow user programs to access the I2C bus in a consistent way that insures all I2C user functions work together. The steps needed to access the I2C bus are as follows: 1. Create a task. 2. The user task requests exclusive access to the I2C bus. Start a "OS_WaitMsg(MSG_I2C_ACCESS, &msgP, OSNO_TIMEOUT, task_label);" 3. Now that we have the I2C bus to ourselves, load the i2c_control structure indicating the I2C bus action needed. 4. Signal the I2C master handler via "OSSignalMsg(MSG_I2C_QUERY, (OStypeMsgP) 1);" 5. Wait for the I2C master handler to signal I/O completion via: "OS_WaitMsg(MSG_I2C_RESPONSE, &msgP, OSNO_TIMEOUT, task_label);" 6. Process the data transferred from the I2C device. 7. Release the I2C bus. This is very important! If the bus is not released all other I2C bus applications will be locked out! To release the bus do: OSProtect(); OSSignalMsg(MSG_I2C_ACCESS, (OStypeMsgP) 1); OSUnprotect(); 5.2. Is there sample programs I can look at? The perfect I2C starter program is the thermal sensor access code. This is in the therm.c source file. It is a very small app that accesses the I2C bus R/O. Other programs are: rtc.c - Relatively complex example. Reads and writes to I2C device. This program accesses the Real Time Clock(RTC). seeprom.c - Medium complexity. Both read and writes to I2C devices. This program accesses the serial EEPROM chips. seepromex.c - This is an optional program which, when compiled in, will give status of the serial EEPROM chips. i2c.c - This is the I2C master controller. All I2C functions access the functions defined here. Warning: The functions in this file are VERY timing sensitive. Be careful when making changes. --------------------------------------------------------------------- 6. TCP/IP services. How does the networking system work? 6.1. Overview The networking part of the software takes up the majority of the system code. We, at GS3 Technologies, have done extensive testing to insure that we have provided our customers with the best software possible. Originally, the software was part of the Microchip PICDEM.net development board. Microchip included the networking software with the agreement that the code is only used on Microchip systems. We decided to start with the Microchip code and add multitasking capabilities using the Salvo RTOS. However, it soon became evident that we needed a major re-write in order to add the features we wanted. After almost two years in development, we have re-written most of the original code and have added numerous enhancements and functions. We think the software, as it exists now, is much easier to work with and it allows much more flexibility for the systems developer. We believe that the software is now ready for real world embedded systems. 6.2. Where do I start in understanding the source code? Perhaps the best way to start is to give an example of a network packet as it arrives in the system and eventually gets processed by the final application code. For this example, we assume that the network packet is an ICMP(ping). 1. A network client sends an ICMP request to our system. 2. The RTL8019AS gets the Ethernet packet, puts it in its queue and asserts the INT pin. The RTL register: ISR reflects the interrupt as well. 3. main() calls the ProcNICINT(), in mac.c. main() invokes ProcNICINT() inside the multitasking loop so the delay in processing network packets is small. 4. ProcNICINT() checks if NICINT_PIN has been asserted. The RTL8019AS ISR register is read and checked for errors. If the INT register reflects ISR_PRX, a message is put in the MSG_GOT_PAK_MAC msg queue. ISR_PRX is set when a packet has arrived successfully with no errors. 5. Task: TaskMACGetHeader(), in macmulti.c, wakes up as a result of the MSG_GOT_PAK_MAC message. The CURRP(CURrent Receive buffer Pointer) register is read from the RTL8019AS. If the CURRP != NICReadPtrS(Our current value of CURRP) it means that we got a proper packet. The Ethernet header is read in from the RTL8019AS. If the header is type: ETHER_IP, ETHER_ARP or a broadcast packet, it is put in the MSG_GOT_PAK_IP message queue. 6. Task: TaskDist(), in netdist.c, wakes up as a result of the MSG_GOT_PAK_IP message. IPGetHeader() is called to find out what kind of IP the packet is from. 7. Since this packet is type ICMP, a message is put in message queue: MSG_ICMP. 8. Task: TaskICMPGetPut(), in icmp.c, wakes up as a result of the MSG_ICMP message. A trasmit buffer is reserved in the RTL8019AS memory via the MACGetTxBuffer() call. The task reads in the entire packet with all the data. IPPutHeader() is called to prepare a transmit buffer in the RTL8019AS memory. IPPutArray() is called to put in additional ICMP data. MACFlush() is called to send the buffer. The receive buffer in the RTL8019AS memory is discarded. 9. The RTL8019AS sends the buffer over the Ethernet cable. A packet that will be processed by a TCP/IP handler (telnet, HTTP, FTP), involves more complexity but the basic structure will be the same. Steps 1-6 are the same for all network packet types. For a much more complex example, let's look at a telnet packet. Steps 1-6 are the same so we continue from step 7. 7. Since this packet is type TCP, a message is put in message queue: MSG_GOT_TCP. 8. Task: TaskTCPProcess(), in tcprcv.c, wakes up as a result of the MSG_GOT_TCP message. FindPacketBuffer() is called to get the next available TCP packet in the packet receive queue. It is possible that multiple MSG_GOT_TCP messages have been pushed in the message queue, since the task: TaskDist() has a higher priority that us. We always need to run FindPacketBuffer() in order to get the packets in proper order. 9. The packet is checksummed and a matching socket is found that is waiting for data. In this case the socket is bound for the telnet server. 10. If the socket is not open yet, we start the open procedure and send a wakeup call to the telnet server. The telnet server will initialize itself as a result of the socket being opened. 11. If the socket is open, the length of the data in the packet is computed and the telnet client is sent a wake up so the data can be processed. 12. An ACK is sent back, to the network client, that corresponds to the TCP/IP packet sequence we just got. 13. From our side, the telnet server wakes up as a result of the wakeup call which arrives via the MSG_GOT_TELNET message queue. All the data is read from the socket, processed and a reply is put in the transmit queue. A TCPFlush() is called to send the data. 14. TCPFlush() eventually calls TransmitTCP(), in tcpxmit.c, to send that packet. TransmitTCP() puts a message on the MSG_TCP_TX queue. 15. TaskTransmitTCP(), in tcpxmit.c, wakes up as a result of the MSG_TCP_TX message. The appropriate message header is built on the transmit buffer in the RTL8019AS memory. MACFlush() is called to send the message over the Ethernet. The transmit buffer is not deleted from memory yet. 16. When the network client receives the data packet (as opposed to a simple ACK) it sends back an ACK of its own. When this ACK reaches us, we release the transmit buffer. This back-and-forth continues until someone decides to close the socket or the connection is somehow dropped. 6.3. Low level access Low level access refers to functions that talk directly with the RTL8019AS chip. All low level networking functions are in mac.c. Note: Care must be taken when changing the code here since much depends on timing. Low level multitasking functions are in macmulti.c. 6.4. Higher level access High level access functions are located in several source files. ARP packets are processed in arp.c and arptsk.c ICMP packets are processed in icmp.c IP packets are processed in ip.c DHCP packets are processed in dhcp.c UDP packets are processed in udp.c TCP packets received are processed in tcprcv.c TCP packets transmitted are processed in tcpxmit.c TCP packet timeout calculations are performed in tcpmulti.c TCP common functions are in tcp.c NTP packets are processed in ntp.c. NTP Synchronization is performed in timesync.c telnet packets are processed in telnet.c http packets are processed in http.c 6.5. Network servers The system, as provided, comes with two network servers. One is telnet and the other is HTTP(web server). Read the sections below on server implementation details. 6.6. Network clients The system, as provided, comes with two network clients. One is NTP and the other is DHCP. These two clients are both UDP based. Currently, there are no TCP based clients defined. However, in the future, SMTP and SNMP are the types of clients that will be provided. --------------------------------------------------------------------- 7. NTP Timing services 7.1. Timing System Details Almost any device that is attached to the Internet requires some sort of time synchronization. Today, this is typicaly accomplished using NTP. NTP is a protocol which allows a client to request the proper time from a server and to provide this time to other clients as well. Please check http://www.ntp.org/ for complete documentation. NTP based timing is a very important feature of the M8722NF system board system software. Time syncronization is accompliced using two systems. When the system boots, the onboard RTC is used to set the system time. If a NTP server is defined, a UDP socket is opened and the UDP time is retreived. After the initial time stamp is processed, the system is slowly synced to NTP using a PD control loop. When the time system achieves stability, the RTC clock is set to NTP time and the system internal timer is the time standard. The system is said to be in sync, with NTP, when the offset from NTP is less that 100ms. When the system is allowed to settle, the offset from NTP is less than 10ms. Although not currently implemented, it is possible to achieve less than 1ms timing with the proper software tuning. The user can get the proper time via the 32 bit unsigned integer: SYSSeconds. The proper way to access the system timer is to use the GetSystemTimer() macro. Here is an example: DWORD Mytime; GetSystemTimer(Mytime); Variable "Mytime" now has the proper time. The SYSSeconds variable provides the time in UTC seconds. Normally, a user will need to use the lctime() and gmtime() functions to get the right time. lctime() formats UTC time to local offset (including DST). gmtime formats time to month, day, year, etc. For an example see the cmdproc.c source file. 7.2. Timing system commands The following commands can be used if #define SYSTEM_TIME_SYNC is set in the sysconfig.h file. These commands can be entered from the serial port command line prompt or the telnet command line prompt. u The "u" command will give the system stats including the NTP Control loop coefficients. set ntp,ip_address e.x. #set ntp,10.0.0.11 set sync,{none|NTP,Sync_interval,Pgain,Dgain} e.x. #set sync,ntp,10,4,1 The first parameter sets the sync type. "none" specifies that no synchronization will be performed. This also excluded RTC clock sync. This is a method to check system drift. "NTP" specifies that system time sync should be done via NTP using the NTP server set. If no NTP server is defined, then time sync will be to the RTC. The second parameter sets the sync interval at which the NTP server will be contacted for a current time stamp. This parameter is specified in seconds. The third parameter sets the Proportional Gain Coefficient for the Time Sync Control Loop. The fourth parameter sets the Differential Gain Coefficient for the Time Sync Control Loop. See the timesync.c source file on how these coefficients are used in the time sync algorithm. T Please note the upper case. The "T" command prints out the time sync values for every time sync operation with the NTP server. This output is continuous until another "T" command is entered. Typical output would be: SYS: 1130456127.820, NTP: 1130456127.814, K: -10, S100ms: 4, SFinal: 4 The first two numbers are the local and NTP values for time. The third number is the correction value that was applied to the local value in order to sync with NTP. The fourth number indicates how many time sync intervals were required to reach below 100ms accuracy. The fifth number indicates how many time sync intervals were required to reach the final time sync value. The fifth number requires a bit more of an explanation. When the system first boots, or is reset, or loses sync, the timesync condition is reset. The timesync interval is started at 5 seconds and the system proceeds to timesync. Remember that "timesync" means <100ms offset from NTP. After the system is synchronized, the timesync interval is doubled and the system timesyncs again. Then, the current timesync interval is compared against the final timesync interval. If we reached the final value, we stop doubling our current value. So, the fifth number refers to the "final timesync interval". 7.3. Timing Related Hardware Features In addition to software time, the system also provides a 1PPS(1 pulse per second) hardware sync signal via the RA4 pin. This pin is connected to a 4.7K pullup resistor and can be accessed via pin 7 of the External Bus Connector. This signal can be used to synchronize external boards. --------------------------------------------------------------------- 8. Web/HTTP Services 8.1. How does the HTTP Server work? This version of the HTTP server is not meant to a complete implementation. It is only a starting point. GS3 Technologies will be implementing more complex versions in the future. The HTTP server, as of version 2.0.0.1, responds as HTTP Version 1.0. The only command implemented in this version is GET. The server can have many sockets open simultaneously, with the maximum number set in "sysconfig.h". The server multitasks the reads from the internal web pages and responses to the web clients. In this implementation, the web pages are in the "index_html.c" file. 8.2. How much memory does it use? HTTP is expensive in terms of memory. Approximately 62 bytes are used for each open connection and about 4K of program memory. In addition, if the user requires it, the number of free memory buffers can be increased, in "memmgt.h" so the HTTP server can respond quicker. This is exremely "RAM" expensive. About 212 bytes are used for each extra buffer. 8.3. What variables are defined for substitution in the HTTP response? The following variables can be included in the HTML page and will be substituted by the server to an appropriate string. In order for the variables to be substituted, they must be prefixed with the two character "$$" sequence. DATELONG - The string will expand to include the complete local date with different device time data. e.x. SYS: 11/06/2005, 0:00:15.460 RTC: 11/06/2005, 0:00:15.860 NTP: 11/06/2005, 0:00:11.953 LOC: 11/05/2005, 19:00:15.460 - EST DATE - The string will expand to include the local date in mm/dd/yy format. TIME - The string will expand to include the local time in hh:mm:ss format. IFCONFIG - The string will expand to include the response from the internal uptime command. e.x. IP: 10.0.0.37, Netmask: 255.255.255.0 Gateway: 10.0.0.11, MAC: 00:04:A3:00:00:00 NTP server: 10.0.0.3, DHCP is Disabled NETSTAT - The string will expand to include the response from the internal netstat command. e.x. Packets Sent: 2403, Received: 2570 NIC I/O Errors: 0, NIC I/O Errors LL: 0 Protocol Errors: 0 UPTIME - The string will expand to include the response from the internal UPTIME command. e.x. Hostname: GS3, Uptime: 0:53:08, I2C Errors: 0 System Temperature: 24 Degrees Celsius Time sync to NTP Interval: 5, PGAIN: 4/128, DGAIN: 9/128, S100ms: 30, Sfinal: 30 VERSION - The string will expand to include the response from the internal VERSION command. e.x. GS3 Embedded System Software Version: 1.5.0.1, Sat Nov 5 18:11:02 EST 2005 (C)Copyright 2003-2005 GS3 Technologies, Inc. TZ - The string will expand to include the response from the internal TZ command. e.x. TZ=EST+5EDT+4,M4.1.0/2,M10.5.0/2 8.4. Where is the web site update software? This version of the HTTP server does not include a program to convert a directory structure to a format that can be read by the HTTP server. Such a program will be available in future versions of the software. The program that Microchip provides, for this purpose, cannot be used. --------------------------------------------------------------------- 9. Telnet and FTP services 9.1. Overview of the Telnet server The telnet server, as is implemented in version 2.0.0.1, is a complete implementation of the telnet protocol. All features, negotiation of different settings, password login and others are provided. 9.2. What is the default telnet userid and password? The default userid is "root". By default, there is no password defined. 9.3. How do I change the Telnet password? The command is: # set pw,new_password 9.4. How do I add more commands? See section 4.5 On adding commands to the serial connection. After the command is added, in cmdproc.c, the telnet.c source file will also need to be changed to process the new command. 9.5. How do stress test the Telnet server? A perl script, called "tnpush", is provided. If the telnet server has a password, then the "tnpush" script will need to be modified (line 34). The tnpush script will send 1 packet per millisecond to the telnet server. This should stress most telnet implementations. 9.6. Where is FTP? FTP is not implemented in version 2.0.0.1 of the software. --------------------------------------------------------------------- 10. MB87222NF-D Development System questions 10.1. Overview of the Development System The "MB87222NF-D Development System"(System) is designed to provide a complete hardware and software testing platform, for the M8722NF Single Board Computer. The primary advantage of the system is that the prototype area is on the MBDEV-A development board. This allows a user to test many different versions of a design, without replacing the main board. After the design is finished, the main board can be used in the completed system. This system design is cost effective solution and a time saver. The System is comprised of the M8722NF single board computer, the MBDEV-A development board, 2 34 pin I/O connection cables, 1 10 pin (I2C Bus)/Power connection cable, a DB9 serial cable, a CAT5 networking cable and a +5V 300mA power supply. The System also includes the GS3 Embedded System Software. Some hardware features of the System include: * All unused PIC 18F8722 I/O pins can be accessed from the development board. * Peripherals for the I2C bus can also be designed and implemented in the development board. * Power can be provided from the Main Board or separately. * Each I/O pin can be connected to an LED or a pullup resistor. If a pin is connected to a pullup resistor, it can then be accessed from the prototype area. 10.2. Providing power to the MBDEV-A Development Board Power to the MBDEV-A can be provided from the main board(via the 10 pin connector) or separately. The MBDEV-A board has its own power connector: JPWR4. If +5V power is connected to both the main board and the development board, the user can select which power source will be used, by putting the appropriate jumper on the JP1 and JP2 headers. There are 4 possible ways to connect a jumper between the pins of JP1 and JP2. None of the possible connections will cause a problem. Please refer to the schematic diagram for reference. 10.3. MBDEV-A - Accessing the I/O pins There are three possible ways to connect the I/O pins on the development board. Method 1 - Direct connection. Using this method, the user just connects a wire from the hole, next to the pin name, to the prototype area. The user then connects a custom circuit on the prototype area. Method 2 - LED connection. Using this method, the user solders a 1K resistor on the "RES" connection next to the pin name. Then, a LED is soldered to the "LED" connection next to the pin name. The user then has his program put the pin "low" and the LED will go on. Keep in mind that the +5V pin is the right one. Solder the LED accordingly. The status of the pin can be monitored by connecting a voltmeter or scope to the hole next to the pin name. Method 3 - Pullup connection Using this method, the user solders a 4K resistor on the "RES" connection next to the pin name. Then, a jumper is soldered to the "LED" connection next to the pin name. Then, the user connects a wire from the hole, next to the pin name, to the prototype area. The user then connects a custom circuit on the prototype area. The I/O pin now has a pullup resistor and the circuit on the prototype area is less cluttered. Note that each pin name has two holes to the left of it. The hole on the right can be used to connect to the prototype area and the hole on the left can be used to monitor the signal. 10.4. MBDEV-A - I2C Bus pins I2C Bus access can be provided, in the prototype area, by connecting to pins SCL and SDA. 10.5. MBDEV-A - INTX, SYNC and DCD pins * The INTX pin is connected to pin RB1 on the 18F8722 MCU. With this connection, a circuit on the prototype area can request a CPU interrupt. * The SYNC pin is connected to RA4 on the 18F8722 MCU. When using the GS3 Software this pin will have a 1PPS signal. Note: This pin has 1 4.7K pullup resistor connected to it. * The DCD pin is connected (via the I/O cables) to pin 1 of the DB9 serial port on the main board. Some systems use this pin to provide a 1PPS timing signal over the RS232 port. Note: The RS232 level connection is not made to the DCD pin. It is up to the user to do this on the prototyping area. In other words, if you need a RS232 level signal on the DCD pin of the serial port, then you must use a TTL-to-RS232 level converter chip. --------------------------------------------------------------------- 11. Complete List of System Commands The command listed below can be antered from the serial command line or the telnet session. Notes: Some commands might be disabled as a result of settings in the "sysconfig.h" source file. The "l" and "T" commands are only available though the serial port. They are used for debugging purposes. Set commands change network related static data only. These settings take effect after the next reboot. Commands are case sensitive. D Debug On After this command is entered, debugging output will be displayed on the serial port. The output might be very heavy or non-existent depending on system activity and settings. d Debug Off All debugging output will be disabled. I Print static IP related info. This will be in effect after reboot. i Print dynamic IP related info. These values might change after reboot. l If defined, this command dumps the TX/RX buffers and the multitasking table to the serial port. n Netstat r Reboot System s Set System parameters default This will restore the system to factory defaults. h Set the system's hostname-Up to 16 chars gw,default_gateway e.x. #s gw,10.0.0.1 ip,ip_address e.x. #s ip,10.0.0.10 mac,mac_address mac_address must be specified in hex e.x. #s mac,00:a2:fb:2c:00:00 netmask,netmask e.x. #s netmask,255.255.255.0 ntp,NTP_time_server_ip_address e.x. #s ntp,10.0.0.2 pw,new_password sync,{none|NTP,Sync_interval,Pgain,Dgain} Enable time syncronization to NTP and setup the Time syncronization control loop coefficients. e.x. #s sync,ntp,10,4,1 tz,STD_name,+/-GMToffset,DST_name,+/-GMToffset,m,w,d,time,m,w,d,time e.x. #s tz,EST,+5,EDT,+4,4,1,0,2,10,5,0,2 - System Default Normal timezone is called: EST and is +5 hours from GMT DST Timezone is called EDT and is +4 hours from GMT DST Start: April, Week 1, Sunday, 02:00 - First Sunday DST End : October, Week 5, Sunday, 02:00 - Last Sunday e.x. #s tz,GMT - GMT Short Format Short Format zones are: UTC,GMT - No DST here EST,CST,MST,PST - Implied USA DST here t Time Display and Stats This command will display the time and date from the System, RTC, NTP and local clocks. Note: If the RTC is busy updating, the output will have the string: "RTC is not responding or busy". This is normal. e.x. #t SYS: 11/09/2005, 4:48:42.040 RTC: 11/09/2005, 4:48:42.180 NTP: 11/09/2005, 4:48:39.230 LOC: 11/08/2005, 23:48:42.040 - EST T Toggle Continuous Syncronized Time Display u System Information v Print System Version y I2C Bus Inventory z Print System Timezone