PROGRAMMER GUIDE

for v2 routers

USED SYMBOLS

Used symbolsDanger – important notice, which may have an influence on the user’s safety or the functionof the device.

Attention – notice on possible problems, which can arise in specific cases.

Information, notice – information, which contains useful advice or special interest.

GPL licenseSource codes under GPL license are available free of charge by sending an email to:

info@conel.cz.

Conel s.r.o., Sokolska 71, 562 04 Usti nad Orlici, Czech Republic

Manual issued in CZ, November 5, 2014

i

CONTENTS

Contents

1 Introduction 1

2 Compiler installation 2

2.1 CoLinux installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.2 Starting the Linux distribution in CoLinux . . . . . . . . . . . . . . . . . . . . . . 52.3 Compiler installation in Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Structure of the user module 8

4 Features of the user module 10

4.1 Add module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.2 Delete modul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.3 Update module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.4 Access to the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Sample project structure 12

5.1 Directory etc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.2 Directory www . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.3 Directory source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.4 Example of makefile for the sample project structure . . . . . . . . . . . . . . . 13

5.4.1 Sample makefile in the source directory . . . . . . . . . . . . . . . . . . 135.4.2 Sample makefile in the directory of project . . . . . . . . . . . . . . . . . 14

6 Compilation of the user module 15

7 Uploading of the user module 16

ii

LIST OF FIGURES

List of Figures1 Cooperative Linux – installation, step 1 . . . . . . . . . . . . . . . . . . . . . . . 22 Cooperative Linux – installation, step 2 . . . . . . . . . . . . . . . . . . . . . . . 23 Cooperative Linux – installation, step 3 . . . . . . . . . . . . . . . . . . . . . . . 34 Cooperative Linux – installation, step 4 . . . . . . . . . . . . . . . . . . . . . . . 35 Cooperative Linux – installation, step 5 . . . . . . . . . . . . . . . . . . . . . . . 46 Cooperative Linux – installation, step 6 . . . . . . . . . . . . . . . . . . . . . . . 47 Starting the Linux distribution in CoLinux – step 1 . . . . . . . . . . . . . . . . . 58 Starting the Linux distribution in CoLinux – step 2 . . . . . . . . . . . . . . . . . 59 Compiler installation – step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710 Compiler installation – step 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 Configuration file init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912 Directory source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213 Makefile in the source directory . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314 Makefile in the directory of project . . . . . . . . . . . . . . . . . . . . . . . . . 1415 Compilation of the user module . . . . . . . . . . . . . . . . . . . . . . . . . . . 1516 User modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617 Added user module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

iii

1. INTRODUCTION

1. Introduction

This manual describes the structure, programming method and uploading user modulesinto the router. User module is used to run special applications in the router.

For user modules is reserved part of the FLASH memory of 2 MB size, which is not erasedwhen you update firmware. This part is connected to the /opt directory, where directories foreach module are created. Modules can use 128 kB MRAM memory size to save data. It isconnected to the directory /var/data. Each module can create a subdirectory corresponding tothe name of module in this directory.

To install the compiler is required operating system Linux (for example CentOS or Fedora).For Windows OS is described in sections 2.1 CoLinux installation and 2.2 Starting the Linuxdistribution in CoLinux how to install the virtualization of Linux and subsequent running FedoraLinux distribution.

1

2. COMPILER INSTALLATION

2. Compiler installation

2.1 CoLinux installation

First, download the program coLinux for virtualization of Linux from the following link http://sourceforge.net/projects/colinux/files/. After starting the installation, the followingscreen is displayed. For the next step of the installation press Next button.

Figure 1: Cooperative Linux – installation, step 1

In the next step of the installation it is displayed window with information about the licenseof coLinux. For the next step of the installation press I Agree button.

Figure 2: Cooperative Linux – installation, step 2

2

2. COMPILER INSTALLATION

Now select the location of the installation of coLinux. Location can be changed by pressingthe Browse button. As the default location is recommended root directory. For the next step ofthe installation press Next button.

Figure 3: Cooperative Linux – installation, step 3

For proper operation of the network is needed to install the WinPCAP program. Downloadthe program from the address http://www.winpcap.org/install/ and then install it. Afterinstalling WinPCAP press Next button for the next step of installation.

Figure 4: Cooperative Linux – installation, step 4

3

2. COMPILER INSTALLATION

The next step is selection of used Linux distribution. For used C compiler should be in-stalled Fedora 10. To start the installation press Install button.

Figure 5: Cooperative Linux – installation, step 5

Now, coLinux is installed and it is downloaded the image of Fedora Linux distribution. Afterinstallation is complete, press Finish button.

Figure 6: Cooperative Linux – installation, step 6

4

2. COMPILER INSTALLATION

2.2 Starting the Linux distribution in CoLinux

In the directory with installed coLinux is an archive with the image of a Fedora Linux. Tostart the archive is available exe file with the name of this Linux distribution. It is displayedwindow, which is shown in the picture below. To extract the archive press Install button.

Figure 7: Starting the Linux distribution in CoLinux – step 1

