diff --git a/APPLICATION_DEVELOPMENT.md b/APPLICATION_DEVELOPMENT.md
new file mode 100644
index 0000000..9199c94
--- /dev/null
+++ b/APPLICATION_DEVELOPMENT.md
@@ -0,0 +1,216 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+#Edgent Application Development, Packaging and Execution.
+
+This file is a work-in-progress.
+
+To develop Edgent applications you will utilize the 
+Edgent SDK/runtime jars, package your application
+artifacts for deploying to an edge device for execution.
+
+The Edgent SDK/runtime jars are published to maven-central.
+Alternatively, you can build the Edgent SDK yourself from a source release
+and the resulting jars will be added to your local maven repository.
+  
+There are a set of Edgent jars for each supported platform: java8, java7, and android.
+The artifact groupId prefix is: org.apache.edgent (for java8),
+org.apache.edgent.java7 and org.apache.edgent.android.  e.g.
+    org.apache.edgent.api  org.apache.edgent.api.java7
+
+See `JAVA_SUPPORT.md` for more information on coordinates, etc.
+
+The Edgent API is most easily used by using java8 lambda expressions.
+If you only want to deploy your Edgent application to a java8 environment
+then your application may use any java8 features it chooses.  You compile
+and run against the Edgent java8 jars.
+
+If you want to deploy your Edgent application to a java7 or android
+environment, it's still easiest to write your application using the Edgent APIs
+with java8 lambda expressions.  You compile with java8 but constrain 
+your application to using java7 features plus java8 lambda expressions.
+The Retrolambda tool is used to convert your application's generated 
+class files to java7.
+(the java7 and android Edgent jars were created in that manner too)
+Your application would then be run against the appropriate
+Edgent platform jars. Alternatively you can forgo the use of lambda
+expressions and write your application in java7 and compile
+and run against the appropriate Edgent platform jars.
+
+For convenience it's easiest to build your Edgent applcation using 
+maven-repository-enabled build tooling (e.g., maven, maven-enabled
+Eclipse or IntelliJ).  The tooling transparently downloads the 
+required Edgent jars from the maven repository.
+
+The supplied Edgent samples poms include support for building for
+a java8, java7 or android execution environent. The poms are
+configured for the generation of a standard jar as well as an
+uber jar for a sample application.
+
+You can clone the samples/template project as a starting point
+for your Edgent application.  See `samples/template/README.md`.
+
+TODO: we would like to provide a maven Edgent Application archetype
+that users can use to create an application project template.
+
+If you can't or don't want to use maven-repository-enabled tooling
+you will need to get a local copy of the Edgent jars and their
+dependencies and add them to your compile classpath.
+The Edgent supplied get-edgent-jars.sh tool can be used to
+get copies of the jars from a maven repository.
+
+
+##Packaging and Execution
+
+Edgent doesn't provide any "deployment" mechanisms other than its primitive
+"register jar" feature (see the IotProvider javadoc).  Generally, managing
+the deployment of application and Edgent jars to edge devices is left to 
+others (as an example, the IBM Watson IoT Platform has device APIs to
+support "firmware" download/update).
+
+To run your Edgent application on an edge device, your application
+jar(s) need to be on the device.  Additionally, the application's 
+dependent Edgent jars (and their transitive dependencies) need to
+be on the device.  It's unlikely the device will be able to retrieve
+the dependencies directly from a remote maven repository such as
+maven central.
+
+Here are three options for dealing with this:
+
+a) construct an uber-jar for your application.
+   The uber jar contains the application's classes and
+   the application's dependent Edgent classes and their
+   transitive dependencies.
+
+   The uber jar is a standalone entity containing
+   everything that's needed to run your application.
+
+   The Edgent samples poms contain configuration information
+   that generates an uber jar in addition to the standard
+   application jar.  Eclipse can also export an uber jar.
+
+b) create an application package bundle.
+   The bundle contains the application's jar
+   and the application's dependent Edgent jars and their
+   transitive dependencies.
+   The bundle is copied to the device and unpacked.
+   A run script forms the appropriate CLASSPATH
+   to the package's jars and starts the application.
+
+   The Edgent supplied package-app.sh tool supports this mode.
+   Eclipse can also export a similar collection
+   of information.
+
+c) separately manage the application's jars and the
+   Edgent jars and their dependencies.
+   Copy the application's jars to the device.
+   Get a copy of the Edgent jars and their dependencies
+   onto the device to be shared by any Edgent applications
+   that want to use them.
+
+   The Apache Edgent project does not release a
+   binary bundle containing all of the Edgent jars
+   and their dependencies.  The binary artifacts
+   are only released to maven central.
+
+   The Edgent supplied get-edgent-jars.sh tool supports this mode.
+   
+##get-edgent-jars.sh
+
+The `get-edgent-jars.sh` script copies the Edgent runtime jars and their
+dependencies from a local or remote maven repository.
+
+The user may then directly use the jars in CLASSPATH specifications
+for Edgent application compilation or execution.
+A `classpath.sh` script is generated to assist with this.
+
+By default the script retrieves the Edgent java8 platform jars for the
+script's default Edgent version.
+
+The script creates and builds a small maven project as
+part of its execution.
+
+```sh
+get-edgent-jars.sh --version 1.2.0-SNAPSHOT  # retrieve the Edgent 1.2.0-SNAPSHOT java8 jars
+This command downloads the Apache Edgent jars and their transitive external dependencies.
+The external dependencies have their own licensing term that you should review.
+A summary of the external dependencies can be found here <TODO URL>.
+Continue? [y/n] y
+##### Generating maven project get-edgent-jars-project...
+##### Generating dependency decls...
+##### Adding dependency decls to pom...
+##### Retrieving jars into local maven repo...
+...
+##### Copying jars...
+##### Generating classpath.sh...
+##### The Edgent jars are in get-edgent-jars-project/edgent-jars
+##### The external jars are in get-edgent-jars-project/ext-jars
+##### CLASSPATH may be set by copying get-edgent-jars-project/java8/classpath.sh and using it like:
+#####    export CLASSPATH=`classpath.sh path-to-parent-of-edgent-jars-dir`
+```
+
+For more usage information:
+
+```sh
+get-edgent-jars.sh -h
+```
+
+##package-app.sh
+
+The `package-app.sh` script creates an application bundle.
+The application bundle can be copied to an edge-device,
+unpacked and then used to run the application.
+
+The application bundle contains the application's jar,
+the application's dependent Edgent jars (as specified in
+the application's pom) and the Edgent jars' dependencies,
+and a run-app.sh script.
+
+The application's pom specified Edgent runtime jars and 
+their dependencies are retrieved from a local or remote
+maven repository.
+
+If the application was built using java8, complied against
+the java8 Edgent jars, and the execution environment is
+java7 or android, use the appropriate script options
+to retrieve the appropriate Edgent platform jars for
+execution.
+
+The run-app.sh script configures the CLASSPATH and runs
+the application.
+
+E.g.,
+
+```sh
+cd MyApp # the project directory
+package-app.sh --mainClass com.mycompany.app.MyApp --appjar target/my-app-1.0-SNAPSHOT.jar
+##### get the app specific dependencies...
+...
+##### create target/app-run.sh...
+##### create target/app-pkg.tar...
+##### Copy target/app-pkg.tar to the destination system"
+##### To run the app:"
+#####     mkdir app-pkg"
+#####     tar xf app-pkg.tar -C app-pkg"
+#####     (cd app-pkg; ./app-run.sh)"
+```
+
+For more usage information:
+
+```sh
+package-app.sh -h
+```
diff --git a/README.md b/README.md
index b9b0dee..15e4fdb 100644
--- a/README.md
+++ b/README.md
@@ -14,204 +14,9 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
-#Apache Edgent SDK samples.
 
