Added Service client to readmes + fixes to doc

device/readme.md

@@ -14,23 +14,10 @@ Use the device SDK to:
 
 ## How to use the Azure IoT device SDK for Python
 
-* [Get started in minutes with the PyPI package][PyPI-install-instructions]
-* [Check out the simple samples provided in this repository][run-samples]
-
-## Application development guides
-For more information on how to use this library refer to the documents below:
-- [Prepare your Python development environment][devbox-setup]
-- [Setup IoT Hub and provision devices][setup-iothub]
-- [Run a Python sample application][run-samples]
+* [Check out the simple samples provided in this repository][samples]
 
 ## Samples
-Whithin the repository, you can find various types of simple samples that can help you get started.
-And if you are looking for end to end samples that show how to do simple analytics and processing of the data generated by your device using Azure services such as Stream Analytics, Big Data, Machine Learning and others, check out our [E2E samples gallery](http://aka.ms/azureiotsamples).
-To run the samples, you can follow [these instructions][run-samples]
-
-* [Simple Sample](samples/iothub_client_sample.py): shows how to connect to IoT Hub and send and receive messages using the AMQP, MQTT or HTTP protocol.
-* [Class Sample using AMQP](samples/iothub_client_sample_class.py): shows how to connect to IoT Hub with a HubManager class to send and receive messages using the AMQP protocol.
-* [Simple Sample X-509](samples/iothub_client_sample_x509.py):  shows how to authenticate a device using X-509 certs and send and receive messages.
+Whithin the repository, you can find various types of [simple samples][samples] that can help you get started.
 
 ## Directory structure
 
@@ -48,7 +35,4 @@ Sample Python applications excercising basic features using AMQP, MQTT and HTTP.
 
 Python C extension module unit tests. The unit tests exercise a mocked Python extension module to test the Python interface. 
 
-[setup-iothub]: https://aka.ms/howtocreateazureiothub
-[devbox-setup]: ../doc/python-devbox-setup.md
-[run-samples]: ../doc/python-run-sample.md
-[PyPI-install-instructions]: ../doc/python-devbox-setup.md#windows-wheels
+[samples]: samples/

device/samples/readme.md

@@ -0,0 +1,34 @@
+# Samples for the Azure IoT device SDK for Python
+
+This folder contains simple samples showing how to use the various features of the Microsoft Azure IoT Hub service from a device running Python.
+
+## List of samples
+
+* [Simple Sample](iothub_client_sample.py): shows how to connect to IoT Hub and send and receive messages using the AMQP, MQTT or HTTP protocol.
+* [Class Sample using AMQP](iothub_client_sample_class.py): shows how to connect to IoT Hub with a HubManager class to send and receive messages using the AMQP protocol.
+* [Simple Sample X-509](iothub_client_sample_x509.py):  shows how to authenticate a device using X-509 certs and send and receive messages.
+
+And if you are looking for end to end samples that show how to do simple analytics and processing of the data generated by your device using Azure services such as Stream Analytics, Big Data, Machine Learning and others, check out our [E2E samples gallery](http://aka.ms/azureiotsamples).
+
+## How to run the samples
+In order to run the device samples you will first need the following prerequisites:
+* [Setup your development environment][devbox-setup]
+> Note: On Windows, it is recommended to install the **iothub-client** module package using pip (see link above).
+* [Create an Azure IoT Hub instance][lnk-setup-iot-hub]
+* [Create a device identity for your device][lnk-manage-iot-hub] and retreive the primary connection string for this device
+
+Once you have a device identity for your sample,
+* Get the sample files:
+   * if you have cloned the repository, Navigate to the folder **device/samples**
+   * if you are using the iothub_client module installed with pip, download the samples folder content to your target.
+* Run the sample application using the following command to run the simple sample (replacing `<device connection string>` with the one generated previously):
+    ```
+	python iothub_client_sample.py -c < device connection string > -p < mqtt|http|amqp >
+    ```
+> You can get details on the options for the sample command line typing:
+> `python iothub_client_sample.py -h`
+* To run the other samples (x-509 and class), replace the name of the .py file in the command line and use the `-h` option to get the details on the available options
+
+[lnk-setup-iot-hub]: https://aka.ms/howtocreateazureiothub
+[lnk-manage-iot-hub]: https://aka.ms/manageiothub
+[devbox-setup]: ../../doc/python-devbox-setup.md