Now, the archive is extracted. After extracting all the images, the wizard will be automati-cally terminated.

Figure 8: Starting the Linux distribution in CoLinux – step 2

5

2. COMPILER INSTALLATION

Now it is possible to run Linux Fedora using the start-Fedora-10.bat file.

We will also need to connect a folder in Windows to Linux due to exchange files. To connectthe folder is needed to perform the following two steps. First it is necessary to modify the bootfile start-Fedora-10.bat. At the end of the file must be attributed name of the folder, which willbe connected as a partition cofs0.

Example of a file with address of connected folder c:/work/linux/:

colinux-daemon.exe kernel=vmlinux initrd=initrd.gz mem=256 cobd0=fedora/Fedoraf10.imgcobd1=fedora/swapf10.img cobd2=fedora/homef10.img root=/dev/cobd0cofs0=c:/work/linux/ ro eth1=tuntap

Then run Fedora Linux distribution and mount cofs0 partition defined in the startup fileusing the following command: mount –t cofs 0 /mnt.

2.3 Compiler installation in Linux

Installation files of a compiler are available on www.stlinux.com or after registration onConel company website (www.conel.com).

In case of Fedora or CentOS distributions, it is necessary to install these RPM files:

stlinux23-arm-bash-3.0-13.arm.rpmstlinux23-arm-filesystem-1.0-12.arm.rpmstlinux23-arm-glibc-2.6.1-60.arm.rpmstlinux23-arm-glibc-dev-2.6.1-60.arm.rpmstlinux23-arm-info-4.8-4.arm.rpmstlinux23-arm-libgcc-4.2.4-60.arm.rpmstlinux23-arm-linux-kernel-headers-2.6.27_stm23_0028-41.noarch.rpmstlinux23-arm-ncurses-5.5-9.arm.rpmstlinux23-arm-ncurses-base-5.5-9.arm.rpmstlinux23-arm-netbase-4.34-7.arm.rpmstlinux23-cross-arm-binutils-2.18.50.0.8-24.i386.rpmstlinux23-cross-arm-cpp-4.2.4-55.i386.rpmstlinux23-cross-arm-distributionutils-1.14-5.i386.rpmstlinux23-cross-arm-filesystem-1.0-4.noarch.rpmstlinux23-cross-arm-gcc-4.2.4-55.i386.rpmstlinux23-host-distributionutils-2.8.4-4.i386.rpm

6

2. COMPILER INSTALLATION

In the directory with the above rpm files, run the command to install the compiler: rpm–ignorearch -ivh *.rpm.

Figure 9: Compiler installation – step 1

For Debian operating system is available archive Router_Toolchain.tgz. Only extract it, noinstallation is needed. For all Linux distributions add the path for running the compiler in thehome directory in the file .bash_profile:

PATH=$PATH:/opt/STM/STLinux-2.3/devkit/arm/bin

Figure 10: Compiler installation – step 2

7

3. STRUCTURE OF THE USER MODULE

3. Structure of the user module

example.tgz

u example

– etc

• init• name• settings• version

– www

• *.cgi• *.html• .htpaswd

– other folders

User module consists of a directory named by a module name. Module name can containup to 24 following characters ’a’-’z’, ’A’-’Z’, ’0’-’9’ and ’_’. This directory must contain etc andwww directories. It may also contain any other user directories. We recommend that files inthese directories do not contain spaces in the name.

etc directory can contain the following configuration files:

• name – This configuration file contains the module name, which will be displayed in theweb interface of the router. It is possible to define any name without characters or lengthrestriction.

• version – This configuration file contains information about the module version. Therecommended format is (rrrr-mm-dd). Example: 1.0.0 (2011-05-30).

• settings – In this configuration file, module can save the configuration, which will bebacked up in compliance with the prescribed form when the backup configuration. Vari-ables must be defined in the following form:

MOD_<Project name>_<variable name>="<value>"

An example may thus be: MOD_EXAMPLE_ENABLED=1.

• init – This configuration file defines an initialization script, which can be called with thefollowing parameters:

– start – User module starts automatically with the start parameter when starting therouter or after installation of a module.

8

3. STRUCTURE OF THE USER MODULE

– stop – User module starts automatically with the stop parameter before uninstallingthe module.

– restart – User module does not start automatically with the restart parameter. It canbe called only by the user.

– status – User module does not start automatically with the status parameter. It canbe called only by the user.

– defaults – User module starts automatically with the defaults parameter after in-stalling the module or when you press RST button.

Figure 11: Configuration file init

www directory contains the web pages and compilated cgi scripts. It may also contain afile .htpasswd for securing access to the module. If this file is not listed here, web configurationof module is not secured.

If you want to use the same password as for accessing the router’s web configuration,create a link to a file /etc/htpasswd.

The entire user module is first packed with tar archiving utility and then compressed usinggzip. The resulting archive has the extension tgz.

9

4. FEATURES OF THE USER MODULE

4. Features of the user module

4.1 Add module

After adding the module in the router’s web interface, module is first copied to a directory/opt. Then a new module starts by calling these scripts.

