Fletch 0.1.0 documentation

index.md

Index: index.md
diff --git a/index.md b/index.md
index aa4357218d4c7605c18484cb17e9a11934f201ba..7d66618f2b2dbb27545522c4cacbd8b6d91eebf8 100644
--- a/index.md
+++ b/index.md
@@ -5,4 +5,183 @@ layout: page
 
 # The Fletch project
 
-More details coming soon.
+Fletch is an **experimental** project to enable highly productive development
+for embedded devices. It is powered by the [Dart
+language](https://www.dartlang.org/docs/dart-up-and-running/ch02.html) and a
+fast, lean runtime.
+
+This page will take you through getting the Fletch platform installed on your
+local developer PC so that you can run and write Fletch programs that target
+embedded devices. Note that the current early version of Fletch supports only a

[wibling, 2015/10/05 15:19:59]

NIT: I would swap "supports" and "only"

[mit, 2015/10/05 17:51:38]

Done.

+single embedded device -- the Raspberry Pi 2 -- and that the only supported

[wibling, 2015/10/05 15:19:59]

NIT: I would remove "that"

[mit, 2015/10/05 17:51:38]

Done.

+client operating systems supported for development are MacOS and Linux (sorry,
+no Windows support).

[wibling, 2015/10/05 15:19:59]

yet? or is that promising too much?

[mit, 2015/10/05 17:51:38]

I think so, let's just leave it as is until we understand the timeline for
Windows support...

+
+If you just want to get a look at what Fletch programs look like, take a peak at

[wibling, 2015/10/05 15:19:59]

peak -> peek

[mit, 2015/10/05 17:51:38]

Done.

+our [samples page](samples.html).
+
+* [Installing the SDK](#installing-the-sdk)
+* [Running your first program](#running-your-first-program)
+* [Preparing your Raspberry Pi 2](#preparing-your-raspberry-pi-2)
+* [Running on the Raspberry Pi](#running-on-the-raspberry-pi)

[Søren Gjesse, 2015/10/05 16:19:51]

Add 2 here as well?

[mit, 2015/10/05 17:51:38]

Done.

+* [Next steps](#next-steps)
+
+## Installing the SDK
+
+First download the SDK. This is available as a .zip archive; pick the one that

[Søren Gjesse, 2015/10/05 16:19:51]

`s around .zip

[mit, 2015/10/05 17:51:38]

Done.

+matches the OS of the PC you will be developing your code on:

[wibling, 2015/10/05 15:19:58]

Perhaps change "be developing your code on" to "be using for development".

[mit, 2015/10/05 17:51:39]

Done.

+
+* [MacOS, 32-bit](http://gsdview.appspot.com/fletch-archive/channels/dev/raw/0.1.0-dev.3.0/sdk/fletch-sdk-macos-ia32-release.zip)
+* [MacOS, 64-bit](http://gsdview.appspot.com/fletch-archive/channels/dev/raw/0.1.0-dev.3.0/sdk/fletch-sdk-macos-x64-release.zip)
+* [Linux, 32-bit](http://gsdview.appspot.com/fletch-archive/channels/dev/raw/0.1.0-dev.3.0/sdk/fletch-sdk-linux-ia32-release.zip)
+* [Linux, 64-bit](http://gsdview.appspot.com/fletch-archive/channels/dev/raw/0.1.0-dev.3.0/sdk/fletch-sdk-linux-x64-release.zip)
+
+
+Unzip this, and make sure that the Fletch command is in path by typing this in a

[wibling, 2015/10/05 15:19:59]

NIT: remove "that"

"path" -> "the path"

Perhaps "this" -> "the below"

[mit, 2015/10/05 17:51:38]

Done.

+terminal window:
+
+~~~
+cd $HOME
+unzip ./Downloads/fletch-sdk-macos-x64-release.zip
+export "PATH=$PATH:$HOME/fletch-sdk/bin"
+~~~
+
+Test that the Fletch program works, it should print a version number to the console:

[wibling, 2015/10/05 15:19:59]

NIT: remove "that"

[mit, 2015/10/05 17:51:38]

Done.

+
+~~~
+fletch --version
+~~~
+
+## Running your first program
+
+Let’s go ahead and run our first Fletch program. This is a simple program that
+prints Hello. In your command line type:
+
+~~~
+cd $HOME/fletch-sdk/samples/general/
+fletch run hello.dart
+~~~
+
+You should see output that looks like this on your screen:

[wibling, 2015/10/05 15:19:59]

Perhaps: "this" -> "the below"

[mit, 2015/10/05 17:51:39]

Done.

+
+~~~
+Hello from Darwin running on ‘michael-pc2’
+~~~
+
+Try to open ```hello.dart``` in your favorite editor. We recommend the Atom

[Søren Gjesse, 2015/10/05 16:19:51]

Isn't just one ` sufficient here?

[mit, 2015/10/05 17:51:39]

Done.

+editor by Github with the Dart plugin. Pretty easy to read, right?

[Søren Gjesse, 2015/10/05 16:19:51]

With the analyzer not supported you will see a bunch of errors for fletch
projects though.

[mit, 2015/10/05 17:51:38]

Yes, added a note, and filed an enhancement bug to track this.

+
+But what actually happened when we asked the ```fletch``` command to run
+```hello.dart```? By default ```fletch``` is connected to a local session,
+which is connected to a local VM (Virtual Machine) running on your developer PC.
+When you ask ```fletch``` to run the program, it compiles the program to byte
+code, and then passes it to the local Fletch VM for execution. The VM passes
+back the result, and fletch prints it to your command line.
+
+![Fletch architecture diagram](https://storage.googleapis.com/fletch-archive/images/Fletch-architecture.png)
+
+Now let’s get things running on your Raspberry!

[Søren Gjesse, 2015/10/05 16:19:51]

Maybe add a paragraph:

If you already have a working Raspberry Pi 2 installed with a recent Raspbian
you can skip to Step 3. The only requirements are that the Raspberry Pi 2 has an
IP address and you can access it from your development machine.

[mit, 2015/10/05 17:51:38]

Done.

+
+## Preparing your Raspberry Pi 2
+
+### Step 1: Raspbian operating system
+
+In this first step we will get a copy of the Raspberry operating system, and get

[wibling, 2015/10/05 15:19:59]

NIT: Either "Raspberry Pi 2's" or "Raspbian" instead of "Raspberry"

[mit, 2015/10/05 17:51:38]

Done.

[mit, 2015/10/05 17:51:39]

Done.

+it written to your SD card. You can skip this step if you already have Raspbian
+running. Otherwise follow these steps to get the image installed:
+
+* Download the zip file containing 'Raspbian Jessie' from the [Raspbian download
+ page](https://www.raspberrypi.org/downloads/raspbian/).
+* Unzip the file by typing this in a termnal window:
+  * On Mac: ```ditto -x -k 2015-09-24-raspbian-jessie.zip .```
+  * On Linux: ```unzip 2015-09-24-raspbian-jessie.zip```
+* Follow the steps to [get the .img file onto your SD
+ Card](https://www.raspberrypi.org/documentation/installation/installing-images/README.md).
+
+### Step 2: Configure the IP address for the Raspberry Pi
+
+We need to enable IP communication between your developer PC and your Raspberry
+Pi. You can either connect your Raspberry to your router (via a cable or WiFi),
+or you
+ add a second Ethernet adapter to your developer PC and connect to the

[wibling, 2015/10/05 15:19:59]

NIT: missing a "can" between "you" and "add"

[mit, 2015/10/05 17:51:38]

Done.

+Raspberry Pi directly via a cable.
+
+There are several ways you can configure the IP number of the Raspberry:
+
+* *Option 1*: If you have your Raspberry connected to a monitor and you are connecting it to a router that uses DHCP (i.e. allocates IPs automatically), then you can use this approach:
+  * Boot the Raspberry
+  * After boot enter ```sudo ip show addr``` in a terminal prompt on the Raspberry.
+  * Note down the IP as we will be using it below.

[wibling, 2015/10/05 15:19:59]

You could also mention that the user can assign a static IP address if they have
a monitor and a keyboard in the case they don't have a dhcp server.

[mit, 2015/10/05 17:51:39]

Done.

+
+* *Option 2*: If you are on a Linux developer PC, you can also configure the image directly from your developer PC.
+  * Mount the SD card
+  * Enter the following in a console: ```$HOME/fletch-sdk/platforms/raspberry-pi2/setup-ip.sh <path to SD card's boot partition>```
+
+* *Option 3*: If you are on a Mac developer PC, you can connect directly to the Raspberry Pi via an USB Network adapter connected to the Raspberry Pi via a networking cable:
+  * Turn off your Raspberry Pi
+  * Open System Preferences and pick the Network icon
+  * Plug the USB Ethernet adapter into your Mac
+  * Change the IPv4 option to ```Manually```
+  * Enter the IP Address ```192.168.2.1```
+  * Go back to System Preferences and pick the Sharing icon

[wibling, 2015/10/05 15:19:59]

Perhaps also mention "Enable sharing for the USB Ethernet Adapter"

[mit, 2015/10/05 17:51:38]

Done.

+  * Turn your Raspberry Pi back on
+  * After a little while you should be able to ping the Raspberry Pi at ```192.168.2.2```

[Søren Gjesse, 2015/10/05 16:19:51]

Is the Mac acting as a DHCP server always assigning 192.168.2.2 in this case?

[mit, 2015/10/05 17:51:39]

Yup. (That is, assuming the Raspberry is the first only network device plugged
into the Mac).

+
+### Step 3: Install Fletch binaries
+
+**Note**: In the steps below, replace ```192.168..``` with whatever IP address you configured above.
+
+The last step is to install the Fletch runtime on the Raspberry Pi (see the
+right-hand side of the architecture diagram above). Use the following commands.
+
+A. Copy the fletch package to the Raspberry Pi (the default password for

[Søren Gjesse, 2015/10/05 16:19:51]

fletch package -> fletch-agent package.

[mit, 2015/10/05 17:51:38]

Done.

+Raspbian is 'raspberry'):

[Søren Gjesse, 2015/10/05 16:19:50]

for Raspbian -> for user 'pi' on Raspbian 

[mit, 2015/10/05 17:51:39]

Done.

+
+~~~
+cd $HOME/fletch-sdk
+scp ./platforms/raspberry-pi2/fletch-agent*.deb pi@192.168..:/home/pi/
+~~~
+
+B. Install the package:
+
+~~~
+ssh pi@192.168.. sudo dpkg --install /home/pi/fletch-agent*.deb
+~~~
+
+You should see something like ```Unpacking fletch-agent...``` on your screen.
+
+## Running on the Raspberry Pi
+
+The Fletch platform is now available on the Raspberry Pi 2. Let’s make our Hello

[wibling, 2015/10/05 15:19:58]

NIT: Consistent use of "Raspberry Pi 2" or "Raspberry Pi". You know which one I
prefer ;)

[mit, 2015/10/05 17:51:38]

Done.

+program run again, this time on the Raspberry Pi 2. Type the following command on

[Søren Gjesse, 2015/10/05 16:19:51]

nit: long line

[mit, 2015/10/05 17:51:39]

Done.

+your local developer PC:
+
+~~~
+cd $HOME/fletch-sdk/
+fletch run ./samples/general/hello.dart in session remote
+~~~
+
+The first time you run in the remote session you will be asked to enter the IP
+address. Enter the IP you picked in the previous step, e.g. ```192.168.2.2```.
+
+You should then see the following output on your screen:
+
+~~~
+Hello from Linux running on raspberrypi.
+~~~
+
+Do you notice the difference? As before Fletch compiled the hello.dart program

[wibling, 2015/10/05 15:19:59]

NIT: Do -> Did

You have talked in past tense in most of the above and below.

[mit, 2015/10/05 17:51:38]

Done.

+to byte code, but this time rather than passing it to the local VM via the local
+session it passed it to the Raspberry Pi via the remote session. On the
+Raspberry Pi, the Fletch VM Agent made sure that a VM (Virtual Machine) was spun
+up, and the program was executed on it. The result of the program (the printing
+to the console) was passed back by the VM to the Fletch command on the developer
+PC, and it was printed to the local console.
+
+## Next steps
+
+Ready for some more fun? Take a look at our [samples](samples.html), and read
+more about the [Fletch tool]()tool.html.
+
+And don’t forget to send us some [feedback](feedback.html), and ask some
+[questions](faq.html).