LARA/LARA eco OEMing  ... Documentation, 2004-06-08
---------------------------------------------------

This document describes how to change the look of the frontend and some other
vendor-specific options using an OEM mechanism.

Contents
--------

1. Requirements
2. Package Content and its purpose
3. What may be changed and how
4. Setup a development environment for the webpages on a running firmware
5. Packaging and adding the OEM content to a firmware

1. Requirements
----------------------------------

This package in its current state is usable when the development
environment provides the following tools and possibilities:
-perl (mandatory, to add the preparated oem file to a firmware binary)
-SMB share (mandatory, to test the changed webpages)
-openssl (optional, to recreate the default SSL keys/certificates)
-md5sum (optional, to change the password of the default users)

Best is a Linux environment or a similar one in another operating system
providing the necessary tools and commands (e.g. cygwin in win32).

2. Package Content and its purpose
----------------------------------

aspfunctions.txt
 Documentation for the asp functions used throughout the web
 pages. Intended for reference only, not as an API. (Most functions have their
 special place in one of the forms and need to stay there, but there are some
 generic ones, e.g. boardName() )

forms-lara.txt, forms-rc1.txt
 Documentation of the various webpages and form parameters submitted in
 them. Shows which fields/parameters are expected and need to be present in the
 forms.

oem.tgz
 OEM data templates, the actual content. Such a file may be added to a firmware
 binary when the OEM changes are complete. Its content is described in section 2.

3. What may be changed and how
------------------------------

The oem.tgz file consists of various files, which influence the look and
behaviour of the devices. It is only necessary to add the files which really
should be changed or for instance additional logos wo the webpages directory. It
is not necessary to provide the whole package and add it to the firmware as
there are fallbacks for the whole content.
The maximum uncompressed size of the whole OEM must not exceed 512 KByte.

boardname
 The name of the device (e.g. LARA eco), used in the whole web frontend. This
 can be accessed from the web pages with the function boardName(). 

ericcert_default.pem
erickey_default.pem
 The default SSL key and certificate, utilized when the user did not create a
 certificate by himself. These two files may be generated with the openssl
 toolkit and the following steps, providing a root CA was already created:

 openssl req -nodes -days 1825 -newkey rsa:1024 -keyout erickey_default.pem -out req.pem 
 openssl ca -in req.pem -out ericcert_default.pem -days 1825 

oem.cdl
 OEM dependent default configuration options for device and users.
 User data has to contain a login name which is located in the option
 'login'. The password is an md5 encrypted hash in the 'pw_hash' option. 
 Such a string can be generated with the following commands:

 echo -n desired_password > /tmp/temp_file && md5sum /tmp/temp_file

webpages
 The complete web environment consists of the actual webpages (.asp), images
 and a style file (style.asp). For small color modifications changing the
 documented style file should be sufficient. You may add new images etc. and
 change the webpages, but please keep in mind that the interface to the internal
 code (the forms and the function calls) need to remain as it is.

4. Setup a development environment
----------------------------------

To test especially the webpages it is necessary to use them on an running device,
as there is active content involved.
To start the development boot a firmware supporting the mechanism, log in to the
device and enter the hidden page URL '__oem.asp' for LARA based devices or
'r1_oem.asp' for LARAeco based devices.
You will see the option "OEM development mode". Check it and enter data needed
for an SMB share (hostname, share name and optionally username and
password). The device will try to connect to this SMB share and, if successful,
use the OEM data provided there from now. It will look for the data as listed in
section 2, if a file does not exists the compiled-in default will be used.

The webpage content is accessed directly from this share, so you may change the
webpages and will immediately notice the effects. Most other data needs to be
activated by pressing 'Apply' at the OEM webpage again. Exception are the
default configuration values and user login data, which will only be activated
when resetting the device.

Additionally it is possible to create a .ZIP file with the OEM related content
and upload it using the section "OEM Upload Settings". During upload the old content
will be deleted and the new one from the .ZIP file will be used immediately.
In this section there is also a "Delete" button which reverts all OEM changes
and deletes the according files on the device.

5. Packaging to a firmware
--------------------------

After the changes are done, they may be added to an already existing final
firmware binary file.
To do this, a perl script 'replacepart.pl' is used. See replacepart.txt for a
description of its usage.