• /opt/<name of module>/etc/install

• /opt/<name of module>/etc/init with parameter "defaults"

• /opt/<name of module>/etc/init with parameter "start"

4.2 Delete modul

The current module is stoped by calling the following script:

• /opt/<name of module>/etc/init with parameter "stop"

• /opt/<name of module>/etc/uninstall

Subsequently, /opt/<name of module> and /var/data/<name of module> directories aredeleted.

4.3 Update module

First, the existing module is stoped by calling the following script:

• /opt/<name of module>/etc/init with parameter "stop"

Then it backs up its configuration from opt/<jméno modulu>/etc/settings file and this mod-ule is deleted from the directory /opt/<jméno modulu>. The new module is then copied to adirectory /opt. After copying, the new module starts by calling this script:

• /opt/<name of module>/etc/init with parameter "defaults"

Now the backup configuration transferred to the new module. The module is started bycalling the following script:

• /opt/<name of module>/etc/init with parameter "start"

10

4. FEATURES OF THE USER MODULE

4.4 Access to the system

User module is started as root, which means it has full access to the system.Access to serial lines should be cared using file check and creation (locks) in directory

/var/lock. Before opening the serial line must be created a lock in directory /var/lock with aname composed of string LCK.. and device name. For example, for device /dev/ttyS0 lockwill have a name LCK..ttyS0. In this file is inserted process identifier (PID) defining a processrunning on an open device. PID contains the end of the line and from the left is filled in byspaces to 11 characters. (E.g. for process 5634: space, space, space, space, space, space,5, 6, 3, 4, end of line). After working with the device, lock must be deleted.

11

5. SAMPLE PROJECT STRUCTURE

5. Sample project structure

The structure of the sample project of a user module named example is shown below. Theformat and content of the files is described in the following chapter.

example

• merge

– etc

– www

• source

5.1 Directory etc

ETC directory contains configuration files as described in chapter 3 Structure of the usermodule.

5.2 Directory www

WWW directory contains web pages of a user module. If this directory contains index.htmlor index.cgi page, it will be referred to this page from the menu of user module in the routerconfiguration.

5.3 Directory source

Source directory contains source codes of the user module and makefile used for compi-lation of source codes.

Figure 12: Directory source

12

5. SAMPLE PROJECT STRUCTURE

5.4 Example of makefile for the sample project structure

5.4.1 Sample makefile in the source directory

Furthermore, in the source directory and in the root directory of the project must be Makefileprovides the compilation of source codes. Below is described makefile for the compilation ofsource codes of the user module.

• CC – The variable CC defines used compiler. For the processor architecture in the routermust be used arm-linux-gcc compiler.

• CFLAGS – The variable CFLAGS defines parameters with which the compilation will bestarted.

• MODULE_EXE – Variable MODULE_EXE defines the name of the final binary file.

• MODULE_OBJ – Variable MODUELE_OBJ defines all objects of the user module.

• ALL – Section ALL is performed, if program make starts without parameter. This sectioncompiles source files defined by the compiler.

• CLEAN – Section CLEAN is performed, if program make starts with parameter clean.This section provides deleting all files having an extension o.

• INSTALL – Section INSTALL is performed, if program make starts with parameter clean.Install section installs source files to the destination directory www.

Figure 13: Makefile in the source directory

13

5. SAMPLE PROJECT STRUCTURE

5.4.2 Sample makefile in the directory of project

• MODNAME – This variable defines the name of the module.

• TEMPDIR – This variable defines directory name for the location of temporary files.

• DESTDIR – This variable defines location of direcoty with user module.

• ALL – Block ALL is performed when make program is called. This block calls the pro-gram make in the source directory and the resulting project packed to the tgz archive.

• CLEAN – Block CLEAN is performed when make program is called with parameter clean.This block calls the program make with clean parameter in the source directory.

Figure 14: Makefile in the directory of project

14

6. COMPILATION OF THE USER MODULE

6. Compilation of the user module

If the project is prepared in accordance with chapter 2 and compiler correctly installed inaccordance with chapter 1, everything is ready to compile a user module.

First it is necessary to get into the directory with a module project. Compilation is startedusing make command and cleaning of auxiliary files using make clean command. Compiledproject can be found in the directory of this project. The file format is the project name with theextension tgz.

Figure 15: Compilation of the user module

15

7. UPLOADING OF THE USER MODULE

7. Uploading of the user module

Compiled user module is loaded into the router via the router’s web interface. In the Cus-tomization part of the menu select User Modules item. On this page, it is possible to add newmodules, delete them or switch to their configuration. Use the Browse button to select the usermodule (compiled module has tgz extension). The module is added using the Add button.

Figure 16: User modules

Added module appears in the list of modules on the same page. If the module containsindex.html or index.cgi page, module name serves as a link to this page. The module can bedeleted using the Delete button.

Updating of the module can be done in the same way like adding a new module. Modulewith a higher (newer) version will replace the existing module. The current module configura-tion is kept in same state.

Figure 17: Added user module

16