-This file is a work-in-progress.
-
-The following describes Edgent Application development in general
-and the Edgent SDK samples in particular.
-
-#Edgent Application Development, Packaging and Execution.
-
-The Edgent SDK/runtime jars are published to maven-central.
-  
-There are a set of Edgent jars for each supported platform: java8, java7, and android.
-The artifact groupId prefix is: org.apache.edgent (for java8),
-org.apache.edgent.java7 and org.apache.edgent.android.  e.g.
-    org.apache.edgent.api  org.apache.edgent.api.java7
-
-See `JAVA_SUPPORT.md` for more information on coordinates, etc.
-
-The Edgent API is most easily used by using java8 lambda expressions.
-If you only want to deploy your Edgent application to a java8 environment
-then your application may use any java8 features it chooses.  You compile
-and run against the Edgent java8 jars.
-
-If you want to deploy your Edgent application to a java7 or android
-environment, it easiest to write your application using the Edgent APIs
-with java8 lambda expressions.  You compile with java8 but constrain 
-your application to using java7 features plus java8 lambda expressions.
-The Retrolambda tool is used to convert your application's generated 
-class files to java7.
-(the java7 and android Edgent jars were created in that manner too)
-Your application would then be run against the appropriate
-Edgent platform jars. Alternatively you can forgo the use of lambda
-expressions and write your application in java7 and compile
-and run against the appropriate Edgent platform jars.
-
-For convenience it's easiest to build your Edgent applcation using 
-maven-repository-enabled build tooling (e.g., maven, maven-enabled
-Eclipse or IntelliJ).  The tooling transparently downloads the 
-required Edgent jars from the maven repository.
-
-The supplied Edgent samples poms include support for building for
-a java8, java7 or android execution environent. The poms are
-configured for the generation of a standard jar as well as an
-uber jar for a sample application.
-
-You can clone the samples/template project as a starting point
-for your Edgent application.  See samples/template/README.md.
-
-TODO: we would like to provide a maven Edgent Application archetype
-that users can use to create an application project template.
-
-If you can't or don't want to use maven-repository-enabled tooling
-you will need to get a local copy of the Edgent jars and their
-dependencies and add them to your compile classpath.
-The Edgent supplied get-edgent-jars.sh tool can be used to
-get copies of the jars from a maven repository.
-
-
-##Packaging and Execution
-
-Edgent doesn't provide any "deployment" mechanisms other than its primitive
-"register jar" feature (see the IotProvider javadoc).  Generally, managing
-the deployment of application and Edgent jars to edge devices is left to 
-others (as an example, the IBM Watson IoT Platform has device APIs to
-support "firmware" download/update).
-
-To run your Edgent application on an edge device, your application
-jar(s) need to be on the device.  Additionally, the application's 
-dependent Edgent jars (and their transitive dependencies) need to
-be on the device.  It's unlikely the device will be able to retrieve
-the dependencies directly from a remote maven repository such as
-maven central.
-
-Here are three options for dealing with this:
-
-a) construct an uber-jar for your application.
-   The uber jar contains the application's classes and
-   the application's dependent Edgent classes and their
-   transitive dependencies.
-
-   The uber jar is a standalone entity containing
-   everything that's needed to run your application.
-
-   The Edgent samples poms contain configuration information
-   that generates an uber jar in addition to the standard
-   application jar.  Eclipse can also export an uber jar.
-
-b) create an application package bundle.
-   The bundle contains the application's jar
-   and the application's dependent Edgent jars and their
-   transitive dependencies.
-   The bundle is copied to the device and unpacked.
-   A run script forms the appropriate CLASSPATH
-   to the package's jars and starts the application.
-
-   The Edgent supplied package-app.sh tool supports this mode.
-   Eclipse can also export a similar collection
-   of information.
-
-c) separately manage the application's jars and the
-   Edgent jars and their dependencies.
-   Copy the application's jars to the device.
-   Get a copy of the Edgent jars and their dependencies
-   onto the device to be shared by any Edgent applications
-   that want to use them.
-
-   The Apache Edgent project does not release a
-   binary bundle containing all of the Edgent jars
-   and their dependencies.  The binary artifacts
-   are only released to maven central.
-
-   The Edgent supplied get-edgent-jars.sh tool supports this mode.
-   
-##get-edgent-jars.sh
-
-The `get-edgent-jars.sh` script copies the Edgent runtime jars and their
-dependencies from a local or remote maven repository.
-
-The user may then directly use the jars in CLASSPATH specifications
-for Edgent application compilation or execution.
-A `classpath.sh` script is generated to assist with this.
-
-By default the script retrieves the Edgent java8 platform jars for the
-script's default Edgent version.
-
-The script creates and builds a small maven project as
-part of its execution.
-
-```sh
-get-edgent-jars.sh --version 1.2.0-SNAPSHOT  # retrieve the Edgent 1.2.0-SNAPSHOT java8 jars
-This command downloads the Apache Edgent jars and their transitive external dependencies.
-The external dependencies have their own licensing term that you should review.
-A summary of the external dependencies can be found here <TODO URL>.
-Continue? [y/n] y
-##### Generating maven project get-edgent-jars-project...
-##### Generating dependency decls...
-##### Adding dependency decls to pom...
-##### Retrieving jars into local maven repo...
-...
-##### Copying jars...
-##### Generating classpath.sh...
-##### The Edgent jars are in get-edgent-jars-project/edgent-jars
-##### The external jars are in get-edgent-jars-project/ext-jars
-##### CLASSPATH may be set by copying get-edgent-jars-project/java8/classpath.sh and using it like:
-#####    export CLASSPATH=`classpath.sh path-to-parent-of-edgent-jars-dir`
-```
-
-For more usage information:
-
-```sh
-get-edgent-jars.sh -h
-```
-
-##package-app.sh
-
-The `package-app.sh` script creates an application bundle.
-The application bundle can be copied to an edge-device,
-unpacked and then used to run the application.
-
-The application bundle contains the application's jar,
-the application's dependent Edgent jars (as specified in
-the application's pom) and the Edgent jars' dependencies,
-and a run-app.sh script.
-
-The application's pom specified Edgent runtime jars and 
-their dependencies are retrieved from a local or remote
-maven repository.
-
-If the application was built using java8, complied against
-the java8 Edgent jars, and the execution environment is
-java7 or android, use the appropriate script options
-to retrieve the appropriate Edgent platform jars for
-execution.
-
-The run-app.sh script configures the CLASSPATH and runs
-the application.
-
-E.g.,
-
-```sh
-cd MyApp # the project directory
-package-app.sh --mainClass com.mycompany.app.MyApp --appjar target/my-app-1.0-SNAPSHOT.jar
-##### get the app specific dependencies...
-...
-##### create target/app-run.sh...
-##### create target/app-pkg.tar...
-##### Copy target/app-pkg.tar to the destination system"
-##### To run the app:"
-#####     mkdir app-pkg"
-#####     tar xf app-pkg.tar -C app-pkg"
-#####     (cd app-pkg; ./app-run.sh)"
-```
-
-For more usage information:
-
-```sh
-package-app.sh -h
-```
+See [APPLICATION_DEVELOPMENT.md](APPLICATION_DEVELOPMENT.md) for general
+information on Edgent Application Development, Packaging and Execution.
 
 #Building the Edgent samples
 
