AVRprog HOWTO ------------- Revision: V0.6 2005-12-28 Check "http://micha.freeshell.org/avr/download.html#AVRprog" for latest version. This document contains step-by-step instructions how to build AVRprog with network support from sources. ================================================================================ Content: 1) What is needed to get it working 2) How to build and test the components 3) How to install ================================================================================ 1) What is needed to get it working ----------------------------------- First you have to understand what is mandatory and what is optional ... AVRprog consist of three main components: Frontend (mandatory): Implements the user interface. This part can be a simple text based command interpreter or a graphical window with buttons and input fields. The 'frontend' uses the 'backend interface' to communicate with the 'backend'. Backend (mandatory): The 'backend' is something like a driver manager. The programmer drivers are part of the 'backend'. The 'backend' is responsible for autodetection of the correct programmer driver and presenting an uniform interface for all drivers to the 'frontend', the 'backend interface'. The 'backend interface' ist the API (Application Programming Interface) of the backend - a set of C function calls in this case. Netlayer (optional): The 'netlayer' is not mandatory! It is an extension of the above construction. It uses a network connection between a client and a server machine (Note: This can be a single machine using the loopback device). A daemon running on the server machine uses the 'backend interface' to access the local 'backend'. On the client machine a 'backend interface' is provided for the 'frontend'. The 'netlayer' is therefore transparent for the 'frontend'. Hardware requirements: ---------------------- - A machine that is capable of running one of the supported operating systems. For DOS an Intel 80286-10 is sufficient. Slower machines are not tested. Note: For RS-232 ports on IBM PCs you *need* at least a 16550A UART. Machines that are fast enough to service unbuffered UARTs have buffered ones onboard ... machines with unbuffered UARTs are not fast enough! Check your UART and use a separate card if you found an unbuffered UART like 8250 or 16450. - Supported programmer Check "http://micha.freeshell.org/avr/AVRprog/AVRprog.html#Backends" and get (or solder it yourself) a programmer that is supported by the desired backend. - [Network interface card] Optional - loopback device is sufficient. Software requirements (not shipped with the sources): ----------------------------------------------------- The following development tools should be installed on your system to compile the packages (The listed ones are tested, others may work too): UNIX: - GNU C compiler (gcc), C++ support is not required Versions 2.91, 2.95, 3.0, 3.3 and 4.0 are known to work (The HP ANSI-C compiler can also be used but needs different flags => They are included commented out in the Makefiles) - GNU make, SystemV make or BSD make - TCL/TK 8.0 or higher - X Window system header files - gunzip decompressor DOS: - Borland C Version 3.1 is known to work - Borland make - pkunzip decompressor - Ethernet packet drivers for your network card A wrapper is included to support Token Ring cards via IBM LanSupportProgram The source code, documentation and this HOWTO can be downloaded from: "http://micha.freeshell.org/avr/download.html#AVRprog" ================================================================================ 2) How to build and test the components --------------------------------------- Only the configuration with network support is described here (Normally there is no reason to omit the 'netlayer'). The components form a stack, the components on the bottom are required by the ones above: 'frontend' 'netlayer client' . . . . . . . . . .(network connection) 'netlayer server' 'backend' Therefore we have to build things in ascending order. So we have to start with the 'backend'. To make it easier to deal with several versions, create the following directories within the location you want to build the package: AVRprog_backend AVRprog_netlayer AVRprog_netlayer/server AVRprog_netlayer/client AVRprog_frontend Shorten the names to 8 characters for DOS versions that cannot handle longer filenames. Building the 'backend' ---------------------- Get the sources and copy them into the "AVRprog_backend" directory. Go into that directory and unpack the archive like this: gunzip backend-Vx.x.tar.gz tar -xvf backend-Vx.x.tar or for DOS: PKUNZIP.EXE BAC_Vx_x.ZIP This creates a subdirectory corresponding with the version number. Go into that subdirectory and check the "LICENSE" and "README" files. Go to the "src" subdirectory. Run the "configure" script to get a list of supported operating systems (Omit this step for the DOS version): ./configure Then run the script again and specify the desired OS on the command line. Example: ./configure LINUX Now compile the 'backend' with: make all Now its time to connect a programmer and a supported AVR. Switch power on the programmer and the AVR. To test the 'backend' go to the "bin" subdirectory. Run the test using: ./backend_test or for DOS: .\B_TEST.EXE Use "--help" as parameter to display what parameters are supported/required. Now you must see some checks running and the message "Test was succesful". If you get an error, the sense code indicates what goes wrong: Sense codes: 0 : No sense data 1 : Interface type not supported 2 : Device file not exist or have wrong type 3 : Cannot open device file 4 : No programmer found 5 : Programmer not enabled 6 : Cannot close device file 7 : Communication error (Programmer driver) 8 : Communication timeout (Programmer driver) 9 : Cannot configure device file 10 : Cannot open network connection 11 : Communication error (Network) 12 : No open network connection 13 : MCU not supported 14 : MCU locked 15 : Programming mode not enabled 16 : Programming method not supported Building the 'netlayer' server ------------------------------ Get the sources and copy them into the "AVRprog_netlayer/server" directory. Go into that directory and unpack the archive like this: gunzip netlayer_server-Vx.x.tar.gz tar -xvf netlayer_server-Vx.x.tar or for DOS: PKUNZIP.EXE SER_Vx_x.ZIP This creates a subdirectory corresponding with the version number. Go into that subdirectory and check the "LICENSE" and "README" files. Now we have to copy the backend libraries (Check the "INSTALL" file of the backend for the files to copy). The libraries must be copied to: /AVRprog_netlayer/server/Vx.x/src/lib The header file(s) must be copied to: /AVRprog_netlayer/server/Vx.x/src/include Go to the "src" subdirectory. Now compile the 'netlayer' server and link it against the backend with: make all Now a binary "AVRprogd" should exists in the "../bin" directory. Go to that directory. Network configuration for DOS (skip for UNIX version): Because DOS has no builtin network support, the complete protocol stack is included in the AVRprog daemon binary. The config file WATTCP.CFG is read on startup to get the IP configuration for the host. A sample file exist, modify it to match your local network interface configuration. After that, execute TCPINFO.EXE in the same directory and verify your configuration. Now start the AVRprog daemon: ./AVRprogd or for DOS: .\AVRPROGD.EXE The UNIX version detach from the terminal and run in background. Messages are logged in the system logfile like this: Dez 01 16:48:58 WStation3 AVRprogd: Startup Dez 01 16:48:58 WStation3 AVRprogd: Version: V0.8 Dez 01 16:48:58 WStation3 AVRprogd: Debug level: 0 Dez 01 16:48:58 WStation3 AVRprogd: Detaching from parent ... Dez 01 16:48:58 WStation3 AVRprogd: Accepting connection on port 10000 DOS is a singletasking system, therefore the DOS version stay in foreground and print messages to the console like this: AVRPROGD.EXE (V0.1) Startup. Debug level: 0 Reading 'WATTCP.CFG' ... Accepting connections on port 10000 The protocol stack included in the DOS version provides an ICMP echo reflector, therefore you can 'ping' your DOS machine after starting the daemon to check the network. The UNIX version wants to place a file containing its PID into the "/var/run" directory. If you get this message: Dez 01 16:49:05 WStation3 AVRprogd: ERROR: Cannot create "/var/run/AVRprogd.pid" Dez 01 16:49:05 WStation3 AVRprogd: Quit you have started the daemon with insufficient permissions to create files into this directory. Adjust permissions or use another account and start the daemon again. Building the 'netlayer' client ------------------------------ Get the sources and copy them into the "AVRprog_netlayer/client" directory. Go into that directory and unpack the archive like this: gunzip netlayer_client-Vx.x.tar.gz tar -xvf netlayer_client-Vx.x.tar This creates a subdirectory corresponding with the version number. Go into that subdirectory and check the "LICENSE" and "README" files. Go to the "src" subdirectory. Now compile the 'netlayer' client with: make all To test the 'netlayer' client, a server must run on the local machine or on a machine accessible via network. Go to the "../bin" directory. Run the test using: ./netclient_test Use "--help" as parameter to display what parameters are supported/required. As hostname you can either use an address or a hostname that your system can resolve to that address. Use "localhost" for loopback to the local machine. The result of the test must be "Test was successful". The 'netlayer' client logs messages in "~/AVRprog_netlayer-client.log" like this: AVRprog netlayer client: Init UNIX Net client (libnetclient.so) V0.6, Protocol V0.0 Debug level: 1 Connect to server 'Server4' ... Using TCP port: '10000' Connection established Disconnect from server ... Disconnected If you get an error, check this file. Building the 'frontend' ----------------------- Get the sources and copy them into the "AVRprog_frontend" directory. Go into that directory and unpack the archive like this: gunzip frontend-Vx.x.tar.gz tar -xvf frontend-Vx.x.tar This creates a subdirectory corresponding with the version number. Go into that subdirectory and check the "LICENSE" and "src/README" files. Now we have to copy the netlayer client library (Check the "INSTALL" file of the netlayer client for the files to copy). The library must be copied to: /AVRprog_frontend/Vx.x/src/lib The header file must be copied to: /AVRprog_frontend/Vx.x/src/include Go to the "src" subdirectory. Now compile the 'frontend' with: make all The 'frontend' binary is created in the "../bin" directory. Check that the X Window system is running or your DISPLAY variable is pointing to an X server on a different machine and that you have permissions to access the display. Go to the "../bin" directory and execute the binary: ./frontend Now a new window must appear. Check that the 'netlayer' server used for the client test is still running. Specify the server machine and programmer port names in the corresponding fields. Set the programmer port type by clicking on the corresponding button. Click on the "Read device code" button. Now the type of the connected MCU must be displayed and the status lines on the bottom are updated. If an error occur, a window is opened which specify the problem. Note: If you want to work with Intel HEX file format, you need our optional converters available from: "http://micha.freeshell.org/avr/download.html#Converters". The frontend must be able to find them via the system search path. Now the build is complete and things are working. If you want to be able to start the server and frontend from any location, read the next section. ================================================================================ 3) How to install ----------------- If you want to use the 'frontend' and the 'netlayer' server on the same machine, you should install them in different directories. Otherwise a name collision would occur or both programs would try to use the same library in "./lib" (to make the 'netlayer' transparent, the client library is accessed via a link with the same name as the 'backend' library). To install the 'netlayer' server, copy the "/AVRprog_netlayer/server/Vx.x/bin" directory to the desired location and rename it if you want. Create a start script (you can also use the name "AVRprogd" for the script) somewhere in the system search path (for example in "/usr/local/bin") like this: #! /bin/sh echo "Change directory ..." cd echo "Starting daemon ..." ./AVRprogd or for DOS (Script name must have extension '.BAT'!): @ECHO OFF ECHO Change directory ... CD ECHO Starting daemon ... .\AVRPROGD.EXE To install the frontend, copy the "/AVRprog_frontend/Vx.x/bin" directory to the desired location and rename it if you want. Create a start script named "AVRprog" somewhere in the system search path (for example in "/usr/local/bin") like this: #! /bin/sh echo "Change directory ..." cd echo "Starting AVRprog frontend ..." ./frontend echo "AVRprog frontend terminated." Set the "execute" attribute for both scripts: chmod 755 /AVRprogd chmod 755 /AVRprog Now you should be able to start AVRprog from any location by typing (if your programmer is connected to your local machine): AVRprogd AVRprog or simply (if your programmer is accessible via network): AVRprog That's it. Enjoy! Michael Baeuerle