--------------------------------------------------------------------------
Homenet3D for OpenWRT (v0.2): Startup            (released 26th June 2014)
--------------------------------------------------------------------------

This document is part of Homenet3D for OpenWRT:
http://caia.swin.edu.au/urp/homenet3d/openwrt

It provides instructions for installing OpenWRT firmware and Homenet3D 
package on the TP-Link WR-1043ND.

For instructions on installing firmware, see: 
http://caia.swin.edu.au/urp/homenet3d/downloads/homenet3d-installing-firmware-v0.2.txt


INTRODUCTION
------------

This guide provides instructions on how to start and access the Homenet3D 
virtual world after installing Homenet3D OpenWRT firmware on a router or
a emulated embedded system.

The Homenet3D server and it's helper scripts are triggered to start as 
daemons with the system start. The three executables are:
  - /bin/homenet3D-server
  - /bin/sys-state
  - /bin/datarate

The 'homenet3D-server' executable is a C program that provides 
communication between to clients and the router over WebSockets(10001) 
as well as accepting constant updates about system state from the 
'sys-state' script on local UDP port 27960.

The 'sys-state' script checks system state every second and sends the 
updates to 'homenet3D-server'. Every 5 seconds the script will send 
all system state information in full, in order to make sure all 
information is correct and up-to-date.

The 'datarate' script calculates the average data being passed through the 
ethernet ports and writes this to files which are read by the system state 
script and in turn sent as an update to the homenet3d-server.


STARTING THE SERVER
-------------------
To run the firmware on the TP-Link WR-1043ND please see section STARTING 
THE SERVER (ARM/MIPS).

To run the firmware in a QEMU emulated ARM or MIPS environment please see 
section STARTING THE SERVER (ARM/MIPS).


STARTING THE SERVER on TP-Link WR-1043ND
----------------------------------------

Then the Homenet3D world will be accessible on your router. Use the router's
IP:
(e.g) http://192.168.1.1/www-threejs


STARTING THE ARM/MIPS SERVER under Qemu
---------------------------------------

In order to get an idea of how this server would run on embedded 
architecture you can use a emulation program called QEMU to run the 
firmware.

For more information on QEMU, please visit: http://www.qemu.org

You will need a QEMU version of 1.6.0 or later. From the command the 
following commands will give you a command line based emulation:

For ARM:
  ~: qemu-system-arm -M realview-pbx-a9 -kernel openwrt-realview-vmlinux.elf \
     -m 128m -nographic -redir tcp:2200::22 -redir tcp:8080::80 -redir tcp:10001::10001
		
For MIPS:
  ~: qemu-system-mipsel -M malta -kernel openwrt-malta-le-vmlinux-initramfs.elf \
     -m 128m -nographic -redir tcp:2200::22 -redir tcp:8080::80 -redir tcp:10001::10001
		
If you have built your own image (rather than our pre-built ARM/MIPS images)
you will need to run:

  ~: udhcpc -i br-lan

(to bind the main network interface to a NAT once the system has started)

Then the Homenet3D world will be accessible at: 
http://localhost:8080/www-threejs

To simulate system state there is a Lua script located at /root/demo.lua
(this script runs automatically when using our pre-built ARM/MIPS images)


IF SOMETHING GOES WRONG
-----------------------

In order to troubleshoot and resolve issues with Homenet3D you will need 
SSH access to the router. You may need to enable this via the OpenWRT web 
interface (under Administration).


CONTRIBUTIONS
-------------

We welcome your feedback and contributions! If you have discovered a bug,
have a request for a new feature, have produced a code patch or a new 
classifier model, please contact:
Grenville Armitage (garmitage@swin.edu.au)
Dominic Allan (dallan@swin.edu.au)


CONTACT
-------

The Homenet3D website is: http://www.caia.swin.edu.au/urp/homenet3d

If you have any questions or want to report any bugs please contact:
Grenville Armitage (garmitage@swin.edu.au)
Dominic Allan (dallan@swin.edu.au)

Centre for Advanced Internet Architectures
Swinburne University of Technology
Melbourne, Australia
CRICOS number 00111D
http://www.caia.swin.edu.au