====== Getting Started ====== 
===== Connect =====

Connecting to Carambola2 is pretty easy. There are several ways of doing this. My personal recommendation is: 
  * Serial: **picocom** for Linux and OSX, **putty** for Windows.
  * Ethernet: **ssh** for Linux and OSX, **putty** for Windows.

==== Serial ====
Carambola2 unlike Carambola1 features on-board USB to Serial FTDI interface. It is also powered by USB.

=== putty (Windows) ===
Pretty straight forward. Run program, enter COM port number, select baudrate 115200 and click "connect".

=== picocom (Linux, OSX) ===
  picocom -b 115200 /dev/ttyUSB0

  * Picocom [[http://linux.die.net/man/8/picocom|man]] 
  * To exit, press and hold CTRL, a, q.

==== Ethernet ====
=== putty (Windows) ===

Putty can be used for SSH, Telnet and Serial connectivity. It's a Swiss knife tool for Windows. Usage is as simple as in serial mode. Run, enter IP address, select protocol and connect.
=== ssh (Linux, OSX) ===

SSH is not enabled by default. In order to enable enter on your Carambola:

  passwd

Then enter password and repeat. After this Carambola can be connected:

  ssh root@192.168.1.1

Where ''root'' is your default root user and 192.168.1.1 IP address.

=== telnet (Linux, OSX) ===
This option is enabled in fresh OpenWrt. Connecting to Carambola is straightforward.

  telnet 192.168.1.1

Where 192.168.1.1 is your Carambola's IP address.
==== Advanced ====

[[carambola:2:gettingstarted:connect-advanced]]
===== Build firmware =====

This procedure must be performed on your computer. We use Xubuntu and Ubuntu but many other distributions should work. It is also possible to build on OSX. Building on Windows platform is not recommended. 

==== Install packages to your computer ====

In order to build OpenWrt, you will need few software packages on your computer. Some are mandatory, some optional.

  sudo apt-get install subversion g++ ncurses-term zlib1g-dev gawk flex patch openssh-server minicom picocom tftp tftpd gettext libncurses5 libncurses5-dev unzip quilt git git-doc git-gui libxml-parser-perl libssl-dev

==== Get latest sources ====
Get latest sources from 8devices OpenWrt branch.

  git clone https://github.com/8devices/carambola2 carambola2
  cd carambola2

==== Build image ====
If you are building firmware for the first time just run:

  ./build.sh

This will update package feeds and build minimal image firmware image. 
If you want to customize your build look for more details in [[carambola:2:gettingstarted:build-advanced|advanced]] section.


Note that building OpenWrt firmware takes some time. On moderate computer it might take 1 to 3 hours. CPU load during this process is usual close to 100%.
You should see build log like this:

{{:carambola_where_to_start_2.png?nolink&|}}

==== Advanced ====
If you feel like something is missing or looking for some goodies, this section is for you.

  * [[carambola:2:gettingstarted:build-advanced]]

==== Useful links ====

  * [[http://wiki.openwrt.org/doc/howto/build?s|Openwrt building (official web page)]]

===== Upload firmware =====
This section covers few methods how to upgrade firmware on Carambola2. Some methods require only USB-Serial connection, some only LAN, some LAN and Serial. Also you might need to install/setup other software to perform these tasks.

==== Web interface / LUCI ====
This method is recommended for novices. Connect to Carambola web interface, browse for firmware upgrade (System -> Backup / Flash firmware), select file and press upgrade.

==== sysupgrade ====
Login to Carambola and download binary image to RAM. (Alter IP and path to match your binary image location)

  scp test@192.168.1.105:/home/test/carambola2/bin/ar71xx/openwrt-ar71xx-generic-carambola2-squashfs-sysupgrade.bin /tmp

Perform upgrade procedure.

  sysupgrade -v -n /tmp/openwrt-ar71xx-generic-carambola2-squashfs-sysupgrade.bin
  
Or if you wish to save configuration files:

  etc/ethers
  etc/config/wireless
  etc/config/system
  etc/config/network
  etc/config/dropbear
  etc/config/firewall
  etc/config/dhcp
  etc/dropbear/dropbear_rsa_host_key
  etc/dropbear/dropbear_dss_host_key

type:

  sysupgrade -v -c /tmp/openwrt-ar71xx-generic-carambola2-squashfs-sysupgrade.bin

==== USB recovery ====

If you have Carambola2 with new 'Caraboot' boot-loader, you can use USB recovery functionality to perform upgrade. **NOTE:** using this method will destroy any configuration changes you made.
You have the new boot-loader if U-Boot version looks like this:

  =====================================
  Caraboot v2.0 (AR9331) U-boot
  http://www.8devices.com/
  -------------------------------------
  DRAM:  64 MB
  Flash: 16 MB


To perform recovery, you need USB flash drive formatted with FAT32 file system. Copy Carambola sysupgrade image to root directory of the flash drive and rename the file to '8dev_recovery.bin'. Plug USB drive to Carambola's USB port, press device reset button (marked S2), while holding reset-to-defaults button (next to USB port, marked S1). Hold reset-to-default (S1) button until WIFI LED on development board flashes 4 times. This means boot-loader found recovery image, and will flash it immediately. After flashing finished, LED will blink 2 times and device will reboot. If boot-loader can't find recovery image in USB media, it will try booting OpenWRT normally.

If you have serial console connected, process should look like this:
{{:carambola:2:usb-recovery.png?nolink&1000|}}

==== Advanced ====
[[carambola:2:gettingstarted:flash-advanced]]

[[carambola:2:uboot]]