@@ -229,4 +34,4 @@
 
 ##Running the samples
 
-See the README in each sample category directory.
+See the README.md in each sample category directory.
diff --git a/console/run-sample.sh b/console/run-sample.sh
index 7cbd42a..b11529e 100755
--- a/console/run-sample.sh
+++ b/console/run-sample.sh
@@ -60,5 +60,5 @@
   exit 1
 fi
 
-java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*"
+java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@"
 
diff --git a/scenarios/README.md b/scenarios/README.md
index 7a2d3ac..da1d9e3 100644
--- a/scenarios/README.md
+++ b/scenarios/README.md
@@ -20,36 +20,50 @@
 
 See the Recipe this was created for [here](https://developer.ibm.com/recipes/tutorials/apache-quarks-on-pi-to-watson-iot-foundation/).  If that link doesn't work, try [here](https://developer.ibm.com/recipes/tutorials/apache-edgent-on-pi-to-watson-iot-foundation/). 
 
+See the README.md in the samples root directory for information on building the samples.
+
+The build generated uber jar contains all of the dependent 
+Edgent jars and their transitive dependencies.
+
+The desired sample can be run using the run-sample.sh script. e.g.,
+
+```sh
+cd scenarios
+./run-sample.sh IotpRangeSensor quickstart true true  # see below
+```
+
+For usage information:
+
+```sh
+./run-sample.sh
+./run-sample.sh --list
+```
+
+If you want to run a sample from the standard jar there are two options:
+a) get a local copy of all of the Edgent jars and their dependencies.
+   Form a CLASSPATH to the jars and run the sample's main class.
+   The get-edgent-jars.sh script can be used to get the jars from
+   a maven repository (local or remote).
+b) create an application package bundle.  The bundle includes the
+   sample(s) jar and a copy of all of the dependent Edgent jars
+   and their dependencies.  The package-app.sh script can be
+   used to create this bundle.
+   The package-app.sh script also creates a run-app.sh script.
+   The run-app.sh script configures the CLASSPATH and runs the main class.
+
+
 ## Requirements: 
-* You must have Pi4J installed on the device (if you are running outside of a Raspberry Pi, you will have to download the JARs and include them in your classpath)
-* You must have Edgent downloaded and built
 * You will need to have an HC-SR04 Range sensor hooked up with your EchoPin set to pin 18 and your TripPin at pin 16 (see these instructions on hardware setup: http://www.modmypi.com/blog/hc-sr04-ultrasonic-range-sensor-on-the-raspberry-pi). To use a simulated sensor, pass in true as your second argument. 
 * You will need to have an LED hooked up to pin 12 (See these instructions to set up an LED, however use pin 12 as your control pin: https://projects.drogon.net/raspberry-pi/gpio-examples/tux-crossing/gpio-examples-1-a-single-led/). To use a simulated LED, pass in true as your third argument. 
 * You will need to have your device registered with Watson IoTF and a device.cfg file, or you can use a quickstart version by passing in "quickstart" as your first argument.
- 
-To compile, export your Edgent install and PI4J libraries (on Raspberry Pi, the default Pi4J location is `/opt/pi4j/lib`):
-
-`$ EDGENT=<edgent-root-dir>`
-
-`$ export PI4J_LIB=<Pi4J-libs>  # directory where pi4j-core.jar resides`
-
-`$ cd $EDGENT`
-
-`$ ./gradlew  # builds the range sensor sample only if the PI4J_LIB environment variable is set`
-
-To run: 
- 
-`$ CP=$EDGENT/build/distributions/java8/samples/lib/edgent.samples.scenarios.jar`
-
-`$ MAIN=org.apache.edgent.samples.scenarios.iotp.range.sensor.IotpRangeSensor`
 
 
-`$ java -cp $CP $MAIN <device cfg file> <simulatedSensor?> <simulatedLED?>`
+`./run-sample.sh IotpRangeSensor <device cfg file> <simulatedSensor?> <simulatedLED?>`
 
 To run with a device.cfg file, range sensor, and LED:
 
-`$ java -cp $CP $MAIN device.cfg false false`
+`./run-sample.sh IotpRangeSensor  device.cfg false false`
 
 To run in fully simulated mode (no sensors and using IoTF quickstart): 
 
-`$ java -cp $CP $MAIN quickstart true true`
\ No newline at end of file
+`./run-sample.sh IotpRangeSensor  quickstart true true`
diff --git a/scenarios/run-sample.sh b/scenarios/run-sample.sh
index fea6ead..2b2c92b 100755
--- a/scenarios/run-sample.sh
+++ b/scenarios/run-sample.sh
@@ -60,5 +60,6 @@
   exit 1
 fi
 
-java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*"
+set -x
+java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@"
 
diff --git a/topology/run-sample.sh b/topology/run-sample.sh
index c9568d5..1614a7d 100755
--- a/topology/run-sample.sh
+++ b/topology/run-sample.sh
@@ -70,5 +70,5 @@
   exit 1
 fi
 
-java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*"
+java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@"
 
diff --git a/utils/README.md b/utils/README.md
index 348edae..7381f2e 100644
--- a/utils/README.md
+++ b/utils/README.md
@@ -6,7 +6,7 @@
 The desired sample can be run using the run-sample.sh script. e.g.,
 
 ```sh
-cd topology
+cd utils
 ./run-sample.sh PeriodicSourceWithMetrics
 ```
 
diff --git a/utils/run-sample.sh b/utils/run-sample.sh
index 8e9128a..697f44f 100755
--- a/utils/run-sample.sh
+++ b/utils/run-sample.sh
@@ -60,5 +60,5 @@
   exit 1
 fi
 
-java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*"
+java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@"